Difference between revisions of "Music sequence"

From SM64Decomp Wiki
Jump to navigation Jump to search
(add formular for calculating tick length)
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
dasdasdasdMusic in Super Mario 64 is controlled by sequence files. They are in .m64 format, which is similar to [[wikipedia:MIDI|MIDI]]. A sequence file has a sequence script, that can spawn channels, which have channel scripts, that can spawn layers (also known as tracks), which have layer scripts that can play notes. Each note is performed using an instrument from a sound bank. A sequence file can use multiple banks. The mapping from sequences to sound banks is described in '''sound/sequences.json'''. Channels can switch between banks using a command. However, in practice most sequences limit themselves to a single sound bank. The main exception is sequence 0, which is responsible for sound effects.
 
dasdasdasdMusic in Super Mario 64 is controlled by sequence files. They are in .m64 format, which is similar to [[wikipedia:MIDI|MIDI]]. A sequence file has a sequence script, that can spawn channels, which have channel scripts, that can spawn layers (also known as tracks), which have layer scripts that can play notes. Each note is performed using an instrument from a sound bank. A sequence file can use multiple banks. The mapping from sequences to sound banks is described in '''sound/sequences.json'''. Channels can switch between banks using a command. However, in practice most sequences limit themselves to a single sound bank. The main exception is sequence 0, which is responsible for sound effects.
  
−
A sequence may play up to 16 channels with up to 4 layers per channel.
+
A sequence may play up to 16 channels with up to 4 layers per channel. Several notes can be played simultaneously on a single layer.
 +
 
 +
A sequence is played as long as the sequence script is not ended. A channel (including layers) is active as long as the channel script is not ended.
 +
 
 +
== Note properties ==
 +
A note can be played by the commands <code>layer_note0</code>, <code>layer_note1</code> and <code>layer_note2</code> (only valid if <code>chan_largenoteson</code> has been called on the layer's channel) or <code>layer_smallnote0</code>, <code>layer_smallnote1</code> and <code>layer_smallnote2</code> (only valid if <code>chan_largenotesoff</code> has been called on the layer's channel; default state). A note is defined by the following properties:
 +
 
 +
=== Pitch ===
 +
Also known as '''note'''. The pitch defines the frequency in which the instrument is to be played. See list of notes below for available pitches.
 +
 
 +
=== Play percentage ===
 +
Also known as '''timestamp'''. This defines the note value, such as half or quarter note. This also implies a layer delay of the same amount. See note values below for possible values.
 +
 
 +
=== Velocity ===
 +
This is the volume of the note.
 +
 
 +
=== Duration ===
 +
Also known as '''gate''' or '''gate time'''. A value of 0 menas the note is heard during the whole percentage, 128 is half of the percentage and 255 almost none.
 +
 
 +
== List of notes ==
 +
This is a list of notes as used by the ''layer_note#'' and ''layer_smallnote#'' commands.
 +
{| class="wikitable"
 +
!Octave
 +
!Note
 +
!Decimal
 +
!Hex (note0)
 +
!Hex (note1)
 +
!Hex (note2)
 +
|-
 +
! rowspan="3" |0
 +
!A
 +
|0
 +
|0x00
 +
|0x40
 +
|0x80
 +
|-
 +
!A♯/B♭
 +
|1
 +
|0x01
 +
|0x41
 +
|0x81
 +
|-
 +
!B
 +
|2
 +
|0x02
 +
|0x42
 +
|0x82
 +
|-
 +
! rowspan="12" |1
 +
!C
 +
|3
 +
|0x03
 +
|0x43
 +
|0x83
 +
|-
 +
!C♯/D♭
 +
|4
 +
|0x04
 +
|0x44
 +
|0x84
 +
|-
 +
!D
 +
|5
 +
|0x05
 +
|0x45
 +
|0x85
 +
|-
 +
!D♯/E♭
 +
|6
 +
|0x06
 +
|0x46
 +
|0x86
 +
|-
 +
!E
 +
|7
 +
|0x07
 +
|0x47
 +
|0x87
 +
|-
 +
!F
 +
|8
 +
|0x08
 +
|0x48
 +
|0x88
 +
|-
 +
!F♯/G♭
 +
|9
 +
|0x09
 +
|0x49
 +
|0x89
 +
|-
 +
!G
 +
|10
 +
|0x0A
 +
|0x4A
 +
|0x8A
 +
|-
 +
!G♯/A♭
 +
|11
 +
|0x0B
 +
|0x4B
 +
|0x8B
 +
|-
 +
!A
 +
|12
 +
|0x0C
 +
|0x4C
 +
|0x8C
 +
|-
 +
!A♯/B♭
 +
|13
 +
|0x0D
 +
|0x4D
 +
|0x8D
 +
|-
 +
!B
 +
|14
 +
|0x0E
 +
|0x4E
 +
|0x8E
 +
|-
 +
! rowspan="12" |2
 +
!C
 +
|15
 +
|0x0F
 +
|0x4F
 +
|0x8F
 +
|-
 +
!C♯/D♭
 +
|16
 +
|0x10
 +
|0x50
 +
|0x90
 +
|-
 +
!D
 +
|17
 +
|0x11
 +
|0x51
 +
|0x91
 +
|-
 +
!D♯/E♭
 +
|18
 +
|0x12
 +
|0x52
 +
|0x92
 +
|-
 +
!E
 +
|19
 +
|0x13
 +
|0x53
 +
|0x93
 +
|-
 +
!F
 +
|20
 +
|0x14
 +
|0x54
 +
|0x94
 +
|-
 +
!F♯/G♭
 +
|21
 +
|0x15
 +
|0x55
 +
|0x95
 +
|-
 +
!G
 +
|22
 +
|0x16
 +
|0x56
 +
|0x96
 +
|-
 +
!G♯/A♭
 +
|23
 +
|0x17
 +
|0x57
 +
|0x97
 +
|-
 +
!A
 +
|24
 +
|0x18
 +
|0x58
 +
|0x98
 +
|-
 +
!A♯/B♭
 +
|25
 +
|0x19
 +
|0x59
 +
|0x99
 +
|-
 +
!B
 +
|26
 +
|0x1A
 +
|0x5A
 +
|0x9A
 +
|-
 +
! rowspan="12" |3
 +
!C
 +
|27
 +
|0x1B
 +
|0x5B
 +
|0x9B
 +
|-
 +
!C♯/D♭
 +
|28
 +
|0x1C
 +
|0x5C
 +
|0x9C
 +
|-
 +
!D
 +
|29
 +
|0x1D
 +
|0x5D
 +
|0x9D
 +
|-
 +
!D♯/E♭
 +
|30
 +
|0x1E
 +
|0x5E
 +
|0x9E
 +
|-
 +
!E
 +
|31
 +
|0x1F
 +
|0x5F
 +
|0x9F
 +
|-
 +
!F
 +
|32
 +
|0x20
 +
|0x60
 +
|0xA0
 +
|-
 +
!F♯/G♭
 +
|33
 +
|0x21
 +
|0x61
 +
|0xA1
 +
|-
 +
!G
 +
|34
 +
|0x22
 +
|0x62
 +
|0xA2
 +
|-
 +
!G♯/A♭
 +
|35
 +
|0x23
 +
|0x63
 +
|0xA3
 +
|-
 +
!A
 +
|36
 +
|0x24
 +
|0x64
 +
|0xA4
 +
|-
 +
!A♯/B♭
 +
|37
 +
|0x25
 +
|0x65
 +
|0xA5
 +
|-
 +
!B
 +
|38
 +
|0x26
 +
|0x66
 +
|0xA6
 +
|-
 +
! rowspan="12" |4
 +
!C
 +
|39
 +
|0x27
 +
|0x67
 +
|0xA7
 +
|-
 +
!C♯/D♭
 +
|40
 +
|0x28
 +
|0x68
 +
|0xA8
 +
|-
 +
!D
 +
|41
 +
|0x29
 +
|0x69
 +
|0xA9
 +
|-
 +
!D♯/E♭
 +
|42
 +
|0x2A
 +
|0x6A
 +
|0xAA
 +
|-
 +
!E
 +
|43
 +
|0x2B
 +
|0x6B
 +
|0xAB
 +
|-
 +
!F
 +
|44
 +
|0x2C
 +
|0x6C
 +
|0xAC
 +
|-
 +
!F♯/G♭
 +
|45
 +
|0x2D
 +
|0x6D
 +
|0xAD
 +
|-
 +
!G
 +
|46
 +
|0x2E
 +
|0x6E
 +
|0xAE
 +
|-
 +
!G♯/A♭
 +
|47
 +
|0x2F
 +
|0x6F
 +
|0xAF
 +
|-
 +
!A
 +
|48
 +
|0x30
 +
|0x70
 +
|0xB0
 +
|-
 +
!A♯/B♭
 +
|49
 +
|0x31
 +
|0x71
 +
|0xB1
 +
|-
 +
!B
 +
|50
 +
|0x32
 +
|0x72
 +
|0xB2
 +
|-
 +
! rowspan="12" |5
 +
!C
 +
|51
 +
|0x33
 +
|0x73
 +
|0xB3
 +
|-
 +
!C♯/D♭
 +
|52
 +
|0x34
 +
|0x74
 +
|0xB4
 +
|-
 +
!D
 +
|53
 +
|0x35
 +
|0x75
 +
|0xB5
 +
|-
 +
!D♯/E♭
 +
|54
 +
|0x36
 +
|0x76
 +
|0xB6
 +
|-
 +
!E
 +
|55
 +
|0x37
 +
|0x77
 +
|0xB7
 +
|-
 +
!F
 +
|56
 +
|0x38
 +
|0x78
 +
|0xB8
 +
|-
 +
!F♯/G♭
 +
|57
 +
|0x39
 +
|0x79
 +
|0xB9
 +
|-
 +
!G
 +
|58
 +
|0x3A
 +
|0x7A
 +
|0xBA
 +
|-
 +
!G♯/A♭
 +
|59
 +
|0x3B
 +
|0x7B
 +
|0xBB
 +
|-
 +
!A
 +
|60
 +
|0x3C
 +
|0x7C
 +
|0xBC
 +
|-
 +
!A♯/B♭
 +
|61
 +
|0x3D
 +
|0x7D
 +
|0xBD
 +
|-
 +
!B
 +
|62
 +
|0x3E
 +
|0x7E
 +
|0xBE
 +
|-
 +
!6
 +
!C
 +
|63
 +
|0x3F
 +
|0x7F
 +
|0xBF
 +
|}
 +
 
 +
