Ultimate PPMCK MML Reference

Version: 1.1.3 - 2007/08/14
Links updated by Jikoo - 2010/06/28

Table of Contents

What is PPMCK?

H7's PPMCK is a third expansion of the famous MCK, a program that will convert your Music Markup Language (MML) text files into NES music instructions. You can play the generated file in various NSF players and plugins. With this new expansion, you get access to tons of tracks. The original NES only has a few sound-generating channels. Various third-party chips were included in some games to expand this. PPMCK, to my knowledge, takes advantage of all of them. This allows for rich, complex chiptunes not available in the original MCK.

I had trouble learning MML because the documentation out there was sparse and mostly in other languages. So this effort is to help everyone reference the different commands using MML under h7's PPMCK. After reading this I hope you gain a greater understanding of utilizing all of PPMCK's channels so you can make great chiptunes efficiently!

Download PPMCK software from http://takamatsu.cool.ne.jp/dutycycle/ppmck.html.

Headers

Compiler Instructions

#TITLE <string>

<string>
The title of your tune. It will probably display in most players.
31 characters maximum.
You cannot comment anything out on this line.

#COMPOSER <string>

<string>
The person who composed the actual music. This may also display in players.
Save your musical pseudonym for #PROGRAMER
31 characters maximum.
You cannot comment anything out on this line.

#PROGRAMER <string>

<string>
The person who typed the MML. Will not necessarily display in players.
The typo "PROGRAMER" is actually correct usage.
31 characters maximum.
You cannot comment anything out on this line.

#OCTAVE-REV <num>

<num> (0 or 1)
If set to 0, a ">" will raise the track one octave. "<" will lower one octave.
If set to 1, a "<" will raise the track one octave. ">" will lower one octave.
If this instruction is left out, a 0 is assumed.

#EX-DISKFM

Enables the Famicom Disk System channel F.

#EX-NAMCO106 <num>

Enables Namco106 channels P,Q,R,S,T,U,V, and W.

<num> (1 to 8)
This is the number of channels you want to enable simultaneously. For example, entering 3 will enable P, Q and R only. Entering 8 will enable all of its channels: P through W.

#EX-VRC6

Enables VRC6 channels M, N and O.

#EX-VRC7

Enables VRC7 channels G, H, I, J, K and L.

#EX-MMC5

Enables MMC5 channels a and b.

#EX-FME7

Enables FME7 channels X, Y, and Z.

#BANK-CHANGE <num>

<num> (1 to 14)
The number of the track you'd like to enable bank-switching on. Entering a 1 will bankswitch track A, 2 for B, 3 for C, and so on.

If you're working on a complex piece, you might see this error from NESASM:

NESASM has to organize data into 8 kilobyte banks. If a track takes up more than 8K, a bank will overflow. If you get this error and see a track that has a lot of data, try bankswitching it so the data can continue into a another bank.

#BANK-CHANGE <num1> <num2>

<num1> (0 to 2)
The bank you are switching into.

<num2> (1 to 14)
The track you'd like to switch into the bank specified by <num1>.

This is simply a more detailed usage of #BANK-CHANGE <num>. If you're using the DPCM track E, don't use 0 as DPCM samples are stored in banks 1 and 2.

#EFFECT-INCLUDE

WARNING! OPTIONAL! This will replace the file "effect.h" you allegedly wrote for special instructions in assembly. Usually it is automatically generated for you per ppmck. It defines various macros so don't mess with it unless you know what you are doing.

#NO-BANKSWITCH

Disables bankswitching. When used, you will specify a specific bank using #SETBANK.

#SETBANK <letter>,<num>

<letter> (A to Z, a, or b)
The track you'd like to bankswitch.

<num>
The bank you'd like to use for the track specified with <letter>.

Just calling #SETBANK with no parameters will assume you want all tracks to be on bank 0.

#SETBANK <num1>,<num2>

<num1> (Usually 1 - 3)

The bank you'd like to move.

<num1> (Any number)

The destination bank. Note that if you pick a bank number higher than the previous filesize divided by 8192 plus one, it will pad unused banks with $FF.

Example

#DPCM-RESTSTOP

When used, it will cause the DPCM track E to stop playing instantaneously when using a rest note "r", instead of letting the sample play out until its end or until retriggered by another note.

Macro Definitions

