mirror of
https://github.com/OldUnreal/libxmp.git
synced 2026-04-02 21:37:43 -07:00
275 lines
14 KiB
Plaintext
275 lines
14 KiB
Plaintext
|
|
Introduction.
|
|
=============
|
|
|
|
The text below was intended to be the documentation on the fileformat used
|
|
in this release of ProTracker. However, we decided to wait with the actual
|
|
implementation of the format until having released a couple of versions,
|
|
because we'd like to hear some comments, suggestions etc. upon it first.
|
|
So read it lightly, and feel free to post your opinion to one of the authors
|
|
(see the ReadMe.doc file elsewhere on the disk). Note that since this is only
|
|
a suggestion, don't start programming a revolutionary new piece of code based
|
|
on this info yet; we may change the format :)... Here we go...
|
|
|
|
- Signed Tom "Outland" Bech of CryptoBurners.
|
|
|
|
-**-
|
|
|
|
Protracker release 3.01 Beta. Fileformat documentation.
|
|
=======================================================
|
|
|
|
This document includes the complete documentation of the fileformat used in
|
|
Protracker 3.01ß, and instructions on how to use it. Fields marked "*Reserved*"
|
|
are reserved for future use and are guarantied to cause hangup if messed with.
|
|
|
|
General
|
|
-------
|
|
|
|
With this release of Protracker we have decided to change the filestructure
|
|
of the musicfiles produced with the program. We felt the old format was
|
|
too obsolete, messy and out of date for us to use any further. So we invented
|
|
this new format. The format is based upon Interchanged File Format (IFF)
|
|
chunks, originally developed by Electronic Arts, but now in widely use on the
|
|
Amiga. The format allows considerable flexibility and does not suffer too
|
|
severly from changes and updates, and is therefore perfect for our use.
|
|
|
|
The Format
|
|
----------
|
|
|
|
We will in this section introduce and describe each chunk type appearing in a
|
|
Protracker music file. Look in the next section for the sequencial description.
|
|
|
|
** Contents of Chunk "VERS":
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "VERS" Chunk identifier.
|
|
4 4 ???????? Chunk length (in bytes).
|
|
8 2 ???????? Version number (word).
|
|
10 6 "PT3.01" Version ID string.
|
|
--------------------------------------------------------------------------------
|
|
|
|
This chunk is used by Protracker to identify the producer of the module, and
|
|
if necessary perform upgrade-conversion if the file was made with a pre-
|
|
vious version of Protracker. There can be at maximum one "VERS" chunk in a
|
|
Protracker music file. This chunk is not critical; it may be obmitted, but
|
|
be aware of the possible incompatibility problems that may arise if it's left
|
|
out.
|
|
|
|
** Contents of Chunk "INFO":
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "INFO" Chunk identifier.
|
|
4 4 ???????? Chunk length (in bytes).
|
|
8 32 [..??..] Song name (string).
|
|
40 2 ???????? Number of instruments (word).
|
|
42 2 ???????? Number of positions (word).
|
|
44 2 ???????? Number of patterns (word).
|
|
46 2 ???????? Overall volume factor (word).
|
|
48 2 0006h Default speed (#VB) (word).
|
|
50 2 ???????? Packed field. See below.
|
|
--------------------------------------------------------------------------------
|
|
|
|
Protracker uses this chunk to set different internal variables, and to store
|
|
vital information used in replay and processing of the file. The song name
|
|
is a maximum 32 Chars long ASCII string. It need not be NULL-terminated.
|
|
Number of instruments indicates the number of instruments used in the song,
|
|
it may range from 0 to 65535. At present version number, however, there may
|
|
be maximum 255 instruments in one song. Number of positions reflects the
|
|
actual length of the song, that is; how many patterns that will be played during
|
|
a complete cycle. This number may vary from 0 to 65535. Number of patterns,
|
|
on the other side, reflects how many _different_ patterns that will be played
|
|
during the song. This number is used to calculate the total length (in bytes)
|
|
of the song. The Overall Volume factor is used to compute the final volume
|
|
of all channels after the individual channel-volumes have been figured out.
|
|
In this way it is easy to control the loudness of the music from the program/
|
|
song itself. Default speed is the number of VBlank frames between each pattern
|
|
position change, and is as default set to 0006h. The packed field consists
|
|
of these bits (right to left order):
|
|
|
|
Bit Meaning 0 1 Default
|
|
--------------------------------------------------------------------------------
|
|
0 Filter flag. Filter off. Filter on. 0
|
|
1 Timing method. VBlank. CIA timing (BPM). 0
|
|
2 File type. Module. Song (no instruments). 0
|
|
3 Packstatus. Packed patterns. Raw patterns. 1
|
|
4 Length flag. Equal pattern length. Variable pattern length. 0
|
|
5 Voices flag. 4 voices. 8 voices. 0
|
|
6 Sample res. 8 bit. 16 bit. 0
|
|
7 *Reserved* x
|
|
8 *Reserved* x
|
|
9 *Reserved* x
|
|
10 *Reserved* x
|
|
11 *Reserved* x
|
|
12 *Reserved* x
|
|
13 *Reserved* x
|
|
14 *Reserved* x
|
|
15 *Reserved* x
|
|
--------------------------------------------------------------------------------
|
|
|
|
There can be at most one "INFO" chunk in a Protracker musicfile. This chunk is
|
|
vital; it _must_ be present for the replay routine to function properly.
|
|
|
|
** Contents of Chunk "INST":
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "INST" Chunk identifier.
|
|
4 4 ???????? Chunk length (in bytes).
|
|
8 32 [..??..] Instrument name (string).
|
|
40 2 ???????? Length of instrument (word).
|
|
42 2 ???????? Instrument loop start (word).
|
|
44 2 ???????? Instrument loop length (word).
|
|
46 2 ???????? Instrument volume (word).
|
|
48 2 ???????? Instrument finetuning (integer).
|
|
--------------------------------------------------------------------------------
|
|
|
|
The "INST" chunk is used to store information about an instruments properties,
|
|
such as length and volume. The instrument name is a maximum 32 Chars long ASCII
|
|
string. It need not be NULL-terminated. The Length field describes the length
|
|
of the instrument (in words) and thus ranges from 0 to 128Kb (65535 words).
|
|
Instrument Loop Start sets the offset from which to start playing after the
|
|
first replay. This value may vary from 0 to the instrument length. Instrument
|
|
Loop End sets the length of the loop to play after the first replay, relative
|
|
to the loop start value. It may thus vary from 0 to [Ins_len-Loop_start].
|
|
Instrument volume indicates which volume to use in the replay of the sample,
|
|
if the song doesn't say differently. This value varies between 0 and 40h.
|
|
Instrument finetuning sets the sample-rate correction difference and varies
|
|
from -7 to 7 (0fff9 to 0007h).
|
|
There may be any number of "INST" chunks in a Protracker music file,
|
|
limited to the number of instruments actually used in the song. This
|
|
chunk is not vital; it may be left out if the song-only bit of the control
|
|
word in the "INFO" chunk is set. Otherwise, it should result in an error.
|
|
|
|
** Contents of Chunk "PPOS":
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "PPOS" Chunk identifier.
|
|
4 4 0ffh Chunk length (in bytes).
|
|
8 256 [..??..] Pattern position table.
|
|
--------------------------------------------------------------------------------
|
|
|
|
This chunk contains the table defining which pattern to play in a given song-
|
|
position. Each entry in the table is a byte indicating which out of 256
|
|
possible patterns to play. There may be at maximum one "PPOS" chunk in a
|
|
Protracker musicfile. This chunk is vital; it _must_ be present to play the
|
|
song.
|
|
|
|
** Contents of Chunk "PTRN":
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "PTRN" Chunk identifier.
|
|
4 4 ???????? Chunk length (in bytes).
|
|
8 32 [..??..] Pattern name.
|
|
40 ? [..??..] Pattern data.
|
|
--------------------------------------------------------------------------------
|
|
|
|
This chunk is used in a module of variable pattern length. The chunk must thus
|
|
appear as many times as there are patterns in the song. The chunk length divided
|
|
by 8 ( >>3 ) will show the pattern length (default 64). Pattern name is a 32
|
|
byte long ASCII string, describing the pattern, eg. "Intro part 3". It need not
|
|
be NULL-terminated. This chunk is critical; it must be present in the file, or
|
|
it will be regarded invalid. NOTE: This chunk is not in use in the present
|
|
version (3.01B), and will be ignored if found.
|
|
|
|
** Contents of Chunk "SMPL":
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "SMPL" Chunk identifier.
|
|
4 4 ???????? Chunk length (!in bytes!).
|
|
8 ? [..??..] Raw sample data.
|
|
--------------------------------------------------------------------------------
|
|
|
|
The "SMPL" chunk contains the raw sample data of an instrument. This chunk is
|
|
not critical; if the song-only bit of the "INFO" chunk is set, it may be
|
|
obmitted. If, however, the file is a module, then the number of "SMPL" chunks in
|
|
the file must be equal to or greater than the number of instruments used in the
|
|
song. If not, the file will be regarded incomplete.
|
|
|
|
** Contents of Chunk "CMNT":
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "CMNT" Chunk identifier.
|
|
4 4 ???????? Chunk length (in bytes).
|
|
8 ? [..??..] Raw ASCII text.
|
|
--------------------------------------------------------------------------------
|
|
|
|
The "CMNT" chunk is used for a signature, comments, greetings, date of
|
|
completion or whatever information the composer wishes to include with his or
|
|
hers creation. This chunks is not critical; it may be left out and will
|
|
typically be ignored by most applications.
|
|
|
|
These are the chunks that may appear in a Protracker musicfile. If other chunks
|
|
are encountered, they will be ignored. Any program dealing with this fileformat
|
|
should perform tests to determine the validity of the file in consideration.
|
|
Using the Protracker.library will guarantee correct handling of musicfiles, and
|
|
we strongly encourage the use of this runtime shared library instead of hacking
|
|
away on your own. Look elsewhere on this disk for the library documentation,
|
|
the library can be found in the "LIBS/" directory.
|
|
|
|
The sequential format
|
|
---------------------
|
|
|
|
In this section we will describe how the various chunks are expected to be
|
|
located within the file. These rules _must_ be followed or it will wreak
|
|
havoc when tried manipulated with inside Protracker. Here comes the header in
|
|
table form:
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "FORM" Indicate start of IFF file.
|
|
4 4 ???????? File length.
|
|
8 4 "MODL" IFF type identifier.
|
|
-------------------------------------------------------------------------------
|
|
|
|
This header must be found in the start of the file, or it will be rejected as
|
|
not being a Protracker musicfile. From offset 12 in the file, things may vary
|
|
somewhat. The only rules are these: After a "INST" chunk a "SMPL" or a new
|
|
"INST" chunk _must_ follow. This "SMPL" chunk will be regarded as the sample
|
|
data of the instrument(s) preceding it. If after a "INST" chunk another "INST"
|
|
chunk follows, and the module-flag in the "INFO" chunk is set, then all "INST"
|
|
chunks following each other will share the same sampledata found in the first
|
|
"SMPL" chunk after them. Also, all "INST" and "SMPL" chunks must be found in
|
|
sequence. That is, when a "INST" chunk is found for the first time in a file,
|
|
all other "INST" and "SMPL" chunks must follow. If this is not so, an error
|
|
message should be given, and processing terminated. Note that in a song-only
|
|
file, no "SMPL" chunks should be included. If any "SMPL" chunks are encountered
|
|
in such a file, they should be ignored and a warning given. All other chunks
|
|
used in a musicfile may be located anywhere in the file, usually in the
|
|
beginning of it, but no assumptions of their locations should be taken. Note
|
|
that all used chunks _must_ be found _before_ the "BODY" chunk, which is the
|
|
last chunk to be found in the file. Searching for chunks should stop when
|
|
encountering a "BODY" chunk. The "BODY" chunk is constructed like this:
|
|
|
|
OFFSET Length Contents Meaning
|
|
--------------------------------------------------------------------------------
|
|
0 4 "BODY" Chunk identifier.
|
|
4 4 ???????? Chunk length (in bytes).
|
|
8 ? [..??..] Raw pattern data.
|
|
-------------------------------------------------------------------------------
|
|
|
|
Chunk summary
|
|
-------------
|
|
|
|
Now follows a list of the chunks that have meaning in a Protracker musicfile:
|
|
|
|
Chunk Function Critical?
|
|
-------------------------------------------------------------------------------
|
|
"VERS" Contains information about the producer of the file. No
|
|
"INFO" Contains vital information and standard settings. Yes
|
|
"INST" Information about instruments; such as length, volume etc. Yes
|
|
"SMPL" Raw sample data associated with one or more instruments. No
|
|
"PPOS" Position table. Information about patternsequence. Yes
|
|
"CMNT" Comments, greetings etc. Contains information in ASCII code. No
|
|
"PTRN" Pattern data. Used only in modules of varying patternlengths. Yes
|
|
"BODY" Pattern data. Used in modules of equal patternlengths (default). Yes
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
/* End Of File */
|