== Note durations ==
 +
The effective duration of a note and the delay commands is based on the currently set sequence tempo. The duration of a single tick in seconds can be calculated using the following formular: <code>time = 1.25 / tempo</code>.
 +
{| class="wikitable"
 +
!Note
 +
!Ticks
 +
!Duration (120 BPM)
 +
|-
 +
|whole
 +
|192
 +
|2s
 +
|-
 +
|half dotted (2nd + 4th)
 +
|144
 +
|1.5s
 +
|-
 +
|half
 +
|96
 +
|1s
 +
|-
 +
|quarter dottet (4th + 8th)
 +
|72
 +
|0.75s
 +
|-
 +
|quarter (4th)
 +
|48
 +
|0.5s
 +
|-
 +
|eighth dottet (8th + 16th)
 +
|36
 +
|0.375s
 +
|-
 +
|quarter tuplet
 +
|32
 +
|0.333s
 +
|-
 +
|eighth (8th)
 +
|24
 +
|0.25s
 +
|-
 +
|sixteenth dottet (16th + 32th)
 +
|18
 +
|0.1875s
 +
|-
 +
|eigthth tuplet
 +
|16
 +
|0.1666s
 +
|-
 +
|sixteenth (16th)
 +
|12
 +
|0.125s
 +
|-
 +
|32th dottet (32th + 64th)
 +
|9
 +
|0.09375s
 +
|-
 +
|sixteenth tuplet (16th)
 +
|8
 +
|0.08333s
 +
|-
 +
|32th
 +
|6
 +
|0.0625s
 +
|-
 +
|32th tuplet
 +
|4
 +
|0.041666s
 +
|-
 +
|64th
 +
|3
 +
|0.03125s
 +
|-
 +
|64th tuplet
 +
|2
 +
|0.0208333s
 +
|}
  
 
== Create sequences ==
 
== Create sequences ==
Line 27: Line 522:
 
!Bytecode (US)
 
!Bytecode (US)
 
!Description
 
!Description
−
!
 
 
|-
 
|-
 
!seq_end
 
!seq_end
Line 34: Line 528:
 
|0xff
 
|0xff
 
|End of script, loop or function
 
|End of script, loop or function
−
|
 
 
|-
 
|-
 
!seq_delay1
 
!seq_delay1
Line 41: Line 534:
 
|0xfe
 
|0xfe
 
|Delay for 1 tick
 
|Delay for 1 tick
−
|
 
 
|-
 
|-
 
!seq_delay
 
!seq_delay
Line 48: Line 540:
 
|0xfd, var
 
|0xfd, var
 
|Delay for X ticks
 
|Delay for X ticks
−
|
 
 
|-
 
|-
 
!seq_call
 
!seq_call
Line 55: Line 546:
 
|0xfc, addr
 
|0xfc, addr
 
|Call a function
 
|Call a function
−
|
 
 
|-
 
|-
 
!seq_jump
 
!seq_jump
Line 62: Line 552:
 
|0xfb, addr
 
|0xfb, addr
 
|Jump to a point in the sequence script
 
|Jump to a point in the sequence script
−
|
 
 
|-
 
|-
 
!seq_beqz
 
!seq_beqz
Line 69: Line 558:
 
|0xfa, addr
 
|0xfa, addr
 
|Jump if Q == 0, where Q is an s8 used to hold temporary sequence script state
 
|Jump if Q == 0, where Q is an s8 used to hold temporary sequence script state
−
|
 
 
|-
 
|-
 
!seq_bltz
 
!seq_bltz
Line 76: Line 564:
 
|0xf9, addr
 
|0xf9, addr
 
|Jump if Q < 0
 
|Jump if Q < 0
−
|
 
 
|-
 
|-
 
!seq_loop
 
!seq_loop
Line 83: Line 570:
 
|0xf8, u8
 
|0xf8, u8
 
|Repeat until <code>loopend</code> for X iterations (256 if X = 0)
 
|Repeat until <code>loopend</code> for X iterations (256 if X = 0)
−
|
 
 
|-
 
|-
 
!seq_loopend
 
!seq_loopend
Line 90: Line 576:
 
|0xf7
 
|0xf7
 
|Loop end marker
 
|Loop end marker
−
|
 
 
|-
 
|-
 
!seq_bgez
 
!seq_bgez
Line 97: Line 582:
 
|0xf5, addr
 
|0xf5, addr
 
|Jump if Q >= 0
 
|Jump if Q >= 0
−
|
 
 
|-
 
|-
 
!seq_reservenotes
 
!seq_reservenotes
Line 104: Line 588:
 
|0xf2, u8
 
|0xf2, u8
 
|Reserve X notes for exclusive use by this sequence (dropping earlier reservations). A limited number of notes can be played at once (configurable per level, usually 16); if more than that are played, an existing one will be stopped and reused. This command can prevent that from happening across sequences.
 
|Reserve X notes for exclusive use by this sequence (dropping earlier reservations). A limited number of notes can be played at once (configurable per level, usually 16); if more than that are played, an existing one will be stopped and reused. This command can prevent that from happening across sequences.
−
|
 
 
|-
 
|-
 
!seq_unreservenotes
 
!seq_unreservenotes
Line 111: Line 594:
 
|0xf1
 
|0xf1
 
|Drop all earlier reservations made by this sequence.
 
|Drop all earlier reservations made by this sequence.
−
|
 
 
|-
 
|-
 
!seq_transpose
 
!seq_transpose
Line 118: Line 600:
 
|0xdf, s8
 
|0xdf, s8
 
|Set transposition in semitones.
 
|Set transposition in semitones.
−
|
 
 
|-
 
|-
 
!seq_transposerel
 
!seq_transposerel
Line 125: Line 606:
 
|0xde, s8
 
|0xde, s8
 
|Change transposition by some delta.
 
|Change transposition by some delta.
−
|
 
 
|-
 
|-
 
!seq_settempo
 
!seq_settempo
Line 132: Line 612:
 
|0xdd, u8
 
|0xdd, u8
 
|Set tempo in BPM.
 
|Set tempo in BPM.
−
|
 
 
|-
 
|-
 
!seq_addtempo
 
!seq_addtempo
Line 139: Line 618:
 
|0xdc, s8
 
|0xdc, s8
 
|Change tempo by some delta.
 
|Change tempo by some delta.
−
|
 
 
|-
 
|-
 
!seq_setvol
 
!seq_setvol
Line 146: Line 624:
 
|0xdb, u8
 
|0xdb, u8
 
|Set volume scale (0…255 = none to twice normal).
 
|Set volume scale (0…255 = none to twice normal).
−
|
 
 
|-
 
|-
 
!seq_changevol
 
!seq_changevol
Line 153: Line 630:
 
|0xda, s8
 
|0xda, s8
 
|Change volume scale by some delta.
 
|Change volume scale by some delta.
−
|
 
 
|-
 
|-
 
!seq_initchannels
 
!seq_initchannels
Line 160: Line 636:
 
|0xd7, u16
 
|0xd7, u16
 
|Initialize channels (bitmask). This copies mute behavior and note allocation policy.
 
|Initialize channels (bitmask). This copies mute behavior and note allocation policy.
−
|
 
 
|-
 
|-
 
!seq_disablechannels
 
!seq_disablechannels
Line 167: Line 642:
 
|0xd6, u16
 
|0xd6, u16
 
|Uninitialize channels (bitmask).
 
|Uninitialize channels (bitmask).
−
|
 
 
|-
 
|-
 
!seq_setmutescale
 
!seq_setmutescale
Line 174: Line 648:
 
|0xd5, s8
 
|0xd5, s8
 
|Set volume multiplier for muted mode (0…127).
 
|Set volume multiplier for muted mode (0…127).
−
|
 
 
|-
 
|-
 
!seq_mute
 
!seq_mute
Line 181: Line 654:
 