Unless otherwise noted, You can use up to 512 different values in the { } total. Any values placed after a "|" will be looped, but the first set of values will be gone through first. A case where this does not apply is a wavetable definition for the FDS (See @FM<num>).

@<num> = { ~ | ~ }

<num> (0 - 127)
A number you set for your reference when calling throughout your MML.

Valid parameter values for tracks A, B, a, b: (0 - 3)
Valid parameter values for tracks M and N: (0 - 7)

This will define a duty cycle envelope macro.

@@<num> to call.

For tracks A, B, a, and b, you must use integers 0 to 3 in the { }. They correspond to these duty cycles:

Tracks M and N can use 8 different duty cycles. Use integers 0 through 8.

Example

@v<num> = { ~ | ~ }

<num> (0 - 127)
A number you set for your reference when calling throughout your MML.

Valid parameter values: (varies per track/chip)

This will define a volume envelope macro.

@v<num> to call.

Example

@EP<num> = { ~ | ~ }

<num> (0 - 127)
A number you set for your reference when calling throughout your MML. T

Valid parameter values: (-127 - 126)

This will define a pitch envelope macro.

EP<num> to call.
ENOF to turn off.

The pitch macro is useable on most channels except DPCM playback track E. It's a different kind of envelope really, in that each value will begin a note slide and will continue sliding in the same fashion until either the next value is read in the envelope or it is turned back off in the track. Parameters in the negatives will slide down, positives slide up. The higher the parameter value the faster it will slide.

Example

@EN<num> = { ~ | ~ }

<num> (0 - 127)
A number you set for your reference when calling throughout your MML.

This will define an arpeggio envelope macro.

EN<num> to call.
ENOF to turn off.

The arpeggio macro will rapidly progress through the series of notes. You can in fact use this on the Triangle track C as well. Sometimes this is used to simulate a chord. The parameters you put in will step the note up or down in semitones relative to the note called on the track.

Example

@MP<num> = { <param1> <param2> <param3> }

<num> (0 - 63)
A number you set for your reference when calling throughout your MML.

<param1> (0 - 255)
Delay until vibrato starts.

<param2> (1 - 255)
Vibrato speed.

<param3> (0 - 255)
Vibrato depth.

This will define a vibrato macro.

MP<num> to call.
MPOF to turn off.

You can modulate the pitch with a sort of sine wave with the vibrato macro. The vibrato macro is useable on most channels except DPCM track E. <param1> will dictate the time to wait after the note attack to start the vibrato. <param2> dictates how quickly to vibrate the pitch. Finally, <param3> dictates how far from the root note to swing.

Example

@DPCM<num> = { "<str>", <param1>, <param2>, <param3>, <param4> }

<num> (0 - 63)
The note [semitone] to map the sample to in the E track. Starts with note c0. Because it maps to semitones, it's recommended to use values that correspond to the "white keys" of a keyboard (e.g. DPCM0, DPCM2, DPCM4 for C0, D0 and E0 respectively, and so on). It's easier to type and read.

<str>
The file path to the DMC sample file relative to the location of ppmck_e.exe.

<param1> (0 - 15)
Changes the pitch of the sample. 15 is normal. 0 is slow/low. Steps are in semitones.

<param2> (0 - 4081)
OPTIONAL. The playback size of the sample. Specifying 0 or leaving this parameter out will make playback size equal filesize, which is ok. If the sample filesize is less than the size you specify here, the sample will be padded to it at playback.

<param3> (0 - 15)
OPTIONAL. To use, you must specify param1 and 2 also. This param3 is the Initial Delta Counter value, which is written to $4011 on note trigger. $ff is recommended. If you put in $00, you may get clicks. Using a non-zero value may change the volume of Triangle track C and and Noise Track D.

<param4> (0 - 2)
OPTIONAL. To use, you must specify param1, 2 and 3 also. DMC Playback mode.
0 = normal playback mode.
1 = looped playback mode.
2 = normal playback mode with IRQ (not recommended).

Defines the path to and paramaters for a delta pulse modulation channel (DPCM) sample to be played on track E. The DPCM channel will play back 1-bit samples. Useful for drums and other short sound effects. There is no volume control, so adjust your volumes accordingly before conversion to the DMC format.

Example

@FM<num> = { ~ }

<num> (0 - 127)
A number you set for your reference when calling throughout your MML.

Valid parameter values: (0 - 63)

Must use 64 two-digit parameters.

