.1 DigiTrekker Module Format (*.DTM) rev1.0 page 1 ------------------------------------------------------------------------------- This documentation describes the DigiTrekker Module Format. This format was first introduces with DigiTrekker 3.0, anyway 3.0 was the first version ever published. All number below are given in decimal format. Hexadecimal numbers are given the prefix '0x'. Symbols given in brackets [] are used to refer to the value of this field for later use. Module characteristics: ----------------------- o no limit on channels o up to 255 instruments o up to 255 patterns o up to 255 sequence positions o patterns split up into tracks o any number of rows per track o 8/16 bit samples The DigiTrekker Modules (DTM's) are organized in the IFF chunk format. The chunk length and all other integer and long values are stored in Intel byte order with the LSB first and the MSB last. A chunk is built like this: 4 byte ID, eg. "SONG" 4 byte length, eg. 0x05680100 The whole file is a sequence of such chunks. The main advantage of this tech- nique is that the module format can be easyly enhanced without the need of re- organization. Therefore only a new chunk would be added. If you encounter any chunk ID you don't know, don't care and forget the chunk. The song itself uses cascaded chunks, which means that some chunks are built up by chunks again. Terminology ------------------ Module: the file which contains a song Song: everything necessary to play your composition Sequence: the sequence (=order) tells you when to play which pattern Pattern: a table with 1 entry for each channel which maps a track to it Track: (64) rows of notes which are played one after the other Channel: the voice on which the sound is calculated and played Row: the notes of the tracks which are played at the same time Frame: the time a row is played is divided into frames Overview ========================== +SONG==========================================================================+ | NAME+ INFO+ INIT------+ PSEQ+ PATT+ INST--------+ TRAK---+ SAMP--------+| |! !! ! !sped+vpan+! ! !! ! !samp+text+ ! !trak+ ! !samp+text+ !| |! !! ! !! !! !! ! !! ! !! !! !..! !! !..! !! !! !..!| |! !! ! !+--- +--- ! ! !! ! !+--- +--- ! !+--- ! !+--- +--- !| |+---- +---- +---------- +---- +---- +------------ +------- +------------ | +==============================================================================+ ..1 DigiTrekker Module Format (*.DTM) rev1.0 page 2 ------------------------------------------------------------------------------- The SONG chunk (0) ============================================================ This is the main chunk. The whole song is placed into it, so if you try to load a module without a SONG chunk, it's no DTM. The SONG chunk contains no actual data, it only contains many sub-chunks which contain the actual data. The NAME chunk (1) ============================================================ Here you can read the modules name. If this chunk is missing, the module doesn't have a name. The INFO chunk (1) ============================================================ This chunk contains some important data necessary for further processing. This chunk must be included in every song. Offset # Bytes Description ------ ------- ----------- 0 2 number of channels [NOC] 2 2 sequence length [LEN] 4 2 number of patterns [NOP] 6 2 number of tracks [NOT] 8 2 number of instruments [NOI] The INIT chunk (1) ============================================================ Startup information for the song is placed here. This chunk consists of some other chunks again. The sped chunk (2) ------------------------------ The sped (speed) chunk contains the initial speed of the song when it is started. Offset # Bytes Description ------ ------- ----------- 0 2 speed, given in frames per row (see effect 0x0F) 2 2 tempo, given in beats/minute (see effect 0x10) The vpan chunk (2) ------------------------------ Here is the initial volume panning for each channel stored. Therefore this chunk should contain two bytes for each channel. See effect 0x11 for changing the panning during playback. Offset # Bytes Description ------ ------- ----------- 0 1 left volume (0-64) 1 1 right volume (0-64) ..1 DigiTrekker Module Format (*.DTM) rev1.0 page 3 ------------------------------------------------------------------------------- The PSEQ chunk (1) ============================================================ The pattern sequence is stored in this chunk. The length of this chunk should be the same as the LEN value of the INFO chunk. The sequence is a table of 1 byte entries which are the numbers of the patterns to be played. The PATT chunk (1) ============================================================ Unlike all conventional trackers, DT splits the well-known patters into many peaces. Those peaces are the tracks, which are then MAPPED together to build a pattern. The big advantage with comes with that is that there's no more need of copying frequently used tracks, like rythm tracks. Therefore, here are all patterns stored, wich gives a total number of entries of NOP*NOC. Each entry is a integer (2 bytes) and identifies a track number. The INST chunk (1) ============================================================ This chunk contains the information about the instruments used in this module. Note that an instrument is not the same as a sample. An instrument is anything which may appear in the instument list and may be a sample, text, ... Also this version of DT only supports samples and text instruments, there will probably be some wave-table and FM instruments too in future releases. Again, this chunk consists of many sub-chunks, which give the information for each single instrument. The text chunk (2) ------------------------------ Text instruments can't be played, they only appear as a text line in the instrument list. This text is the only data stored in a text chunk. Offset # Bytes Description ------ ------- ----------- 0 ? instrument name The samp chunk (2) ------------------------------ This chunk is used for samples. It contains some information about how to process the sample. Offset # Bytes Description ------ ------- ----------- 0 32 instrument name 32 4 length of sample 36 4 loop start \ 40 4 loop end / =0: no loop 44 2 C-4 sample rate 46 1 default volume (0-64) 47 1 bits per sample (8/16) 48 13 file name of sample 61 3 reserved ..1 DigiTrekker Module Format (*.DTM) rev1.0 page 4 ------------------------------------------------------------------------------- The TRAK chunk (1) ============================================================ Just like the INST chunk, the TRAK chunk consists of many trak chunks which hold the notes of the track. Today there are 6 bytes of data for each note which define the pitch, the instrument, the volume, an effect and its parameter. But as the DTM format is designed for eternity, the tracks are stored in a way which keeps the number of bytes per note open. The trak chunk (2) ------------------------------ Here are the notes of a track stored. They are split up into their means, so that at first there are all pitches, followed by all instruments, volumes and so on. If there is need for a 2nd effect/parameter in the future of for any- thing other, this way of storing data keeps all doors open. Offset # Bytes Description ------ ------- ----------- 0 2 number of rows [NOR] 2 NOR pitch 2+NOR NOR instrument 2+2*NOR NOR volume 2+3*NOR NOR effect 2+4*NOR NOR higher byte of parameter 2+5*NOR NOR lower byte of parameter Pitch, instrument, volume and effect values start with 1. 0 means that there's no value given. So a volume of 1 is actually a volume of 0, an effect of 5 is effect 4 in reality and so on. The pitch ranges from 1 to 96 for the notes C-0 to H-7. Note that C-0 is the real music notation and NOT the notation of MOD files. The .MOD C-1 note is a C-4 in DTM. A value of 0x80 for a note is a note-off command. The instrument is just like it is. Legal values are from 1 to NOI. The volume value ranges from 1 to 65 for the volume 0-64. Effects 0x01-0x10 are the same as effects 0x00-0x0F in MOD modules. 0x00: no effect 0x01: slide pitch x/128th seminotes up 0x02: slide pitch down 0x03: slide to note 0x04: vibrato speed xx, depth yy 0x05: continue slide-to, slide volume 0x06: cont. vibrato, slide volume 0x07: tremolo speed xx, depth yy 0x08: unused 0x09: set sample offset to x*16 0x0A: slide volume 0x0B: jump to sequence position x 0x0C: unused (set volume) 0x0D: break pattern and resume at row x 0x0E: extended FX 0x0F: set speed&tempo (=frames per row) 0x10: set tempo 0x11: set stereo panning (0-64) 0x12: slide stereo panning 0x13: add x to sample offset 0x14: store value (used for sync) 0x15: retrigger note 0x16: tremor xx frames on, yy off ..3. DigiTrekker Module Format (*.DTM) rev1.0 page 5 ------------------------------------------------------------------------------- The parameter depends on the effect. 0x01, 0x02, 0x03, 0x04: The pitch is given in 1/128th seminote. Therefore the old traditional logarighmic values have to be recalculated into DT's linear parameters, which are a much more convenient and accurate. As an standard you can use a multiplicator of 8 to convert old MOD values. This is not an accurate way of delogarithming values, but it's an average. 0x03, 0x05: If a pitch is given together with these effects, it's used as a further parameter. The effect acts like effect 0x01 or 0x02, but won't change the pitch byond the given note. Is no note given, the fade continues. 0x04, 0x07: The higher byte gives the periode of the vibrato/tremor in 64/x frames. With a value of 1 it takes 64 frames to complete the periode. The lower byte defines the amplitude of the pitch/volume change. 0x05, 0x06, 0x0A: Either the high or low parameter has to be 0 or FF. Is the high parameter none of both, then add it to the current volume after each frame. Is the low parameter different to 0 and FF, then subtract the value from the volume after each frame. Is the high/low parameter FF, then the low/high parameter is subtracted/ added from/to the volume at the beginning of the note (=fine slide) 0x0E: The high parameter gives the sub-effect number and the low parameter is its effect: Fn 0x0: unused (set Amiga filter) Fn 0x1: fine slide up (use effect 0x01 with parameter FFxx instead) Fn 0x2: fine slide down (use effect 0x02 with parameter xxFF instead) Fn 0x3: set glissando on/off. If ON effect 0x03 only plays full seminotes. Fn 0x4: set vibrato waveform: 0=sine, 1=saw, 2=square, 3=random Fn 0x5: set finetune to x-8 seminotes, this effects the C-4 samplerate. Fn 0x6: loop pattern, 0: set loop start, <>0: loop x times back Fn 0x7: set tremolo waveform: 0=sine, 1=saw, 2=square, 3=random Fn 0x8: unused Fn 0x9: retrigger sample (use effect 0x15 with parameter x000 instead) Fn 0xA: fine volume slide up (use effect 0x0A with param 0xFF instead) Fn 0xB: fine volume slide down (use effect 0x0A with param FF0x instead) Fn 0xC: cut sample (set volume to 0) after x frames Fn 0xD: delay note: start note after x frames Fn 0xE: delay pattern: wait the time for x rows after current row 0x0F: The high parameter sets the frames per row, the low parameter defines how many frames per second should be played, which is identical to a value of x*125/50 for effect 0x10 0x11: The high and low parameter define the pan volume for left/right 0x12: The high/low parameter is a signed byte which is added to the pan vol. 0x14: This effect is used for synchronizing music and grafic in demos 0x15: The parameter is interpretet like this: dfxy (delay,function,x,y) The delay tells after how many frames the retrigger should take place, the function tells what should happen with the volume. Depending on that value the x and y values change their meaning: Fn 0: don't change volume Fn 1: subtract xy from volume Fn 2: add xy to volume Fn 3: multiply volume by x and divide it by y ..1 DigiTrekker Module Format (*.DTM) rev1.0 page 6 ------------------------------------------------------------------------------- The SAMP chunk (1) ============================================================ As the INST chunk before, the SAMP chunk contains sub-chunks for the single instruments. The type of sub-chunk depends on the type of instrument. If you encounter an unknown chunk, skip the instrument as well as the chunk. The number of sub-chunks should be the same as the NOI field in the INFO chunk tells. The samp chunk (2) ------------------------------ Sample values are stored as either 8 bit or 16 bit signed mono PCM values. The length of the chunk should be the same as the length field in the inst- chunk for the sample. The text chunk (2) ------------------------------ If someone has to tell a whole story, he can put it in here. This chunk is of no interest for playback, but could be used for placing some lyrics in the song. That's all... If you want to contact the author, write to Snail Mail: E-mail: MuseNet: ---------------- -------------- ------------------------- Horst Beham Jr., d5c01@unix1.htl-leonding.ac.at White_Bunny@ Kappernstr. 30 ! only valid until July '95 ! chezmoto.ai.mit.edu 4201 4614 Marchtrenk ! new address after that ! oceana.sdsc.edu 4201 Austria