|0xd4
 
|0xd4
 
|Set sequence to muted mode. Depending on what behavior has been set this will do different things; from lowering volume to not running scripts.
 
|Set sequence to muted mode. Depending on what behavior has been set this will do different things; from lowering volume to not running scripts.
−
|
 
 
|-
 
|-
 
!seq_setmutebhv
 
!seq_setmutebhv
Line 188: Line 660:
 
|0xd3, u8
 
|0xd3, u8
 
|Set mute behavior (bitmask). Bit 0x20 lowers volume, bit 0x40 does something to layers, and bit 0x80 pauses the sequence script. Default mute behavior is to have all of those bits set.
 
|Set mute behavior (bitmask). Bit 0x20 lowers volume, bit 0x40 does something to layers, and bit 0x80 pauses the sequence script. Default mute behavior is to have all of those bits set.
−
|
 
 
|-
 
|-
 
!seq_setshortnotevelocitytable
 
!seq_setshortnotevelocitytable
Line 195: Line 666:
 
|0xd2, addr
 
|0xd2, addr
 
|Set velocity table for short notes (see further down). Target should be an array of bytes in the sequence data of length 16.
 
|Set velocity table for short notes (see further down). Target should be an array of bytes in the sequence data of length 16.
−
|
 
 
|-
 
|-
 
!seq_setshortnotedurationtable
 
!seq_setshortnotedurationtable
Line 202: Line 672:
 
|0xd1, addr
 
|0xd1, addr
 
|Set duration table for short notes (see further down). Target should be an array of bytes in the sequence data of length 16.
 
|Set duration table for short notes (see further down). Target should be an array of bytes in the sequence data of length 16.
−
|
 
 
|-
 
|-
 
!seq_setnoteallocationpolicy
 
!seq_setnoteallocationpolicy
Line 209: Line 678:
 
|0xd0, u8
 
|0xd0, u8
 
|Set note allocation policy (bitmask). If bit 0x1 is set, it will try to steal notes back from what was previously played on the same layer. If bit 0x2 is set, notes will be allocated exclusively from the channel’s reserved notes, else if 0x4 is set, from the channel’s or sequence’s reserved notes, else if 0x8 is set, from unreserved notes, otherwise from all sources. Not used by the game.
 
|Set note allocation policy (bitmask). If bit 0x1 is set, it will try to steal notes back from what was previously played on the same layer. If bit 0x2 is set, notes will be allocated exclusively from the channel’s reserved notes, else if 0x4 is set, from the channel’s or sequence’s reserved notes, else if 0x8 is set, from unreserved notes, otherwise from all sources. Not used by the game.
−
|
 
 
|-
 
|-
 
!seq_setval
 
!seq_setval
Line 216: Line 684:
 
|0xcc, u8
 
|0xcc, u8
 
|Set Q to a constant.
 
|Set Q to a constant.
−
|
 
 
|-
 
|-
 
!seq_bitand
 
!seq_bitand
Line 223: Line 690:
 
|0xc9, u8
 
|0xc9, u8
 
|Bitand Q by a constant.
 
|Bitand Q by a constant.
−
|
 
 
|-
 
|-
 
!seq_subtract
 
!seq_subtract
Line 230: Line 696:
 
|0xc8, u8
 
|0xc8, u8
 
|Subtract a constant from Q.
 
|Subtract a constant from Q.
−
|
 
 
|-
 
|-
 
!seq_startchannel
 
!seq_startchannel
Line 237: Line 702:
 
|0x90-0x9f, addr
 
|0x90-0x9f, addr
 
|Start channel N, with a given channel script.
 
|Start channel N, with a given channel script.
−
|
 
 
|-
 
|-
 
!seq_getvariation
 
!seq_getvariation
Line 244: Line 708:
 
|0x80-0x8f
 
|0x80-0x8f
 
|Set Q to the variation bit, which is initially either 0 or 0x80 (i.e. -128, since Q is s8). This bit comes from the sequence load command. For instance, to play the Koopa shell music, the game plays sequence 0x8E, which is the same as sequence 0xE but with the variation bit set.
 
|Set Q to the variation bit, which is initially either 0 or 0x80 (i.e. -128, since Q is s8). This bit comes from the sequence load command. For instance, to play the Koopa shell music, the game plays sequence 0x8E, which is the same as sequence 0xE but with the variation bit set.
−
|
 
 
|-
 
|-
 
!seq_setvariation
 
!seq_setvariation
Line 251: Line 714:
 
|0x70-0x7f
 
|0x70-0x7f
 
|Set the variation bit to Q.
 
|Set the variation bit to Q.
−
|
 
 
|-
 
|-
 
!seq_subvariation
 
!seq_subvariation
Line 258: Line 720:
 
|0x50-0x5f
 
|0x50-0x5f
 
|Subtract the variation bit from Q.
 
|Subtract the variation bit from Q.
−
|
 
 
|-
 
|-
 
!seq_testchdisabled
 
!seq_testchdisabled
Line 265: Line 726:
 
|0x00-0x0f
 
|0x00-0x0f
 
|Set Q to 1 or 0, depending on whether channel N has been disabled by channel script.
 
|Set Q to 1 or 0, depending on whether channel N has been disabled by channel script.
−
|
 
 
|}
 
|}
  
 
=== Channel commands ===
 
=== Channel commands ===
 
