NSFe
NSFe is the Extended Nintendo Sound Format created by Disch and popularized by the NotSoFatso NSF player. It is based on the original NSF file format, but its data is organized differently and is not backward compatible with it.
Structure
The NSFe begins with a four byte header, containing the four characters 'NSFE'.
offset # of bytes Function ---------------------------- $0000 4 FOURCC 'N','S','F','E' (header)
After the header, a series of chunks will appear.
UTF-8 encoding is recommended for all strings used by this format.
Chunks
All chunks have the same primary structure:
offset # of bytes Function ---------------------------- $0000 4 DWORD Length of chunk data (n). Does not include the chunk's 8 byte header. $0004 4 FOURCC Four character chunk ID. $0008 n ---- Chunk data of specified length.
There are three chunks that are required for a well formed NSFe:
- 'INFO' - Similar to an NSF header, must appear before 'DATA' chunk.
- 'DATA' - Raw ROM data.
- 'NEND' - Last NSFe chunk in file.
Note the 'INFO' chunk must precede the 'DATA' chunk, and the 'NEND' chunk marks the end of the file; no further chunks should be read past 'NEND'.
If the first byte of a chunk's FourCC ID is a capital letter (i.e. 'A' to 'Z'), it indicates that this chunk is mandatory, and if the NSFe player cannot read this type of chunk it should not attempt to play the file. All other chunks are considered optional, and may be skipped by the NSFe player if necessary.
The NSFe format does not have a version number. Future revisions of the format, if necessary, can be accomplished with new mandatory chunk types.
INFO
This required chunk describes the music data contained. This is similar to the NSF header.
offset # of bytes Function
----------------------------
$0000 2 WORD (lo, hi) load address of data ($8000-FFFF)
$0002 2 WORD (lo, hi) init address of data ($8000-FFFF)
$0004 2 WORD (lo, hi) play address of data ($8000-FFFF)
$0006 1 BYTE PAL/NTSC bits
bit 0: if clear, this is an NTSC tune
bit 0: if set, this is a PAL tune
bit 1: if set, this is a dual PAL/NTSC tune
bits 2-7: not used. they *must* be 0
$0007 1 BYTE Extra Sound Chip Support
bit 0: if set, this song uses VRC6 audio
bit 1: if set, this song uses VRC7 audio
bit 2: if set, this song uses FDS audio
bit 3: if set, this song uses MMC5 audio
bit 4: if set, this song uses Namco 163 audio
bit 5: if set, this song uses Sunsoft 5B audio
bits 6,7: future expansion: they *must* be 0
$0008 1 BYTE Total songs (1=1 song, 2=2 songs, etc)
$0009 1 BYTE Starting song (0=1st song, 1=2nd song, etc)
Note the following differences from NSF:
- Title, author, and copyright information is not mandatory. See the 'auth' chunk for details.
- If bankswitching is required, it is specified in a subsequent 'BANK' chunk.
- The play routine will be called at the NMI rate for the specified system (NTSC or PAL) unless a 'RATE' chunk is used.
- The first song in the NSFe is 0, unlike NSF which begins with 1.
This chunk must be at least 9 bytes long. If starting song is missing, 0 may be assumed. Any extra data in this chunk may be ignored.
DATA
This chunk contains the raw ROM data. It will be placed at the load address specified by the 'INFO' chunk, unless bankswitched (the same as in NSF). There is no minimum length for this chunk, but data past 1MB is unusable due to the bank switching mechanisms of the NSF mapper.
NEND
This chunk may be any length, but any contained data may be ignored. Typically it will have 0 length.
There should be no chunks following the 'NEND' chunk.
BANK
If the bank chunk is present, this NSFe should use bankswitching, and it contains 8 bytes specifying the 8 banks to initialize with. See NSF for bankswitching details.
If this chunk is less than 8 bytes, presume 0 for the missing bytes. If longer, ignore the extra bytes.
RATE
offset # of bytes Function ---------------------------- $0000 2 WORD (lo, hi) Play speed, in 1/1000000th sec ticks, NTSC $0002 2 WORD (lo, hi) Play speed, in 1/1000000th sec ticks, PAL (Optional) $0004 2 WORD (lo, hi) Play speed, in 1/1000000th sec ticks, Dendy (Optional)
This chunk has 4 bytes. If present, the NSFe should use a custom rate for calling the PLAY routine. See equivalent in NSF header at $06E and $078.
If the NSFe uses the default video refresh rates for PLAY, this chunk should be omitted for compatibility with older players.
If the Dendy speed is omitted, any Dendy playback should use the PAL speed. (If the PAL speed is omitted, its default rate should be used.) Use with the regn chunk to enable Dendy playback.
(Added 2018-1-2)
plst
This optional chunk specifies the order in which to play tracks. Each byte specifies a track from the NSFe (note that the first track in the NSFe is track 0).
The length of the playlist is specified by the length of this chunk. It is not required to play all tracks, and they may be duplicated.
A player should normally stop when the playlist is finished. It may be useful to allow the user to turn off the playlist and select tracks from the NSFe manually.
psfx
This optional chunk contains a tracks which are "sound effects" rather than music. Each byte specifies a track from the NSFe (note that the first track in the NSFe is track 0).
The length of this list is specified by the length of this chunk. Duplicate tracks may appear.
A player implementation may treat this as an optional alternate playlist for sound effects, like the 'plst' chunk above, where the 'plst' is the music only playlist, and 'psfx' is the sound effects playlist. It can also be treated as adding a "sound effect" flag to every listed track. (As a result, the user could be given the option not to listen to sound effects.)
(Added 2018-8-25)
time
This optional chunk contains a list of 4 byte signed integers. Each integer represents the length in milliseconds for the corresponding NSFe track. Note this is unrelated to the 'plst' chunk; the times are for the tracks in the NSFe, not the tracks int he playlist. When the track has played for the specified time, it should begin fading out. A time of 0 is valid, and should begin fadeout immediately. A time of less than 0 represents the "default" time, which should be handled accordingly by the player.
This chunk should come after the 'INFO' chunk, so that the number of tracks is already known.
If this chunk is not long enough to specify all tracks in the NSF, a default time should be assumed for these tracks. Any extra data should be ignored.
fade
This optional chunk contains a list of 4 byte signed integers. It is like the 'time' chunk, but instead specifies a fadeout length in milliseconds for each track. A fade time of 0 means the track should immediately end rather than fading out. A fade time of less than 0 represents the default fade time.
This chunk should come after the 'INFO' chunk, so that the number of tracks is already known.
If this chunk is not long enough to specify all tracks in the NSF, a default time should be assumed for these tracks. Any extra data should be ignored.
tlbl
This optional chunk contains names for each track (tlbl = track label). This contains a series of null-terminated strings, in track order. (Like 'time' and 'fade', this is not related to the 'plst' chunk's playlist.)
This chunk should come after the 'INFO' chunk, so that the number of tracks is already known.
If there are not enough strings for every track, subsequent tracks should receive a default label (or no label) according to the player. Extra strings can be ignored.
taut
This optional chunk contains an author name for each track (taut = track author), useful if several composers contributed to this NSF. This contains a series of null-terminated strings, in track order. (Not related to 'plst' order.)
This chunk should come after the 'INFO' chunk, so that the number of tracks is already known.
If there are not enough strings for every track, subsequent tracks should receive an empty author. Extra strings can be ignored.
(Added 2018-8-25)
auth
This optional chunk contains four null-terminated strings describing in order:
- Game title
- Artist
- Copyright
- Ripper
If not all strings are present, a default string (typically "<?>") can be assumed by the player.
text
This optional chunk contains a single null-terminated string of any length. This may include a description of the contents, or any message from the author.
Newlines may either be CR+LF or LF, as commonly found in text files.
(Added 2012-12-16)
mixe
offset # of bytes Function ---------------------------- $0000 1 BYTE Specify output device (see below), 0 for end of list. $0001 2 WORD Signed 16-bit integer specifying millibels (1/100 dB) comparison with APU square volume
This optional chunk contains a list of output devices, and mixing information for each of them.
The comparison specifies relatively how loud a square wave played on the device at maximum volume (or other suitable waveform) compared to one at the same frequency from the built-in APU square channel.
The primary use of this is for N163 games, which mix the expansion audio at different levels on a per-game basis. For other expansion audio there is no evidence of variation on that basis, so this chunk is not necessary for those. A default value may be assumed if this chunk is not present, or if a present expansion device is not given in this chunk.
It may also be useful for homebrew music, especially multi-chip NSF, where the user may wish to be specific about the mix.
Device byte values:
- 0 - Marks the end of list (optional), all data in the chunk after this will be ignored.
- 1 - APU Tri / Noise / DPCM - Compares a full volume PCM square to the APU - Default: TO DO *
- 2 - VRC6 - Default: 0
- 3 - VRC7 - Comparison: TO DO *
- 4 - FDS - Default: 760
- 5 - MMC5 - Default: 0
- 6 - N163 - Default: 1100 or 1860 *
- 7 - Sunsoft 5B - Default: TO DO *
Note: This is a new chunk specification. Default values are under active investigation. Test NSFe and ROMs to measure these values are forthcoming. VRC7 cannot produce a square wave, another suitable test will be investigated. Sunsoft 5B may have internal clipping, which will have to be accommodated for its test.
(Added 2018-8-6)
regn
offset # of bytes Function
----------------------------
$0000 1 BYTE Bitfield of supported regions.
bit 0: NTSC
bit 1: PAL
bit 2: Dendy
bit 3-7: Reserved (always clear)
$0001 1 BYTE Specifies preferred region if multiple regions are supported. (Optional)
0 - NTSC
1 - PAL
2 - Dendy
This chunk adds support for the Dendy region, and the ability to specify which region is preferred (for players that can support multiple regions). This chunk should appear after the INFO chunk, and overrides its region data (byte 6).
If this chunk is present, and Dendy region is chosen by the player, the X register should be set to 2 for the INIT call. If otherwise unspecified, Dendy playback will use the PAL rate (see RATE chunk above).
(Added 2018-8-21)
