# 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. | 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
! | Stop | Immediately terminates compilation of the current song. Nothing after the ! command will even be read by the program (excluding preprocessing directives; see below). | c4 d4 e4 ! c4 c4 c4
? | 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 "remotely" call that loop with this command. Loops may not be nested. | (6)32
* | Loop recall | Calls the most recently used loop. | *8
[[ ]] | Subloop | 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.

### #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.

### #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 '/'.

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

Preprocessing directives (these are read and processed before everything else):

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

### #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.
Note that all "special" commands are case insensitive.

Return to the main page