MML Tutorial

I know there are already tutorials on this subject, but I figured the more there are, the more likely you'll find one that you like and is therefore easier to understand. This tutorial is split into two parts. The first part is taken from my post on Nintendo Life, and is included here. The second part is an external file, but I thought it would be nice to have them all in one place. The link to the second tutorial is at the bottom. If you have any reasonable questions about MML on Petit Computer, please let me know!

Part 1: Basics of MML (Taken from Nintendo Life)
This isn't an in-depth tutorial, just a sort of "quick start". Also, there are other ways to write MML in Petit Computer, but I'm going to do it the way I think is easiest: using DATA portions. This tutorial assumes that you have basic music experience, such as the ability to read music and understand simple notation/musical concepts (like scales). It also assumes that you know what a DATA section is (it's just a way to store data in textual form. There, now you know!). If you're ever lost at a particular Petit Computer command, you can look it up in the Petit Computer Manual. If you're not sure about octave designations, you can look here (I forget them all the time too).

So, we'll start with an empty program. The most basic stuff we're going to need right now is BGMCLEAR, BGMSETD, and a DATA section headed by a label. Here's what it'll look like:

BGMCLEAR 128 BGMSETD 128, @MYSONG @MYSONG DATA 0

The first line says "Whatever song you had as song 128... well I don't care about it. I want it GONE". Song 128 doesn't exist yet, but it's still a good idea to clear it just in case (just like clearing your variables at the start of your program). The next line says "Alright, go out and find @MYSONG and shove all that data into song 128". Well, if you look down at the label for our song, you'll see just one piece of data: 0. This represents the end of our song, so you should always stick that at the end. If you run this program, it doesn't really do anything. Let's start slow and add just a single note: C. What C will it be, some of you may ask? Well, we'll see.

BGMCLEAR 128 BGMSETD 128, @MYSONG BGMPLAY 128 @MYSONG DATA "C" DATA 0

I added 2 lines: BGMPLAY 128 just tells the program to play the song 128. That's the song we're filling up, so it should play... well, our song. I also added DATA "C". Notice that the C is in double quotes: all MML should be surrounded by double quotes (making it a string type), except for the 0 at the end. It's very important that you DON'T put the 0 in quotes. So, go ahead and run the program. If you did it right, you should hear a nice Piano sound playing "middle C" (that's octave 4 if you're looking at that chart I linked to). This is rather important: this means that Petit Computer defaults to a piano and that it defaults to octave 4. But what if you don't want a piano? Well, let's look at the manual: if you jump down to page 40, you'll see the start of a very important table: the sound list. This isn't the usual "BEEP" sounds, but special MML sounds. If you look at the very first one, you'll see that it's an Acoustic Piano. That's the sound we just heard in our program, but let's change it to.... a Vibraphone (sound 11). Let's add one extra line to make it a Vibraphone, along with adding more notes:

BGMCLEAR 128 BGMSETD 128, @MYSONG BGMPLAY 128 @MYSONG DATA "@11" DATA "CDEFG" DATA 0

The line I added was DATA "@11". The @ tells the MML to start using the specified instrument from now on. What this means is that you can stick an @ followed by an instrument in the middle of a series of notes and it will switch instruments right there. Cool, right? Well, it's not always useful, so let's play our music. It should play the lower half of the C Major scale in a Vibraphone sound (not that it matters, it's just notes rising). Notice that I squashed all the notes together; in MML, this is how you do it. Some of you may start to wonder "Hey, there are multiple notes named A, B, C etc. How do I tell it to play one in a different octave?". Well, let's change the one line with the notes to look like this:

DATA "CDEFGAB<C"

If you play it, it should be the regular old C Major scale. That < in there tells Petit Computer to go up to the next octave. Remember, octaves start on C, and changing the octave wherever you want means that ALL notes following will be raised to the next octave. For instance, if we were to extend that line again:

DATA "CDEFGAB<CDEFG"

If you play your song now, you'll notice that the following DEFG after the < are higher than the original ones. This is because we went up to the next octave. Try moving the < around in that sequence of notes to see how it changes. So what about sharps and flats? Well, they're + and - respectively in MML. For instance, if we want to play the F Major scale instead, we'll change our DATA line to:

DATA "FGAB-<CDEF"

Remember, F Major has 1 flat (B flat), and that's exactly what we've put in MML. The flat/sharp follows the note, so it's read "B flat" or "B minus" if you like. Also notice where the < is this time: it's still before the C, but it's not in the same place as our C Major scale. Remember, the octave starts on C, so C is the first note in an octave. This means that if we just stick "C" there without having <, it will play a C lower than the "FGAB-" we had previously, which isn't what we want in a scale. Note that you don't ALWAYS need the < in front of a C, it's just when you're crossing an octave boundary. The opposite of, which lowers the octave. Here's the whole F Major scale then:

DATA "FGAB-B-AGFAAF"

If you play it, you'll hear the standard "concert" version of the scale, in which you ascend, descend, and then do the same with the arpeggio. Next, we should probably add some note lengths. Right now, everything has been the default length, which is a quarter note. If you want to set the length of a note, just follow it with the number specifying the length. The first link has a list of all the lengths. For instance: 4=Quarter note, 8=Eighth note, 16=Sixteenth note, etc. OK, let's make "Mary Had a Little Lamb":

DATA "E4D4C4D4E4E4E2D4D4D2E4G4G2E4D4C4D4E4E4E4E4D4D4E4D4C1"

Yuck, look at all those 4's. Remember, 4 is the default note length, so you don't need to put it. Those 2's are half notes, and the 1 at the end is a whole note. The length of the note should always follow the note itself. What if we want to change the tempo, volume, and starting octave? Let's make our "Merry Had A Little Lamb" rather fast and really high (but a little quieter):

BGMCLEAR 128 BGMSETD 128, @MYSONG BGMPLAY 128 @MYSONG DATA "@11T240O6V80" DATA "L4EDCDEEE2DDD2EGG2EDCDEEEEDDEDC1" DATA 0

Woah, I changed a lot! Let's start at with the first: I added some stuff to the DATA line that had our instrument. Now we've got T240 which tells us to go at 240 beats per minute, O6 which tells us to start up at octave 6 instead of octave 4 (look at the chart to see how much higher that is on the scale), and V80 to bring down the volume. Volume can range from 0 to 127, so 80 is... uhhh we'll say 2/3 volume. Next, on the next line I added "L4" and removed all the 4's. The L4 tells Petit Computer that notes without a length should default to this length. You can use L commands wherever you want, and it'll only affect the notes following it (until another L is reached which changes it). Try inserting L's followed by a length at various places in the song to see how it changes it. Notice that the E2, G2, and C1 don't change even if you mess with the L's, this is because the L only alters notes that don't have a length. Let's jump ahead a little bit:

BGMCLEAR 128 BGMSETD 128, @MYSONG BGMPLAY 128 @MYSONG DATA ":0@11T240O6V80" DATA "L4EDCDEEERDDDREGGREDCDEEEEDDEDC1" DATA ":1@0T240O4V100" DATA "L4EDCDEEERDDDREGGREDCDEEEEDDEDC1" DATA 0

That was quite a jump, so let's look at each change individually. The first change was the line immediately following the @MYSONG, I added a :0 to the beginning. Petit Computer can play 8 streams of music simultaneously, so I'm telling the Vibraphone part to fill in the first stream (which is 0). This is the default, which is why we didn't need it before. However, if you look, it looks like I've duplicated the song. But, it you look at the third data line, you'll see :1, which means that all the data following it should go into the second stream (which is 1). Also notice that the second stream is a different instrument, louder, and in a different octave. If you go ahead and play the song, you'll hear that the first stream plays just like it always did, but the second stream is now the piano (from the @0 on the third data line) and louder (from the V100 on the third data line). This shows that each stream is fully independent: whatever you do on one will not affect the other. Lastly, if you look closely at the note portion, you'll see I put R's instead of 2. R just stands for rest, and it acts like any other note (except that it's silence). Thus, instead of holding the notes for a half note (the 2), I play a quarter note and then a quarter rest (which adds up to the same as a half note).

And that's all I have for the "Basics of MML". I'll post another time with the more advanced stuff, like shaping notes and other effects. Using just the stuff you've hopefully learned by now, you should be able to make some nice melodies. If you want to continue without me, you can look at the first link I posted to see every single MML command available. Just start throwing stuff into the "Mary Had A Little Lamb" song and see what happens!

Part 2: Advanced MML Commands
https://db.tt/DzKtvhXe