Command Reference



Standard commands:

The following is a list of commands that are available in music. With only a few noted exceptions, they may all be used anywhere within a song. Also, unless otherwise noted, valid values for all commands are from 0 to 255.
Command Purpose Discription Example
# Channel Which channel all the following commands will be written to. Valid values are 0 to 7. Note that channels 6 and 7 are shared by sound effects, and may cut out temporarily when a sound effect plays on that channel. #0
c, d, e, f, g, a, b Note Use + or - after the letter to specify a sharp or flat, respectively. A number should appear after the note; this number should denote the note's duration. 1 is a whole note, 2 is a half note, 4 a quarter note, 8 an eighth note, etc. There are ways to specify notes of other durations; see below. If no duration is specified, then the duration will be the value specified by the l command c16 g+8 a-1
r Rest Similar to a normal note, the number after it defines its length. r16 r8 r1
^ Tie Attach this to a note or rest to extend its length. The number after it defines its length. c4^8 r1^2
h Tune Changes the value of all subsequent notes by the value specified. All integers, even negative ones, are valid. Note that this only affects how AddmusicK interprets the notes. h4 h-3
o Octave Specifies what octave the following notes should be read as. Valid values are 1 to 6. Note that this command only affects how AddmusicK interprets the notes; the SPC program does not have an "octave" command. o3 c16 o2 c16
< Lower octave Lowers the current octave by one. o3 c16 > c16
> Raise octave Rasies the current octave by one. o3 c16 < c16
l Default length Specifies the length of notes, rests, or ties whose lengths are not specified. The value's duration is measured in the same manner as that of a note (e.g. 1 is a whole note, 2 is a half note, etc.). This command does not decrease the song's size. It exists solely to make the song more readable. l8
{ } Triplet Any notes surrounded by curly braces will be treated as triplets (i.e. their durations will be multiplied by 2/3). {c4 d4 c4}
@ Instrument Specify the instrument to play. Valid values are 0 - 18, 21-29, and 30+. 30 and above are "custom" instruments, which are described below. @28
v Volume Sets the volume for the currently playing channel. Valid values are 0 to 255. v240
w Global volume Sets the volume for the entire song. Valid values are 0 to 255. w200
y Pan Set the pan for the current channel. Valid values are from 0 to 20; is all the way to the right, and 20 is all the way to the left. 10 is centered. If two extra arguments are specified, then a 1 will indicate that that speaker (left,right) should have surround sound enabled. y10 y10,0,1
q Quantization This command is specified in hex. The first digit specifies how long of a delay there is between each note. Valid values are from 0 to 7, with 7 having the smallest delay. The second digit controls the volume. Valid values are from 0 to F, with F being the loudest. The volume portion of this command is compatible with the v command. q7F q70
t Tempo How quickly the song should play. To convert from BPM to this, multiply the BPM by 0.4. Please be aware that the higher the tempo is, the more likely your song is to experience slowdown. In general, tempos below t60 should be safe. Keep in mind that if t60 seems too slow, you can halve your note lengths to simulate doubling the tempo. t40
p Vibrato Pulsate the pitch over a period of time. There may be either two or three arguments to this command, separated by commas. If there are two arguments, then the first is the rate (speed) and the second is the extent (amplitude). If there are three values, then the first is the duration of the delay before the vibrato starts, the second is the rate, and the third is the extent. The delay and rate are measured in the same manner as notes (1 is the length of a whole note, etc.) p24,12,8 p12,8
n Noise Starts playing noise on the current channel instead of using the current instrument's sample. ADSR and such are preserved, and the effect can be cancelled by using an instrument. The value must be a hex value between 0 and 1F. n5 n1F
& Pitch slide Slides the pitch between the note that came before this command and the note that comes after it. While this is the easiest way to do this, the $DD hex command offers more flexibility. c4&d4
? Misc. Causes this song to not loop (useful for, for example, victory themes). ?
/ Intro This will mark the intro to this song. An intro only plays once; when a song "ends" it will jump back to the position specified by this intro marker (if this command is not specified, then it simply jumps back to the song's start). /
("", $) Sample load Loads the sample specified in quotes, with a tuning value specified in hex after the $. The tuning value multiplies the pitch by this value (so 1 does not alter the pitch, 2 doubles it, etc). While the use of custom instruments is generally preferred over raw sample loading for space saving concerns, this command may still be useful. ("Sample.brr", $04)
[] Loop Repeats whatever is contained within the brackets by the value spcified. Extremely useful for saving space. Loops may not be nested. [c8 d8]16
()[] Label loop Exactly the same as the normal loop command, but assigns a value to it as specified by the parentheses. See the next command for more information. Loops may not be nested. (6)[c8 d8]16
() Label loop call Calls the specified loop. Define a loop with the previous command, and then call that loop with this command. Loops may not be nested. (6)32
* Loop recall Calls the most recently used loop. *8
(!)[] Remote code definition Defines a set of hex commands or other non-note non-loop commands that you can set to be called automatically at certain "events", such as whenever a note starts or some number of ticks before a note ends. These function very similarly to label loops (in fact, you can call their data from a normal label loop), but they have two major differences: They cannot contain note data in any shape or form (they also cannot be repeated, but that's only useful for notes anyway), and they must be defined before any channel data. This means they won't actually take effect until you call them with the next command.

I recommend you combine this with the replacement command ("=", see below) to keep your code readable if you have multiple remote codes. This way you can give each remote code a name.

Note: Command (!0) (possibly others, !1 and !2 are fine) is broken. Do not use. 		(!6)[$FA $01 $55]
(!7)[$FA $01 $00 v250]
(!) Remote code call This command will set up an event with the data contained in the remote code you specify. You must also specify the "trigger" for this code, or the event type (see below). Finally, certain events require an argument. For this you may either specify a hex value or a note value (e.g. 2 would be a half note). Note that you can only have one remote code running at any given time. There are only two exceptions: You may have a "run code when a note is keyed on" remote code at any time, and the "run once right now" event type may also be run at any time. You can use this command inside loops.

Available event types:

(!n, 0):

Disable the remote commands for this channel, including the "key on" event type if it's also running. Note that whatever code is used for this event is not run, so any code can be used.

(!n, -1):

Key on. This will allow you to undo the changes done by other events. It can be run alongside other event types.

(!n, 1, x):

x ticks after key on. Ties and rests won't trigger this event. If the time to wait is longer than the current note, the code will never be triggered.

(!n, 2, x):

x ticks before key off. Relative to the qXX command. This will only work on notes shorter than 80 ticks (a little more than a half note) due to the internal method in which the NSPC engine handles ties and such, so anything beyond that you'll have to use events 3 or 4. If the time to wait is longer than the current note, the code will never be triggered.

(!n, 3):

Key off. This is also relative to the qXX command. Unlike 2, this cancels the note cut event, so the note keeps playing. The note is absolutely keyed off, however, before the next note begins (this does not trigger this event).

(!n, 4):

Run once, right now. This is also compatible with all other events, and because it can be used within loops, it effectively allows you to have a third layer of nested loops (see [[ ]] for the second layer).

(!n, 5):

Reserved. Do not use this event type.
(!6, 1, 4) (!7, -1)
[[ ]] Superloop A special loop variation. Normal loops may go inside of this and this may be placed in normal loops. You may not assign a value to this kind of a loop with parantheses, nor may you call it with the * command. [[c8 d8]]32
$ Hex Inserts a hex command. Hex commands may do many other things not included in this list of "normal" commands, such as fade the volume over time. See here for a list of all available hex commands. $DA $01
"=" Replacement Replaces what is on the right side of the equals sign with what is on the left side. The result can be used almost anywhere (so you could, for example, use this to give label loops names instead of just numbers, or to assign custom instruments names, etc.). Note that only replacement candidates found after this command are actually replaced. In addition, this command is greedy; i.e. if you create a "B" command and a "BB" command, "BB" in your music file will not be treated as two separate "B" commands, but as one "BB" command. This may seem obvious, but be careful just in case. Also note that this command can be recursive and its relations transitive; if you say that "AB=BC" and "BC=CD" then "AB" will be converted to "CD". "cymbal=@38"
"drumloop=6"


Special commands



#samples

This command will define which samples this song uses. Syntax is the following:

#samples
{
        #samplegroup
        "sample1.brr"
        "sample2.brr"
        "sample3.brr"
}

Where "#samplegroup" is the name of the sample group you want to use (typically #default or #optimized), and "sample1.brr" (etc.) are the file paths of the samples to use. You may use any number of samples, or none at all. If this command is not used, then the song is assumed to use the #default sample group.

See also #path.

#instruments

This command will define any custom instruments to use. Syntax is the following:

#instruments
{
        "sample1.brr" $aa $bb $cc $dd $ee
        "sample2.brr" $aa $bb $cc $dd $ee
        @0 $aa $bb $cc $dd $ee
        n1F $aa $bb $cc $dd $ee
}
Where "sample1.brr" (etc.) is the name of the sample to use for this instrument (it must match up with a sample loaded by the #samples command). Alternatively, it may be @ followed by a non-custom instrument, which will load the sample that that instrument uses, or n and a hex value from 0 - 1F, which will play noise with the specified clock (pitch).
aa is the first ADSR value (to use ADSR, make sure that it is >= $80. Otherwise GAIN is used.).
bb is the second ADSR value.
cc is the GAIN value.
dd is the tuning multiplier.
ee is the tuning submultiplier (so dd and ee together are something like "dd.ee"; ee is the decimal/fractional portion).
All of those values are in hex.

If you're using custom samples for your instruments, then this command must always be preceded by the #samples command.

#pad

Specifies a minimumm size for this song. This isn't so much useful for porters, but more for ASMers. It will guarantee that a song is at least the specified size. For example, #pad 2F0

#spc, #author, #game, #comment, #title, #length

This command will let you define the tags that will be inserted into each song's automatically generated SPC. The command, when used, looks like this: 
#spc
{
	#author "Author's name"
	#game	"Game's name"
	#comment "A comment"
	#title	"Song's name"
}

The fields may be in any order and any may be ommitted. There is also the optional #length field; if used, it defines how long this song's generated SPC file will play for. Normally the program will attempt to figure this out if #length is ommitted, but it will fail if the tempo changes during the song's run. When this is the case, use #length "2:00" (or however long your song is) to overcome this.

#path

This will specify the default path in which to look for custom samples for this song. For example, this:


#samples
{
        #default
        "SMB1 Overworld/Sample1.brr"
        "SMB2 Overworld/Sample2.brr"
}


Is equivalent to this:


#path "SMB1 Overworld"

#samples
{
        #default
        "Sample1.brr"
        "Sample2.brr"
}


This applies to anywhere else a sample name is used as well (such as the #instruments command). You should not include the final '/'.

#halvetempo

This will halve a song's tempo, notes, and all hex commands that use a "duration" field. Use this if your song is suffering from slowdown, which is mostly a result of using high tempos (higher than t60 or so usually).

#option

Handles various miscellaneous song options. You must put these at the top of your song file before any channel data.
Parameter Discription
tempoimmunity This command will disable the "tempo hike" effect caused by the timer going below 100 seconds. Use this, for example, in the death theme, game over theme, level clear theme, etc.
dividetempo Same as #halvetempo, but allows you to specify a value that's not a power of 2.
smwvtable Forces the song to use SMW's velocity table instead of the default N-SPC one.
noloop Lets AddmusicK know that this song should only play once and not loop one it is finished.

Usage is simple. Example: #option noloop. Or #option dividetempo 3. Etc. Remember, once again, that these must come before any channel data!

#define, #undef, #ifdef, #ifndef, #if, #endif, #error

Preprocessing directives (these are read and processed before everything else). Note when using these, they must be the first and only thing on their line. This is to make sure that all preprocessor functions are as agnostic to the music format as possible.
Command Purpose Discription Example
#define Definition Defines a constant as existing, and optionally gives it a value. #define SAMPLED
#define VERSION 5
#undef Un-definition Defines a constant as not existing. #undef SAMPLED
#ifdef Test Anything from this point to the next #endif will only be compiled if the specified value has been defined by #define. #ifdef SAMPLED
#ifndef Test Anything from this point to the next #endif will only be compiled if the specified value has not been defined by #define. #ifndef SAMPLED
#if Test Tests the relationship between the specified constant and an integer. Valid relations are ==, <, >, <=, >=, and !=. If the relationship holds true, then everything from this point to the next #endif is compiled. #if VERSION >= 4
#endif End Compliment to the other tests. Ends their range of effect. #endif
#error Error checking Throws an error and stops compilation. Obviously, you'll want to use this with #ifs, #ifdefs, etc. #endif


#amk

Specifies which AddmusicK "song parser" this song was designed for. It is inserted automatically by AddmusicK to the bottom of every song if that song does not already contain it or an alternative (such as #am4 or #amm). The equals sign should be followed by an integer value. The "correct" value to use will only change if future features are added AddmusicK that make older song files incompatible with new ones, so that these older files may be identified and parsed correctly. Because this command is inserted automatically, you should not need to worry about it. As with the preprocessor directives, this should be the first and only thing on any line it's on. Finally, #am4 and #amm override #amk in all circumstances, with no warnings, even if they come before #amk.


Note that all "special" commands are case insensitive.

Return to the main page