ref: 673b39642b4b0dd17bd51c45ecb504e4d228111b
dir: /docs/music_commands.md/
# Music Commands Defined in [macros/scripts/audio.asm](https://github.com/pret/pokecrystal/blob/master/macros/scripts/audio.asm) and [audio/engine.asm:MusicCommands](https://github.com/pret/pokecrystal/blob/master/audio/engine.asm). Note: Commands that are intended for the song channels (1-4) can be used by the sound effect channels (5-8) if the sound effect channel exits sound effect mode with the `toggle_sfx` command. ## <code>channel_count <i>n</i></code> Used at the start of each sound header to specify how many channels are used in the sound. `n`: Number of channels [`1`, `4`] ## <code>channel <i>index</i>, <i>address</i></code> Used for each channel in a sound header. `index`: Channel number [`1`, `8`] `address`: Pointer to the sound data ## <code>note <i>pitch</i>, <i>length</i></code> Play a basic note. Used by channels 1-3. `pitch`: Pitch of note (see [constants/audio_constants.asm](https://github.com/pret/pokecrystal/blob/master/constants/audio_constants.asm)) `length`: Length of note in "ticks" [`1`, `16`]. The exact duration of a tick is dependant on the current "speed" (see `note_type` and `drum_speed`) and the current "tempo" (see `tempo`). ## <code>drum_note <i>instrument</i>, <i>length</i></code> Play a predefined drum note. Used by channel 4. `instrument`: Instrument ID [`1`, `12`] (see `toggle_noise`) `length`: Length of note [`1`, `16`] ## <code>rest <i>length</i></code> Basic rest. Used by channels 1-4. `length`: Length of rest [`1`, `16`] ## <code>square_note <i>length</i>, <i>volume</i>, <i>fade</i>, <i>frequency</i></code> Sound effect square note. Used by channels 5-7. `length`: Length of note [`0`, `255`] `volume`: Initial volume [`0`, `15`] `fade`: Volume fade [`-7`, `7`] `frequency`: Note frequency [`0`, `65535`] ## <code>noise_note <i>length</i>, <i>volume</i>, <i>fade</i>, <i>frequency</i></code> Sound effect noise note. Used by channel 8. `length`: Length of note [`0`, `255`] `volume`: Initial volume [`0`, `15`] `fade`: Volume fade [`-7`, `7`] `frequency`: Note frequency [`0`, `255`] ## `$D0`−`$D7`: <code>octave <i>n</i></code> Set the octave for the notes played on the current channel. Used by channels 1-3. `n`: New octave [`1`, `8`] ## `$D8`: <code>note_type <i>length</i>, <i>volume</i>, <i>fade/wave_instrument</i></code> Set persistent note properties. Used by channels 1-3. `length`: Base note length [`1`, `15`] (`12` is often used for 4/4 common time because `12` is factorable by both `3` and `4`. Therefore it works very well for quarter notes, eighth notes, sixteenth notes, and triplets.) `volume`: Initial volume [`0`, `15`] for channels 1-2, [`0`, `3`] for channel 3 (see `volume_envelope`) `fade`: Volume fade [`-7`, `7`] (applies to channels 1-2) `wave_instrument`: Wave instrument ID (applies to channel 3) (see [audio/wave_samples.asm](https://github.com/pret/pokecrystal/blob/master/audio/wave_samples.asm)) ## `$D8`: <code>drum_speed <i>length</i></code> Set persistent note properties. Used by channel 4. `length`: Base note length [`1`, `15`] (use `12` for common time) ## `$D9`: <code>transpose <i>num_octaves</i>, <i>num_pitches</i></code> Transpose all notes played on the current channel. Used by channels 1-3. `num_octaves`: Number of octaves to subtract from each note `num_pitches`: Number of pitches to add to each note ## `$DA`: <code>tempo <i>tempo</i></code> Set the tempo for all playing channels. This should only be used by channel 1. The formula to convert from this tempo to BPM is: BPM = 19200 / `tempo` This formula also works backwards to convert BPM to tempo: `tempo` = 19200 / BPM Only set or change this value when all playing channels are triggering a note or rest at the same time, otherwise desyncs may happen. ## `$DB`: <code>duty_cycle <i>duty_cycle</i></code> Set the square duty (sound) for the current channel. Used by channels 1-2. The only accepted values are 0-3. - 0 = 12.5% waveform: `_______¯` - 1 = 25% waveform: `______¯¯` - 2 = 50% waveform: `____¯¯¯¯` - 3 = 75% waveform: `__¯¯¯¯¯¯` (sounds the same as 25%) To change the sound for channel 3, use `note_type` or `volume_envelope`. ## `$DC`: <code>volume_envelope <i>volume</i>, <i>fade/wave_instrument</i></code> Set the volume envelope for the current channel. Used by channels 1-3. `volume`: Initial volume [`0`, `15`] for channels 1-2, [`0`, `3`] for channel 3 `fade`: Volume fade [`-7`, `7`] (applies to channels 1-2) `wave_instrument`: Wave instrument ID (applies to channel 3) (see [audio/wave_samples.asm](https://github.com/pret/pokecrystal/blob/master/audio/wave_samples.asm)) For channel 3, the only acceped `volume` values are 0-3. - 0 = Mute - 1 = 100% volume - 2 = 50% volume - 3 = 25% volume Note about `fade`: A positive value means a decrease in volume; a negative value means an increase in volume. A small magnitude means a quick change; a large magnitude means a slow change. It is stored in signed magnitude representation, so a value of `8` is the same as (negative) `0`. ## `$DD`: <code>pitch_sweep <i>length</i>, <i>pitch_change</i></code> Set pitch sweep properties. Used by channel 5. `length`: Duration of effect [`0`, `15`] `pitch_change`: Extent of effect [`-7`, `8`] Note: `8` is used in place of `0` ## `$DE`: <code>duty_cycle_pattern <i>a</i>, <i>b</i>, <i>c</i>, <i>d</i></code> Set duty cycle pattern (ie, pulse width modulation). Used by channels 5-6. This cycles the channel through 4 duty cycles, one per frame. Each argument defines a duty cycle, same as the `duty_cycle` command. ## `$DF`: <code>toggle_sfx</code> Toggle between pitch-based songs and frequency-based sound effects. Can be used by any channel. Note: Similar to the pokered command `execute_music`, however `execute_music` can only be used on channels 5-8 and can not be disabled for the duration of the sound once it is enabled. ## `$E0`: <code>pitch_slide <i>duration</i>, <i>octave</i>, <i>pitch</i></code> Bend the pitch of the next note played, and only that note. Used by channel 1. `duration`: Duration of the target note after slide effect `octave`: Target octave `pitch`: Target pitch (see [constants/audio_constants.asm](https://github.com/pret/pokecrystal/blob/master/constants/audio_constants.asm)) ## `$E1`: <code>vibrato <i>delay</i>, <i>extent</i>, <i>rate</i></code> Apply vibrato to current channel. Used by channels 1-3. `delay`: Delay until vibrato effect begins for each note [`0`, `255`] `extent`: Amplitude of vibrato [`0`, `15`] `rate`: Frequency of vibrato [`0`, `15`] ## `$E2`: <code>unknownmusic0xe2 <i>unknown</i></code> ## `$E3`: <code>toggle_noise <i>id</i></code> Set the "drum kit" to be used if it is currently unset. Mute the channel otherwise. Used by channel 4. `id`: Drum kit ID [`0`, `5`] (see [audio/drumkits.asm](https://github.com/pret/pokecrystal/blob/master/audio/drumkits.asm)) Note: The drum kit ID is initially unset at the start of a song. When muting the channel, the `id` argument must not be present. ## `$E4`: <code>force_stereo_panning <i>left_enable</i>, <i>right_enable</i></code> Set left/right stereo output for the current channel, regardless of user's stereo setting. Used by channels 1-4. `left_enable`: `TRUE`/`FALSE` `right_enable`: `TRUE`/`FALSE` ## `$E5`: <code>volume <i>left_volume</i>, <i>right_volume</i></code> Set master volume for left/right speakers. Typically only used by channel 1. `left_volume`: Left speaker volume [`0`, `7`] `right_volume`: Right speaker volume [`0`, `7`] Note: Minimum volume, `0`, is not muted. ## `$E6`: <code>pitch_offset <i>pitch_offset</i></code> Adjust the pitch of all notes on the current channel. Used by channels 1-3. `pitch_offset`: Frequency adjustment of each pitch Note: Similar to the pokered command `toggle_perfect_pitch`. `toggle_perfect_pitch` can be replaced with a combination of `pitch_offset 1` and `pitch_offset 0`. ## `$E7`: <code>unknownmusic0xe7 <i>unknown</i></code> ## `$E8`: <code>unknownmusic0xe8 <i>unknown</i></code> ## `$E9`: <code>tempo_relative <i>value</i></code> ## `$EA`: <code>restart_channel <i>address</i></code> ## `$EB`: <code>new_song <i>id</i></code> ## `$EC`: <code>sfx_priority_on</code> ## `$ED`: <code>sfx_priority_off</code> ## `$EE`: <code>unknownmusic0xee <i>address</i></code> ## `$EF`: <code>stereo_panning <i>left_enable</i>, <i>right_enable</i></code> Set left/right stereo output for the current channel, if the user has stereo mode enabled. Used by channels 1-4. `left_enable`: `TRUE`/`FALSE` `right_enable`: `TRUE`/`FALSE` ## `$F0`: <code>sfx_toggle_noise <i>id</i></code> Set the "drum kit" to be used if it is currently unset. Mute the channel otherwise. Used by channel 8. `id`: Drum kit ID [`0`, `5`] (see [audio/drumkits.asm](https://github.com/pret/pokecrystal/blob/master/audio/drumkits.asm)) Note: The drum kit ID is initially unset at the start of a song. When muting the channel, the `id` argument must not be present. ## `$F1`: <code>music0xf1</code> ## `$F2`: <code>music0xf2</code> ## `$F3`: <code>music0xf3</code> ## `$F4`: <code>music0xf4</code> ## `$F5`: <code>music0xf5</code> ## `$F6`: <code>music0xf6</code> ## `$F7`: <code>music0xf7</code> ## `$F8`: <code>music0xf8</code> ## `$F9`: <code>unknownmusic0xf9</code> ## `$FA`: <code>set_condition <i>condition</i></code> ## `$FB`: <code>sound_jump_if <i>condition</i>, <i>address</i></code> ## `$FC`: <code>sound_jump <i>address</i></code> ## `$FD`: <code>sound_loop <i>count</i>, <i>address</i></code> Execute a branch of sound commands a total of `count` times. `count`: Number of times to execute the loop (including the first execution) (use `0` for an infinite loop) `address`: Pointer to the start of the loop of sound commands ## `$FE`: <code>sound_call <i>address</i></code> Execute a branch of sound commands, returning to the call point once a `sound_ret` command is reached. `address`: Pointer to the branch of sound commands to call ## `$FF`: <code>sound_ret</code> Return to the caller (ie, `sound_call`) if in a sub branch. End the sound otherwise.