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