home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga Shareware Floppies / map2.dms / map2.adf / ProTracker3.01 / PT-Fileformat.doc < prev    next >
Text File  |  1993-01-26  |  14KB  |  275 lines
  1.  
  2. Introduction.
  3. =============
  4.  
  5. The text below was intended to be the documentation on the fileformat used
  6. in this release of ProTracker. However, we decided to wait with the actual
  7. implementation of the format until having released a couple of versions,
  8. because we'd like to hear some comments, suggestions etc. upon it first.
  9. So read it lightly, and feel free to post your opinion to one of the authors
  10. (see the ReadMe.doc file elsewhere on the disk). Note that since this is only
  11. a suggestion, don't start programming a revolutionary new piece of code based
  12. on this info yet; we may change the format :)... Here we go...
  13.  
  14.  - Signed Tom "Outland" Bech of CryptoBurners.
  15.  
  16.                                     -**-
  17.  
  18. Protracker release 3.01 Beta. Fileformat documentation.
  19. =======================================================
  20.  
  21. This document includes the complete documentation of the fileformat used in
  22. Protracker 3.01ß, and instructions on how to use it. Fields marked "*Reserved*"
  23. are reserved for future use and are guarantied to cause hangup if messed with.
  24.  
  25. General
  26. -------
  27.  
  28. With this release of Protracker we have decided to change the filestructure
  29. of the musicfiles produced with the program. We felt the old format was
  30. too obsolete, messy and out of date for us to use any further. So we invented
  31. this new format. The format is based upon Interchanged File Format (IFF)
  32. chunks, originally developed by Electronic Arts, but now in widely use on the
  33. Amiga. The format allows considerable flexibility and does not suffer too
  34. severly from changes and updates, and is therefore perfect for our use.
  35.  
  36. The Format
  37. ----------
  38.  
  39. We will in this section introduce and describe each chunk type appearing in a
  40. Protracker music file. Look in the next section for the sequencial description.
  41.  
  42. ** Contents of Chunk "VERS":
  43.  
  44. OFFSET        Length        Contents    Meaning
  45. --------------------------------------------------------------------------------
  46.  0         4        "VERS"        Chunk identifier.
  47.  4         4        ????????    Chunk length (in bytes).
  48.  8         2        ????????    Version number (word).
  49. 10         6        "PT3.01"    Version ID string.
  50. --------------------------------------------------------------------------------
  51.  
  52. This chunk is used by Protracker to identify the producer of the module, and
  53. if necessary perform upgrade-conversion if the file was made with a pre-
  54. vious version of Protracker. There can be at maximum one "VERS" chunk in a
  55. Protracker music file. This chunk is not critical; it may be obmitted, but
  56. be aware of the possible incompatibility problems that may arise if it's left
  57. out.
  58.  
  59. ** Contents of Chunk "INFO":
  60.  
  61. OFFSET        Length        Contents    Meaning
  62. --------------------------------------------------------------------------------
  63.  0         4        "INFO"        Chunk identifier.
  64.  4         4        ????????    Chunk length (in bytes).
  65.  8        32        [..??..]    Song name (string).
  66. 40         2        ????????    Number of instruments (word).
  67. 42         2        ????????    Number of positions (word).
  68. 44         2        ????????    Number of patterns (word).
  69. 46         2        ????????    Overall volume factor (word).
  70. 48         2        0006h        Default speed (#VB) (word).
  71. 50         2        ????????    Packed field. See below.
  72. --------------------------------------------------------------------------------
  73.  
  74. Protracker uses this chunk to set different internal variables, and to store
  75. vital information used in replay and processing of the file. The song name
  76. is a maximum 32 Chars long ASCII string. It need not be NULL-terminated.
  77. Number of instruments indicates the number of instruments used in the song,
  78. it may range from 0 to 65535. At present version number, however, there may
  79. be maximum 255 instruments in one song. Number of positions reflects the
  80. actual length of the song, that is; how many patterns that will be played during
  81. a complete cycle. This number may vary from 0 to 65535. Number of patterns,
  82. on the other side, reflects how many _different_ patterns that will be played
  83. during the song. This number is used to calculate the total length (in bytes)
  84. of the song. The Overall Volume factor is used to compute the final volume
  85. of all channels after the individual channel-volumes have been figured out.
  86. In this way it is easy to control the loudness of the music from the program/
  87. song itself. Default speed is the number of VBlank frames between each pattern
  88. position change, and is as default set to 0006h. The packed field consists
  89. of these bits (right to left order):
  90.  
  91. Bit    Meaning        0            1             Default
  92. --------------------------------------------------------------------------------
  93.  0    Filter flag.    Filter off.        Filter on.              0
  94.  1    Timing method.    VBlank.            CIA timing (BPM).             0
  95.  2    File type.    Module.            Song (no instruments).        0
  96.  3    Packstatus.    Packed patterns.    Raw patterns.                 1
  97.  4    Length flag.    Equal pattern length.    Variable pattern length.      0
  98.  5    Voices flag.    4 voices.        8 voices.                     0
  99.  6    Sample res.     8 bit.             16 bit.                      0
  100.  7    *Reserved*                                           x
  101.  8    *Reserved*                                  x
  102.  9    *Reserved*                                  x
  103. 10    *Reserved*                                    x
  104. 11    *Reserved*                                  x
  105. 12    *Reserved*                                  x
  106. 13    *Reserved*                                  x
  107. 14    *Reserved*                                  x
  108. 15    *Reserved*                                  x
  109. --------------------------------------------------------------------------------
  110.  
  111. There can be at most one "INFO" chunk in a Protracker musicfile. This chunk is
  112. vital; it _must_ be present for the replay routine to function properly.
  113.  
  114. ** Contents of Chunk "INST":
  115.  
  116. OFFSET        Length        Contents    Meaning
  117. --------------------------------------------------------------------------------
  118.  0         4        "INST"        Chunk identifier.
  119.  4         4        ????????    Chunk length (in bytes).
  120.  8        32        [..??..]    Instrument name (string).
  121. 40         2        ????????    Length of instrument (word).
  122. 42         2        ????????    Instrument loop start (word).
  123. 44         2        ????????    Instrument loop length (word).
  124. 46         2        ????????    Instrument volume (word).
  125. 48         2        ????????    Instrument finetuning (integer).
  126. --------------------------------------------------------------------------------
  127.  
  128. The "INST" chunk is used to store information about an instruments properties,
  129. such as length and volume. The instrument name is a maximum 32 Chars long ASCII
  130. string. It need not be NULL-terminated. The Length field describes the length
  131. of the instrument (in words) and thus ranges from 0 to 128Kb (65535 words).
  132. Instrument Loop Start sets the offset from which to start playing after the
  133. first replay. This value may vary from 0 to the instrument length. Instrument
  134. Loop End sets the length of the loop to play after the first replay, relative
  135. to the loop start value. It may thus vary from 0 to [Ins_len-Loop_start]. 
  136. Instrument volume indicates which volume to use in the replay of the sample,
  137. if the song doesn't say differently. This value varies between 0 and 40h.
  138. Instrument finetuning sets the sample-rate correction difference and varies
  139. from -7 to 7 (0fff9 to 0007h).
  140.   There may be any number of "INST" chunks in a Protracker music file,
  141. limited to the number of instruments actually used in the song. This
  142. chunk is not vital; it may be left out if the song-only bit of the control
  143. word in the "INFO" chunk is set. Otherwise, it should result in an error.
  144.  
  145. ** Contents of Chunk "PPOS":
  146.  
  147. OFFSET        Length        Contents    Meaning
  148. --------------------------------------------------------------------------------
  149.  0         4        "PPOS"        Chunk identifier.
  150.  4         4        0ffh        Chunk length (in bytes).
  151.  8           256        [..??..]    Pattern position table.
  152. --------------------------------------------------------------------------------
  153.  
  154. This chunk contains the table defining which pattern to play in a given song-
  155. position. Each entry in the table is a byte indicating which out of 256
  156. possible patterns to play. There may be at maximum one "PPOS" chunk in a
  157. Protracker musicfile. This chunk is vital; it _must_ be present to play the
  158. song.
  159.  
  160. ** Contents of Chunk "PTRN":
  161.  
  162. OFFSET        Length        Contents    Meaning
  163. --------------------------------------------------------------------------------
  164.  0         4        "PTRN"        Chunk identifier.
  165.  4         4        ????????    Chunk length (in bytes).
  166.  8              32              [..??..]        Pattern name.
  167. 40             ?        [..??..]    Pattern data.
  168. --------------------------------------------------------------------------------
  169.  
  170. This chunk is used in a module of variable pattern length. The chunk must thus
  171. appear as many times as there are patterns in the song. The chunk length divided
  172. by 8 ( >>3 ) will show the pattern length (default 64). Pattern name is a 32
  173. byte long ASCII string, describing the pattern, eg. "Intro part 3". It need not
  174. be NULL-terminated. This chunk is critical; it must be present in the file, or
  175. it will be regarded invalid. NOTE: This chunk is not in use in the present
  176. version (3.01B), and will be ignored if found.
  177.  
  178. ** Contents of Chunk "SMPL":
  179.  
  180. OFFSET        Length        Contents    Meaning
  181. --------------------------------------------------------------------------------
  182.  0         4        "SMPL"        Chunk identifier.
  183.  4         4        ????????    Chunk length (!in bytes!).
  184.  8             ?        [..??..]    Raw sample data.
  185. --------------------------------------------------------------------------------
  186.  
  187. The "SMPL" chunk contains the raw sample data of an instrument. This chunk is
  188. not critical; if the song-only bit of the "INFO" chunk is set, it may be
  189. obmitted. If, however, the file is a module, then the number of "SMPL" chunks in
  190. the file must be equal to or greater than the number of instruments used in the
  191. song. If not, the file will be regarded incomplete.
  192.  
  193. ** Contents of Chunk "CMNT":
  194.  
  195. OFFSET        Length        Contents    Meaning
  196. --------------------------------------------------------------------------------
  197.  0         4        "CMNT"        Chunk identifier.
  198.  4         4        ????????    Chunk length (in bytes).
  199.  8             ?        [..??..]    Raw ASCII text.
  200. --------------------------------------------------------------------------------
  201.  
  202. The "CMNT" chunk is used for a signature, comments, greetings, date of
  203. completion or whatever information the composer wishes to include with his or
  204. hers creation. This chunks is not critical; it may be left out and will
  205. typically be ignored by most applications.
  206.  
  207. These are the chunks that may appear in a Protracker musicfile. If other chunks
  208. are encountered, they will be ignored. Any program dealing with this fileformat
  209. should perform tests to determine the validity of the file in consideration.
  210. Using the Protracker.library will guarantee correct handling of musicfiles, and
  211. we strongly encourage the use of this runtime shared library instead of hacking
  212. away on your own. Look elsewhere on this disk for the library documentation,
  213. the library can be found in the "LIBS/" directory.
  214.  
  215. The sequential format
  216. ---------------------
  217.  
  218. In this section we will describe how the various chunks are expected to be
  219. located within the file. These rules _must_ be followed or it will wreak
  220. havoc when tried manipulated with inside Protracker. Here comes the header in
  221. table form:
  222.  
  223. OFFSET        Length        Contents    Meaning
  224. --------------------------------------------------------------------------------
  225.   0         4        "FORM"        Indicate start of IFF file.
  226.   4         4        ????????    File length.
  227.   8         4        "MODL"        IFF type identifier.
  228. -------------------------------------------------------------------------------
  229.  
  230. This header must be found in the start of the file, or it will be rejected as
  231. not being a Protracker musicfile. From offset 12 in the file, things may vary
  232. somewhat. The only rules are these: After a "INST" chunk a "SMPL" or a new 
  233. "INST" chunk _must_ follow. This "SMPL" chunk will be regarded as the sample
  234. data of the instrument(s) preceding it. If after a "INST" chunk another "INST"
  235. chunk follows, and the module-flag in the "INFO" chunk is set, then all "INST"
  236. chunks following each other will share the same sampledata found in the first
  237. "SMPL" chunk after them. Also, all "INST" and "SMPL" chunks must be found in
  238. sequence. That is, when a "INST" chunk is found for the first time in a file,
  239. all other "INST" and "SMPL" chunks must follow. If this is not so, an error
  240. message should be given, and processing terminated. Note that in a song-only
  241. file, no "SMPL" chunks should be included. If any "SMPL" chunks are encountered
  242. in such a file, they should be ignored and a warning given. All other chunks
  243. used in a musicfile may be located anywhere in the file, usually in the
  244. beginning of it, but no assumptions of their locations should be taken. Note
  245. that all used chunks _must_ be found _before_ the "BODY" chunk, which is the
  246. last chunk to be found in the file. Searching for chunks should stop when
  247. encountering a "BODY" chunk. The "BODY" chunk is constructed like this:
  248.  
  249. OFFSET        Length        Contents    Meaning
  250. --------------------------------------------------------------------------------
  251.   0         4        "BODY"        Chunk identifier.
  252.   4         4        ????????    Chunk length (in bytes).
  253.   8         ?        [..??..]    Raw pattern data.
  254. -------------------------------------------------------------------------------
  255.  
  256. Chunk summary
  257. -------------
  258.  
  259. Now follows a list of the chunks that have meaning in a Protracker musicfile:
  260.  
  261. Chunk      Function                                  Critical?
  262. -------------------------------------------------------------------------------
  263. "VERS"      Contains information about the producer of the file.               No
  264. "INFO"      Contains vital information and standard settings.                Yes
  265. "INST"      Information about instruments; such as length, volume etc.        Yes
  266. "SMPL"    Raw sample data associated with one or more instruments.           No
  267. "PPOS"      Position table. Information about patternsequence.                Yes
  268. "CMNT"    Comments, greetings etc. Contains information in ASCII code.       No
  269. "PTRN"      Pattern data. Used only in modules of varying patternlengths.     Yes
  270. "BODY"    Pattern data. Used in modules of equal patternlengths (default).  Yes
  271. -------------------------------------------------------------------------------
  272.  
  273.  
  274. /* End Of File */
  275.