

                              The .MOD File Format
                              --------------------
                          Second Release.  August 1993

   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 Enigma 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 will...)









                                     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, or FLT8 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.
   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.
   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


   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.

   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 - Tremolo                             F - 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 5





   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.

   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.

   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)

   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".

   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.

   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.







                                     Page 6





   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)

   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)

   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.


                                     Page 7





   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

   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.

   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.







                                     Page 8





   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


















































                                     Page 9



