User Tools

Site Tools


mus_file_format

MUS File Format

License

The bulk of information for this article comes from public domain sources, in particular The MUS File Format by Vladimir Arnost. The rest was filled in through various sources and contributions. As such, even though most articles on this site are licensed under the Creative Commons Attribution license, this article is here by released into the public domain.

File Structure

The MUS file format is similar to the MIDI file format. It consists of a header, a variable length list of instruments used followed by music events. Unlike the MIDI file, the MUS file has only a single track.

The header always starts with a magic value 'MUS' 0x1A. Following the magic value is a 2 byte length and 2 byte offset value. The offset specifies the offset from the beginning of the file where the actual midi commands begin. The length specifies the length of the score from the offset to the end of the file. Because the length is a 2 byte value the score is limited to 64KB.

The channels field specifies the number of channels that are used in the score not including channel 15. The sec_channels field specifies the number of secondary channels used. num_instruments indicates the number of instruments contained in the variable length instruments list.

4D 55 53 1A ll ll oo oo cc cc ss ss nn nn dd dd

struct mus_header {
    unsigned int   id;              // identifier "MUS" 0x1A
    unsigned short length;          // the length of the score
    unsigned short offset;          // score offset from beginning of file
    unsigned short channels;	    // count of primary channels
    unsigned short sec_channels;    // count of secondary channels
    unsigned short num_instruments; // number of instruments in variable length section
    unsigned short dummy;
 
    unsigned short instruments[];   // variable-length list of instruments
};

Because the length and offset specify the beginning of the score, extra space may be included between the last instrument in the instruments list and the beginning of the score to store other information such as author and copyright info. There is no standard format for this information and readers may or may not recognize it.

It is important to note that these 16 bit values are in little-endian format unlike MIDI which uses big-endian for integer values.

Body

+--7----6----5----4----3----2----1----0-+
|Last|  Event type  |  Channel number   |
+---------------------------------------+

The MUS body is a single track of grouped sound events and time values. An event begins with a byte similar to a MIDI event. The left nibble (4 bits) contain the command in the three least significant bits. The most significant bit is 0 if more events follow in the group or 1 if the event is the last in the group and a time value follows. Events in a group are to be executed simultaneously. The time value specifies the number of ticks to wait before processing the next event (group).

The right nibble, 4 least significant bits of the event specifies the channel to which the event applies. Each instrument is assigned a channel which is used throughout the score. Channels 0 through 14 may be used for any instruments. Channel 15 is exclusively for percussion.

Following the event byte is one or more data bytes. The following table describes each event and the data that follows.

Command Data Description
0 0nnnnnnn Release note. The data for the release note command consists of a single byte. The most significant bit is always 0. The remaining 7 bits, nnnnnnn specify the note which is to be released.
1 vnnnnnnn 0xxxxxxx Play note. The data for the play note command consists of either one or two bytes. The first byte specifies the note to be played in the 7 least significant bits nnnnnnn. If the most significant bit v is 1, a second byte follows specifying the volume at which to play the note. If the most significant bit is 0, no volume byte follows and the previous volume value is used. If the volume byte is present, the most significant bit is always 0 followed by the volume value in the range 0-127.
2 xxxxxxxx Pitch wheel. The data for the pitch wheel is a single byte in the range 0-255. Pitch change varies according to the following:

0 - down two half-tones
64 - down one half-tone
128 - normal (default)
192 - up one half-tone
255 - up two half-tones
3 0xxxxxxx System event (valueless controller). The data byte for the system event specifies a system wide event. The most significant bit is always 0. The remaining 7 bits xxxxxxx specifies the system event number. The events are specified according to the following:

10 - All sounds off (120)
11 - All notes off (123)
12 - Mono (126)
13 - Poly (127)
14 - Reset all controllers (121)

