Fourth Woods Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== MUS File Format ======

//Vladimir Arnost//, QA-Software\\
Updated:    March 9, 1996\\
Version:    1.31\\
Internet:   xarnos00@dcse.fee.vutbr.cz\\
FIDO:       2:423/36.2\\


===== 1. General Description =====

A .MUS file is a simple clone of .MID file. It uses the same instruments, similar commands and the same principle: a list of sound events. It consists of two parts: header and body.

NOTE: All numerical values mentioned in this document are zero-based. If not specified otherwise, all numbers are given in decimal.  Hexadecimal numbers are suffixed by 'h' (e.g. 5Ch). Bits are numbered in this fashion: LSB (right-most) = 0, MSB (left-most) = 7.

===== 2. MUS File Header =====

The MUS header has the following structure:

<code cpp>
struct MUSheader {
    char    ID[4];        // identifier "MUS" 0x1A
    WORD    scoreLen;
    WORD    scoreStart;
    WORD    channels;     // count of primary channels
    WORD    sec_channels; // count of secondary channels
    WORD    instrCnt;
    WORD    dummy;
    // variable-length part starts here
    WORD    instruments[];
};
</code>

NOTE: WORD is a 16-bit unsigned integer (little-endian)

The header has two parts: the fixed-length and the variable-length part. The former contains file identifier, score start and length, number of channels and number of used instruments. The latter part is actually a list of used instruments. The instruments are stored as numbers which are arranged in this fashion:

^ Instrument Number ^ Meaning ^
|   0 - 127         | standard MIDI instruments |
|  135 - 181        | standard MIDI percussions (notes 35 - 81) |

`scoreStart' is the absolute file position of the score and `scoreLen' is its length in bytes. Usage of a 16-bit number as length limits .MUS file size to 64KB.

`channels' tells you how many channels are utilized in the song. The channel number 15 (percussions) is not included in the sum.


===== 3. MUS File Body =====

Unlike MID files, MUS body contains only one track. File body is a sequence of sound events and time records. A sound event consists of one or more bytes encoded as follows:

1st byte -- event descriptor:
<code>
+--7----6----5----4----3----2----1----0-+
|Last|  Event type  |  Channel number   |
+---------------------------------------+
</code>
`Event type' is one of these:
  0 - release note
  1 - play note
  2 - pitch wheel (bender)
  3 - system event (valueless controller)
  4 - change controller
  5 - ???
  6 - score end
  7 - ???

`Channel number' determines which channel this event refers to. Channels provide only logical score division. Every channel carries its own settings (instrument #, panning, volume) and the channel number specifies only which settings to use. In general, the channel number itself is almost irrelevant and may be chosen arbitrarily within the interval 0 to 14. The only exception is the channel number 15, which is dedicated ONLY to percussions.

`Last' - if set, the event is followed by time information. This means that this is the last event in a group of events which occur at the same time. The time information is a number of ticks to wait before processing next event. One tick is usually 1/140 sec (in Doom I, II and Heretic; Raptor uses 1/70 sec).

Time information can be read in this way:
  1. time = 0
  2. READ a byte
  3. time = time * 128 + byte AND 127
  4. IF (byte AND 128) GO TO 2
  5. RETURN time

The time info is a series of 7-bit chunks. The bit #7 is set until the last byte whose bit 7 is zero. This scheme allows small numbers occupy less space than large ones.

