1                          NSF format spec version 2
2
3                    by Benjamin Gerard <ben@sashipa.com>
4
5                                 2003/04/25
6
7
8Abstract:
9
10   This document describes the NSF (Nintendo Sound Format) version 2 file.
11   It explains why I have made a new version of this format. The information
12   on the NSF1 file format comes from nsfspec.txt by Kevin Horton
13   <khorton@iquest.net>.
14
15Introduction:
16
17    NSF version 1 format was a rigid format. As I want to add play time
18    information precalculated for each songs in the file, I have to modify
19    the current file format. By the way, I have tried to make a more
20    flexible format so that people can add other information in NSF files
21    (like date, ripper ...). Others improvements has been added and will be
22    explain in this documentation.
23
24Portability:
25
26    The NSF2 should be backward compatible with NSF1. This means that old
27    NSF player should be able to load NSF2 files (without extra
28    information).  Obviously NSF2 file loader is able to load either NSF1 or
29    NSF2 files. NSF2 loader can skip unknown additional information, so any
30    additional information can be added to NSF2 file as soon it respect the
31    format definition.
32
33NSF1 file format:
34
35    NSF1 file format starts with a 128 bytes header which is followed by
36    song data. The length of the data must be determined by the file length.
37    This can be a problem if you want to play NSF file thru file transfer
38    protocol that does not handle stream length.
39
40    Multi byte values are stored in little endian (LSB first).
41    BYTE : 1 byte unsigned (0..255)
42    WORD : 2 bytes unsigned (0..65536)
43    LONG : 4 bytes unsigned (0..2^32-1)
44
45    NSF1 header overview:
46
47    Offset  Size  Type   Description
48
49    0000     5   STRING  "NESM",01Ah  ; denotes an NES sound format file
50    0005     1   BYTE    Version number (currently 01h)
51    0006     1   BYTE    Total songs   (1=1 song, 2=2 songs, etc)
52    0007     1   BYTE    Starting song (1= 1st song, 2=2nd song, etc)
53    0008     2   WORD    (lo/hi) load address of data (8000-FFFF)
54    000a     2   WORD    (lo/hi) init address of data (8000-FFFF)
55    000c     2   WORD    (lo/hi) play address of data (8000-FFFF)
56    000e     32  STRING  The name of the song, null terminated
57    002e     32  STRING  The artist, if known, null terminated
58    004e     32  STRING  The Copyright holder, null terminated
59    006e     2   WORD    (lo/hi) speed, in 1/1000000th sec ticks, NTSC
60    0070     8   BYTE    Bankswitch Init Values (see text, and FDS section)
61    0078     2   WORD    (lo/hi) speed, in 1/1000000th sec ticks, PAL
62    007a     1   BYTE    PAL/NTSC bits:
63                 bit 0: if clear, this is an NTSC tune
64                 bit 0: if set, this is a PAL tune
65                 bit 1: if set, this is a dual PAL/NTSC tune
66                 bits 2-7: not used. they *must* be 0
67    007b    1   BYTE    Extra Sound Chip Support
68                 bit 0: if set, this song uses VRCVI
69                 bit 1: if set, this song uses VRCVII
70                 bit 2: if set, this song uses FDS Sound
71                 bit 3: if set, this song uses MMC5 audio
72                 bit 4: if set, this song uses Namco 106
73                 bit 5: if set, this song uses Sunsoft FME-07
74                 bits 6,7: future expansion: they *must* be 0
75    007c    4   ----    4 extra bytes for expansion (must be 00h)
76    0080    nnn ----    The music program/data follows
77
78NSF2 file format:
79
80    NSF2 file format starts with the same header than NSF1 excepted that
81    the version number (offset 5) is set to 2 and that the 3 first bytes of
82    reserved contains the length in bytes of the data section (stored as a
83    LONG but without the MSB which is reserved for future used and must be
84    set to 0).
85
86    At the end of the data section, the file may contain extra information
87    stored within chunks.
88
89    Extra Chunk format:
90
91    Offset  Size  Type   Description
92
93    0000       4  STRING "NESM" ; denotes an extension.
94    0004       4  STRING TYPE   ; type of extension.
95    0008       4  LONG   SIZE   ; Extension total size (including this header)
96    000C  SIZE-12               ; Extension data (depends on TYPE)
97
98    The number of extra format chunk is unlimited. The loader can skip unknown
99    TYPE because it knows its size.
100
101    Currently only one TYPE has been defined : "TIME". It handles songs
102    playing time. The data of "TIME" chunk is an array of LONG which values
103    give the song length in frames. The first LONG gives the total number of
104    frame for all songs. In most case the size of the array is number of
105    songs + 1. But the current loader is able to load less or more entry.
106    In case there is less entry than the number of song, the missing entries
107    are set to zero, which mean no time info for this song.
108
109
110