




                              The .MOD File Format
                              --------------------
                           Third Release.  March 1994

  This document describes the format of Amiga .MOD files.  It was written  by
  DNA (Dave Coombs) and originally included as part of the Superiority Mix MOD
  player by Enigma (Avery Pennarun) of Superiority Complex.

  You will only need this information if you're going to write a  MOD player.
  If you aren't, don't bother reading this - you'll likely find it  extremely
  boring and confusing.  If, on the other hand, you're an aspiring programmer
  longing to make a  MOD player, read on...  you'll likely find it  extremely
  boring and confusing.

  I should warn you, though, that .MOD is NOT the easiest file format on  the
  planet.  We had even less information than this to start out with, so a lot
  of the details here are either fuzzy, nonexistent, or have been filled in as
  EnigmaLogic wrote Superiority MIX.

  This file  was painstakingly  typed  by DNA  (Dave Coombs)  of  Superiority
  Complex.  Just colour me overworked and underpaid...  :-)  You are  free to
  upload and distribute this document wherever and however you want, so long as
  it's unmodified.  The  latest version of Superiority  MIX will include  any
  revisions to this document. Although I made this as accurate as possible, I
  can't guarantee that there are no errors, so use this information at your own
  risk.

  Please contact me  at the  address below if  you find  any glaring  errors,
  corrections, or more complete information regarding the format of MOD files
  or other related file formats:
                           Dave Coombs
                           569 Cambrian Cr.
                           Thunder Bay, ON
                           Canada
                           P7C 5C2
  ---

  Extra special thanks go out to Andrew Sears of Whitby, Ontario, who  posted
  all this information on NANet for us! We'd be lost without you! Also thanks
  to whoever gave this information to HIM... (Thomas House was mentioned in the
  original file) and so on.

  ---

  NOTES:
    -  All numbers are decimal, unless I state otherwise.
    -  "Word" variables are NOT stored with the Intel byte inversion thing. ie
       40E6 hex WOULD be stored as 40 E6, not E6 40. To use these values on an
       Intel processor (8086, 286, etc), you have to switch the bytes around.

  Have fun... (I'm SURE you won't...)


                                     Page 1






  MOD FILE STRUCTURE
  ------------------

  OFFSET    LENGTH    DESCRIPTION
  ------    ------    -----------

  0         20        The title of the song. Remember to pad it with null (0)
                      bytes.  If a title is exactly 20 characters long, it is
                      NOT null-terminated automatically.
  50        30        Info for sample #1 - described below
  80        30        Info for sample #2
             .
             .        There are 31 info blocks if M.K., FLT4, FLT8, 6CHN,
             .        8CHN, or OCTA is at
             .        position 1080.  Otherwise, there are 15 and all offsets
             .        are adjusted.
             .
  920       30        Info for sample #31
  950       1         The number of pattern-positions in this song.  Range is
                      1 to 128.
  951       1         This byte  is  always  set to  127.    Something  about
                      Noisetracker's "Restart" byte.  Probably not important,
                      but it's there anyway.
  952       128       Song positions 0-127. Each byte holds a number from 0 to
                      63 indicating which pattern to play at that position.
  1080      4         The four letters "M.K."   When a  couple of guys  named
                      Mahoney and Kaktus increased the number of samples in a
                      MOD file from 15 to 31, they stuck their initials in here
                      to signify a 31 sample song. Startrekker puts "FLT4" or
                      "FLT8" there instead.  If  the signature is not  there,
                      then it's a 15  sample song and these  4 bytes are  NOT
                      present.  Also note  that M.K. and  FLT4 denote a  four
                      channel module. 6CHN means it has six channels, and 8CHN
                      and OCTA indicate eight channels... More on that later.
  1084      1024      Data for pattern #0 - described below
             .
             .
             .
  xxxx      xxxx      There are 1-64 patterndata blocks. The highest number in
                      the position table at offset 952 will tell you how many
                      patterns to load. e.g. if the highest pattern number in
                      the table is  63, load 64  patterns because it's  zero-
                      based. NOTE: When scanning for highest position number,
                      scan ALL bytes in the table, not just the ones that will
                      actually play.  (dumb, I know)
  yyyy      yyyy      The sampledata (actual digital sound) starts right after
                      the last pattern. Use the sampleinfo near the beginning
                      to determine which samples to load and how long each is.




                                     Page 2





  SAMPLEINFO STRUCTURE
  --------------------

  OFFSET    LENGTH    DESCRIPTION
  ------    ------    -----------

  0         22        Sample name.  This is  padded with null bytes like  the
                      song title.
  22        2         Sample length in words. To get the actual number of bytes
                      in the sample, just multiply by two. (Remember that this
                      is a word variable, and NOT stored with the Intel  byte
                      inversion!)
  24        1         The lower four bits of this byte are the finetune value
                      for the song, stored as a signed four-bit number.  (see
                      below)  The upper four bits aren't used, and should  be
                      set to 0000 for compatibility.

                      Value     Finetune
                      0         0
                      1         +1
                      2         +2
                      3         +3
                      4         +4
                      5         +5
                      6         +6
                      7         +7
                      8         -8
                      9         -7
                      A         -6
                      B         -5
                      C         -4
                      D         -3
                      E         -2
                      F         -1

  25        1         Default sample volume.  It  can range from 00h to  40h,
                      which is  0 to  64  decimal. Note  that this  is  often
                      overridden by some special effects, but if it isn't, you
                      should use this value.
  26        2         Loop start. It is stored as the number of words from the
                      start of the sample.  Multiply by two to get the offset
                      in bytes.  When the player reaches the end of a  sample
                      that has loopstart and looplength set, it should continue
                      playing the sample at loopstart.  After that, it should
                      return to loopstart whenever  it has played  looplength
                      more bytes.
  28        2         Loop length.  It is stored as the number of words to be
                      looped.  Looplength is set to ONE (TWO once multiplied)
                      by some MOD trackers when no looping is to be in effect.
                      Others use ZERO.



                                     Page 3





  PATTERNDATA STRUCTURE
  ---------------------

  Each note is stored as four bytes (see below), and each note in each of the
  four tracks is stored after one another, like this:

  OFFSET    LENGTH    DESCRIPTION
  ------    ------    -----------
  0         4         Note 1, Track 1 - described below
  4         4         Note 1, Track 2
  8         4         Note 1, Track 3
  12        4         Note 1, Track 4
  16        4         Note 2, Track 1
            .
            .
            .
  1020      4         Note 64, Track 4

  NOTE:     Six-channel mods and eight-channel mods work just like the  four-
            channel variety, except the data for each row will be longer. For
            example, in a six-channel song, Note 1 Track 4 will be followed by
            Note 1 Track 5.  Then comes Note  1 Track 6, and THEN it goes  to
            Note 2 Track 1.  Thus,  in a six-channel song, each pattern  will
            take 1.5 times as much space, and in an eight-channel song,  each
            pattern will be twice as long.

  Information for each note is disorganized as follows:

  +----Byte 1----+ +Byte 2+   +---- Byte 3 ---+ +Byte 4+
  |              | |      |   |               | |      |
  0000        0000-00000000   0000         0000-00000000
  upper 4        12-bit      lower 4          12-bit
  bits of         note       bits of          effect
  sample         period      sample           command
  number                     number

  NOTE:  "Upper 4 bits of sample number" is "Reserved" in a 15-sample MOD.
















                                     Page 4





  WHAT THE HECK IS A "PERIOD?"
  ----------------------------

  Well, a period is just a stupid (and I DO mean stupid) method of storing what
  note the player is supposed to play.  Here's the period table we used:

  OCTAVE    C    C#   D    D#   E    F    F#   G    G#   A    A#   B 
    0       1712 1616 1525 1440 1359 1283 1211 1143 1078 1018 961  907    
    1       856  808  763  720  679  641  605  571  539  509  480  453
    2       428  404  381  360  340  321  303  286  270  254  240  227
    3       214  202  191  180  170  160  151  143  135  127  120  113
    4       107  101  95   90   85   80   76   71   67   64   60   57
    5       53   50   48   45   42   40   38   36   34   32   30   28
    6       27   25   24   22   21   20   19   18   17   16   15   14
    7       13   N/A  12   11   N/A  10   N/A  9    8    8    N/A  7
     
  As you can see, there are N/A's at the bottom.  That's because when you get
  that high  up (octave  7...) the  periods are  so close  together that  the
  computer can't tell  the difference  (nor can most  humans) between  notes.
  Nevertheless, we had NO CLUE how to use a period table when we started.  We
  simply had the  nifty collection  of numbers  you see  dangling above  this
  paragraph. Our best guess would be that you're supposed to create a look-up
  table so that you  can turn the  useless period number  into a more  useful
  frequency.  This, of course, prompted  the question "Why?"  So, we  (mostly
  Avery) thought, and we decided to trash the thing and come up with a formula
  that does the conversion for you...  The formula we used is:
                       Freq = 10,000 * 340 / period

     It works, and it's good enough. I can't tell the difference, can YOU tell
  the difference?  This takes a bit  of tweaking - if you change the  numbers
  slightly, you may get better/worse sound.

  Version 1.2  of  MIX  uses  a totally  different  method  of  figuring  out
  frequencies from periods. I did this when I discovered that DNA's Christmas
  music didn't  sound quite  like it  did when  it was  composed!   Actually,
  Christmas '93 used MIX 1.1, so it sounded off-key... but MIX 1.2 will  play
  the songs correctly.  When  I load a MOD,  I use the following  translation
  table (C source code):

  unsigned periodtable[96]={
       1712,1616,1524,1440,1356,1280,1208,1140,1076,1016,960,906,  // 0
        856, 808, 762, 720, 678, 640, 604, 570, 538, 508,480,453,  // 1
        428, 404, 381, 360, 339, 320, 302, 285, 269, 254,240,226,  // 2
        214, 202, 190, 180, 170, 160, 151, 143, 135, 127,120,113,  // 3
        107, 101,  95,  90,  85,  80,  76,  71,  67,  64, 60, 57,  // 4
         54,  51,  48,  45,  42,  40,  38,  36,  34,  32, 30, 28,  // 5
         27,  25,  24,  23,  21,  20,  19,  18,  17,  16, 15, 14,  // 6
         13,  13,  12,  11,  11,  10,   9,   9,   8,   8,  8,  7}; // 7





                                     Page 5





  Search through the table until you find a value <= the one stored in the MOD.
  Make 'x' the index into the table that you found the value.  So, the OCTAVE
  number is x/12, and the note number is x%12 (meaning, x MOD 12).

  When you actually play the song, use the following frequency table to look up
  the proper frequency to play.  The frequency value is:
        freqtable[note] >> (7-octave)

  For non-C programmers, look up value number 'note' in freqtable (which will
  be from 0-11, just  like the freqtable).   Then, right-shift it  '7-octave'
  times (a right shift is the same as a divide by 2... two right shifts is the
  same as a divide by 4, etc).

  And here's frequency table (more C source code):

  // frequency table for octave 7
  long freqtable[12]={
            //c         c#        d       d#         e        f
            8226*32L,8748*32L,9272*32L,9800*32L,10420*32L,11007*32L,
            //f#        g         g#        a         a#         b
            11696*32L,12400*32L,13070*32L,13950*32L,14760*32L,15646*32L
            };































                                     Page 6





  EFFECT COMMANDS
  ---------------

  Since all I'm supposed to tell you in this file is the format of the MOD file
  and how to read it, I'm not going  to tell you how to go about playing  the
  song. I will, however, tell you what all the effect commands do.  An effect
  command consists of 3 "nibbles." (a nibble is exactly 4 bits, or half a byte)
  The first nibble is the command, ranging from 0 to F.  The second and third
  nibbles are the effect data, and each effect uses them differently.  If the
  first (command) nibble is  E, then the second  byte is an extended  command
  name, and the third byte is the data.  Here's a super-brief listing of  all
  the commands.

  0 - None/Arpeggio                  8 - NOT USED
  1 - Portamento Up                  9 - Sample Offset
  2 - Portamento Down                A - Volume Slide
  3 - Tone Portamento                B - Position Jump
  4 - Vibrato                        C - Set Volume
  5 - Tone Portamento + Volume Slide D - Pattern Break
  6 - Vibrato + Volume Slide         E - Extended Command (below)
  7 - TremoloF - Set Speed

  The extended commands:
  E0 - Filter on/off                 E8 - NOT USED
  E1 - Fineslide Up                  E9 - Retrig
  E2 - Fineslide Down                EA - FineVol Up
  E3 - Glissando Control             EB - FineVol Down   
  E4 - Vibrato Control               EC - Note Cut
  E5 - Set Finetune                  ED - Note Delay
  E6 - Patternloop                   EE - Pattern Delay   
  E7 - Tremolo Control               EF - Invert Loop






















                                     Page 7





  0 - None/Arpeggio
  -----------------
  Usage: 0xy, where x and y are numbers of halfnotes to add. Arpeggio is used
  to simulate chords by playing the original  note for 1 tick, then adding  x
  halfnotes and playing that note for 1 tick, then adding y halfnotes to  the
  original value, playing that note for 1  tick, then starting over.  If  you
  want no effect, just leave  both parameters at 0.   There are 50 ticks  per
  second, and "songspeed" ticks per note.


  1 - Portamento Up
  -----------------
  Usage: 1xx, where xx is the speed of the slide, in hex. This command simply
  slides the sample pitch up.  Our  sources say that you cannot slide  higher
  than B-3 (period 113), but I sure  don't know why.  The portamento will  be
  called every tick, as many times as the speed of the song. Each tick, xx is
  subtracted from the period.   Make SURE you  start the slide __AFTER__  the
  first tick!


  2 - Portamento Down
  -------------------
  Usage: 2xx, where xx is the speed of the slide, in hex.  This command works
  exactly the same as Portamento up,  except xx is added to the period  every
  tick.  Apparently, you cannot slide lower than C-1.  Again, start AFTER the
  first tick.

  3 - Tone Portamento
  -------------------
  Usage: destination note + 3xx,  where xx is the speed  of the slide.   This
  command will slide from the old note to the new note, at speed xx. MODs don't
  have to worry about the slide direction, because it will always be toward the
  new note. You only have to worry about the speed. To keep on sliding at the
  same speed, a "300" command is issued. (command 3, parameters 0 and 0) Same
  rule about starting after the first tick applies.


  4 - Vibrato
  -----------
  Usage: 4xy, where x is the speed, and y is the depth.  This command  wavers
  the pitch of the note real quickly.   To keep on vibrating, just issue  the
  command "400".  I wouldn't be surprised if the _AFTER_ the first tick thing
  applies here too.  Same with many of the following effects...  :)


  5 - Tone Portamento + Volume Slide
  ----------------------------------
  Usage: 5x0 or 50y.   (see the Volume Slide command)   To use this  command,
  there has to be a Tone Portamento already in effect. This command continues
  the portamento, and also slides the volume.



                                     Page 8





  6 - Vibrato + Volume Slide
  --------------------------
  Usage: 6x0 or  60y.  (again,  see the Volume  Slide command)   To use  this
  command, there has to be a Vibrato already in effect. This command continues
  the vibrato, and also slides the volume.


  7 - Tremolo
  -----------
  Usage: 7xy, where x is the speed, and  y is the depth.  This command  works
  just like Vibrato, except the volume of the note is vibrated instead of the
  pitch.


  9 - Sample Offset
  -----------------
  Usage: 9xx, where xx is  the offset.  Instead  of starting the note at  the
  beginning of the sample, this command will let you start from wherever  you
  want.  Take the value of xx, multiply it by 256, and start from that offset
  in the sample.


  A - Volume Slide
  ----------------
  Usage: Ax0 or A0y.  This command slides  the volume of the sample.  In  the
  first case, Ax0, the volume is slid up at speed x.  In the case of A0y, the
  volume is slid down at speed y. (ie - the value is added or subtracted from
  the volume every tick) Make sure you start the slide _AFTER_ the first tick!


  B - Position Jump
  -----------------
  Usage: Bxx, where xx is  the position to jump to.   This command stops  the
  current pattern and jumps to the position specified by xx. xx can range from
  0-127.


  C - Set Volume
  --------------
  Usage: Cxx, where xx is new volume.  This command changes the volume of the
  current note.  The volume stays in effect until another note is encountered
  with a new sample  number (you can  continue at this  volume and with  this
  sample by using sample #0)  xx can range from 0-40 hex.


  D - Pattern Break
  -----------------
  Usage: D00.   This  command stops  the  current pattern  and jumps  to  the
  beginning of the next position in the position table. (If that was the last
  position, the song will end)



                                     Page 9





  F - Set Speed
  -------------
  Usage: Fxx, where xx is the speed of the song.  This command sets the speed
  of the song. If xx is between 1 and 1B hex, then that is the number of ticks
  per note. If it's more than 1B, then it's the number of beats per minute.  


  And now all the extended commands:
     
  E0 - Filter Status
  ------------------
  Usage: E0x, where x is the filter status, 0 or 1.  This command plays  with
  the sound filter on some Amigas.  1 disconnects the filter, and 0 turns  it
  on.


  E1 - Fineslide Up
  -----------------
  Usage: E1x, where x is the value to adjust by. This command works just like
  normal Portamento up, except it only slides once. It slides the pitch by x.


  E2 - Fineslide Down
  -------------------
  Usage: E2x, where x is the value to adjust by. This command works just like
  normal Portamento down, except it only slides once.  It slides the pitch by
  x.


  E3 - Glissando Control
  ----------------------
  Usage: E3x, where x is the glissando status, 0 or 1.  This command must  be
  used with the Tone Portamento command.   When glissando is activated,  tone
  portamento will slide by a halfnote at a time, instead of a straight slide.
  1 enables glissando, and 0 disables it.


  E4 - Set Vibrato Waveform
  -------------------------
  Examples: 
       E40  Set sine (default)
       E44  Don't retrig waveform
       E41  Set ramp down
       E45  Don't retrig waveform
       E42  Set squarewave
       E46  Don't retrig waveform
       E43  Set random
       E47  Don't retrig waveform





                                    Page 10





  E5 - Set finetune
  -----------------
  Usage: E5x, where x is the finetune value.  This command sets the  finetune
  value. x represents the exact same values that it did when I told you about
  the finetune value near the top of this doc.  Why you'd ever want to change
  it in the middle of a song, I do not know.


  E6 - Patternloop
  ----------------
  Usage: E6x.  If x  is 0, then that  spot is set as  the start of the  loop.
  Farther on down the pattern, if you encounter something like E63, then  you
  have to jump back up to the start of the loop three times before carrying on.


  E7 - Set tremolo waveform
  -------------------------
  Usage: Just like the vibrato waveform control.


  E9 - Retrig note
  ----------------
  Usage: E9x, where x is the tick to retrig at. This command will restart the
  same sample every "x" ticks during the current note. If you retrig with the
  command E91 in speed 6 (6 ticks per note), that note will be played six times
  in one note slot.  This amounts  to restarting the note every x/50ths of  a
  second.


  EA - Fine Volume Slide Up
  -------------------------
  Usage: EAx, where x is  the value to slide by.   This command works like  a
  normal volume slide up, except it slides only on the first tick instead of on
  every tick in the note.  It adjusts the volume by x.



















                                    Page 11





  EB - Fine Volume Slide Down
  ---------------------------
  Usage: EBx, where x is the value to slide by. This command works like a fine
  volume slide up.  It adjusts the volume by x.


  EC - Note Cut
  ED - Note Delay
  EE - Pattern Delay
  EF - Invert Loop
  ------------------

  We have no idea.  :-)  The information we received explaining the format of
  MOD files got cut off at this point...  Your guess is as good as mine.

  ---

  END OF FILE - Mod File Format Description.  Have a nice day.



































                                    Page 12