<code>
   Event  Type
   --------------------
     0    Release note
          +-7---6---5---4---3---2---1---0-+
          | 0 |    Note number 0 - 127    |
          +-------------------------------+

     1    Play note
          +-7---6---5---4---3---2---1---0-+  +-7---6---5---4---3---2---1---0-+
          |Vol|    Note number 0 - 127    |  | 0 |    Note volume 0 - 127    |
          +-------------------------------+  +-------------------------------+

          `Note volume' is present only if `Vol' bit is set. Otherwise the
          previous value is used and the second byte is not present.
          NOTE: Each channel keeps track of its own last volume value.
                More than one note can be played at once in one channel.
          Channel 15 is dedicated to drums and percussions. `Note number'
          acts as an instrument selector there. See Appendix C

     2    Pitch wheel
          +-7---6---5---4---3---2---1---0-+
          |       Pitch wheel value       |
          +-------------------------------+

          Sets pitch wheel (bender) value of a channel. Some handy values are
          shown in the table (all values in the range 0-255 can be used):

          +-------------------------------+
          | Value |  Pitch change         |
          |-------+-----------------------|
          |    0  |  two half-tones down  |
          |   64  |  one half-tone down   |
          |  128  |  normal (default)     |
          |  192  |  one half-tone up     |
          |  255  |  two half-tones up    |
          +-------------------------------+

     3    System event (Valueless controller)
          +-7---6---5---4---3---2---1---0-+
          | 0 |          Number           |
          +-------------------------------+

          Number  MIDI ctrl   Description
            10    120 (78h)   All sounds off
            11    123 (7Bh)   All notes off
            12    126 (7Eh)   Mono
            13    127 (7Fh)   Poly
            14    121 (79h)   Reset all controllers

          NOTE: The second column (MIDI ctrl) lists the corresponding MIDI
                controller number. It is not needed unless you want to
                convert MUS file data to MIDI.

     4    Change controller
          +-7---6---5---4---3---2---1---0-+  +-7---6---5---4---3---2---1---0-+
          | 0 |     Controller number     |  | 0 |      Controller value     |
          +-------------------------------+  +-------------------------------+

          Number  MIDI ctrl   Description
            0       N/A       Instrument (patch, program) number
            1      0 or 32    Bank select: 0 by default
            2      1 (01h)    Modulation pot (frequency vibrato depth)
            3      7 (07h)    Volume: 0-silent, ~100-normal, 127-loud
            4     10 (0Ah)    Pan (balance) pot: 0-left, 64-center (default),
                              127-right
            5     11 (0Bh)    Expression pot
            6     91 (5Bh)    Reverb depth
            7     93 (5Dh)    Chorus depth
            8     64 (40h)    Sustain pedal (hold)
            9     67 (43h)    Soft pedal

          NOTE: MUS controller 0 has no equivalent MIDI controller, but
                is encoded as MIDI event 0Cxh--patch change (`x' is the
                channel number)

     5    Unknown
          Not known what data (if any) this command takes.

     6    Score end
          No data.

          Marks the end of score. Must be present at the end, otherwise the
          player may go off the rails. In DOOM this command restarts playing.

     7    Unknown
          Not known what data (if any) this command takes.
</code>

APPENDIX A - Note numbers
-------------------------

   +=====================================================================+
   | Octave |  C  | C# | D  | D# | E  | F  | F# | G  | G# | A  | A# | B  |
   ======================================================================|
   |    0   |   0 |  1 |  2 |  3 |  4 |  5 |  6 |  7 |  8 |  9 | 10 | 11 |
   |    1   |  12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
   |    2   |  24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 |
   |    3   |  36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 |
   |    4   |  48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 |
   |    5   |  60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 |
   |    6   |  72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 |
   |    7   |  84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 |
   |    8   |  96 | 97 | 98 | 99 |100 |101 |102 |103 |104 |105 |106 |107 |
   |    9   | 108 |109 |110 |111 |112 |113 |114 |115 |116 |117 |118 |119 |
   |   10   | 120 |121 |122 |123 |124 |125 |126 |127 |    |    |    |    |
   +=====================================================================+


APPENDIX B - Instrument Patch Map
---------------------------------

   Block 0-7  PIANO                    Block 8-15  CHROM PERCUSSION
     0  Acoustic Grand Piano             8  Celesta
     1  Bright Acoustic Piano            9  Glockenspiel
     2  Electric Grand Piano            10  Music Box
     3  Honky-tonk Piano                11  Vibraphone
     4  Rhodes Paino                    12  Marimba
     5  Chorused Piano                  13  Xylophone
     6  Harpsichord                     14  Tubular-bell
     7  Clavinet                        15  Dulcimer

   Block 16-23  ORGAN                  Block 24-31  GUITAR
    16  Hammond Organ                   24  Acoustic Guitar (nylon)
    17  Percussive Organ                25  Acoustic Guitar (steel)
    18  Rock Organ                      26  Electric Guitar (jazz)
    19  Church Organ                    27  Electric Guitar (clean)
    20  Reed Organ                      28  Electric Guitar (muted)
    21  Accordion                       29  Overdriven Guitar
    22  Harmonica                       30  Distortion Guitar
    23  Tango Accordion                 31  Guitar Harmonics

   Block 32-39  BASS                   Block 40-47  STRINGS
    32  Acoustic Bass                   40  Violin
    33  Electric Bass (finger)          41  Viola
    34  Electric Bass (pick)            42  Cello
    35  Fretless Bass                   43  Contrabass
    36  Slap Bass 1                     44  Tremolo Strings
    37  Slap Bass 2                     45  Pizzicato Strings
    38  Synth Bass 1                    46  Orchestral Harp
    39  Synth Bass 2                    47  Timpani

   Block 48-55  ENSEMBLE               Block 56-63  BRASS
    48  String Ensemble 1               56  Trumpet
    49  String Ensemble 2               57  Trombone
    50  Synth Strings 1                 58  Tuba
    51  Synth Strings 2                 59  Muted Trumpet
    52  Choir Aahs                      60  French Horn
    53  Voice Oohs                      61  Brass Section
    54  Synth Voice                     62  Synth Brass 1
    55  Orchestra Hit                   63  Synth Bass 2

   Block 64-71  REED                   Block 72-79  PIPE
    64  Soprano Sax                     72  Piccolo
    65  Alto Sax                        73  Flute
    66  Tenor Sax                       74  Recorder
    67  Baritone Sax                    75  Pan Flute
    68  Oboe                            76  Bottle Blow
    69  English Horn                    77  Shakuhachi
    70  Bassoon                         78  Whistle
    71  Clarinet                        79  Ocarina

   Block 80-87  SYNTH LEAD             Block 88-95  SYNTH PAD
    80  Lead 1 (square)                 88  Pad 1 (new age)
    81  Lead 2 (sawtooth)               89  Pad 2 (warm)
    82  Lead 3 (calliope)               90  Pad 3 (polysynth)
    83  Lead 4 (chiffer)                91  Pad 4 (choir)
    84  Lead 5 (charang)                92  Pad 5 (bowed glass)
    85  Lead 6 (voice)                  93  Pad 6 (metal)
    86  Lead 7 (5th sawtooth)           94  Pad 7 (halo)
    87  Lead 8 (bass & lead)            95  Pad 8 (sweep)

   Block 96-103  SYNTH EFFECTS         Block 104-111  ETHNIC
    96  FX 1 (rain)                    104  Sitar
    97  FX 2 (soundtrack)              105  Banjo
    98  FX 3 (crystal)                 106  Shamisen
    99  FX 4 (atmosphere)              107  Koto
   100  FX 5 (brightness)              108  Kalimba
   101  FX 6 (goblin)                  109  Bag Pipe
   102  FX 7 (echo drops)              110  Fiddle
   103  FX 8 (star-theme)              111  Shanai

   Block 112-119  PERCUSSIVE           Block 120-127  SOUND EFFECTS
   112  Tinkle Bell                    120  Guitar Fret Noise
   113  Agogo                          121  Breath Noise
   114  Steel Drums                    122  Seashore
   115  Woodblock                      123  Bird Tweet
   116  Taiko Drum                     124  Telephone Ring
   117  Melodic Tom                    125  Helicopter
   118  Synth Drum                     126  Applause
   119  Reverse Cymbal                 127  Gun Shot