This will define a wavetable for the FDS track F. A 0 corresponds to the lowest sample value, 63 the highest. You can create some cool wave patterns with 64 samples.

@@<num> to change to this instrument on track F. Be careful not to get confused. This is the same way to change a duty cycle on a square wave channel. You can use a utility like MUMEM to help you make a wave visually, then copy a list of sample values to the clipboard. Check out these example definitions.

Example FDS Waveforms

@N<num> = { <param1>, ~ }

<num> (0 - 127)
A number you set for your reference when calling throughout your MML.

<param1> (0 - 31*)
The buffer number for the N106 chip. *The maximum buffer number varies with the number of parameters (samples) you are specifying. Short samples (few parameters specified) can use more buffers. See below.

Valid parameter values: (00 - 15) or you can use hex ($00 - $0F)

You can specify 4 - 32 samples, in increments of 4. You have to use certain buffers (<param1>) with certain numbers of specified samples. Check this chart:

Example N106 Instruments

@OP0 = { ~ }

Valid parameter values: ($00 - $FF)

Must use 8 parameters.
e.g. { $00 $00 $00 $00 $00 $00 $00 $00 }

This will define the custom user instrument for the VRC7.

@@<num> to call up instrument for the track. Special procedures are necessary to call up the custom user-defined instrument.
@@1 - @@15 are built-in instruments listed below.
@@17 - @@31 are the same built-in instruments as @@1 - @@15.

Keep in mind that calling @@0 in the actual track is reserved: it's a shortcut for the last VRC7 instrument you called within the track. If you want to call on your user-defined VRC7 instrument, first use @@64. To call your second user-defined instrument (OP1) then use @@65 and so on. Calling a different instrument will override the last called. You can use the @@0 shortcut on other VRC7 tracks as long as you've selected one of the instruments as stated above.

The eight parameters you enter correspond to the VRC7's 8 registers for controlling its FM synthesis. You can read more about this in Kevin Horton's VRC7 Documentation (See references).

Descriptions of VRC7 Built-in Instruments

Example

@MW<num> = { ~ }

<num> (0 - 7)
A number you set for your reference when calling throughout your MML.

Valid parameter values: (0 - 7)

You must use 32 parameters.

This is a 32 parameter wavetable-like envelope for modulating FDS track F's pitch. It's similar to the @EP macro, but the values don't correspond semitone-for-semitone. Check out this chart which shows how the values change the pitch per frame.

You will not "call" this effect with @MW or MW. This definition merely sets up the actual effect, @MH, which needs its own definition for delay, speed and depth. @MW is an envelope for modulating the FDS pitch and @MH is a macro for modulating the amount that @MW envelope modulates the pitch. It's like taking a xerox of a xerox. Crazy stuff happens.

Example

@MH<num> = { <param1>, <param2>, <param3>, <param4> }

<num> (0 - 15)
A number you set for your reference when calling throughout your MML. Needs to have a corresponding @MW<num> definition to put into action.

<param1> (0 - 255)
Delay until corresponding @MW<num> pitch envelope kicks in.

<param2> (0 - 4095)
Speed at which corresponding @MW<num> pitch envelop progresses.

<param3> (0 - 63)
Depth at which corresponding @MW<num> pitch envelop swings.
0 = 0% of any possible swing defined in the @MW envelop,
63 = 100% of any possible swing defined in the @MW envelop.

<param4> (0 - 7)
Chooses which @MW<num> envelop definition to use for the effect. To use @MW0, which you defined beforehand, you just put a 0 here.

This will define a "vibrato" modulator for the chosen @MW envelope you want to use (param4). Once you have both an @MW<num> and this @MH<num> defined, you're ready to apply it to the FDS F track.

MH<num> to call.
MHOF to turn off the effect. You can reenable with the same one or another if you like, of course.

Example

Commands

Commenting Methods

Group Commenting: /* ~ */

This will treat everything in between these as commenting and will not be compilied with the assembler.

Line Commenting: ;

Anything after a ";" in a line will be commented out.

Example

Musical Notation

Entering Notes: <note><sharp/flat><len>

<note> (c, d, e, f, g, a or b)
The note of the scale you'd like to play.

<sharp/flat> (+ or -)
OPTIONAL. Insert a "+" here to raise the note one semitone. Insert a "-" to lower one. This is essentially "sharp" and "flat".

