home *** CD-ROM | disk | FTP | other *** search
/ Action Ware 12: Heretic & Hexen / actionware12.iso / acware12 / sounds / mus_play / mus_form.doc < prev    next >
Text File  |  1994-10-29  |  13KB  |  299 lines
  1.  
  2.                               MUS File Format
  3.                               ═══════════════
  4.  
  5. Written by Vladimir Arnost, QA-Software
  6. Date: Oct 29, 1994
  7. Internet: xarnos00@dcse.fee.vutbr.cz
  8.  
  9.  
  10. 1. General Description
  11. ──────────────────────
  12.  
  13.    A .MUS file is a simple clone of .MID file. It uses the same instruments,
  14.    similar commands and the same principle: a list of sound events.
  15.    It consists of two parts: header and body.
  16.  
  17.  
  18. 2. MUS File Header
  19. ──────────────────
  20.  
  21.    The MUS header has the following structure:
  22.  
  23.         struct MUSheader {
  24.                 char    ID[4];          // identifier "MUS" 0x1A
  25.                 WORD    scoreLen;
  26.                 WORD    scoreStart;
  27.                 WORD    channels;
  28.                 WORD    dummy1;
  29.                 WORD    instrCnt;
  30.                 WORD    dummy2;
  31.         // variable-length part starts here
  32.                 WORD    instruments[];
  33.         };
  34.  
  35.    NOTE: WORD is a 16-bit unsigned integer (little-endian)
  36.  
  37.    The header has two parts: the fixed-length and the variable-length parts.
  38.    The former contains file identifier, score start and length, number of
  39.    channels and number of used instruments. The latter part is actually
  40.    a list of used instruments. The instruments are stored as numbers which
  41.    are arranged in this fashion:
  42.  
  43.     Instrument Number      Meaning
  44.         0 - 127           standard MIDI instruments
  45.       135 - 181           standard MIDI percussions (notes 35 - 81)
  46.  
  47.    scoreStart is the absolute file position of the score and scoreLen is its
  48.    length in bytes. Use of 16-bit number as length limits .MUS file size to
  49.    64KB.
  50.  
  51.    channels tells you how many channels are utilized in the song. The channel
  52.    number 15 (percussions) is not included in the sum.
  53.  
  54.  
  55. 3. MUS File Body
  56. ────────────────
  57.  
  58.    Unlike MID files, MUS body contains only one track. File body is
  59.    a sequence of sound events and time records. A sound event consists of
  60.    one or more bytes encoded as follows:
  61.  
  62.    1st byte -- event descriptor:
  63.          ╓──7─┬──6─┬──5─┬──4─┬──3─┬──2─┬──1─┬──0─╖
  64.          ║Last│  Event type  │  Channel number   ║
  65.          ╙────┴────┴────┴────┴────┴────┴────┴────╜
  66.  
  67.              'Event type' is one of these:
  68.                0 - release note
  69.                1 - play note
  70.                2 - pitch wheel
  71.                3 - tempo ???
  72.                4 - change controller
  73.                5 - ???
  74.                6 - score end
  75.                7 - ???
  76.  
  77.              'Channel number' determines which channel this event refers to.
  78.  
  79.              'Last' - if set, the event is followed by time information. This
  80.              means that this is the last event in a group of events which
  81.              occur at the same time. The time information is a number of
  82.              ticks to wait before processing next event. One tick is usually
  83.              1/128 sec (Raptor uses 1/64 sec).
  84.  
  85.              Time information can be read in this way:
  86.                1. time = 0
  87.                2. read a byte
  88.                3. time = time * 128 + byte AND 127
  89.                4. if (byte AND 128) go to 2
  90.                5. return time
  91.              The time info is a series of 7-bit chunks. The 8th bit is set
  92.              until the last byte whose 8th bit is zero. This scheme allows
  93.              small numbers occupy less space than large ones.
  94.  
  95.    Event  Type
  96.    ────────────────────
  97.      0    Release note
  98.           ╓─7─┬─6─┬─5─┬─4─┬─3─┬─2─┬─1─┬─0─╖
  99.           ║ 0 │    Note number 0 - 127    ║
  100.           ╙───┴───┴───┴───┴───┴───┴───┴───╜
  101.  
  102.      1    Play note
  103.           ╓─7─┬─6─┬─5─┬─4─┬─3─┬─2─┬─1─┬─0─╖  ╓─7─┬─6─┬─5─┬─4─┬─3─┬─2─┬─1─┬─0─╖
  104.           ║Vol│    Note number 0 - 127    ║  ║ 0 │    Note volume 0 - 127    ║
  105.           ╙───┴───┴───┴───┴───┴───┴───┴───╜  ╙───┴───┴───┴───┴───┴───┴───┴───╜
  106.  
  107.           Note volume is present only if 'Vol' is set. Otherwise the previous
  108.           value is used and the second byte is not present.
  109.           NOTE: Each channel keeps track of its own last volume value.
  110.                 More than one note can be played at once in one channel.
  111.           Channel 15 is dedicated to drums and percussions. Note number acts
  112.           as an instrument selector there. see Appendix C
  113.  
  114.      2    Pitch wheel
  115.           ╓─7─┬─6─┬─5─┬─4─┬─3─┬─2─┬─1─┬─0─╖
  116.           ║       Pitch wheel value       ║
  117.           ╙───┴───┴───┴───┴───┴───┴───┴───╜
  118.  
  119.           Sets pitch wheel (bender) value of a channel. Some handy values are
  120.           shown in the table (all values in the range 0-255 can be used):
  121.  
  122.           ┌─────┬───────────────────────┐
  123.           │Value│  Pitch change         │
  124.           ├─────┼───────────────────────┤
  125.           │   0 │  two half-tones down  │
  126.           │  64 │  one half-tone down   │
  127.           │ 128 │  normal (default)     │
  128.           │ 192 │  one half-tone up     │
  129.           │ 255 │  two half-tones up    │
  130.           └─────┴───────────────────────┘
  131.  
  132.      3    Unknown (set tempo???)
  133.           ╓─7─┬─6─┬─5─┬─4─┬─3─┬─2─┬─1─┬─0─╖
  134.           ║         Unknown value         ║
  135.           ╙───┴───┴───┴───┴───┴───┴───┴───╜
  136.  
  137.      4    Change control
  138.           ╓─7─┬─6─┬─5─┬─4─┬─3─┬─2─┬─1─┬─0─╖  ╓─7─┬─6─┬─5─┬─4─┬─3─┬─2─┬─1─┬─0─╖
  139.           ║ 0 │     Controller number     ║  ║ 0 │      Controller value     ║
  140.           ╙───┴───┴───┴───┴───┴───┴───┴───╜  ╙───┴───┴───┴───┴───┴───┴───┴───╜
  141.  
  142.           Number     Description
  143.             0        Instrument (patch) number
  144.             3        Volume: 0-silent, ~100-normal, 127-loud
  145.             4        Pan (balance): 0-left, 64-center (default), 127-right
  146.  
  147.           No other controller's functions are known to me.
  148.  
  149.      5    Unknown
  150.           Not known what data (if any) this command takes.
  151.  
  152.      6    Score end
  153.           No data.
  154.  
  155.           Marks the end of score. Must be present at the end, otherwise the
  156.           player may go off the rail. In DOOM this command restarts playing.
  157.  
  158.      7    Unknown
  159.           Not known what data (if any) this command takes.
  160.  
  161.  
  162. APPENDIX A - Note numbers
  163. ─────────────────────────
  164.  
  165.    ╔════════╦═════╤════╤════╤════╤════╤════╤════╤════╤════╤════╤════╤════╗
  166.    ║ Octave ║  C  │ C# │ D  │ D# │ E  │ F  │ F# │ G  │ G# │ A  │ A# │ B  ║
  167.    ╠════════╬═════╪════╪════╪════╪════╪════╪════╪════╪════╪════╪════╪════╣
  168.    ║    0   ║   0 │  1 │  2 │  3 │  4 │  5 │  6 │  7 │  8 │  9 │ 10 │ 11 ║
  169.    ║    1   ║  12 │ 13 │ 14 │ 15 │ 16 │ 17 │ 18 │ 19 │ 20 │ 21 │ 22 │ 23 ║
  170.    ║    2   ║  24 │ 25 │ 26 │ 27 │ 28 │ 29 │ 30 │ 31 │ 32 │ 33 │ 34 │ 35 ║
  171.    ║    3   ║  36 │ 37 │ 38 │ 39 │ 40 │ 41 │ 42 │ 43 │ 44 │ 45 │ 46 │ 47 ║
  172.    ║    4   ║  48 │ 49 │ 50 │ 51 │ 52 │ 53 │ 54 │ 55 │ 56 │ 57 │ 58 │ 59 ║
  173.    ║    5   ║  60 │ 61 │ 62 │ 63 │ 64 │ 65 │ 66 │ 67 │ 68 │ 69 │ 70 │ 71 ║
  174.    ║    6   ║  72 │ 73 │ 74 │ 75 │ 76 │ 77 │ 78 │ 79 │ 80 │ 81 │ 82 │ 83 ║
  175.    ║    7   ║  84 │ 85 │ 86 │ 87 │ 88 │ 89 │ 90 │ 91 │ 92 │ 93 │ 94 │ 95 ║
  176.    ║    8   ║  96 │ 97 │ 98 │ 99 │100 │101 │102 │103 │104 │105 │106 │107 ║
  177.    ║    9   ║ 108 │109 │110 │111 │112 │113 │114 │115 │116 │117 │118 │119 ║
  178.    ║   10   ║ 120 │121 │122 │123 │124 │125 │126 │127 │    │    │    │    ║
  179.    ╚════════╩═════╧════╧════╧════╧════╧════╧════╧════╧════╧════╧════╧════╝
  180.  
  181.  
  182. APPENDIX B - Instrument Patch Map
  183. ─────────────────────────────────
  184.  
  185.    Block 0-7  PIANO                    Block 8-15  CHROM PERCUSSION
  186.      0  Acoustic Grand Piano             8  Celesta
  187.      1  Bright Acoustic Piano            9  Glockenspiel
  188.      2  Electric Grand Piano            10  Music Box
  189.      3  Honky-tonk Piano                11  Vibraphone
  190.      4  Rhodes Paino                    12  Marimba
  191.      5  Chorused Piano                  13  Xylophone
  192.      6  Harpsichord                     14  Tubular-bell
  193.      7  Clavinet                        15  Dulcimer
  194.  
  195.    Block 16-23  ORGAN                  Block 24-31  GUITAR
  196.     16  Hammond Organ                   24  Acoustic Guitar (nylon)
  197.     17  Percussive Organ                25  Acoustic Guitar (steel)
  198.     18  Rock Organ                      26  Electric Guitar (jazz)
  199.     19  Church Organ                    27  Electric Guitar (clean)
  200.     20  Reed Organ                      28  Electric Guitar (muted)
  201.     21  Accordion                       29  Overdriven Guitar
  202.     22  Harmonica                       30  Distortion Guitar
  203.     23  Tango Accordion                 31  Guitar Harmonics
  204.  
  205.    Block 32-39  BASS                   Block 40-47  STRINGS
  206.     32  Acoustic Bass                   40  Violin
  207.     33  Electric Bass (finger)          41  Viola
  208.     34  Electric Bass (pick)            42  Cello
  209.     35  Fretless Bass                   43  Contrabass
  210.     36  Slap Bass 1                     44  Tremolo Strings
  211.     37  Slap Bass 2                     45  Pizzicato Strings
  212.     38  Synth Bass 1                    46  Orchestral Harp
  213.     39  Synth Bass 2                    47  Timpani
  214.  
  215.    Block 48-55  ENSEMBLE               Block 56-63  BRASS
  216.     48  String Ensemble 1               56  Trumpet
  217.     49  String Ensemble 2               57  Trombone
  218.     50  Synth Strings 1                 58  Tuba
  219.     51  Synth Strings 2                 59  Muted Trumpet
  220.     52  Choir Aahs                      60  French Horn
  221.     53  Voice Oohs                      61  Brass Section
  222.     54  Synth Voice                     62  Synth Brass 1
  223.     55  Orchestra Hit                   63  Synth Bass 2
  224.  
  225.    Block 64-71  REED                   Block 72-79  PIPE
  226.     64  Soprano Sax                     72  Piccolo
  227.     65  Alto Sax                        73  Flute
  228.     66  Tenor Sax                       74  Recorder
  229.     67  Baritone Sax                    75  Pan Flute
  230.     68  Oboe                            76  Bottle Blow
  231.     69  English Horn                    77  Shakuhachi
  232.     70  Bassoon                         78  Whistle
  233.     71  Clarinet                        79  Ocarina
  234.  
  235.    Block 80-87  SYNTH LEAD             Block 88-95  SYNTH PAD
  236.     80  Lead 1 (square)                 88  Pad 1 (new age)
  237.     81  Lead 2 (sawtooth)               89  Pad 2 (warm)
  238.     82  Lead 3 (calliope)               90  Pad 3 (polysynth)
  239.     83  Lead 4 (chiffer)                91  Pad 4 (choir)
  240.     84  Lead 5 (charang)                92  Pad 5 (bowed glass)
  241.     85  Lead 6 (voice)                  93  Pad 6 (metal)
  242.     86  Lead 7 (5th sawtooth)           94  Pad 7 (halo)
  243.     87  Lead 8 (bass & lead)            95  Pad 8 (sweep)
  244.  
  245.    Block 96-103  SYNTH EFFECTS         Block 104-111  ETHNIC
  246.     96  FX 1 (rain)                    104  Sitar
  247.     97  FX 2 (soundtrack)              105  Banjo
  248.     98  FX 3 (crystal)                 106  Shamisen
  249.     99  FX 4 (atmosphere)              107  Koto
  250.    100  FX 5 (brightness)              108  Kalimba
  251.    101  FX 6 (goblin)                  109  Bag Pipe
  252.    102  FX 7 (echo drops)              110  Fiddle
  253.    103  FX 8 (star-theme)              111  Shanai
  254.  
  255.    Block 112-119  PERCUSSIVE           Block 120-127  SOUND EFFECTS
  256.    112  Tinkle Bell                    120  Guitar Fret Noise
  257.    113  Agogo                          121  Breath Noise
  258.    114  Steel Drums                    122  Seashore
  259.    115  Woodblock                      123  Bird Tweet
  260.    116  Taiko Drum                     124  Telephone Ring
  261.    117  Melodic Tom                    125  Helicopter
  262.    118  Synth Drum                     126  Applause
  263.    119  Reverse Cymbal                 127  Gun Shot
  264.  
  265.  
  266. APPENDIX C - Percussion Key Map
  267. ───────────────────────────────
  268.  
  269.    In channel #15, the note number does not affect the pitch but
  270.    the instrument type. The default pitch for percussions is 60 (C-5).
  271.  
  272.    Note Instrument                     Note Instrument
  273.  
  274.     35  Acoustic Bass Drum              59  Ride Cymbal 2
  275.     36  Bass Drum                       60  High Bongo
  276.     37  Slide Stick                     61  Low Bango
  277.     38  Acoustic Snare                  62  Mute High Conga
  278.     39  Hand Clap                       63  Open High Conga
  279.     40  Electric Snare                  64  Low Conga
  280.     41  Low Floor Tom                   65  High Timbale
  281.     42  Closed High-Hat                 66  Low Timbale
  282.     43  High Floor Tom                  67  High Agogo
  283.     44  Pedal High Hat                  68  Low Agogo
  284.     45  Low Tom                         69  Cabasa
  285.     46  Open High Hat                   70  Maracas
  286.     47  Low-Mid Tom                     71  Short Whistle
  287.     48  High-Mid Tom                    72  Long Whistle
  288.     49  Crash Cymbal 1                  73  Short Guiro
  289.     50  High Tom                        74  Long Guiro
  290.     51  Ride Cymbal 1                   75  Claves
  291.     52  Chinses Cymbal                  76  High Wood Block
  292.     53  Ride Bell                       77  Low Wood Block
  293.     54  Tambourine                      78  Mute Cuica
  294.     55  Splash Cymbal                   79  Open Cuica
  295.     56  Cowbell                         80  Mute Triangle
  296.     57  Crash Cymbal 2                  81  Open Triangle
  297.     58  Vibraslap
  298.  
  299.