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