<len> (1 - 99999999999)
The length of the note you'd like to play. This number is the length of a measure divided by this number. For example, a c4 will play a quarter note C.

If no length is given, a the length you specified with the l<len> command is assumed.

Example

Rests: r<len>

<len> (1 - 99999999999)
The length of the note you'd like to rest. This number is the length of a measure divided by this number. For example, a c4 will play a quarter note C.

If no length is given, a the length you specified with the l<len> command is assumed.

Example

Tempo and Note Length

Tempo: t<num>

<num> (1 - 255)
The tempo of the track, not the entire song.

You'll use this after a track header to set its tempo. It won't set all tracks simulataneously unless you type every track letter you're using before this command. Strange? Check the example.

120 bpm is assumed if you don't specify a tempo.

Example

Tempo: @t<len>,<num>

<len> (1 - 99999999999)
Default note length per measure (see entering notes).

<num> (1 - 99999999999)
Number of frames per measure.

This is a more specific tempo assignment. It follows the following formula:
14400/<num>/<len>

It's essentially <len> notes every <num> frames.

Example

Default Note Length: l<len>

<len> (1 - 99999999999)
The default note length for the track you specify. Same rules as entering a note.

Leaving this out will assume you want quarter notes.

Example

Quantize Note: q<num1>, <num2>

<num1> (1 - 8)
Divides lengths of entered notes by this number per the formula listed below. Won't affect attack times.

<num2> (1 - 8)
OPTIONAL. Adds to divisor per the formula below. If not specified, 0 assumed.

<num1> / (8 + <num2>) = Quantized Note Length

This will quantize the length of notes played, but not when they are played.

q4 is assumed if you don't specify any quantization for a track.

Example

Quantize Note: @q<num>

<num> (0 - 65535)
Number of frames to cut off of each note.

Note tie: &

Ties two of the same notes together.

Example

Note tie: ^

Ties two of the same notes together, but you only need to tie lengths, note completely written out notes. Recommended over &.

Example

Octaves and More Notation

Octave: o<num>

<num> (varies per track/chip)
Sets default octave for a track.

Example

Octave raise: >

This will raise the notes following one octave, unless you messed with #OCTAVE-REV. You can use more than one in a row.

Example

Octave lower: <

This will lower the notes following one octave, unless you messed with #OCTAVE-REV. You can use more than one in a row.

Example

Direct Notation: n<num>,n<len>

<num> (0 - 99)
A specific note number, unlike entering letters you're entering in semitones from c0.

<len> (0 - 99999999999)
The same note length you'd use with regular notation

A different way to enter notes instead of letters, per the following chart:

Remember each tracks octave restrictions.

Example

Super Direct Notation: @n<num>,<len>

<num> (8 - 2034) ($0008 - $07f2)
Value to write to the frequency register directly.

<len> (0 - 99999999999)
The same note length you'd use with regular notation

This will let you choose a note by writing directly to the frequency register. Why you'd want to do this I don't know. You could get some pretty strange pitches by tinkering. But here is a chart showing you which notes correspond roughly. The higher the <num>, the lower the pitch. You can get higher frequencies. For example, to get C3, just divide C2's value $06AE by two. $06AE/2 = $0357.

The FDS behaves differently. As <num> increases, pitch increases. To get C3, you'd just divide C2's value by two: $0983/2 = $04C1 = C3.

The N106 doesn't work with this method.

Transpose: K<num>

<num> (-99 - 99)
Transposes the notes that follow <num> semitones relative to the notes entered (remember your default octave).

Loops and Other Commands

Set static volume: v<num>

<num> (Varies per track/chip)
Value that sets the track volume, overriding any volume envelopes you have. You can call back any envelope you want, of course. Remember each track's volume restrictions:

Example

Increase Volume: v+<num>

<num> (Varies per track/chip)
The number of levels you want to increase the volume by. Keep in mind tracks' volume minimum and maximum (see @v or v commands).

You must specify a static volume with v<num> before using this.

Example

Decrease Volume: v-<num>

<num> (Varies per track/chip)
The number of levels you want to decrease the volume by. Keep in mind tracks' volume minimum and maximum (see @v or v commands).

You must specify a static volume with v<num> before using this.

Example

FDS Hardware Envelope: EH<fade>,<num>

<fade> (0 or 1)
0 fades FDS Track F's volume downward.
1 fades it upward.

