home *** CD-ROM | disk | FTP | other *** search
/ Large Pack of OldSkool DOS MOD Trackers / digitr23.zip / FORMAT.TXT < prev    next >
Text File  |  1995-07-03  |  20KB  |  456 lines
  1.                                                       ┌─-─--·· · · ··--─-─┐
  2. ╒═════════════════════════════════════════════════════│    █▐ ∩-f/┤¢tστ's │══╕
  3. ├─────────────────────────────────────────────────────│    █▐             │──┤
  4. │                                                     │ ▐███▐  ▀ ▐███▌  ▀ │  │
  5. │   ≡≡≡ DIGITRAKKER ≡≡≡ FILE-FORMAT DESCRIPTION ≡≡≡   │ █  █▐ █▐ █  █▐ █▐ │  │
  6. │                                                     │ ▐███▐ █▐ ▐███▐ █▐ │  │
  7. ├─────────────────────────────────────────────────────│             █▐    │──┤
  8. ╘═════════════════════════════════════════════════════│  t r a k k▐██▌e r │══╛
  9.                                                       └─-─--·· · · ··--─-─┘
  10.  
  11. ------------------------------ by proton/N-Factor ----------------------------
  12.  
  13.  
  14. This file contains information about the songmodule-format "MDL", the
  15. instrument-format "IST" and the old sample-format "SPL".
  16. If you have some problems or if you have questions about these formats, which
  17. are not answered in here, just contact me.
  18.  
  19.  
  20.  
  21.  
  22. ╔════════════════════════════════════════════════════════════════════════════╗
  23. ║                        THE SONGMODULE-FORMAT  (MDL)                   V1.0 ║
  24. ╚════════════════════════════════════════════════════════════════════════════╝
  25.  
  26. Offset Lenght Description
  27.  
  28.  000    004     "DMDL"; the four letters mark the mdl-format
  29.  004    001     version; the current version is 10h (=1.0)
  30.  005    ???     the different data-blocks are stored at this position
  31.  
  32. Some words to the format version-number:
  33. - if the low-nibble increases, there are extensions in the format, but old
  34.   loaders should be able to load the new modules (or most of them...)
  35. - if the high-nibble increases, there are changes in the format which make old
  36.   loaders unable to read the new songfiles
  37.  
  38. The MDL-songmodule-format is subdivided into the following blocks:
  39.  
  40. "IN"    infoblock; contains most songparameters, like speed, length etc.
  41. "ME"    songmessage; contains the songinformation from the composer
  42. "PA" c  pattern; contains the length, names and tracklists for every pattern
  43. "TR"    tracks; contains all the tracks for the pattern
  44. "II" n  instruments; contains all information for the used instruments
  45. "VE" n  volume-envelopes; contains the construction of all used vol-envelopes
  46. "PE" n  panning-envelopes; the same for the used pan-envelopes
  47. "IS" c  sampleinfos; contains information for every used sample
  48. "SA"    samples; contains the sample-datas
  49.  
  50. [[ c = blockstructure changes from v0.0 to v1.0 ]]
  51. [[ n = new in version 1.0                       ]]
  52.  
  53. The sequence of the blocks in a file is not fixed so they can be stored in any
  54. way. Digitrakker uses the descripted sequence.
  55.  
  56. The structure for every block is the same:
  57.  
  58. Offset Lenght Description
  59.  
  60.  000    002     "xx"; block-ID (example: "IN" for infoblock)
  61.  002    004     blocklength; this dword contains the length of the FOLLOWING
  62.         datas.
  63.  006 <blocklen> datas for this block...
  64.  
  65. The next block will be at offset (006 + <blocklength>).
  66.  
  67. ┌────────────────────────────────────────────────────────────────────────────┐
  68. │                          The Song-Infoblock  (IN)                          │
  69. └────────────────────────────────────────────────────────────────────────────┘
  70.  
  71. Offset Lenght Description
  72.  
  73.  000    002     "IN"; infoblock-ID
  74.  002    004     blocklenght
  75.  006    032     songname; name of the songmodule (filled with spaces [32])
  76.  038    020     composername; name of the song-composer
  77.  058    002     songlength; Digitrakker supports up to 255 songpositions
  78.  060    002     songrepeat
  79.  062    001     mainvolume (001-255)
  80.  063    001     song-speed (001-255)
  81.  064    001     beats per minute (004-255)
  82.  065    032     channel-information: bit 0-6 - panposition (0=left,127=right)
  83.                      bit 7   - 0=channel on, 1=channel off
  84.                 [number of channels = last active channel]
  85.  097  <snglen>  sequencer; contains the number of the pattern for every
  86.         songposition
  87.  ???  <chnnam>  the names for every channel (8 chars for one name).
  88.         <chnnam> = 8 * <number of channels>
  89.  
  90. ┌────────────────────────────────────────────────────────────────────────────┐
  91. │                            The Songmessage (ME)                            │
  92. └────────────────────────────────────────────────────────────────────────────┘
  93.  
  94. Offset Lenght Description
  95.  
  96.  000    002     "ME"; songmessage-ID
  97.  002    004     blocklenght
  98.  006    ???     songmessage; every line is closed with the CR-char (13). A
  99.         0-byte stands at the end of the whole text.
  100.  
  101. ┌────────────────────────────────────────────────────────────────────────────┐
  102. │                           The Patterndatas  (PA)                           │
  103. └────────────────────────────────────────────────────────────────────────────┘
  104.  
  105. Offset Lenght Description
  106.  
  107.  000    002     "PA"; patterndata-ID
  108.  002    004     blocklenght
  109.  006    001     number of pattern; values from 1 to 255 are possible
  110.  007  <patlar>  the datablocks for all saved pattern
  111.  
  112. The structure of one pattern-datablock:
  113.  
  114.  000    001    number of used channels (0-32)
  115.  001    001    patternlength-1; the actual digitrakker-version only
  116.         supports patterns with 64 rows (always 63 in this byte)
  117.  002    016    pattern-name (filled with [32])
  118.  018  <trklar>  tracksequencing-list
  119.                 <trklar> = 2 * number of channels in this pattern
  120.  
  121. The tracksequencing-lists descripe which track is used as which voice in the
  122. pattern. The first word in this list is the number of the track at voice 0.
  123. The second is track for voice 1 and so on...
  124. As every track is saved independend, it is possible to save some discspace by
  125. this methode: If the song contains equal tracks at several positions in
  126. the patterns, these double tracks will only saved one time.
  127. Track 0 is not saved and represents an empty track.
  128.  
  129. ┌────────────────────────────────────────────────────────────────────────────┐
  130. │                            The Trackdatas  (TR)                            │
  131. └────────────────────────────────────────────────────────────────────────────┘
  132.  
  133. Offset Lenght Description
  134.  
  135.  000    002     "TR"; trackdata-ID
  136.  002    004     blocklenght
  137.  006    002     number of tracks
  138.  008    ???     track-datablocks; every trackdatablock is stored in this way:
  139.         Ofs.000 Len.002         length of the trackdatas
  140.             002 <trackdatalen>  datas for this track
  141.  
  142. Every track consists of 64 notepositions and every notposition contains 6
  143. bytes:
  144.  
  145. byte 0              - note-value; 1=C-0,2=C#0,...,120=B-9,0=nothing,255=stopper
  146. byte 1              - sample-number; 1-255; 0=nothing
  147. byte 2              - volume; 1-255; 0=no volume change
  148. byte 3, low nibble  - number of the first effect-command
  149. byte 3, high nibble - number of the second effect-command
  150. byte 4              - databyte for the first effect-command
  151. byte 5              - databyte for the second effect-command
  152.  
  153. So one track needs 6 * 64 = 384 bytes in the memory. Digitrakker stores the
  154. tracks in a packed way. The structure of this (very effective!) packformat is
  155. the following:
  156.  
  157.      bit 76543210
  158. byte 0 - xxxxxxyy
  159.  
  160. if yy = 00 -> <xxxxxx>+1 is the number of the empty notepositions which are
  161.           following.
  162. if yy = 01 -> the last noteposition will be repeated <xxxxxx>+1 times.
  163. if yy = 10 -> the noteslot from position <xxxxxx> is copied to the actual
  164.           position.
  165. if yy = 11 -> the following datas will be put in the actual noteslot:
  166.         bit 2 = 1 -> note
  167.         bit 3 = 1 -> sample
  168.         bit 4 = 1 -> volume
  169.         bit 5 = 1 -> effectcommand numbers
  170.         bit 6 = 1 -> databyte for effect 1
  171.         bit 7 = 1 -> databyte for effect 1
  172.  
  173. ┌────────────────────────────────────────────────────────────────────────────┐
  174. │                           The Instruments (II)                             │
  175. └────────────────────────────────────────────────────────────────────────────┘
  176.  
  177. Offset Lenght Description
  178.  
  179.  000    002     "II"; intrument-ID
  180.  002    004     blocklenght
  181.  006    001     number of saved instruments; values from 0 to 255 are possible
  182.  007  <inslar>  the datablocks for all used instruments
  183.  
  184. The structure of one instrument-datablock:
  185.  
  186.  000    001     instrument-number; (1-255)
  187.  001    001    number of samples in instrument; (1-16)
  188.  001    032     instrument-name; the name of the instrument (filled with [32])
  189.  033  <is-len>  this block contains the infos for all defined samples in the
  190.         instrument; every info consist of 14 bytes, so
  191.         <is-len> = 14 * number of defined samples
  192.  
  193. The structure of one instrument-sample datablock:
  194.  
  195.  000    001     sample-number; (1-255)
  196.  001    001     playrange-end (0-119,0='c-0'); the last note for this sample;
  197.         a higher note uses one of the next samples
  198.  002    001     volume (1-255)
  199.  003    001     bit 0-5 -> volumeenvelope-number (0-63)
  200.         bit 6   -> flag, if volume is used
  201.         bit 7   -> flag, if volumeenvelope is used
  202.  004    001     panning (0-127)
  203.  005    001     bit 0-5 -> panningenvelope-number (0-63)
  204.         bit 6   -> flag, if panning is used
  205.         bit 7   -> flag, if panningenvelope is used
  206.  006    002     fadeout-speed (0-65535)
  207.  008    001     vibrator-speed (0-255)
  208.  009    001     vibrator-depth (0-255)
  209.  010    001     vibrator-sweep (0-255)
  210.  011    001     vibrator-form (0-2)
  211.  012    002     ** reserved ** (should be set to <0>)
  212.  
  213. ┌────────────────────────────────────────────────────────────────────────────┐
  214. │                         The Volume-Envelopes  (VE)                         │
  215. └────────────────────────────────────────────────────────────────────────────┘
  216.  
  217. Offset Lenght Description
  218.  
  219.  000    002     "VE"; volume-envelope-ID
  220.  002    004     blocklenght
  221.  006    001     number of saved vol-envelopes (0-64)
  222.  007  <ve-lar>  volume-envelope datas; a datablock contains 33 bytes, so
  223.         <ve-lar> = 33 * number of saved vol-envelopes;
  224.  
  225. The structure of one envelope-datablock:
  226.  
  227.  000    001     envelope-number; (0-63)
  228.  001    030     the positions of the 15 points are stored here; the first
  229.         byte is the x-distance from the last point (1-255; 0 means,
  230.         that no more points are defined; take 1 for the first point),
  231.                 the second byte is the y-position (0-63)
  232.  031    001     bit 0-3 -> sustain-point (0-14)
  233.         bit 4   -> flag, if sustain is on
  234.         bit 5   -> flag, if loop is on
  235.                 bit 6-7 -> ** reserved ** (should be set to <0>)
  236.  032    001     bit 0-3 -> loop-start (0-14)
  237.         bit 4-7 -> loop-end (0-14)
  238.  
  239. ┌────────────────────────────────────────────────────────────────────────────┐
  240. │                         The Panning-Envelopes (PE)                         │
  241. └────────────────────────────────────────────────────────────────────────────┘
  242.  
  243. Offset Lenght Description
  244.  
  245.  000    002     "PE"; panning-envelope-ID
  246.  002    004     blocklenght
  247.  006    001     number of saved pan-envelopes (0-64)
  248.  007  <pe-lar>  panning-envelope datas; a datablock contains 33 bytes, so
  249.         <pe-lar> = 33 * number of saved pan-envelopes
  250.         see at "VE" for the description of an envelope-datablock
  251.  
  252. ┌────────────────────────────────────────────────────────────────────────────┐
  253. │                         The Sample-Infoblocks (IS)                         │
  254. └────────────────────────────────────────────────────────────────────────────┘
  255.  
  256. Offset Lenght Description
  257.  
  258.  000    002     "IS"; sampleinfo-ID
  259.  002    004     blocklenght
  260.  006    001     number of saved samples; values from 0 to 255 are possible
  261.  007  <samlar>  sample-infoblocks; a infoblock for one sample contains 59
  262.                 bytes, so <samlar> = 59 * number of saved samples
  263.  
  264. The structure of one sample-infoblock:
  265.  
  266.  000    001     sample-number; (1-255)
  267.  001    032     sample-name; the name of the sample (filled with [32])
  268.  033    008     filename of the sample
  269.  041    004     C-4 sample-frequence in hz
  270.  045    004     sample-length
  271.  049    004     sample-repeatstart
  272.  053    004     sample-repeatlength; if this value is set to 0, the sample
  273.         will not loop
  274.  057    001     ** not used ** (this was the volume in old v0.0-modules)
  275.  058    001     infobyte:
  276.         bit 0   -> 0=8 bit sample, 1=16 bit sample
  277.         bit 1   -> 0=forward looping, 1=bidirectional looping
  278.                 bit 2,3 -> packmethode (0=not packed, 1=8bit packing,
  279.                            2=16bit packing, 3=not defined)
  280.                 bit 4-7 -> ** reserved ** (should be set to <0>)
  281.  
  282. ┌────────────────────────────────────────────────────────────────────────────┐
  283. │                            The Sampledatas (SA)                            │
  284. └────────────────────────────────────────────────────────────────────────────┘
  285.  
  286. Offset Lenght Description
  287.  
  288.  000    002     "SA"; sampledata-ID
  289.  002    004     blocklenght
  290.  006    ???     sampledatas; samples are stored in numeric sequence
  291.  
  292. Unpacked samples are stored in signed form. Packmethode (1) is designed for
  293. 8 bit samples, Packmethode (2) for 16 bit samples. Methode (3) isn't defined
  294. in this version.
  295.  
  296.  
  297. The description of the sample-packmethode (1) [8bit packing]:...
  298. ────────────────────────────────────────────────────────────────
  299.  
  300. This methode is based on the huffman-algorithm. It's an easy form, but very
  301. fast and effective on samples. The packed sample is a bit-data-stream:
  302.  
  303.     Byte 0    Byte 1    Byte 2    Byte 3
  304. Bit 76543210  fedcba98  nmlkjihg  ....rqpo
  305.  
  306. A packed byte is stored in the following form:
  307.  
  308. xxxx10..0s => byte = <xxxx> + (number of <0>-bits between s and 1) * 16 - 8 ;
  309.           if s=1 then byte = byte xor 255
  310.  
  311. If there are no <0>-bits between the first bit (sign) and the <1>-bit, you
  312. have the following form:
  313.  
  314. xxx1s      => byte = <xxx> ; if s=1 then byte = byte xor 255
  315.  
  316. To depack one byte, you have to use the following algorithm:
  317. ┌────────────────────────────────────────────────────────────────────────────┐
  318. │       read bit                                                             │
  319. │       sign = bit                                                           │
  320. │       read bit                                                             │
  321. │       if bit = 1                                                           │
  322. │               then  read [3bits]                                           │
  323. │                     byte = [3bits]                                         │
  324. │                     goto next                                              │
  325. │               else  byte = 8                                               │
  326. │loop:  read bit                                                             │
  327. │       if bit = 0                                                           │
  328. │               then  byte = byte + 16                                       │
  329. │                     goto loop                                              │
  330. │               else  read [4bits]                                           │
  331. │                     byte = byte + [4bits]                                  │
  332. │next:   if sign = 1                                                         │
  333. │               then byte = byte xor 255                                     │
  334. └────────────────────────────────────────────────────────────────────────────┘
  335.  
  336. Two examples:
  337.  
  338. xxxx  s
  339. 1001101 = ( 9 + 1 * 16 - 8 ) xor 255 = 238
  340.  
  341. xxx s
  342. 01010 = 2
  343.  
  344. Note that the depacked bytes are delta values. To convert them to real data
  345. use this algorithm:
  346.  
  347. oldbyte = 0
  348. for sampleposition = 1 to samplelength
  349.     newbyte = byte [sampleposition] + oldbyte
  350.     byte [sampleposition] = newbyte
  351.     oldbyte = newbyte
  352. next sampleposition
  353.  
  354. When a sample ends, the next one will start with the next byte (not in the
  355. bit-stream...!).
  356.  
  357.  
  358. The description of the sample-packmethode (2) [16bit packing]:...
  359. ────────────────────────────────────────────────────────────────
  360.  
  361. This works as methode (1) but it only crunches every 2nd byte (the high-
  362. bytes of 16 bit samples). So when you depack 16 bit samples, you have to
  363. read 8 bits from the data-stream first. They present the lowbyte of the
  364. sample-word. Then depack the highbyte in the descripted way (methode [1]).
  365. Only the highbytes are delta-values. So take the lowbytes as they are.
  366. Go on this way for the whole sample!
  367.  
  368.  
  369. ┌────────────────────────────────────────────────────────────────────────────┐
  370. │                    ** Differences to older formats **                      │
  371. └────────────────────────────────────────────────────────────────────────────┘
  372.  
  373. Changes from v0.0 to v1.0:
  374. - block "PN" (patternnames) doesn't exist in v1.0-modules (patternnames now
  375.   stored in block "PA")
  376.   the old v0.0 structure of the "PN"-block:
  377.     000    002     "PN"; patternnames-ID
  378.     002    004     blocklenght
  379.     006  <patnam>  the names for every pattern (16 chars for one name).
  380.            <patnam> = 16 * <number of patterns>
  381. - structure of block "PA" changes completely
  382.   the old v0.0 structure of the "PA"-block:
  383.     000    002     "PA"; patterndata-ID
  384.     002    004     blocklenght
  385.     006    001     number of pattern; values from 1 to 255 are possible
  386.     007  <patlar>  tracksequencing-list for the used patterns;
  387.            <patlar> = 64 * number of patterns (32 words with the
  388.            tracknumbers for every pattern)
  389. - new blocks in v1.0-modules: "II" (instruments), "VE" (volume-envelope) and
  390.   "PE" (panning-envelope)
  391. - volumebyte (byte 57) in the sample-datablocks (block "IS") isn't used;
  392.   the C-4 sample-frequence increases from a word (2 bytes) to a dword (4
  393.   bytes), so one whole sample-infoblock has a length of 59 bytes
  394.  
  395.  
  396.  
  397.  
  398. ╔════════════════════════════════════════════════════════════════════════════╗
  399. ║                        THE INSTRUMENT-FORMAT  (IST)                   V0.0 ║
  400. ╚════════════════════════════════════════════════════════════════════════════╝
  401.  
  402. The IST-format has the same structure like the MDL-format:
  403.  
  404. Offset Lenght Description
  405.  
  406.  000    004     "DIST"; the four letters mark the ist-format
  407.  004    001     version; the current version is 00h (=0.0)
  408.  005    ???     the different data-blocks are stored at this position
  409.  
  410. The IST-instrument-format is subdivided into the following blocks:
  411.  
  412. "II"    instruments; contains all information for the saved instrument
  413. "VE"    volume-envelopes; contains the construction of all vol-envelopes for
  414.         this instrument
  415. "PE"    panning-envelopes; the same for the pan-envelopes
  416. "IS"    sampleinfos; contains information for every used sample
  417. "SA"    samples; contains the sample-datas
  418.  
  419. The structures for the several blocks are the same as in the mdl-format.
  420. The instrument-infoblock ("II") contains one instrument only.
  421.  
  422.  
  423.  
  424.  
  425. ╔════════════════════════════════════════════════════════════════════════════╗
  426. ║                          THE SAMPLE-FORMAT  (SPL)                     V0.0 ║
  427. ╚════════════════════════════════════════════════════════════════════════════╝
  428.  
  429. Here comes the description for the old sample-format "SPL", which was used in
  430. older tracker-versions (V2.0-V2.2). This format isn't supported any longer in
  431. Digitrakker, that means you can read it, but you can't save samples in this
  432. form.
  433. The reason for this step was the fact, that there are too many sample-formats
  434. and it makes no sense to introduce a new one, because the existing IFF-format
  435. nearly contains all infos you need for a Digitrakker-sample.
  436.  
  437. Offset Lenght Description
  438.  
  439.  000    004     "DSPL"; the four letters mark the spl-format
  440.  004    001     version; the current version is 0
  441.  005    032     sample-name; the name of the sample (filled with [32])
  442.  037    008     filename of the sample
  443.  045    002     C-4 sample-frequence in hz (00000-65535)
  444.  047    004     sample-length
  445.  051    004     sample-repeatstart
  446.  055    004     sample-repeatlength; if this value is set to 0, the sample
  447.         will not loop
  448.  059    001     sample-volume (1-255)
  449.  060    001     infobyte:
  450.         bit 0   -> 0=8 bit sample, 1=16 bit sample
  451.         bit 1   -> 0=forward looping, 1=bidirectional looping
  452.         bit 2,3 -> packmethode (0=not packed, methodes 2 and 3 doesn't
  453.                exist in this version)
  454.         bit 4-7 -> not used (should be set to 0)
  455.  061    ???     sampledatas... (see above)
  456.