APPENDIX C - Percussion Key Map
-------------------------------

   In channel #15, the note number does not affect the pitch but
   the instrument type. The default pitch for percussions is 60 (C-5).

   Note Instrument                     Note Instrument

    35  Acoustic Bass Drum              59  Ride Cymbal 2
    36  Bass Drum                       60  High Bongo
    37  Slide Stick                     61  Low Bango
    38  Acoustic Snare                  62  Mute High Conga
    39  Hand Clap                       63  Open High Conga
    40  Electric Snare                  64  Low Conga
    41  Low Floor Tom                   65  High Timbale
    42  Closed High-Hat                 66  Low Timbale
    43  High Floor Tom                  67  High Agogo
    44  Pedal High Hat                  68  Low Agogo
    45  Low Tom                         69  Cabasa
    46  Open High Hat                   70  Maracas
    47  Low-Mid Tom                     71  Short Whistle
    48  High-Mid Tom                    72  Long Whistle
    49  Crash Cymbal 1                  73  Short Guiro
    50  High Tom                        74  Long Guiro
    51  Ride Cymbal 1                   75  Claves
    52  Chinses Cymbal                  76  High Wood Block
    53  Ride Bell                       77  Low Wood Block
    54  Tambourine                      78  Mute Cuica
    55  Splash Cymbal                   79  Open Cuica
    56  Cowbell                         80  Mute Triangle
    57  Crash Cymbal 2                  81  Open Triangle
    58  Vibraslap

TABLE 3  -  General MIDI Minimum Sound Module Specifications
 
Voices:
A minimum of either 24 fully dynamically allocated voices available simultaneously for both melodic and percussive sounds or 16 dynamically allocated voices for melody plus eight for percussion.
 
Channels:
General MIDI mode supports all sixteen MIDI channels. Each channel can play a variable number of voices (polyphony). Each channel can play a different instrument (timbre). Keybased Percussion is always on Channel 10.
 
Instruments:
A minimum of sixteen different timbres playing various instrument sounds. A minimum of 128 preset for Intruments (MIDI program numbers).
 
Note on/Note off:
Octave Registration: Middle C(C3) = MIDI key 60. All Voices including percussion respond to velocity.
 
Controllers:
Controller # 	
Description
1 	Modulation
7 	Main Volume
10 	Pan
11 	Expression
64 	Sustain
121 	Reset All Controllers
123 	All Notes Off
  	 
Registered
Parameter # 	
Description
0 	Pitch Bend Sensitivity
1 	Fine Tuning
2 	Coarse Tuning
 
Additional Channel Messages:
Channel Pressure (Aftertouch)
Pitch Bend
 
Power-Up Defaults:
Pitch Bend Amount = 0
Pitch Bend Sensitivity = +-2 semitones
Volume = 90
All Other Controllers = reset