| 1 | NES Music Format Spec |
| 2 | --------------------- |
| 3 | |
| 4 | |
| 5 | By: Kevin Horton khorton@iquest.net |
| 6 | |
| 7 | |
| 8 | NOTE: |
| 9 | ----- |
| 10 | |
| 11 | |
| 12 | Remember that I am very willing to add stuff and update this spec. If |
| 13 | you find a new sound chip or other change let me know and I will get back |
| 14 | with you. E-mail to the above address. |
| 15 | |
| 16 | |
| 17 | V1.61 - 06/27/2000 Updated spec a bit |
| 18 | V1.60 - 06/01/2000 Updated Sunsoft, MMC5, and Namco chip information |
| 19 | V1.50 - 05/28/2000 Updated FDS, added Sunsoft and Namco chips |
| 20 | V1.32 - 11/27/1999 Added MMC5 register locations |
| 21 | V1.30 - 11/14/1999 Added MMC5 audio bit, added some register info |
| 22 | V1.20 - 09/12/1999 VRC and FDS prelim sound info added |
| 23 | V1.00 - 05/11/1999 First official NSF specification file |
| 24 | |
| 25 | |
| 26 | |
| 27 | This file encompasses a way to transfer NES music data in a small, easy to |
| 28 | use format. |
| 29 | |
| 30 | The basic idea is one rips the music/sound code from an NES game and prepends |
| 31 | a small header to the data. |
| 32 | |
| 33 | A program of some form (6502/sound emulator) then takes the data and loads |
| 34 | it into the proper place into the 6502's address space, then inits and plays |
| 35 | the tune. |
| 36 | |
| 37 | Here's an overview of the header: |
| 38 | |
| 39 | offset # of bytes Function |
| 40 | ---------------------------- |
| 41 | |
| 42 | 0000 5 STRING "NESM",01Ah ; denotes an NES sound format file |
| 43 | 0005 1 BYTE Version number (currently 01h) |
| 44 | 0006 1 BYTE Total songs (1=1 song, 2=2 songs, etc) |
| 45 | 0007 1 BYTE Starting song (1= 1st song, 2=2nd song, etc) |
| 46 | 0008 2 WORD (lo/hi) load address of data (8000-FFFF) |
| 47 | 000a 2 WORD (lo/hi) init address of data (8000-FFFF) |
| 48 | 000c 2 WORD (lo/hi) play address of data (8000-FFFF) |
| 49 | 000e 32 STRING The name of the song, null terminated |
| 50 | 002e 32 STRING The artist, if known, null terminated |
| 51 | 004e 32 STRING The Copyright holder, null terminated |
| 52 | 006e 2 WORD (lo/hi) speed, in 1/1000000th sec ticks, NTSC (see text) |
| 53 | 0070 8 BYTE Bankswitch Init Values (see text, and FDS section) |
| 54 | 0078 2 WORD (lo/hi) speed, in 1/1000000th sec ticks, PAL (see text) |
| 55 | 007a 1 BYTE PAL/NTSC bits: |
| 56 | bit 0: if clear, this is an NTSC tune |
| 57 | bit 0: if set, this is a PAL tune |
| 58 | bit 1: if set, this is a dual PAL/NTSC tune |
| 59 | bits 2-7: not used. they *must* be 0 |
| 60 | 007b 1 BYTE Extra Sound Chip Support |
| 61 | bit 0: if set, this song uses VRCVI |
| 62 | bit 1: if set, this song uses VRCVII |
| 63 | bit 2: if set, this song uses FDS Sound |
| 64 | bit 3: if set, this song uses MMC5 audio |
| 65 | bit 4: if set, this song uses Namco 106 |
| 66 | bit 5: if set, this song uses Sunsoft FME-07 |
| 67 | bits 6,7: future expansion: they *must* be 0 |
| 68 | 007c 4 ---- 4 extra bytes for expansion (must be 00h) |
| 69 | 0080 nnn ---- The music program/data follows |
| 70 | |
| 71 | This may look somewhat familiar; if so that's because this is somewhat |
| 72 | sorta of based on the PSID file format for C64 music/sound. |
| 73 | |
| 74 | |
| 75 | Loading a tune into RAM |
| 76 | ----------------------- |
| 77 | |
| 78 | If offsets 0070h to 0077h have 00h in them, then bankswitching is *not* |
| 79 | used. If one or more bytes are something other than 00h then bankswitching |
| 80 | is used. If bankswitching is used then the load address is still used, |
| 81 | but you now use (ADDRESS AND 0FFFh) to determine where on the first bank |
| 82 | to load the data. |
| 83 | |
| 84 | |
| 85 | Each bank is 4K in size, and that means there are 8 of them for the |
| 86 | entire 08000h-0ffffh range in the 6502's address space. You determine where |
| 87 | in memory the data goes by setting bytes 070h thru 077h in the file. |
| 88 | These determine the inital bank values that will be used, and hence where |
| 89 | the data will be loaded into the address space. |
| 90 | |
| 91 | Here's an example: |
| 92 | |
| 93 | METROID.NSF will be used for the following explaination. |
| 94 | |
| 95 | The file is set up like so: (starting at 070h in the file) |
| 96 | |
| 97 | |
| 98 | 0070: 05 05 05 05 05 05 05 05 - 00 00 00 00 00 00 00 00 |
| 99 | 0080: ... music data goes here... |
| 100 | |
| 101 | Since 0070h-0077h are something other than 00h, then we know that this |
| 102 | tune uses bankswitching. The load address for the data is specified as |
| 103 | 08000h. We take this AND 0fffh and get 0000h, so we will load data in |
| 104 | at byte 0 of bank 0, since data is loaded into the banks sequentially |
| 105 | starting from bank 0 up until the music data is fully loaded. |
| 106 | |
| 107 | Metroid has 6 4K banks in it, numbered 0 through 5. The 6502's address |
| 108 | space has 8 4K bankswitchable blocks on it, starting at 08000h-08fffh, |
| 109 | 09000h-09fffh, 0a000h-0afffh ... 0f000h-0ffffh. Each one of these is 4K in |
| 110 | size, and the current bank is controlled by writes to 05ff8h thru 05fffh, |
| 111 | one byte per bank. So, 05ff8h controls the 08000h-08fffh range, 05ff9h |
| 112 | controls the 09000h-09fffh range, etc. up to 05fffh which controls the |
| 113 | 0f000h-0ffffh range. When the song is loaded into RAM, it is loaded into |
| 114 | the banks and not the 6502's address space. Once this is done, then the |
| 115 | bank control registers are written to set up the inital bank values. |
| 116 | To do this, the value at 0070h in the file is written to 05ff8h, 0071h |
| 117 | is written to 05ff9h, etc. all the way to 0077h is written to 05fffh. |
| 118 | This is should be done before every call to the init routine. |
| 119 | |
| 120 | If the tune was not bankswitched, then it is simply loaded in at the |
| 121 | specified load address, until EOF |
| 122 | |
| 123 | |
| 124 | Initalizing a tune |
| 125 | ------------------ |
| 126 | |
| 127 | This is pretty simple. Load the desired song # into the accumulator, |
| 128 | minus 1 and set the X register to specify PAL (X=1) or NTSC (X=0). |
| 129 | If this is a single standard tune (i.e. PAL *or* NTSC but not both) |
| 130 | then the X register contents should not matter. Once the song # and |
| 131 | optional PAL/NTSC standard are loaded, simply call the INIT address. |
| 132 | Once init is done, it should perform an RTS. |
| 133 | |
| 134 | |
| 135 | Playing a tune |
| 136 | -------------- |
| 137 | |
| 138 | Once the tune has been initalized, it can now be played. To do this, |
| 139 | simply call the play address several times a second. How many times |
| 140 | per second is determined by offsets 006eh and 006fh in the file. |
| 141 | These bytes denote the speed of playback in 1/1000000ths of a second. |
| 142 | For the "usual" 60Hz playback rate, set this to 411ah. |
| 143 | |
| 144 | To generate a differing playback rate, use this formula: |
| 145 | |
| 146 | |
| 147 | 1000000 |
| 148 | PBRATE= --------- |
| 149 | speed |
| 150 | |
| 151 | Where PBRATE is the value you stick into 006e/006fh in the file, and |
| 152 | speed is the desired speed in hertz. |
| 153 | |
| 154 | |
| 155 | "Proper" way to load the tune |
| 156 | ----------------------------- |
| 157 | |
| 158 | 1) If the tune is bankswitched, go to #3. |
| 159 | |
| 160 | 2) Load the data into the 6502's address space starting at the specified |
| 161 | load address. Go to #4. |
| 162 | |
| 163 | 3) Load the data into a RAM area, starting at (start_address AND 0fffh). |
| 164 | |
| 165 | 4) Tune load is done. |
| 166 | |
| 167 | |
| 168 | "Proper" way to init a tune |
| 169 | --------------------------- |
| 170 | |
| 171 | 1) Clear all RAM at 0000h-07ffh. |
| 172 | |
| 173 | 2) Clear all RAM at 6000h-7fffh. |
| 174 | |
| 175 | 3) Init the sound registers by writing 00h to 04000-0400Fh, 10h to 4010h, |
| 176 | and 00h to 4011h-4013h. |
| 177 | |
| 178 | 4) Set volume register 04015h to 00fh. |
| 179 | |
| 180 | 5) If this is a banked tune, load the bank values from the header into |
| 181 | 5ff8-5fffh. |
| 182 | |
| 183 | 6) Set the accumulator and X registers for the desired song. |
| 184 | |
| 185 | 7) Call the music init routine. |
| 186 | |
| 187 | |
| 188 | "Proper" way to play a tune |
| 189 | --------------------------- |
| 190 | |
| 191 | 1) Call the play address of the music at periodic intervals determined |
| 192 | by the speed words. Which word to use is determined by which mode |
| 193 | you are in- PAL or NTSC. |
| 194 | |
| 195 | |
| 196 | Sound Chip Support |
| 197 | ------------------ |
| 198 | |
| 199 | Byte 007bh of the file stores the sound chip flags. If a particular flag |
| 200 | is set, those sound registers should be enabled. If the flag is clear, |
| 201 | then those registers should be disabled. |
| 202 | |
| 203 | * VRCVI Uses registers 9000-9002, A000-A002, and B000-B002, write only. |
| 204 | |
| 205 | Caveats: 1) The above registers are *write only* and must not disrupt music |
| 206 | code that happens to be stored there. |
| 207 | |
| 208 | 2) Major caveat: The A0 and A1 lines are flipped on a few games!! |
| 209 | If you rip the music and it sounds all funny, flip around |
| 210 | the xxx1 and xxx2 register pairs. (i.e. 9001 and 9002) 9000 |
| 211 | and 9003 can be left untouched. I decided to do this since it |
| 212 | would make things easier all around, and this means you only |
| 213 | will have to change the music code in a very few places (6). |
| 214 | Esper2 and Madara will need this change, while Castlevania 3j |
| 215 | will not for instance. |
| 216 | |
| 217 | 3) See my VRCVI.TXT doc for a complete register description. |
| 218 | |
| 219 | * VRCVII Uses registers 9010 and 9030, write only. |
| 220 | |
| 221 | Caveats: 1) Same caveat as #1, above. |
| 222 | |
| 223 | 2) See my VRCVII.TXT doc for a complete register description. |
| 224 | |
| 225 | * FDS Sound uses registers from 4040 through 4092. |
| 226 | |
| 227 | Caveats: 1) 6000-DFFF is assumed to be RAM, since 6000-DFFF is RAM on the |
| 228 | FDS. E000-FFFF is usually not included in FDS games because |
| 229 | it is the BIOS ROM. However, it can be used on FDS rips to help |
| 230 | the ripper (for modified play/init addresses). |
| 231 | |
| 232 | 2) Bankswitching operates slightly different on FDS tunes. |
| 233 | 5FF6 and 5FF7 control the banks 6000-6FFF and 7000-7FFF |
| 234 | respectively. NSF header offsets 76h and 77h correspond to |
| 235 | *both* 6000-7FFF *AND* E000-FFFF. Keep this in mind! |
| 236 | |
| 237 | * MMC5 Sound Uses registers 5000-5015, write only as well as 5205 and 5206, |
| 238 | and 5C00-5FF5 |
| 239 | |
| 240 | Caveats: 1) Generating a proper doc file. Be patient. |
| 241 | |
| 242 | 2) 5205 and 5206 are a hardware 8*8 multiplier. The idea being |
| 243 | you write your two bytes to be multiplied into 5205 and 5206 |
| 244 | and after doing so, you read the result back out. Still working |
| 245 | on what exactly triggers it (I think a write to either 5205 |
| 246 | or 5206 triggers the multiply). |
| 247 | |
| 248 | 3) 5C00-5FF5 should be RAM to emulate EXRAM while in MMC5 mode. |
| 249 | |
| 250 | Note: Thanks to Mamiya for the EXRAM info. |
| 251 | |
| 252 | |
| 253 | * Namco 106 Sound Uses registers 4800 and F800. |
| 254 | |
| 255 | This works similar to VRC7. 4800 is the "data" port which is |
| 256 | readable and writable, while F800 is the "address" port and is |
| 257 | writable only. |
| 258 | |
| 259 | The address is 7 bits plus a "mode" bit. Bit 7 controls |
| 260 | address auto-incrementing. If bit 7 is set, the address will |
| 261 | auto-increment after a byte of data is read or written from/to |
| 262 | 4800. |
| 263 | |
| 264 | $40 ffffffff f:frequency L |
| 265 | $42 ffffffff f:frequency M |
| 266 | $44 ---sssff f:frequency H s:tone length (8-s)*4 in 4bit-samples |
| 267 | $46 tttttttt t:tone address(4bit-address,$41 means high-4bits of $20) |
| 268 | $47 -cccvvvv v:linear volume 1+c:number of channels in use($7F only) |
| 269 | $40-47:ch1 $48-4F:ch2 ... $78-7F:ch8 |
| 270 | ch2-ch8 same to ch1 |
| 271 | |
| 272 | $00-3F(8ch)...77(1ch) hhhhllll tone data |
| 273 | h:odd address data(signed 4bit) |
| 274 | l:even address data(signed 4bit) |
| 275 | |
| 276 | real frequency = (f * NES_BASECYCLES) / (40000h * (c+1) * (8-s)*4 * 45) |
| 277 | NES_BASECYCLES 21477270(Hz) |
| 278 | |
| 279 | Note: Very Special thanks to Mamiya for this information! |
| 280 | |
| 281 | |
| 282 | * Sunsoft FME-07 Sound uses registers C000 and E000 |
| 283 | |
| 284 | This is similar to the common AY 3-8910 sound chip that is |
| 285 | used on tons of arcade machines, and in the Intellivision. |
| 286 | |
| 287 | C000 is the address port |
| 288 | E000 is the data port |
| 289 | |
| 290 | Both are write-only, and behave like the AY 3-8910. |
| 291 | |
| 292 | Note: Special thanks to Mamiya for this information as well |
| 293 | |
| 294 | |
| 295 | Caveats |
| 296 | ------- |
| 297 | |
| 298 | 1) The starting song number and maximum song numbers start counting at |
| 299 | 1, while the init address of the tune starts counting at 0. To |
| 300 | "fix", simply pass the desired song number minus 1 to the init |
| 301 | routine. |
| 302 | |
| 303 | 2) The NTSC speed word is used *only* for NTSC tunes, or dual PAL/NTSC tunes. |
| 304 | The PAL speed word is used *only* for PAL tunes, or dual PAL/NTSC tunes. |
| 305 | |
| 306 | 3) The length of the text in the name, artist, and copyright fields must |
| 307 | be 31 characters or less! There has to be at least a single NULL byte |
| 308 | (00h) after the text, between fields. |
| 309 | |
| 310 | 4) If a field is not known (name, artist, copyright) then the field must |
| 311 | contain the string "<?>" (without quotes). |
| 312 | |
| 313 | 5) There should be 8K of RAM present at 6000-7FFFh. MMC5 tunes need RAM at |
| 314 | 5C00-5FF7 to emulate its EXRAM. 8000-FFFF Should be read-only (not |
| 315 | writable) after a tune has loaded. The only time this area should be |
| 316 | writable is if an FDS tune is being played. |
| 317 | |
| 318 | 6) Do not assume the state of *anything* on entry to the init routine |
| 319 | except A and X. Y can be anything, as can the flags. |
| 320 | |
| 321 | 7) Do not assume the state of *anything* on entry to the play routine either. |
| 322 | Flags, X, A, and Y could be at any state. I've fixed about 10 tunes |
| 323 | because of this problem and the problem, above. |
| 324 | |
| 325 | 8) The stack sits at 1FFh and grows down. Make sure the tune does not |
| 326 | attempt to use 1F0h-1FFh for variables. (Armed Dragon Villigust did and |
| 327 | I had to relocate its RAM usage to 2xx) |
| 328 | |
| 329 | 9) Variables should sit in the 0000h-07FFh area *only*. If the tune writes |
| 330 | outside this range, say 1400h this is bad and should be relocated. |
| 331 | (Terminator 3 did this and I relocated it to 04xx). |
| 332 | |
| 333 | That's it! |
| 334 | |
| 335 | |
| 336 | |