home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 February / PCWorld_2000-02_cd.bin / Software / Servis / FFE / MOD.SWG / 0005_DTM.pas < prev    next >
Pascal/Delphi Source File  |  1996-09-04  |  14KB  |  336 lines
  1.  
  2. This  documentation describes the DigiTrekker Module Format. This format
  3. was  first  introduces  with DigiTrekker 3.0,  anyway  3.0 was the first
  4. version ever published.
  5.  
  6. All  number  below are given in  decimal format. Hexadecimal numbers are
  7. given the prefix '0x'.
  8.  
  9. Symbols  given  in  brackets [] are used  to  refer to the value of this
  10. field for later use.
  11.  
  12. Module characteristics:
  13. -----------------------
  14. o no limit on channels
  15. o up to 255 instruments
  16. o up to 255 patterns
  17. o up to 255 sequence positions
  18. o patterns split up into tracks
  19. o any number of rows per track
  20. o 8/16 bit samples
  21.  
  22.  
  23. The  DigiTrekker Modules (DTM's) are organized  in the IFF chunk format.
  24. The  chunk  length and all other integer  and  long values are stored in
  25. Intel byte order with the LSB first and the MSB last.
  26.  
  27. A chunk is built like this:
  28. 4 byte ID, eg. "SONG"
  29. 4 byte length, eg. 0x05680100
  30.  
  31. The  whole file is a sequence of such chunks. The main advantage of this
  32. tech- nique is that the module format can be easyly enhanced without the
  33. need  of re- organization. Therefore only a new chunk would be added. If
  34. you  encounter  any chunk ID you don't  know,  don't care and forget the
  35. chunk.
  36.  
  37. The  song itself uses cascaded chunks,  which means that some chunks are
  38. built up by chunks again.
  39.  
  40.  
  41. Terminology
  42. ------------------
  43. Module:   the file which contains a song
  44. Song:     everything necessary to play your composition
  45. Sequence: the sequence (=order) tells you when to play which pattern
  46. Pattern:  a table with 1 entry for each channel which maps a track to it
  47. Track:    (64) rows of notes which are played one after the other
  48. Channel:  the voice on which the sound is calculated and played
  49. Row:      the notes of the tracks which are played at the same time
  50. Frame:    the time a row is played is divided into frames
  51.  
  52.  
  53. Overview
  54. ==========================
  55.  
  56. ╔SONG══════════════════════════════════════════════════════════════════════════╗
  57. ║ NAME┐ INFO┐  INIT──────┐  PSEQ┐ PATT┐  INST────────┐  TRAK───┐  SAMP────────┐║
  58. ║│    ││    │ │sped┐vpan┐│ │    ││    │ │samp┐text┐  │ │trak┐  │ │samp┐text┐  │║
  59. ║│    ││    │ ││   ││   ││ │    ││    │ ││   ││   │..│ ││   │..│ ││   ││   │..│║
  60. ║│    ││    │ │└─── └─── │ │    ││    │ │└─── └───   │ │└───   │ │└─── └───   │║
  61. ║└──── └────  └──────────  └──── └────  └────────────  └───────  └──────────── ║
  62. ╚══════════════════════════════════════════════════════════════════════════════╝
  63.  
  64. The SONG chunk (0)
  65. ============================================================
  66. This  is the main chunk. The whole song is placed into it, so if you try
  67. to load a module without a SONG chunk, it's no DTM.
  68.  
  69. The SONG chunk contains no actual data, it only contains many sub-chunks
  70. which contain the actual data.
  71.  
  72.  
  73. The NAME chunk (1)
  74. ============================================================
  75. Here you can read the modules name. If this chunk is missing, the module
  76. doesn't have a name.
  77.  
  78.  
  79. The INFO chunk (1)
  80. ============================================================
  81. This   chunk   contains  some  important   data  necessary  for  further
  82. processing. This chunk must be included in every song.
  83.  
  84. Offset  # Bytes Description
  85. ------  ------- -----------
  86. 0       2       number of channels      [NOC]
  87. 2       2       sequence length         [LEN]
  88. 4       2       number of patterns      [NOP]
  89. 6       2       number of tracks        [NOT]
  90. 8       2       number of instruments   [NOI]
  91.  
  92.  
  93. The INIT chunk (1)
  94. ============================================================
  95. Startup  information for the song is placed here. This chunk consists of
  96. some other chunks again.
  97.  
  98.  
  99.   The sped chunk (2)
  100.   ------------------------------
  101.   The sped (speed) chunk contains the initial speed of the song when it is
  102.   started.
  103.  
  104.     Offset  # Bytes Description
  105.     ------  ------- -----------
  106.     0       2       speed, given in frames per row (see effect 0x0F)
  107.     2       2       tempo, given in beats/minute   (see effect 0x10)
  108.  
  109.  
  110.   The vpan chunk (2)
  111.   ------------------------------
  112. Here  is  the initial volume panning  for each channel stored. Therefore
  113. this  chunk  should contain two bytes  for each channel. See effect 0x11
  114. for changing the panning during playback.
  115.  
  116.     Offset  # Bytes Description
  117.     ------  ------- -----------
  118.     0       1       left volume (0-64)
  119.     1       1       right volume (0-64)
  120.  
  121. The PSEQ chunk (1)
  122. ============================================================
  123. The  pattern sequence is stored in this  chunk. The length of this chunk
  124. should be the same as the LEN value of the INFO chunk. The sequence is a
  125. table  of  1  byte entries which are  the  numbers of the patterns to be
  126. played.
  127.  
  128.  
  129. The PATT chunk (1)
  130. ============================================================
  131. Unlike  all conventional trackers, DT splits the well-known patters into
  132. many peaces. Those peaces are the tracks, which are then MAPPED together
  133. to  build  a  pattern. The big advantage  with  comes  with that is that
  134. there's  no  more  need of copying  frequently  used  tracks, like rythm
  135. tracks.
  136.  
  137. Therefore,  here  are all patterns stored,  wich gives a total number of
  138. entries  of NOP*NOC. Each entry is a  integer (2 bytes) and identifies a
  139. track number.
  140.  
  141.  
  142. The INST chunk (1)
  143. ============================================================
  144. This  chunk contains the information about  the instruments used in this
  145. module.  Note  that  an  instrument  is not  the  same  as  a sample. An
  146. instrument is anything which may appear in the instument list and may be
  147. a sample, text, ...
  148.  
  149. Also  this  version  of DT only  supports  samples and text instruments,
  150. there  will probably be some wave-table and FM instruments too in future
  151. releases.
  152.  
  153. Again,   this  chunk  consists  of   many  sub-chunks,  which  give  the
  154. information for each single instrument.
  155.  
  156.   The text chunk (2)
  157.   ------------------------------
  158. Text instruments can't be played, they only appear as a text line in the
  159. instrument list. This text is the only data stored in a text chunk.
  160.  
  161.     Offset  # Bytes Description
  162.     ------  ------- -----------
  163.     0       ?       instrument name
  164.  
  165.  
  166.   The samp chunk (2)
  167.   ------------------------------
  168. This  chunk is used for samples.  It contains some information about how
  169. to process the sample.
  170.  
  171.     Offset  # Bytes Description
  172.     ------  ------- -----------
  173.     0       32      instrument name
  174.     32      4       length of sample
  175.     36      4       loop start \
  176.     40      4       loop end   / =0: no loop
  177.     44      2       C-4 sample rate
  178.     46      1       default volume (0-64)
  179.     47      1       bits per sample (8/16)
  180.     48      13      file name of sample
  181.     61      3       reserved
  182.  
  183. The TRAK chunk (1)
  184. ============================================================
  185. Just  like  the INST chunk, the TRAK  chunk consists of many trak chunks
  186. which hold the notes of the track.
  187.  
  188. Today  there  are 6 bytes of data  for each note which define the pitch,
  189. the  instrument, the volume, an effect and its parameter. But as the DTM
  190. format  is  designed for eternity, the tracks  are stored in a way which
  191. keeps the number of bytes per note open.
  192.  
  193.   The trak chunk (2)
  194.   ------------------------------
  195. Here  are  the  notes of a track  stored.  They  are split up into their
  196. means,  so  that  at  first  there  are  all  pitches,  followed  by all
  197. instruments,   volumes   and  so  on.  If   there  is  need  for  a  2nd
  198. effect/parameter  in  the  future of for  any-  thing other, this way of
  199. storing data keeps all doors open.
  200.  
  201.     Offset  # Bytes Description
  202.     ------  ------- -----------
  203.     0       2       number of rows [NOR]
  204.     2       NOR     pitch
  205.     2+NOR   NOR     instrument
  206.     2+2*NOR NOR     volume
  207.     2+3*NOR NOR     effect
  208.     2+4*NOR NOR     higher byte of parameter
  209.     2+5*NOR NOR     lower byte of parameter
  210.  
  211. Pitch,  instrument, volume and effect values  start with 1. 0 means that
  212. there's  no value given. So a volume of  1 is actually a volume of 0, an
  213. effect of 5 is effect 4 in reality and so on.
  214.  
  215. The pitch ranges from 1 to 96 for the notes C-0 to H-7. Note that C-0 is
  216. the  real music notation and NOT the notation of MOD files. The .MOD C-1
  217. note is a C-4 in DTM. A value of 0x80 for a note is a note-off command.
  218.  
  219.   The instrument is just like it is. Legal values are from 1 to NOI.
  220.  
  221.   The volume value ranges from 1 to 65 for the volume 0-64.
  222.  
  223.   Effects 0x01-0x10 are the same as effects 0x00-0x0F in MOD modules.
  224.    0x00: no effect                     0x01: slide pitch x/128th seminotes up
  225.    0x02: slide pitch down              0x03: slide to note
  226.    0x04: vibrato speed xx, depth yy    0x05: continue slide-to, slide volume
  227.    0x06: cont. vibrato, slide volume   0x07: tremolo speed xx, depth yy
  228.    0x08: unused                        0x09: set sample offset to x*16
  229.    0x0A: slide volume                  0x0B: jump to sequence position x
  230.    0x0C: unused (set volume)           0x0D: break pattern and resume at row x
  231.    0x0E: extended FX                   0x0F: set speed&tempo (=frames per row)
  232.    0x10: set tempo                     0x11: set stereo panning (0-64)
  233.    0x12: slide stereo panning          0x13: add x to sample offset
  234.    0x14: store value (used for sync)   0x15: retrigger note
  235.    0x16: tremor xx frames on, yy off
  236.  
  237.   The parameter depends on the effect.
  238.  
  239.    0x01, 0x02, 0x03, 0x04:
  240. The  pitch  is given in 1/128th  seminote. Therefore the old traditional
  241. logarighmic  values have to be recalculated into DT's linear parameters,
  242. which  are  a much more convenient and  accurate. As an standard you can
  243. use  a  multiplicator  of 8 to convert  old  MOD  values. This is not an
  244. accurate way of delogarithming values, but it's an average.
  245.  
  246.    0x03, 0x05:
  247. If  a pitch is given together with these effects, it's used as a further
  248. parameter.  The  effect acts like effect  0x01 or 0x02, but won't change
  249. the pitch byond the given note. Is no note given, the fade continues.
  250.  
  251.    0x04, 0x07:
  252. The  higher byte gives the periode of the vibrato/tremor in 64/x frames.
  253. With  a value of 1 it takes 64 frames to complete the periode. The lower
  254. byte defines the amplitude of the pitch/volume change.
  255.  
  256.    0x05, 0x06, 0x0A:
  257. Either  the  high  or  low  parameter has to  be  0  or  FF. Is the high
  258. parameter  none  of both, then add it  to  the current volume after each
  259. frame.  Is  the low parameter different to  0  and FF, then subtract the
  260. value  from  the volume after each  frame. Is the high/low parameter FF,
  261. then  the low/high parameter is subtracted/  added from/to the volume at
  262. the beginning of the note (=fine slide)
  263.  
  264.    0x0E:
  265.      The high parameter gives the sub-effect number and the low parameter is
  266.      its effect:
  267.      Fn 0x0: unused (set Amiga filter)
  268.      Fn 0x1: fine slide up (use effect 0x01 with parameter FFxx instead)
  269.      Fn 0x2: fine slide down (use effect 0x02 with parameter xxFF instead)
  270.      Fn 0x3: set glissando on/off. If ON effect 0x03 only plays full seminotes.
  271.      Fn 0x4: set vibrato waveform:  0=sine, 1=saw, 2=square, 3=random
  272.      Fn 0x5: set finetune to x-8 seminotes, this effects the C-4 samplerate.
  273.      Fn 0x6: loop pattern, 0: set loop start, <>0: loop x times back
  274.      Fn 0x7: set tremolo waveform:  0=sine, 1=saw, 2=square, 3=random
  275.      Fn 0x8: unused
  276.      Fn 0x9: retrigger sample (use effect 0x15 with parameter x000 instead)
  277.      Fn 0xA: fine volume slide up (use effect 0x0A with param 0xFF instead)
  278.      Fn 0xB: fine volume slide down (use effect 0x0A with param FF0x instead)
  279.      Fn 0xC: cut sample (set volume to 0) after x frames
  280.      Fn 0xD: delay note: start note after x frames
  281.      Fn 0xE: delay pattern: wait the time for x rows after current row
  282.  
  283.    0x0F:
  284. The  high  parameter sets the frames  per row, the low parameter defines
  285. how  many  frames per second should be  played,  which is identical to a
  286. value of x*125/50 for effect 0x10
  287.  
  288.    0x11: The high and low parameter define the pan volume for left/right
  289.  
  290.    0x12: The high/low parameter is a signed byte which is added to the pan vol.
  291.  
  292.    0x14: This effect is used for synchronizing music and grafic in demos
  293.  
  294.    0x15:
  295.      The parameter is interpretet like this: dfxy (delay,function,x,y)
  296.      The delay tells after how many frames the retrigger should take place, the
  297.      function tells what should happen with the volume. Depending on that value
  298.      the x and y values change their meaning:
  299.      Fn 0: don't change volume
  300.      Fn 1: subtract xy from volume
  301.      Fn 2: add xy to volume
  302.      Fn 3: multiply volume by x and divide it by y
  303.  
  304. The SAMP chunk (1)
  305. ============================================================
  306. As  the  INST chunk before, the  SAMP  chunk contains sub-chunks for the
  307. single  instruments.  The  type  of sub-chunk  depends  on  the  type of
  308. instrument.  If  you encounter an unknown  chunk, skip the instrument as
  309. well as the chunk.
  310.  
  311. The number of sub-chunks should be the same as the NOI field in the INFO
  312. chunk tells.
  313.  
  314.   The samp chunk (2)
  315.   ------------------------------
  316. Sample  values  are  stored as either 8  bit  or  16 bit signed mono PCM
  317. values.  The length of the chunk should  be the same as the length field
  318. in the inst- chunk for the sample.
  319.  
  320.  
  321.   The text chunk (2)
  322.   ------------------------------
  323. If  someone has to tell a whole story, he can put it in here. This chunk
  324. is  of  no  interest for playback, but  could  be  used for placing some
  325. lyrics in the song.
  326.  
  327. If you want to contact the author, write to
  328.  
  329.   Snail Mail:       E-mail:                          MuseNet:
  330.   ----------------  --------------                   -------------------------
  331.   Horst Beham Jr.,  d5c01@unix1.htl-leonding.ac.at   White_Bunny@
  332.   Kappernstr. 30    ! only valid until July '95 !     chezmoto.ai.mit.edu 4201
  333.   4614 Marchtrenk   ! new address after that    !     oceana.sdsc.edu 4201
  334.   Austria
  335.  
  336.