{| class="wikitable"
 
{| class="wikitable"
−
|+
 
 
!Mnemonic
 
!Mnemonic
 
!Param 1
 
!Param 1
Line 277: Line 736:
 
!Bytecode (US)
 
!Bytecode (US)
 
!Description
 
!Description
−
!
 
 
|-
 
|-
 
!chan_end
 
!chan_end
Line 285: Line 743:
 
|0xff
 
|0xff
 
|End of script, loop or function
 
|End of script, loop or function
−
|
 
 
|-
 
|-
 
!chan_delay1
 
!chan_delay1
Line 293: Line 750:
 
|0xfe
 
|0xfe
 
|Delay for 1 tick
 
|Delay for 1 tick
−
|
 
 
|-
 
|-
 
!chan_delay
 
!chan_delay
Line 301: Line 757:
 
|0xfd, var
 
|0xfd, var
 
|Delay for X ticks
 
|Delay for X ticks
−
|
 
 
|-
 
|-
 
!chan_call
 
!chan_call
Line 309: Line 764:
 
|0xfc, addr
 
|0xfc, addr
 
|Call a function
 
|Call a function
−
|
 
 
|-
 
|-
 
!chan_jump
 
!chan_jump
Line 317: Line 771:
 
|0xfb, addr
 
|0xfb, addr
 
|Jump to a point in the channel script
 
|Jump to a point in the channel script
−
|
 
 
|-
 
|-
 
!chan_beqz
 
!chan_beqz
Line 325: Line 778:
 
|0xfa, addr
 
|0xfa, addr
 
|Jump if Q == 0, where Q is an s8 used to hold temporary channel script state
 
|Jump if Q == 0, where Q is an s8 used to hold temporary channel script state
−
|
 
 
|-
 
|-
 
!chan_bltz
 
!chan_bltz
Line 333: Line 785:
 
|0xf9, addr
 
|0xf9, addr
 
|Jump if Q < 0
 
|Jump if Q < 0
−
|
 
 
|-
 
|-
 
!chan_loop
 
!chan_loop
Line 341: Line 792:
 
|0xf8, u8
 
|0xf8, u8
 
|Repeat until <code>loopend</code> for X iterations (256 if X = 0)
 
|Repeat until <code>loopend</code> for X iterations (256 if X = 0)
−
|
 
 
|-
 
|-
 
!chan_loopend
 
!chan_loopend
Line 349: Line 799:
 
|0xf7
 
|0xf7
 
|Loop end marker
 
|Loop end marker
−
|
 
 
|-
 
|-
 
!chan_break
 
!chan_break
Line 357: Line 806:
 
|0xf6
 
|0xf6
 
|Decrease loop/function stack depth by 1. Combine with a jump to break out of a loop.
 
|Decrease loop/function stack depth by 1. Combine with a jump to break out of a loop.
−
|
 
 
|-
 
|-
 
!chan_bgez
 
!chan_bgez
Line 365: Line 813:
 
|0xf5, addr
 
|0xf5, addr
 
|Jump if Q >= 0
 
|Jump if Q >= 0
−
|
 
 
|-
 
|-
 
!chan_hang
 
!chan_hang
Line 373: Line 820:
 
|0xf3
 
|0xf3
 
|Infinite delay.
 
|Infinite delay.
−
|
 
 
|-
 
|-
 
!chan_reservenotes
 
!chan_reservenotes
Line 381: Line 827:
 
|0xf2, u8
 
|0xf2, u8
 
|Reserve X notes for exclusive use by this channel (dropping earlier reservations).
 
|Reserve X notes for exclusive use by this channel (dropping earlier reservations).
−
|
 
 
|-
 
|-
 
!chan_unreservenotes
 
!chan_unreservenotes
Line 389: Line 834:
 
|0xf1
 
|0xf1
 
|Drop all earlier reservations made by this channel.
 
|Drop all earlier reservations made by this channel.
−
|
 
 
|-
 
|-
 
!chan_dyncall
 
!chan_dyncall
Line 397: Line 841:
 
|0xe4
 
|0xe4
 
|If Q != -1, make a function call to position dyntable[Q], where dyntable is a channel-specific u16 array which can set by <code>setdyntable</code>/<code>dynsetdyntable</code>.
 
|If Q != -1, make a function call to position dyntable[Q], where dyntable is a channel-specific u16 array which can set by <code>setdyntable</code>/<code>dynsetdyntable</code>.
−
|
 
 
|-
 
|-
 
!chan_setvibratodelay
 
!chan_setvibratodelay
Line 405: Line 848:
 
|0xe3, u8
 
|0xe3, u8
 
|Set delay until vibrato starts for each note.
 
|Set delay until vibrato starts for each note.
−
|
 
 
|-
 
|-
 
!chan_setvibratoextentlinear
 
!chan_setvibratoextentlinear
Line 413: Line 855:
 
|0xe2, u8, u8, u8
 
|0xe2, u8, u8, u8
 
|Set vibrato extent for each note as a function that starts at X, goes up linearly to Y over a time span given by Z, then stays there.
 
|Set vibrato extent for each note as a function that starts at X, goes up linearly to Y over a time span given by Z, then stays there.
−
|
 
 
|-
 
|-
 
!chan_setvibratoratelinear
 
!chan_setvibratoratelinear
Line 421: Line 862:
 
|0xe1, u8, u8, u8
 
|0xe1, u8, u8, u8
 
|Like above except for vibrato rate.
 
|Like above except for vibrato rate.
−
|
 
 
|-
 
|-
 
!chan_setvolscale
 
!chan_setvolscale
Line 429: Line 869:
 
|0xe0, u8
 
|0xe0, u8
 
|Set scale factor for volume (0…255 = none to twice normal).
 
|Set scale factor for volume (0…255 = none to twice normal).
−
|
 
 
|-
 
|-
 
!chan_setvol
 
!chan_setvol
Line 437: Line 876:
 
|0xdf, u8
 
|0xdf, u8
 
|Set scale factor #2 for volume (0…255 = none to twice normal). The two scale factors are separately controlled by outer audio logic, e.g. when changing between rooms, when playing sound effects, etc. The game almost exclusively uses setvol, so that should probably be preferred, but setvolscale shows up in a few locations in the sound effect sequence.
 
|Set scale factor #2 for volume (0…255 = none to twice normal). The two scale factors are separately controlled by outer audio logic, e.g. when changing between rooms, when playing sound effects, etc. The game almost exclusively uses setvol, so that should probably be preferred, but setvolscale shows up in a few locations in the sound effect sequence.
−
|
 
 
|-
 
|-
 
!chan_freqscale
 
!chan_freqscale
Line 445: Line 883:
 
|0xde, u16
 
|0xde, u16
 
|Pitch bend using a raw frequency multiplier X/2^15.
 
|Pitch bend using a raw frequency multiplier X/2^15.
−
|
 
 
|-
 
|-
 
!chan_setpan
 
!chan_setpan
Line 453: Line 890:
 
|0xdd, u8
 
|0xdd, u8
 
|Set the pan for this channel (0…128)
 
|Set the pan for this channel (0…128)
−
|
 
 
|-
 
|-
 
!chan_setpanchanweight
 
!chan_setpanchanweight
Line 461: Line 897:
 
|0xdc, u8
 
|0xdc, u8
 
|The pan for each note will be computed as W * channel pan + (1 - W) * note pan. This sets W (0…128 maps to 0…1). W defaults to 1.0.
 
|The pan for each note will be computed as W * channel pan + (1 - W) * note pan. This sets W (0…128 maps to 0…1). W defaults to 1.0.
−
|
 
 
|-
 
|-
 
!chan_transpose
 
!chan_transpose
Line 469: Line 904:
 
|0xdb, s8
 
|0xdb, s8
 
|Set transposition in semitones.
 
|Set transposition in semitones.
−
|
 
 
|-
 
|-
 
!chan_setenvelope
 
!chan_setenvelope
Line 477: Line 911:
 
|0xda, addr
 
|0xda, addr
 
|Set ADSR envelope. See below for format.
 
|Set ADSR envelope. See below for format.
−
|
 
 
|-
 
|-
 
!chan_setdecayrelease
 
!chan_setdecayrelease
Line 485: Line 918:
 
|0xd9, u8
 
|0xd9, u8
 
|Set ADSR decay/release rate.
 
|Set ADSR decay/release rate.
−
|
 
 
|-
 
|-
 
!chan_setvibratoextent
 
!chan_setvibratoextent
Line 493: Line 925:
 
|0xd8, u8
 
|0xd8, u8
 
|Set vibrato extent.
 
|Set vibrato extent.
−
|
 
 
|-
 
|-
 
!chan_setvibratorate
 
!chan_setvibratorate
Line 501: Line 932:
 
|0xd7, u8
 
|0xd7, u8
 
|Set vibrato rate.
 
|Set vibrato rate.
−
|
 
 
|-
 
|-
 
!chan_setupdatesperframe
 
!chan_setupdatesperframe
Line 509: Line 939:
 
|0xd6, u8
 
|0xd6, u8
 
|Seems like it was meant to set the number of updates per frame? But it doesn’t actually do anything.
 
|Seems like it was meant to set the number of updates per frame? But it doesn’t actually do anything.
−
|
 
 
|-
 
|-
 
!chan_setreverb
 
!chan_setreverb
Line 517: Line 946:
 
|0xd4, u8
 
|0xd4, u8
 
|Set amount of reverb (or “dry/wet mix”?).
 
|Set amount of reverb (or “dry/wet mix”?).
−
|
 
 
|-
 
|-
 
!chan_pitchbend
 
!chan_pitchbend
Line 525: Line 953:
 
|0xd3, s8
 
|0xd3, s8
 
|Pitch bend by <= 1 octave in either direction (-127…127).
 
|Pitch bend by <= 1 octave in either direction (-127…127).
−
|
 
 
|-
 
|-
 
!chan_setsustain
 
!chan_setsustain
Line 533: Line 960:
 
|0xd2, u8
 
|0xd2, u8
 
|Set ADSR sustain volume.
 
|Set ADSR sustain volume.
−
|
 
 
|-
 
|-
 
!chan_setnoteallocationpolicy
 
!chan_setnoteallocationpolicy
Line 541: Line 967:
 
|0xd1, u8
 
|0xd1, u8
 
|Set note allocation policy for channel. See the description for sequence scripts.
 
|Set note allocation policy for channel. See the description for sequence scripts.
−
|
 
 
|-
 
|-
 
!chan_stereoheadseteffects
 
!chan_stereoheadseteffects
Line 549: Line 974:
 
|0xd0, u8
 
|0xd0, u8
 
|Enable (1) or disable (0) some pan/volume effects related to stereo/headset. I don’t know which ones precisely – pan ''is'' still taken into account even with this disabled. With this disabled, stereo/headset gets the same output.
 
|Enable (1) or disable (0) some pan/volume effects related to stereo/headset. I don’t know which ones precisely – pan ''is'' still taken into account even with this disabled. With this disabled, stereo/headset gets the same output.
−
|
 
 
|-
 
|-
 
!chan_setval
 
!chan_setval
Line 557: Line 981:
 
|0xcc, u8
 
|0xcc, u8
 
|Set Q to a constant.
 
|Set Q to a constant.
−
|
 
 
|-
 
|-
 
!chan_readseq
 
!chan_readseq
Line 565: Line 988:
 
|0xcb, addr
 
|0xcb, addr
 
|Set Q to sequenceData[X + Q].
 
|Set Q to sequenceData[X + Q].
−
|
 
 
|-
 
|-
 
!chan_setmutebhv
 
!chan_setmutebhv
Line 573: Line 995:
 
|0xca, u8
 
|0xca, u8
 
|Set mute behavior for this channel.
 
|Set mute behavior for this channel.
−
|
 
 
|-
 
|-
 
!chan_bitand
 
!chan_bitand
Line 581: Line 1,002:
 
|0xc9, u8
 
|0xc9, u8
 
|Bitand Q by a constant.
 
|Bitand Q by a constant.
−
|
 
 
|-
 
|-
 
!chan_subtract
 
!chan_subtract
Line 589: Line 1,009:
 
|0xc8, u8
 
|0xc8, u8
 
|Subtract a constant from Q.
 
|Subtract a constant from Q.
−
|
 
 
|-
 
|-
 
!chan_writeseq
 
!chan_writeseq
Line 597: Line 1,016:
 
|0xc7, u8, addr
 
|0xc7, u8, addr
 
|Overwrite the byte at the given position in the sequence script by (Q + X).
 
|Overwrite the byte at the given position in the sequence script by (Q + X).
−
|
 
 
|-
 
|-
 
!chan_setbank
 
!chan_setbank
Line 605: Line 1,023:
 
|0xc6, u8
 
|0xc6, u8
 
|Switch bank within instrument bank sets, to the X’th bank, 0-indexed, counting from the end.
 
|Switch bank within instrument bank sets, to the X’th bank, 0-indexed, counting from the end.
−
|
 
 
|-
 
|-
 
!chan_dynsetdyntable
 
!chan_dynsetdyntable
Line 613: Line 1,030:
 
|0xc5
 
|0xc5
 
|If Q != -1, set dyntable to point to position dyntable[Q] in the sequence data.
 
|If Q != -1, set dyntable to point to position dyntable[Q] in the sequence data.
−
|
 
 
|-
 
|-
 
!chan_largenoteson
 
!chan_largenoteson
Line 621: Line 1,037:
 
|0xc4
 
|0xc4
 
|Set notes for this channel to use “large notes” format. SM64 does this for all channels. (See <code>note</code> vs. <code>shortnote</code> in the layer section below.)
 
|Set notes for this channel to use “large notes” format. SM64 does this for all channels. (See <code>note</code> vs. <code>shortnote</code> in the layer section below.)
−
|
 
 
|-
 
|-
 
!chan_largenotesoff
 
!chan_largenotesoff
Line 629: Line 1,044:
 
|0xc3
 
|0xc3
 
|Set notes for this channel to use “short notes” format.
 
|Set notes for this channel to use “short notes” format.
−
|
 
 
|-
 
|-
 
!chan_setdyntable
 
!chan_setdyntable
Line 637: Line 1,051:
 
|0xc2, addr
 
|0xc2, addr
 
|Set dyntable to point to a given u16 array from the sequence data.
 
|Set dyntable to point to a given u16 array from the sequence data.
−
|
 
 
|-
 
|-
 
!chan_setinstr
 
!chan_setinstr
Line 645: Line 1,058:
 
|0xc1, u8
 
|0xc1, u8
 
|Set instrument (program?) within bank. 0x80-0x83 set raw waves (sawtooth, triangle, sine, square), 0x7f is special, otherwise 0-indexed.
 
|Set instrument (program?) within bank. 0x80-0x83 set raw waves (sawtooth, triangle, sine, square), 0x7f is special, otherwise 0-indexed.
−
|
 
 
|-
 
|-
 
!chan_dynsetlayer
 
!chan_dynsetlayer
Line 653: Line 1,065:
 
|0xb0-0xbf
 
|0xb0-0xbf
 
|If Q != -1, start layer N, with layer script given by dyntable[Q].
 
|If Q != -1, start layer N, with layer script given by dyntable[Q].
−
|
 
 
|-
 
|-
 
!chan_freelayer
 
!chan_freelayer
Line 661: Line 1,072:
 
|0xa0-0xaf
 
|0xa0-0xaf
 
|Stop layer N.
 
|Stop layer N.
−
|
 
 
|-
 
|-
 
!chan_setlayer
 
!chan_setlayer
Line 669: Line 1,079:
 
|0x90-0x9f, addr
 
|0x90-0x9f, addr
 
|Start layer N, with layer script starting at address X.
 
|Start layer N, with layer script starting at address X.
−
|
 
 
|-
 
|-
 
!chan_ioreadval
 
!chan_ioreadval
Line 677: Line 1,086:
 
|0x80-0x8f
 
|0x80-0x8f
 
|Set Q to IO[N], where IO is an array of bytes that can be read/written by both the game and the channel script. If N < 4, IO[N] is then set to -1.
 
|Set Q to IO[N], where IO is an array of bytes that can be read/written by both the game and the channel script. If N < 4, IO[N] is then set to -1.
−
|
 
 
|-
 
|-
 
!chan_iowriteval
 
!chan_iowriteval
Line 685: Line 1,093:
 
|0x70-0x7f
 
|0x70-0x7f
 
|Set IO[N] to Q.
 
|Set IO[N] to Q.
−
|
 
 
|-
 
|-
 
!chan_setnotepriority
 
!chan_setnotepriority
Line 693: Line 1,100:
 
|0x60-0x6f
 
|0x60-0x6f
 
|Set note priority for later notes played on this channel to N. When the game wants to play a note and there aren’t any free notes available, a note with smaller or equal priority is discarded. Should be >= 2; 0 and 1 have internal meaning. Defaults to 3.
 
|Set note priority for later notes played on this channel to N. When the game wants to play a note and there aren’t any free notes available, a note with smaller or equal priority is discarded. Should be >= 2; 0 and 1 have internal meaning. Defaults to 3.
−
|
 
 
|-
 
|-
 
!chan_ioreadvalsub
 
!chan_ioreadvalsub
Line 701: Line 1,107:
 
|0x50-0x5f
 
|0x50-0x5f
 
|Decrease Q by IO[N].
 
|Decrease Q by IO[N].
−
|
 
 
|-
 
|-
 
!chan_ioreadval2
 
!chan_ioreadval2
Line 709: Line 1,114:
 
|0x40-0x4f, u8
 
|0x40-0x4f, u8
 
|Set Q to IO2[X], where IO2 is the IO array for channel N.
 
|Set Q to IO2[X], where IO2 is the IO array for channel N.
−
|
 
 
|-
 
|-
 
!chan_iowriteval2
 
!chan_iowriteval2
Line 717: Line 1,121:
 
|0x30-0x3f, u8
 
|0x30-0x3f, u8
 
|Set IO2[X] to Q, where IO2 is the IO array for channel N.
 
|Set IO2[X] to Q, where IO2 is the IO array for channel N.
−
|
 
 
|-
 
|-
 
!chan_disablechannel
 
!chan_disablechannel
Line 725: Line 1,128:
 
|0x20-0x2f
 
|0x20-0x2f
 
|Disable channel N for the parent sequence.
 
|Disable channel N for the parent sequence.
−
|
 
 
|-
 
|-
 
!chan_startchannel
 
!chan_startchannel
Line 733: Line 1,135:
 
|0x10-0x1f, addr
 
|0x10-0x1f, addr
 
|Start channel N for the parent sequence, with channel script starting at address X.
 
|Start channel N for the parent sequence, with channel script starting at address X.
−
|
 
 
|-
 
|-
 
!chan_testlayerfinished
 
!chan_testlayerfinished
Line 741: Line 1,142:
 
|0x00-0x0f
 
|0x00-0x0f
 
|Set Q to 1 or 0, depending on whether layer N has been disabled (either forcibly or by finishing its script).
 
|Set Q to 1 or 0, depending on whether layer N has been disabled (either forcibly or by finishing its script).
−
|
 
 
|}
 
|}
  
 
=== Layer commands ===
 
