Fourth Woods Wiki

User Tools

Site Tools

Trace:
the_mus_file_format

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
the_mus_file_format [2011/11/06 18:26] – javapimpthe_mus_file_format [2023/08/18 18:15] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +
 +====== 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