The number in parenthesis following each description is the corresponding MIDI controller value. This doesn't have anything to do with the MUS format and isn't included in the byte. It's just here for reference.
4 0ccccccc 0vvvvvvv Change controller. This message is sent when a controller value changes. Controllers include devices such as pedals and levers. Certain controller numbers are reserved for specific purposes. See Channel Mode Messages.
5 unknown Unknown.
6 none Score end. This message marks the end of the score and must always be the last command.
7 unknown Unknown.

Notes

The following table lists the numbers corresponding to notes for use in note on and note off commands.

Octave Notes
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

Controller Codes

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

Instrument Patch Map

This is a list of 128 sounds, with corresponding MIDI program numbers. Most of these are imitative sounds, though the list includes synth sounds, ethnic instruments and a handful of sound effects.

The sounds fall roughly into sixteen families of eight variations each. Grouping sounds makes it easy to re-orchestrate a piece using similar sounds. The instrument map isn't the final word on musical instruments of the world, but it's pretty complete.

Prog# Instrument Prog# Instrument
(0-7 Piano) (8-15 Chrome Percussion)
0 Acoustic Grand 8 Celesta
1 Bright Acoustic 9 Glockenspiel
2 Electric Grand 10 Music Box
3 Honky-Tonk 11 Vibraphone
4 Electric Piano 1 12 Marimba
5 Electric Piano 2 13 Xylophone
6 Harpsichord 14 Tubular Bells
7 Clav 15 Dulcimer
(16-23 Organ) (24-31 Guitar)
16 Drawbar 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 Accoridan 29 Overdriven Guitar
22 Harmonica 30 Distortion Guitar
23 Tango Accordian 31 Guitar Harmonics
(32-39 Bass) (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 Strings
39 Synth Bass 2 47 Timpani
(48-55 Ensemble) (56-63 Brass)
48 String Ensemble 1 56 Trumpet
49 String Ensemble 2 57 Trombone
50 SynthStrings 1 58 Tuba
51 SynthStrings 2 59 Muted Trumpet
52 Choir Aahs 60 French Horn
53 Voice Oohs 61 Brass Section
54 Synth Voice 62 SynthBrass 1
55 Orchestra Hit 63 SynthBrass 2
(64-71 Reed) (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 Blown Bottle
69 English Horn 77 Skakuhachi
70 Bassoon 78 Whistle
71 Clarinet 79 Ocarina
(80-87 Synth Lead) (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 (chiff) 91 Pad 4 (choir)
84 Lead 5 (charang) 92 Pad 5 (bowed)
85 Lead 6 (voice) 93 Pad 6 (metallic)
86 Lead 7 (fifths) 94 Pad 7 (halo)
87 Lead 8 (bass+lead) 95 Pad 8 (sweep)
(96-103 Synth Effects) (104-110 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 (goblins) 109 Bagpipe
102 FX 7 (echoes) 110 Fiddle
103 FX 8 (sci-fi) 111 Shanai
(112-119 Percussive) (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 Gunshot

Percussion Key Map

This mapping derives from the Roland/Sequential mapping used on early drum machines. As with the Instrument Map, it doesn't cover every percussive instrument in the world, but it's more than adequate as a basic set.

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 Drum Sound Note Drum Sound
35 Acoustic Bass Drum 59 Ride Cymbal 2
36 Bass Drum 1 60 Hi Bongo
37 Side Stick 61 Low Bongo
38 Acoustic Snare 62 Mute Hi Conga
39 Hand Clap 63 Open Hi Conga
40 Electric Snare 64 Low Conga
41 Low Floor Tom 65 High Timbale
42 Closed Hi-Hat 66 Low Timbale
43 High Floor Tom 67 High Agogo
44 Pedal Hi-Hat 68 Low Agogo
45 Low Tom 69 Cabasa
46 Open Hi-Hat 70 Maracas
47 Low-Mid Tom 71 Short Whistle
48 Hi-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 Chinese Cymbal 76 Hi 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

Sources

More Information

mus_file_format.txt · Last modified: 2016/05/14 11:04 (external edit)