=== Layer commands ===
 
{| class="wikitable"
 
{| class="wikitable"
−
|+
 
 
!Mnemonic
 
!Mnemonic
 
!Param 1
 
!Param 1
Line 754: Line 1,153:
 
!Bytecode (US)
 
!Bytecode (US)
 
!Description
 
!Description
−
!
 
 
|-
 
|-
 
!layer_end
 
!layer_end
Line 763: Line 1,161:
 
|0xff
 
|0xff
 
|End of script, loop or function
 
|End of script, loop or function
−
|
 
 
|-
 
|-
 
!layer_call
 
!layer_call
Line 772: Line 1,169:
 
|0xfc, addr
 
|0xfc, addr
 
|Call a function
 
|Call a function
−
|
 
 
|-
 
|-
 
!layer_jump
 
!layer_jump
Line 781: Line 1,177:
 
|0xfb, addr
 
|0xfb, addr
 
|Jump to a point in the layer script
 
|Jump to a point in the layer script
−
|
 
 
|-
 
|-
 
!layer_loop
 
!layer_loop
Line 790: Line 1,185:
 
|0xf8, u8
 
|0xf8, u8
 
|Repeat until <code>loopend</code> for X iterations (256 if X = 0)
 
|Repeat until <code>loopend</code> for X iterations (256 if X = 0)
−
|
 
 
|-
 
|-
 
!layer_loopend
 
!layer_loopend
Line 799: Line 1,193:
 
|0xf7
 
|0xf7
 
|Loop end marker
 
|Loop end marker
−
|
 
 
|-
 
|-
 
!layer_setshortnotedurationfromtable
 
!layer_setshortnotedurationfromtable
Line 808: Line 1,201:
 
|0xe0-0xef
 
|0xe0-0xef
 
|Set the duration for future short notes to table[N], where table defaults to <code>{229, 203, 177, 151, 139, 126, 113, 100, 87, 74, 61, 48, 36, 23, 10, 0}</code> and can be set by <code>setshortnotedurationtable</code>.
 
|Set the duration for future short notes to table[N], where table defaults to <code>{229, 203, 177, 151, 139, 126, 113, 100, 87, 74, 61, 48, 36, 23, 10, 0}</code> and can be set by <code>setshortnotedurationtable</code>.
−
|
 
 
|-
 
|-
 
!layer_setshortnotevelocityfromtable
 
!layer_setshortnotevelocityfromtable
Line 817: Line 1,209:
 
|0xd0-0xdf
 
|0xd0-0xdf
 
|Set the velocity for future short notes to table[N], where table defaults to <code>{12, 25, 38, 51, 57, 64, 71, 76, 83, 89, 96, 102, 109, 115, 121, 127}</code> and can be set by <code>setshortnotevelocitytable</code>.
 
|Set the velocity for future short notes to table[N], where table defaults to <code>{12, 25, 38, 51, 57, 64, 71, 76, 83, 89, 96, 102, 109, 115, 121, 127}</code> and can be set by <code>setshortnotevelocitytable</code>.
−
|
 
 
|-
 
|-
 
!layer_setpan
 
!layer_setpan
Line 826: Line 1,217:
 
|0xca, u8
 
|0xca, u8
 
|Set the pan for this layer (0…128).
 
|Set the pan for this layer (0…128).
−
|
 
 
|-
 
|-
 
!layer_setshortnoteduration
 
!layer_setshortnoteduration
Line 835: Line 1,225:
 
|0xc9, u8
 
|0xc9, u8
 
|Set the duration for future short notes.
 
|Set the duration for future short notes.
−
|
 
 
|-
 
|-
 
!layer_disableportamento
 
!layer_disableportamento
Line 844: Line 1,233:
 
|0xc8
 
|0xc8
 
|Disable portamento for later notes.
 
|Disable portamento for later notes.
−
|
 
 
|-
 
|-
 
!layer_portamento
 
!layer_portamento
Line 853: Line 1,241:
 
|0xc7, u8, u8, u8/var
 
|0xc7, u8, u8, u8/var
 
|Enable portamento (aka glissando; continuously sliding pitch). X describes the mode of operation somehow using its 0x80 bit and a value 0-5 in its lower-order bits. Y describes the target pitch. Z gives the duration, and is a u8 if the 0x80 bit is set, otherwise a var.
 
|Enable portamento (aka glissando; continuously sliding pitch). X describes the mode of operation somehow using its 0x80 bit and a value 0-5 in its lower-order bits. Y describes the target pitch. Z gives the duration, and is a u8 if the 0x80 bit is set, otherwise a var.
−
|
 
 
|-
 
|-
 
!layer_setinstr
 
!layer_setinstr
Line 862: Line 1,249:
 
|0xc6, u8
 
|0xc6, u8
 
|Set instrument/program. Similar to the channel command, except arguments 0x7f and above are not supported.
 
|Set instrument/program. Similar to the channel command, except arguments 0x7f and above are not supported.
−
|
 
 
|-
 
|-
 
!layer_somethingoff
 
!layer_somethingoff
Line 871: Line 1,257:
 
|0xc5
 
|0xc5
 
|Turn off some bool related to how notes decay somehow? (This is the default.)
 
|Turn off some bool related to how notes decay somehow? (This is the default.)
−
|
 
 
|-
 
|-
 
!layer_somethingon
 
!layer_somethingon
Line 880: Line 1,265:
 
|0xc4
 
|0xc4
 
|Turn on the same thing.
 
|Turn on the same thing.
−
|
 
 
|-
 
|-
 
!layer_setshortnotedefaultplaypercentage
 
!layer_setshortnotedefaultplaypercentage
Line 889: Line 1,273:
 
|0xc3, var
 
|0xc3, var
 
|Set the default play percentage for short notes (see below).
 
|Set the default play percentage for short notes (see below).
−
|
 
 
|-
 
|-
 
!layer_transpose
 
!layer_transpose
Line 898: Line 1,281:
 
|0xc2, u8
 
|0xc2, u8
 
|Set transposition in semitones.
 
|Set transposition in semitones.
−
|
 
 
|-
 
|-
 
!layer_setshortnotevelocity
 
!layer_setshortnotevelocity
Line 907: Line 1,289:
 
|0xc1, u8
 
|0xc1, u8
 
|Set velocity for future short notes.
 
|Set velocity for future short notes.
−
|
 
 
|-
 
|-
 
!layer_delay
 
!layer_delay
Line 916: Line 1,297:
 
|0xc0, var
 
|0xc0, var
 
|Delay for N ticks
 
|Delay for N ticks
−
|
 
 
|-
 
|-
 
!layer_note0
 
!layer_note0
Line 924: Line 1,304:
 
|duration
 
|duration
 
|0x00-0x3f, var, u8, u8
 
|0x00-0x3f, var, u8, u8
−
|Play note with play percentage X, velocity Y, duration Z and pitch N. (Is “play percentage” the right term?). Only valid if channel is set to “large notes”.
+
|Play note with specified pitch, percentage, velocity and duration. Only valid if channel is set to “large notes”.
−
|
 
 
|-
 
|-
 
!layer_note1
 
!layer_note1
Line 933: Line 1,312:
 
|
 
|
 
|0x40-0x7f, var, u8
 
|0x40-0x7f, var, u8
−
|Play note with play percentage X, velocity Y, duration 0 and pitch N. Only valid if channel is set to “large notes”.
+
|Play note with specified pitch, percentage and velocity and duration of 0. Only valid if channel is set to “large notes”.
−
|
 
 
|-
 
|-
 
!layer_note2
 
!layer_note2
 +
|pitch
 
|velocity
 
|velocity
 
|duration
 
|duration
−
|
 
 
|
 
|
 
|0x80-0xbf, u8, u8
 
|0x80-0xbf, u8, u8
−
|Play note with velocity X, duration Y, pitch N and the last used play percentage. Only valid if channel is set to “large notes”.
+
|Play note with specified pitch, velocity and duration. Only valid if channel is set to “large notes”.
−
|
 
 
|-
 
|-
 
!layer_smallnote0
 
!layer_smallnote0
Line 951: Line 1,328:
 
|
 
|
 
|0x00-0x3f, var
 
|0x00-0x3f, var
−
|Play note with play percentage X and pitch N, with velocity and duration taken from the short notes settings set by setshortnote{velocity,duration} (or the fromtable variants), defaulting to 0 and 0x80 respectively if not set. Only valid if channel is set to “small notes”.
+
|Play note with specified pitch and percentage and velocity and duration set with layer_setshortnotevelocity and layer_setshortnoteduration. Only valid if channel is set to “small notes”.
−
|
 
 
|-
 
|-
 
!layer_smallnote1
 
!layer_smallnote1
Line 960: Line 1,336:
 
|
 
|
 
|0x40-0x7f
 
|0x40-0x7f
−
|Play note with pitch N and the default play percentage, as set by setshortnotedefaultplaypercentage (there is no built-in default; using it without that command will read uninitialized memory). Velocity and duration is set like in smallnote0. Only valid if channel is set to “small notes”.
+
|Play note with specified pitch and the default play percentage, as set by layer_setshortnotedefaultplaypercentage (there is no built-in default; using it without that command will read uninitialized memory). Velocity and duration is set like in layer_smallnote0. Only valid if channel is set to “small notes”.
−
|
 
 
|-
 
|-
 
!layer_smallnote2
 
!layer_smallnote2
Line 969: Line 1,344:
 
|
 
|
 
|0x80-0xbf
 
|0x80-0xbf
−
|Play note with pitch N and the previous play percentage. Velocity and duration is set like in smallnote0. Only valid if channel is set to “small notes”.
+
|Play note with specified pitch and the previous play percentage. Velocity and duration is set like in layer_smallnote0. Only valid if channel is set to “small notes”.
−
|
 
 
|}
 
|}
  
