SmileBASIC MML Crash Course

Table of Contents


This guide will teach you all about writing MML code in SmileBASIC, for purposes of composing music. A novice understanding of music (writing, notation) is expected.

I do admit: I am not a musician (but I suppose I could always learn…) I just know a bit about music because I played in school band (poorly) for a couple years. There hasn't been a good, comprehensive MML guide, so I took it upon myself. Musical examples might be a bit bland, sorry.

What is MML?

Music Macro Language (MML) is a method of music notation using plain ASCII text. The goal is to be able to describe and compose music as code. It's quite old; as far as I'm aware, there is no single standard. We will be specifically covering the SmileBASIC variant, but most variants have similar syntax and features.

In terms of music notation, MML is very freeform. It describes music literally as a sequence of notes and other commands. It lacks any sense of "structure" in a traditional music sense; MML has no concept of bars, time signatures, keys etc. These are all things you have to take care of yourself. It is, of course, more akin to programming than sheet music. It is, admittedly, somewhat clumsy to do simple things like chords by hand-writing MML, which is why I would personally prefer to use a music tool; but understanding what MML can and can't do is very helpful anyway.

Also, MML does not support comments. When I write comments in my MML examples, I'm using SmileBASIC comment conventions. Including them in the MML code will not work.

How do I use it in SmileBASIC?

There's a few ways you could go about it, but I'll go through the two of them that you will probably find the most useful.

Using Literal BGMPLAY

The BGMPLAY command has a literal form which accepts a text string and plays the result of that MML code. You will likely be using this on DIRECT mode as you learn the syntax.

'play a scale

Using DATA

A very large or complex MML song can be stored in a DATA statement block and loaded into a user BGM track. The DATA block must end with a DATA 0 statement, or this will not work.

'multitrack song (don't try to understand this yet)

The song data can then be stored with BGMSETD and played later with BGMPLAY. When this is done, the text data is combined into one long MML string. The breaks and separation of statements is meaningless.

BGMSETD 128, @SONG  'store
BGMPLAY 128         'play

Writing Notes

Okay, now that you know how to play your MML, you can start writing it! Hopefully. From now on, this guide will not be focused on anything SmileBASIC in particular (with the rare exception, I'm sure) and we're just gonna be writing MML. Let's start with notes.

Note Pitch

Notes are written based on standard pitch notation. To play a C, you write C, and so on. A simple C major scale looks like this, then:


To specify a sharp, you write # or + after the letter, and to specify a flat you write -. A C sharp would be C# or C+. A B flat would be B-. To write double sharps, triple flats, etc. just repeat the symbol as many times as you need. An E flat major scale would look like this:


Do keep in mind that MML has no method to specify key signature for the whole song, or even a specific part. Everything is assumed to be C major, but you can of course use accidentals, sharps, flats, or what have you to your heart's content. You just have to take that into account yourself. If you are writing in, for example, E flat major, you must make sure that every A, B, and E is marked as a flat (except where they would be sharp or natural, of course.)

Note Duration

By default, every note is assumed to be a quarter note. You can change this very easily, of course. All you have to do is write the note length as a number after the note pitch. A eighth note C is C8, a triplet is thus C12C12C12. Here's an example:


You can also write dotted notes, simply by putting . after the note. C#8. is a dotted-eight note C sharp.

As I said before with the key signature thing: MML does not know what time signature is. It does not know what a measure is. It just treats your sequence of notes as a sequence of notes. That's on you.


Rests are written as R. They can be given duration as well, like you would expect.


Simple Commands

MML has a rich set of commands to make your music more interesting, and your life a lot easier. We will go over a few simple ones now, because there's a lot.

Most MML commands are simply a letter or symbol followed by a number, its argument. The ones in this section all follow this expectation. Commands are also treated sequentially like notes (most of the time) and can be used multiple times wherever you need (most of the time.)

Setting the Octave

To set the octave your notes are played at, you use O. The valid range for octaves is 0 through 8. By default, notes are played in the fourth (middle) octave, but what if we want our song to be in the fifth? We just need O5 and we're good to go!


Shifting the Octave

Let's say you want to move your song up one octave without hassle. It's quite easy. If you write <, that means "go up one octave." As well, > means "go down."


Also, when you use !, the meanings of those two symbols are reversed. I don't know what this is useful for, but it must be something.

Setting Default Note Length

As mentioned earlier, every note is a quarter note by default. You can, however, change this default with L. If you toss in L8, now all of the un-numbered notes are eighth notes. The example from earlier can be written differently like this:


Setting the Tempo

The tempo of your song is set to 120 BPM (beats per minute) by default, but can be changed with T. Writing T240 makes the song play at 240 BPM, for example.

Picking your Instrument

SmileBASIC has a vast set of instruments available, the majority of which are based on General MIDI. Every instrument is given a unique number. Of course, instrument 0, Acoustic Grand Piano, is the default used in your song. The @ command tells the system what instrument you want to use at that particular moment.

@0CDE    'acoustic grand piano
@6CDE    'harpischord
@127CDE  'gunshot

More information about instruments will be provided in the appendix.

Setting the Volume

Using V changes the volume of the notes played. The valid range is 0 to 127.

V32C12C12C12DD  'soft
V127EEFF        'LOUD


MML has a looping mechanism built-in, which enables you to… loop the MML sequence. Shocking.

To do so, you just wrap whatever section of your MML in square brackets []. This section will be looped.


If you only want to play a loop some number of times, you can write the number afterwards. [C]8 will only play C eight times.