NSFe

From Nesdev wiki
Jump to: navigation, search


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.

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.

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.
  • There is no custom playback speed; the play routine will be called at the NMI rate for the specified system (NTSC or PAL).
  • 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.

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.

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 recieve a default label (or no label) according to the player. Extra strings can be ignored.

auth

This optional chunk contains four null-terminated strings describing in order:

  1. Game title
  2. Artist
  3. Copyright
  4. 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.

References