<fade> (0 - 63)
The speed at which the FDS Hardware envelope changes.

Doesn't appear to be retriggered with each note. It'll just keep looping through, so call and turn off carefully.

EH<fade>,<num> calls,
EHOF turns off.

FDS @v Retrigger: @vr<num>

<num> (0 or 1)
The envelope to retrigger at the time quantization happens.

This will launch @v<num> volume envelope when the note is cut off by the quantization you specify. Instead of cutting the note off like quantization should, it will instead launch @v<num> at that moment. By choosing a different volume envelope here, you can in effect have two volume envelopes per note.

You can choose a new "first" envelope with another @v<num> command. Calling a static volume using v<num> will deactivate the effect until you call it again.

Example

Time Shift: k<len>

<len> (0 - 99999999999)
How much you want to shift the following notes forward in time, in the same terms as notes. Leaving this out will assume you want to use your l<len> value.

This is a way to create echoes in your songs using two tracks, where one is using a lower volume. Check out this example for a nice bounce echo effect commonly used in many chiptunes.

You might want to use a rest command, because this command seems to be permanent. Consider using rests and thinking how much a track is ahead if you want to adjust the echo back to unison.

Using this effect andrests can shift your echo effect.

Example

Loop Position: L

This will set the loop position in the song. In some cases, tracks may not syncronize at certain tempos because of minute differences in track length. Bracket loops appear not to have this problem.

Repeat Loop: [ ~ ]<num>

<num>
Will loop the notation inside the [ ] <num> times. A space saver. You can nest loops within loops.

Multi Repeat Loop: |: ~ \ ~ \ ~ ... :|<num>

<num>
Will loop the notation before the first\ <num> times, then loops the next section <num> times and so on. A real space saver. You can nest loops within loops.

Example

Self Delay: SD<num>

<num> (1 - ?)
The number of delays.

This is some self-delay effect on a track. I've never gotten it to sound like I want, but it is there. To those trying to achieve this effect it is a space saver I suppose.

SD<num> calls.
SDOF turns off.

Example

Quick Track Table

Multisong NSF Tutorial

With PPMCK release 9, multisong nsf creation is built-in! Which means this tutorial was obsolete! Ho ho! All it takes is a change in command-line arguments. Needless to say, this tutorial will be short.

Basically, when calling ppmckc, just use the -u argument for multisong nsf creation, like so.

This is all you need to change. If you want 5 songs, go right on ahead and put 5 in. If it blows up, it's not my fault! Then, as usual, call nesasm to create the rom. The headers ppmckc produces will contain the necessary data. Just make sure you keep your paths straight.

That's it! Whew!

TODO

• Add complete beginner's tutorial showing how to use each track, including DPCM conversion tips. [SORT OF MAYBE IN PROGRESS - 2007/08/13]

Version History

• 1.1.3 (2007/08/14)
  • Revised VRC7 instrument calls and advice for Loop Position. Thanks again to ~J-@D!~ from 2a03.org.
• 1.1.2 (2006/03/23)
  • Fixed @DPCM definition, parameter 3 should be $ff to prevent $4011 clicks in the sample playback channel. Thanks to ~J-@D!~ from 2a03.org.
• 1.1.1 (2006/03/17)
  • Fixed comment about C channel not being able to use arpeggio. It in fact can. Thanks to Chris Knight for that.
• 1.1.0 (2006/03/09)
  • Added the Multisong NSF Tutorial!
• 1.0.1 (2006/03/05)
  • Changed all tabluar data into table form for clarity. It was getting confused as code examples.
• 1.0.0 (2006/03/05)
  • Initial Release

Special Thanks

• H7, for his wonderful expansion, PPMCK.
• 2A03.org members for their encouragement and support.
• Previous researchers and enthusiasts, whose work and contribution to the scene were vital in development of these tutorials and inspired me to begin my work in MML.

References

1. Woolyss MML Resource
2. Wikipedia Music Macro Language
3. MCK/MML Beginners Guide - nullsleep
4. VRCVI Chip Info - Kevin Horton
5. VRCVII Chip Info - Kevin Horton
6. Namco 106 Mapper Information - goroh
7. 2A03 Sound Channel Hardware Documentation - Brad Taylor
8. 2A03 Technical Reference - Brad Taylor
9. NES Music Format Spec - Kevin Horton
10. 20 Levels of NSF Ripping - gil galad