User:Zzo38/Compound NSF

This is a draft proposal of "Compound NSF" format. The file is a Hamster archive. All chunks are optional other than PAYLOAD.NSF. Unrecognized chunks should be ignored. An implementation does not need to read all chunks; it can skip any chunk that it doesn't need.

Hamster archive is an archive format used by OHRRPGCE. Each file in the archive, or "lump", consists of an ASCII filename, a NUL byte ($00), a length in PDP-11 byte order (medium high byte, high byte, low byte, medium low byte), and the file contents. Filenames are case-insensitive, and contents are uncompressed. The HAMARC tool manipulates Hamster archives.

COMPOSER.TXT

List of composers of each song, one per each line. First line for song $00, second line for song $01, etc.

CONTROLS.BIN

Contains a number of small-endian 16-bit numbers for various optional features. List using word offsets (not byte offsets):

• $00: Start RAM offset to load random data into.
• $01: End RAM offset to load random data into. If supported, all from the start and end offset but not including the end offset, must be RAM addresses, and are filled with random data before calling init.
• $02: If nonzero, write to this RAM address (just before calling play) to request to start a sound effect.
• $03: If nonzero, write to this RAM address to request to stop a sound effect.
• $04: If nonzero, read this RAM address just after play/init returns for trigger events (similar to FastTracker's Wxx command).
• $05: The suggested console variant to emulate for mixing purposes: 0=nothing specified, 1=RF Famicom, 2=AV Famicom, 3=NTSC NES, 4=PAL NES.

Notes:

• If the start and end address of random data are both the same (such as both zero), then this function is not used.
• If random data isn't supported, the contents of RAM will be zeroed out, as per the standard NSF specification.
• The RAM addresses to request sound effects would probably not be used when playing back on an actual NES/Famicom, nor in most other cases. It may be used when the NSF is used in a game for PC or another system; for example if MegaZeux hypothetically supported this format, the MOD SAM command would poke its second parameter into the RAM address given at word offset $02 (and ignore the first parameter).
• Requesting to start a sound effect here does not necessarily actually mean to start a sound effect; the NSF code may do other things with it, such as add/remove/change accompaniment, change the playback rate, play the music an octave lower, transpose into a minor key, start playing backwards from the current point, etc.
• The trigger events also aren't used in an actual NES/Famicom (although it is still possible, such as to implement visuals) nor in most other cases.
• The console variant field is not used for hardware playback. Emulators may choose to use this information to decide mixing volume in order to sound more like the console that the game was tested on or that the music was written for. People who make up their own NSF though should be aware that this can be ignored like everything else outside of the PAYLOAD.NSF lump.

DURATION.TXT

Default duration for each song when using with playlists, in frames.

PAYLOAD.NSF

This chunk has the same as ordinary NSF (version 1) except the header modified as follows:

• Offset $006: If this is zero, then there are 256 songs in total.
• Offset $007: If this is zero, then the default song is number $FF.
• Offset $07C: Volume controls. Bit3 is MMC5 volume and bit2-bit0 is N163 volume. Other bits should always be clear. (This may be subject to moving to another offset for compatibility with NSF2)

MMC5 volume:

• 0 = use default (same as 2A03 square waves)
• 1 = use marked resistance value

N163 volume:

• 0 = default (automatically)
• 1 = 3.6x (Final Lap)
• 2 = 4.0x (Megami Tensei II)
• 3 = 6.0x
• 4 = 6.5x (Rolling Thunder)
• 5 = 7.3x (King of Kings)
• 6 = 8.0x
• 7 = 8.5x (Erika to Satoru no Yumebouken)

Notes:

• Adding ADPCM would be a mess (for several reasons, including that different cartridges use different addresses, and that it won't be able to load a copy of the ROM into original hardware (although it may still be usable with clone hardware)), although it is unlikely that ADPCM would be needed for music, so it is probably OK to not add it.
• An expansion chip that may be added in future though may be UNL-DripGame. (Would probably use $5000 read-only and $5800 read-only and $8000-$8007 write-only.)
• If the new features listed above aren't used, then you can simply extract this lump into a separate file and use any ordinary NSF playback program. It might also be possible to use the volume controls without confusing some existing software (although the playback volume might then be wrong).

SONGTYPE.BIN

Starting bit7 of first byte for song $00, bit6 for song $01, etc, having 32 bytes in total, bit is set if it is a sound effect rather than a full song.

TITLE.TXT

List of song titles, one per each line. First line for song $00, second line for song $01, etc.