NSF File Format

From vgmrips
Jump to: navigation, search

NSF (Nintendo Sound Format) is an emulated format for music of NES and Famicom. The implementation is a 6502 without decimal mode (but including all unofficial opcodes) (decimal flag still exists, but arithmetic is always done in binary regardless of this setting).

Header format

All numbers are in small-endian format.

Address Size Description
$00 6 File format identification ("NESM",$1A,$01)
$06 1 Number of tracks
$07 1 Default track number plus one
$08 2 Load address (must be $8000-$FFFF)
$0A 2 Init address (must be $8000-$FFFF)
$0C 2 Play address
$0E 32 Null terminated title in ASCII format
$2E 32 Null terminated composer in ASCII format
$4E 32 Null terminated copyright in ASCII format
$6E 2 NTSC framerate in microseconds (not always in use)
$70 8 Bankswitching setting
$78 2 PAL framerate in microseconds (not always in use)
$7A 1 TV system: 0=NTSC, 1=PAL, 2=both
$7B 1 Expansion audio
$7C 4 Reserved (must be set to zero)

Any text string in the header which is not specified should be <?> by default.

File loading

Everything starting after the header (which is 128 bytes long) is loaded starting at the specified load address, if all of the bankswitching setting is set to zero. Everything else in the file which does not exist is considered all as zero.

If bankswitching setting is not all zero, then only the low twelve bits of the load address are used. This specifies the amount of padding at the beginning of bank zero, and then all 4K banks are loaded in order from the file. In this case, the bankswitching setting indicates the initial bank number at $8xxx, $9xxx, $Axxx, etc.

If bit2 of the expansion audio flag is set, then the same bank loaded into $Exxx is also initially loaded at $6xxx, and the same bank loaded into $Fxxx is also initially loaded into $7xxx.

Initialization and playback

Initialization step as follows:

  • All RAM at $0000-$07FF is cleared.
  • All RAM at $6000-$7FFF is cleared if bit2 of expansion audio flag is not set.
  • All 2A03 APU registers are initialized to zero, except for $4015 which should be initialized to fifteen (although some players may not do this, so be careful please), and I/O ports which are implementation-dependent, and OAM DMA which is not used at all.
  • Frame counter must be in 4-steps mode, although use of interrupts or not is implementation-specific.
  • Reload initial bank settings if applicable.
  • Initialize stack register according to what the implementation needs.
  • Set A register to the (zero-based) track number that you want to play.
  • Set X register to 0 for NTSC or 1 for PAL.
  • Contents of Y register and flags are unspecified.
  • Call the init subroutine. Wait until it returns before continuing. How it knows if it return is implementation-dependent, although RTS instruction will always work if the stack register has not been tampered with.

During playback, during each frame it should call the play subroutine. Value of registers and flags when entering is unspecified. It should not try to call it again until after it has returned. Returning is same as returning from init.

