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 */