Line 977: Line 1,351:
 
* [https://www.smwcentral.net/?p=section&s=sm64music Custom music] for SM64 on SMW Central
 
* [https://www.smwcentral.net/?p=section&s=sm64music Custom music] for SM64 on SMW Central
 
* [https://hackmd.io/opEB-OmxRa26P8h8pA-x7w m64 format] posted on HackMD
 
* [https://hackmd.io/opEB-OmxRa26P8h8pA-x7w m64 format] posted on HackMD
 +
[[Category:Audio]]

Latest revision as of 14:44, 10 November 2020

dasdasdasdMusic in Super Mario 64 is controlled by sequence files. They are in .m64 format, which is similar to MIDI. A sequence file has a sequence script, that can spawn channels, which have channel scripts, that can spawn layers (also known as tracks), which have layer scripts that can play notes. Each note is performed using an instrument from a sound bank. A sequence file can use multiple banks. The mapping from sequences to sound banks is described in sound/sequences.json. Channels can switch between banks using a command. However, in practice most sequences limit themselves to a single sound bank. The main exception is sequence 0, which is responsible for sound effects.

A sequence may play up to 16 channels with up to 4 layers per channel. Several notes can be played simultaneously on a single layer.

A sequence is played as long as the sequence script is not ended. A channel (including layers) is active as long as the channel script is not ended.

Note properties

A note can be played by the commands layer_note0, layer_note1 and layer_note2 (only valid if chan_largenoteson has been called on the layer's channel) or layer_smallnote0, layer_smallnote1 and layer_smallnote2 (only valid if chan_largenotesoff has been called on the layer's channel; default state). A note is defined by the following properties:

Pitch

Also known as note. The pitch defines the frequency in which the instrument is to be played. See list of notes below for available pitches.

Play percentage

Also known as timestamp. This defines the note value, such as half or quarter note. This also implies a layer delay of the same amount. See note values below for possible values.

Velocity

This is the volume of the note.

Duration

Also known as gate or gate time. A value of 0 menas the note is heard during the whole percentage, 128 is half of the percentage and 255 almost none.

List of notes

This is a list of notes as used by the layer_note# and layer_smallnote# commands.

Octave Note Decimal Hex (note0) Hex (note1) Hex (note2)
0 A 0 0x00 0x40 0x80
A♯/B♭ 1 0x01 0x41 0x81
B 2 0x02 0x42 0x82
1 C 3 0x03 0x43 0x83
C♯/D♭ 4 0x04 0x44 0x84
D 5 0x05 0x45 0x85
D♯/E♭ 6 0x06 0x46 0x86
E 7 0x07 0x47 0x87
F 8 0x08 0x48 0x88
F♯/G♭ 9 0x09 0x49 0x89
G 10 0x0A 0x4A 0x8A
G♯/A♭ 11 0x0B 0x4B 0x8B
A 12 0x0C 0x4C 0x8C
A♯/B♭ 13 0x0D 0x4D 0x8D
B 14 0x0E 0x4E 0x8E
2 C 15 0x0F 0x4F 0x8F
C♯/D♭ 16 0x10 0x50 0x90
D 17 0x11 0x51 0x91
D♯/E♭ 18 0x12 0x52 0x92
E 19 0x13 0x53 0x93
F 20 0x14 0x54 0x94
F♯/G♭ 21 0x15 0x55 0x95
G 22 0x16 0x56 0x96
G♯/A♭ 23 0x17 0x57 0x97
A 24 0x18 0x58 0x98
A♯/B♭ 25 0x19 0x59 0x99
B 26 0x1A 0x5A 0x9A
3 C 27 0x1B 0x5B 0x9B
C♯/D♭ 28 0x1C 0x5C 0x9C
D 29 0x1D 0x5D 0x9D
D♯/E♭ 30 0x1E 0x5E 0x9E
E 31 0x1F 0x5F 0x9F
F 32 0x20 0x60 0xA0
F♯/G♭ 33 0x21 0x61 0xA1
G 34 0x22 0x62 0xA2
G♯/A♭ 35 0x23 0x63 0xA3
A 36 0x24 0x64 0xA4
A♯/B♭ 37 0x25 0x65 0xA5
B 38 0x26 0x66 0xA6
4 C 39 0x27 0x67 0xA7
C♯/D♭ 40 0x28 0x68 0xA8
D 41 0x29 0x69 0xA9
D♯/E♭ 42 0x2A 0x6A 0xAA
E 43 0x2B 0x6B 0xAB
F 44 0x2C 0x6C 0xAC
F♯/G♭ 45 0x2D 0x6D 0xAD
G 46 0x2E 0x6E 0xAE
G♯/A♭ 47 0x2F 0x6F 0xAF
A 48 0x30 0x70 0xB0
A♯/B♭ 49 0x31 0x71 0xB1
B 50 0x32 0x72 0xB2
5 C 51 0x33 0x73 0xB3
C♯/D♭ 52 0x34 0x74 0xB4
D 53 0x35 0x75 0xB5
D♯/E♭ 54 0x36 0x76 0xB6
E 55 0x37 0x77 0xB7
F 56 0x38 0x78 0xB8
F♯/G♭ 57 0x39 0x79 0xB9
G 58 0x3A 0x7A 0xBA
G♯/A♭ 59 0x3B 0x7B 0xBB
A 60 0x3C 0x7C 0xBC
A♯/B♭ 61 0x3D 0x7D 0xBD
B 62 0x3E 0x7E 0xBE
6 C 63 0x3F 0x7F 0xBF

Note durations

The effective duration of a note and the delay commands is based on the currently set sequence tempo. The duration of a single tick in seconds can be calculated using the following formular: time = 1.25 / tempo.

Note Ticks Duration (120 BPM)
whole 192 2s
half dotted (2nd + 4th) 144 1.5s
half 96 1s
quarter dottet (4th + 8th) 72 0.75s
quarter (4th) 48 0.5s
eighth dottet (8th + 16th) 36 0.375s
quarter tuplet 32 0.333s
eighth (8th) 24 0.25s
sixteenth dottet (16th + 32th) 18 0.1875s
eigthth tuplet 16 0.1666s
sixteenth (16th) 12 0.125s
32th dottet (32th + 64th) 9 0.09375s
sixteenth tuplet (16th) 8 0.08333s
32th 6 0.0625s
32th tuplet 4 0.041666s
64th 3 0.03125s
64th tuplet 2 0.0208333s

Create sequences

There are several ways for creating new sequence files.

Seq64

Seq64 is a GUI program for editing sequence files for Super Mario 64 and other Nintendo games. It also features full MIDI importing and exporting.

https://github.com/sauraen/seq64

Manually

Sequence files can also be created manually in a textual format. Create a new assembly file in the sequences directory, for example sound/sequences/us/23_custom_sequence.s. This file should begin with the following header:

.include "seq_macros.inc"
.section .rodata
.align 0

Next you can write down a series of commands. See include/seq_macros.inc or https://hackmd.io/opEB-OmxRa26P8h8pA-x7w for a list of available commands.

Commands

Sequence commands

Mnemonic Param 1 Param 2 Bytecode (US) Description
seq_end 0xff End of script, loop or function
seq_delay1 0xfe Delay for 1 tick
seq_delay ticks 0xfd, var Delay for X ticks
seq_call address 0xfc, addr Call a function
seq_jump address 0xfb, addr Jump to a point in the sequence script
seq_beqz address 0xfa, addr Jump if Q == 0, where Q is an s8 used to hold temporary sequence script state
seq_bltz address 0xf9, addr Jump if Q < 0
seq_loop iterations 0xf8, u8 Repeat until loopend for X iterations (256 if X = 0)
seq_loopend 0xf7 Loop end marker
seq_bgez address 0xf5, addr Jump if Q >= 0
seq_reservenotes numNotes 0xf2, u8 Reserve X notes for exclusive use by this sequence (dropping earlier reservations). A limited number of notes can be played at once (configurable per level, usually 16); if more than that are played, an existing one will be stopped and reused. This command can prevent that from happening across sequences.
seq_unreservenotes 0xf1 Drop all earlier reservations made by this sequence.
seq_transpose semitones 0xdf, s8 Set transposition in semitones.
seq_transposerel semitones 0xde, s8 Change transposition by some delta.
seq_settempo tempo 0xdd, u8 Set tempo in BPM.
seq_addtempo tempo 0xdc, s8 Change tempo by some delta.
seq_setvol volume 0xdb, u8 Set volume scale (0…255 = none to twice normal).
seq_changevol volume 0xda, s8 Change volume scale by some delta.
seq_initchannels channelMask 0xd7, u16 Initialize channels (bitmask). This copies mute behavior and note allocation policy.
seq_disablechannels channelMask 0xd6, u16 Uninitialize channels (bitmask).
seq_setmutescale mulitplier 0xd5, s8 Set volume multiplier for muted mode (0…127).
seq_mute 0xd4 Set sequence to muted mode. Depending on what behavior has been set this will do different things; from lowering volume to not running scripts.
seq_setmutebhv bitmask 0xd3, u8 Set mute behavior (bitmask). Bit 0x20 lowers volume, bit 0x40 does something to layers, and bit 0x80 pauses the sequence script. Default mute behavior is to have all of those bits set.
seq_setshortnotevelocitytable address 0xd2, addr Set velocity table for short notes (see further down). Target should be an array of bytes in the sequence data of length 16.
seq_setshortnotedurationtable address 0xd1, addr Set duration table for short notes (see further down). Target should be an array of bytes in the sequence data of length 16.
seq_setnoteallocationpolicy policyMask 0xd0, u8 Set note allocation policy (bitmask). If bit 0x1 is set, it will try to steal notes back from what was previously played on the same layer. If bit 0x2 is set, notes will be allocated exclusively from the channel’s reserved notes, else if 0x4 is set, from the channel’s or sequence’s reserved notes, else if 0x8 is set, from unreserved notes, otherwise from all sources. Not used by the game.
seq_setval value 0xcc, u8 Set Q to a constant.
seq_bitand value 0xc9, u8 Bitand Q by a constant.
seq_subtract value 0xc8, u8 Subtract a constant from Q.
seq_startchannel channel address 0x90-0x9f, addr Start channel N, with a given channel script.
seq_getvariation 0x80-0x8f Set Q to the variation bit, which is initially either 0 or 0x80 (i.e. -128, since Q is s8). This bit comes from the sequence load command. For instance, to play the Koopa shell music, the game plays sequence 0x8E, which is the same as sequence 0xE but with the variation bit set.
seq_setvariation 0x70-0x7f Set the variation bit to Q.
seq_subvariation 0x50-0x5f Subtract the variation bit from Q.
seq_testchdisabled channel 0x00-0x0f Set Q to 1 or 0, depending on whether channel N has been disabled by channel script.

Channel commands

Mnemonic Param 1 Param 2 Param 3 Bytecode (US) Description
chan_end 0xff End of script, loop or function
chan_delay1 0xfe Delay for 1 tick
chan_delay ticks 0xfd, var Delay for X ticks
chan_call address 0xfc, addr Call a function
chan_jump address 0xfb, addr Jump to a point in the channel script
chan_beqz address 0xfa, addr Jump if Q == 0, where Q is an s8 used to hold temporary channel script state
chan_bltz address 0xf9, addr Jump if Q < 0
chan_loop iterations 0xf8, u8 Repeat until loopend for X iterations (256 if X = 0)
chan_loopend 0xf7 Loop end marker
chan_break 0xf6 Decrease loop/function stack depth by 1. Combine with a jump to break out of a loop.
chan_bgez address 0xf5, addr Jump if Q >= 0
chan_hang 0xf3 Infinite delay.
chan_reservenotes numNotes 0xf2, u8 Reserve X notes for exclusive use by this channel (dropping earlier reservations).
chan_unreservenotes numNotes 0xf1 Drop all earlier reservations made by this channel.
chan_dyncall 0xe4 If Q != -1, make a function call to position dyntable[Q], where dyntable is a channel-specific u16 array which can set by setdyntable/dynsetdyntable.
chan_setvibratodelay 0xe3, u8 Set delay until vibrato starts for each note.
chan_setvibratoextentlinear 0xe2, u8, u8, u8 Set vibrato extent for each note as a function that starts at X, goes up linearly to Y over a time span given by Z, then stays there.
chan_setvibratoratelinear 0xe1, u8, u8, u8 Like above except for vibrato rate.
chan_setvolscale volume 0xe0, u8 Set scale factor for volume (0…255 = none to twice normal).
chan_setvol volume 0xdf, u8 Set scale factor #2 for volume (0…255 = none to twice normal). The two scale factors are separately controlled by outer audio logic, e.g. when changing between rooms, when playing sound effects, etc. The game almost exclusively uses setvol, so that should probably be preferred, but setvolscale shows up in a few locations in the sound effect sequence.
chan_freqscale value 0xde, u16 Pitch bend using a raw frequency multiplier X/2^15.
chan_setpan pan 0xdd, u8 Set the pan for this channel (0…128)
chan_setpanchanweight 0xdc, u8 The pan for each note will be computed as W * channel pan + (1 - W) * note pan. This sets W (0…128 maps to 0…1). W defaults to 1.0.
chan_transpose semitones 0xdb, s8 Set transposition in semitones.
chan_setenvelope address 0xda, addr Set ADSR envelope. See below for format.
chan_setdecayrelease rate 0xd9, u8 Set ADSR decay/release rate.
chan_setvibratoextent extent 0xd8, u8 Set vibrato extent.
chan_setvibratorate rate 0xd7, u8 Set vibrato rate.
chan_setupdatesperframe 0xd6, u8 Seems like it was meant to set the number of updates per frame? But it doesn’t actually do anything.
chan_setreverb reverb 0xd4, u8 Set amount of reverb (or “dry/wet mix”?).
chan_pitchbend bend 0xd3, s8 Pitch bend by <= 1 octave in either direction (-127…127).
chan_setsustain volume 0xd2, u8 Set ADSR sustain volume.
chan_setnoteallocationpolicy policyMask 0xd1, u8 Set note allocation policy for channel. See the description for sequence scripts.
chan_stereoheadseteffects enable 0xd0, u8 Enable (1) or disable (0) some pan/volume effects related to stereo/headset. I don’t know which ones precisely – pan is still taken into account even with this disabled. With this disabled, stereo/headset gets the same output.
chan_setval value 0xcc, u8 Set Q to a constant.
chan_readseq address 0xcb, addr Set Q to sequenceData[X + Q].
chan_setmutebhv 0xca, u8 Set mute behavior for this channel.
chan_bitand value 0xc9, u8 Bitand Q by a constant.
chan_subtract value 0xc8, u8 Subtract a constant from Q.
chan_writeseq address 0xc7, u8, addr Overwrite the byte at the given position in the sequence script by (Q + X).
chan_setbank bank 0xc6, u8 Switch bank within instrument bank sets, to the X’th bank, 0-indexed, counting from the end.
chan_dynsetdyntable 0xc5 If Q != -1, set dyntable to point to position dyntable[Q] in the sequence data.
chan_largenoteson 0xc4 Set notes for this channel to use “large notes” format. SM64 does this for all channels. (See note vs. shortnote in the layer section below.)
chan_largenotesoff 0xc3 Set notes for this channel to use “short notes” format.
chan_setdyntable address 0xc2, addr Set dyntable to point to a given u16 array from the sequence data.
chan_setinstr instrument 0xc1, u8 Set instrument (program?) within bank. 0x80-0x83 set raw waves (sawtooth, triangle, sine, square), 0x7f is special, otherwise 0-indexed.
chan_dynsetlayer 0xb0-0xbf If Q != -1, start layer N, with layer script given by dyntable[Q].
chan_freelayer layer 0xa0-0xaf Stop layer N.
chan_setlayer layer address 0x90-0x9f, addr Start layer N, with layer script starting at address X.
chan_ioreadval 0x80-0x8f Set Q to IO[N], where IO is an array of bytes that can be read/written by both the game and the channel script. If N < 4, IO[N] is then set to -1.
chan_iowriteval 0x70-0x7f Set IO[N] to Q.
chan_setnotepriority 0x60-0x6f Set note priority for later notes played on this channel to N. When the game wants to play a note and there aren’t any free notes available, a note with smaller or equal priority is discarded. Should be >= 2; 0 and 1 have internal meaning. Defaults to 3.
chan_ioreadvalsub 0x50-0x5f Decrease Q by IO[N].
chan_ioreadval2 0x40-0x4f, u8 Set Q to IO2[X], where IO2 is the IO array for channel N.
chan_iowriteval2 0x30-0x3f, u8 Set IO2[X] to Q, where IO2 is the IO array for channel N.
chan_disablechannel channel 0x20-0x2f Disable channel N for the parent sequence.
chan_startchannel channel address 0x10-0x1f, addr Start channel N for the parent sequence, with channel script starting at address X.
chan_testlayerfinished layer 0x00-0x0f Set Q to 1 or 0, depending on whether layer N has been disabled (either forcibly or by finishing its script).

Layer commands

Mnemonic Param 1 Param 2 Param 3 Param 4 Bytecode (US) Description
layer_end 0xff End of script, loop or function
layer_call address 0xfc, addr Call a function
layer_jump address 0xfb, addr Jump to a point in the layer script
layer_loop iterations 0xf8, u8 Repeat until loopend for X iterations (256 if X = 0)
layer_loopend 0xf7 Loop end marker
layer_setshortnotedurationfromtable 0xe0-0xef Set the duration for future short notes to table[N], where table defaults to {229, 203, 177, 151, 139, 126, 113, 100, 87, 74, 61, 48, 36, 23, 10, 0} and can be set by setshortnotedurationtable.
layer_setshortnotevelocityfromtable 0xd0-0xdf Set the velocity for future short notes to table[N], where table defaults to {12, 25, 38, 51, 57, 64, 71, 76, 83, 89, 96, 102, 109, 115, 121, 127} and can be set by setshortnotevelocitytable.
layer_setpan pan 0xca, u8 Set the pan for this layer (0…128).
layer_setshortnoteduration duration 0xc9, u8 Set the duration for future short notes.
layer_disableportamento 0xc8 Disable portamento for later notes.
layer_portamento 0xc7, u8, u8, u8/var Enable portamento (aka glissando; continuously sliding pitch). X describes the mode of operation somehow using its 0x80 bit and a value 0-5 in its lower-order bits. Y describes the target pitch. Z gives the duration, and is a u8 if the 0x80 bit is set, otherwise a var.
layer_setinstr instrument 0xc6, u8 Set instrument/program. Similar to the channel command, except arguments 0x7f and above are not supported.
layer_somethingoff 0xc5 Turn off some bool related to how notes decay somehow? (This is the default.)
layer_somethingon 0xc4 Turn on the same thing.
layer_setshortnotedefaultplaypercentage percentage 0xc3, var Set the default play percentage for short notes (see below).
layer_transpose semitones 0xc2, u8 Set transposition in semitones.
layer_setshortnotevelocity velocity 0xc1, u8 Set velocity for future short notes.
layer_delay ticks 0xc0, var Delay for N ticks
layer_note0 pitch percentage velocity duration 0x00-0x3f, var, u8, u8 Play note with specified pitch, percentage, velocity and duration. Only valid if channel is set to “large notes”.
layer_note1 pitch percentage velocity 0x40-0x7f, var, u8 Play note with specified pitch, percentage and velocity and duration of 0. Only valid if channel is set to “large notes”.
layer_note2 pitch velocity duration 0x80-0xbf, u8, u8 Play note with specified pitch, velocity and duration. Only valid if channel is set to “large notes”.
layer_smallnote0 pitch percentage 0x00-0x3f, var Play note with specified pitch and percentage and velocity and duration set with layer_setshortnotevelocity and layer_setshortnoteduration. Only valid if channel is set to “small notes”.
layer_smallnote1 pitch 0x40-0x7f Play note with specified pitch and the default play percentage, as set by layer_setshortnotedefaultplaypercentage (there is no built-in default; using it without that command will read uninitialized memory). Velocity and duration is set like in layer_smallnote0. Only valid if channel is set to “small notes”.
layer_smallnote2 pitch 0x80-0xbf Play note with specified pitch and the previous play percentage. Velocity and duration is set like in layer_smallnote0. Only valid if channel is set to “small notes”.

See also

Retrieved from "https://sm64decomp.tenry.net/wiki/index.php?title=Music_sequence&oldid=97"