The 6502 codes inside of the .NSF file should never tamper with interrupts in any way (and don't use BRK instruction, since it causes interrupts).

Sound chips

2A03 (always activated):

  • Registers usable are $4000-$4013 and $4015. Interrupts should not be enabled.

Konami VRC6 (bit0 in expansion flag):

  • Registers usable are $9000-$9003, $A000-$A003, $B000-$B002, and are write-only. Order of registers is according to iNES mapper 24 (the game is called 悪魔城伝説).
  • Present on-board the carts for the games: Akumajou Densetsu, Madara and Esper Dream 2.

Konami VRC7 (bit1 in expansion flag):

  • Registers usable are $9010 and $9030, and are write-only.
  • Present on-board the cart for the game Lagrange Point.

2C33 (bit2 in expansion flag):

  • Registers usable are $4040-$4092.
  • Sound chip for the Famicom Disk System
  • Setting this also enables $6000-$DFFF to be RAM and is therefore writable and can be updated (although $E000-$FFFF is write-protected, even though it might still be RAM).
  • Whether or not the contents of FDS RAM is reset on init and on bankswitching is undefined. It is also undefined whether or not writes to RAM in one bank will affect data at other addresses mapped to the same bank.

MMC5 (bit3 in expansion flag):

  • Registers $5000-$5015 are write-only and used for audio.
  • Register $5205 and $5206 are read/write.
  • There is ExRAM at $5C00-$5FFF. This is always in read/write mode. (It overlaps the bankswitching registers, but that is OK.)
  • Present on-board the cart for the games: Just Breed, Metal Slader Glory, Shin 4-Nin Uchi Mahjong.

Namco N163 (bit4 in expansion flag):

  • Registers $4800 and $F800 are used.
  • Present on-board the cart for the games: Erika to Satoru no Yumebouken, Final Lap, King of Kings, Mappy Kids, Megami Tensei II: Digital Devil Story, Namco Classic 2, Rolling Thunder, Sangokushi, Sangokushi 2.

Sunsoft 5B (bit5 in expansion flag):

  • Registers $C000 and $E000 (write-only) are used. This is a YM2149F, where $C000 sets the address (device number zero) and $E000 sets the data. I/O ports are not connected to anything.
  • Present on-board the cart for the game Gimmick!

NEC µPD7756C:

  • Not supported

Mitsubishi M50805:

  • Not supported

It is permitted to use multiple expansion audio at once. There are no conflicts because only the specified addresses of registers are used and not mirrored addresses. However, writes to some registers might also write to FDS RAM if FDS is also activated.

Memory map

Reading:

  • $0000-$07FF is RAM. However, addresses $0100-$01EF is part of the stack and may be reserved by the player. The NSF code should not access it except that part of it may be a stack assigned to the NSF code, and in that case it is OK to be accessed.
  • $4015 (2A03)
  • $4040-$407F, $4090, $4092 (FDS audio; use only if FDS is activated)
  • $4800 (use only if Namco audio is activated)
  • $5205-$5206 (only if MMC5 is activated)
  • $5C00-$5FF7 is ExRAM (only if MMC5 is activated)
  • $6000-$7FFF (RAM)
  • $8000-$FFF9 (ROM; $8000-$DFFF is RAM if FDS is activated) (addresses $FFFA-$FFFF may be reserved by the player)

Writing:

  • $0000-$07FF is RAM. See above about notes of $0100-$01EF.
  • $4000-$4013, $4015 (2A03)
  • $4040-$407F, $4090, $4092 (FDS audio; use only if FDS is activated)
  • $4800 (use only if Namco audio is activated)
  • $5000-$5015 (only if MMC5 audio is activated)
  • $5205-$5206 (only if MMC5 is activated)
  • $5C00-$5FF7 is ExRAM (only if MMC5 is activated)
  • $5FF6-$5FF7 (only if both bankswitching and FDS is activated; set 4K banks for $6xxx and $7xxx)
  • $5FF8-$5FFF (only if bankswitching is activated; set 4K banks for $8xxx up to $Fxxx)
  • $6000-$7FFF (RAM)
  • $9000-$9003, $A000-$A003, $B000-$B002 (use only if VRC6 audio is activated)
  • $C000, $E000 (use only if Sunsoft audio is activated)
  • $F800 (only for Namco 163 audio, if it is activated)

Note that use of mirrors is not allowed; any addresses not specified above are implementation-dependent and should not be touched by NSF code; they may be used by the player for some purpose.


External Links

Players

Composition tools

  • FamiTracker -- tracker music
  • Deflemask -- tracker music. Does not use register $4017 for DPCM but rather 7-bit PCM samples
  • NerdTracker -- tracker music (pretty old)
  • MuseTracker -- tracker music (somewhat old). Does not use register $4017 for DPCM but rather 7-bit PCM samples. Formerly called PornoTracker
  • SuperNSF -- tracker music. Abuses register $4011 for 4 channels of 7-bit PCM streaming. Must convert from an .it file
  • it2nsf -- tracker music. Must convert from an .it file
  • ppMCK -- MML compiler
  • nsd.lib -- MML compiler
  • NTRQ -- native tracker, runs on NES or emulator
  • Pulsar -- native tracker, runs on NES or emulator
  • It is also possible, due to the way the format works, that you can write a program in 6502 code which will parse and interpret data which is appended to the end of a NSF stub (which can be in other file formats).

Documents