home *** CD-ROM | disk | FTP | other *** search
/ Da Capo / da_capo_vol1.bin / programs / amiga / midi / midi_playground / mp.doc < prev    next >
Text File  |  1993-01-23  |  16KB  |  472 lines
  1. MP:        A MIDI Playground
  2. Author:        Daniel J. Barrett, barrett@cs.umass.edu.
  3. No Copyright:    100% Public Domain.
  4.         Please share this program with others.
  5.  
  6. Requirements:    A Commodore Amiga.
  7. Optional:    A MIDI Interface on your serial port.
  8.         1 or more MIDI instruments.
  9.         (Without MIDI, this program is not very useful, except
  10.          perhaps as a source code example for serial port
  11.          programming and parsing input.)
  12.  
  13. Legal stuff:    Use this program entirely at your own risk.  The author
  14.         bears no responsibility for any damage or data loss you
  15.         may incur through the use or misuse of this program.
  16.  
  17.     
  18. GETTING QUICK HELP
  19.  
  20.     At the command line, type:
  21.  
  22.         1>  mp ?
  23.  
  24. TABLE OF CONTENTS
  25.  
  26. Line    Section
  27. ===========================================================================
  28.  18    Getting quick help
  29.  24    Table of contents
  30.  46    What is MP?
  31.  77    What is MP not?
  32.  84    MP concepts
  33. 118    A first exercise
  34. 132    Formal usage instructions for MP
  35. 162    The input text language
  36. 237    Practicing with the text language
  37. 264    Using the file input/output options to make new windows
  38. 277    Using redirection
  39. 306    Translating binary data to/from text
  40. 318    Using an alternate MIDI interface
  41. 359    Problems you may have with MP
  42. 425    Notes about the source code
  43. 457    Notes about the program's internals (and limitations)
  44.     
  45.     
  46. WHAT IS MP?
  47.  
  48.     Have you ever wanted to see what MIDI data your instrument is
  49. transmitting?  Have you ever wanted to send your own MIDI data to your
  50. MIDI instrument?  Then MP is for you!!
  51.  
  52.     MP (MIDI Playground) is a versatile tool for sending, receiving,
  53. and storing MIDI data.  It has many uses:
  54.  
  55.     o    Learning about MIDI.
  56.  
  57.     o    Discovering your instrument's system exclusive data
  58.         format.
  59.  
  60.     o    Testing your instrument's MIDI capabilities.
  61.  
  62.     o    Acting as a patch librarian.  (VERY VERY basic, though.)
  63.  
  64.     o    Helping you write MIDI software.
  65.  
  66.     Essentially, MP is a "translator" program that understands 3
  67. data formats and translates between any pair:
  68.  
  69.         (1)    English text
  70.         (2)    Binary data
  71.         (3)    MIDI data
  72.  
  73. Formats (2) and (3) are really the same, but (2) is stored in files on your
  74. Amiga, and (3) is transmitted via your MIDI interface.
  75.  
  76.     
  77. WHAT IS MP NOT?
  78.  
  79.     MP is not a sequencer.  It does not store any kind of timing
  80. information.  MP simply sends and receives bytes in the order they are
  81. given.
  82.  
  83.     
  84. MP CONCEPTS
  85.  
  86.     Like I said, MP translates between text, binary data, and MIDI
  87. data.  All you need to do is:
  88.  
  89.     (1)    Choose a format for the input.
  90.     (2)    Choose a format for the output.
  91.         (The input and output formats can be the same if you like.)
  92.     (3)    Run MP.
  93.  
  94. For example, you can ask MP to use "text" as input and "MIDI" as output.
  95. This lets you type text in a very easy-to-learn language, and it immediately
  96. gets sent out as MIDI data.  If you reverse these choices (input=MIDI,
  97. output=text), you can watch MIDI data appear on your screen in a simple
  98. but readable format.
  99.  
  100.     Another use would be to use "MIDI" as input and "binary" as output.
  101. This lets you press keys and buttons on your instrument, and have all
  102. the data stored in binary format in an Amiga file.  To send the data back
  103. to the instrument, just use "binary" for input and "MIDI" for output!
  104.  
  105.     Yet another use is for MP to translate between binary data and
  106. readable text.  This can help you to understand the contents of a binary
  107. MIDI file, or to create binary MIDI files by typing simple text commands.
  108. (Note:  this facility will work with ANY binary files, not just those
  109. containing MIDI data.)
  110.  
  111.     You can also ask MP to translate from one format to the same
  112. format!  For example, it can read MIDI data and "echo" it back to the
  113. sending instrument (translating MIDI to MIDI), copy binary files (translating
  114. binary to binary), or let you practice with its text language (text to
  115. text).
  116.  
  117.     
  118. A FIRST EXERCISE
  119.  
  120.     Let's ask MP to translate from MIDI into text.  Make sure your
  121. MIDI synthesizer is hooked up properly to your Amiga.  Type:
  122.  
  123.         1>  mp  -im  -ot
  124.  
  125. (This asks MP to use MIDI input (-im) and text output (-ot).)
  126.  
  127.     Now go to your instrument and play notes, press buttons, turn
  128. dials, etc.  You should see things appearing on your Amiga screen!  To
  129. exit the program, type ^C (control-C) on the Amiga.
  130.  
  131.  
  132. FORMAL USAGE INSTRUCTIONS FOR MP
  133.  
  134.     MP's syntax is:
  135.  
  136.         1>  mp  -i{tbm}  -o{tbm}  [-g infile]  [-p outfile]
  137.  
  138. The flags "-i" and "-o" are mandatory (they MUST appear, in any order).
  139. The flag "-i" represents input, and "-o" represents output.  You also
  140. must fill in the "[choice]" specifying text, binary, or MIDI.  The syntax
  141. is:
  142.  
  143.         t    Text
  144.         b    Binary data
  145.         m    MIDI
  146.  
  147. For example, to read text from the keyboard and send to MIDI:
  148.  
  149.         1>  mp -it -om
  150.  
  151. To read MIDI data and convert it to text:
  152.  
  153.         1>  mp -ot -im
  154.  
  155. If you would like to GET your input from a file (not the keyboard), you may
  156. specify a file name with the -g option.  Similarly, the -p option allows
  157. you to PUT the output into a file (rather than the screen).  The -g and -p
  158. options have no meaning, obviously, if your input and output are MIDI,
  159. respectively.
  160.  
  161.     
  162. THE INPUT TEXT LANGUAGE
  163.  
  164.     If you do not already know what MIDI code looks like (for
  165. example, hexadecimal 90 means "Note On, MIDI channel 0"), then this
  166. section might not be useful to you yet.  But feel free to try!
  167.  
  168.     MP understands many different kinds of text input.  To use the
  169. text input feature, you must learn a very simple syntax.  If you are a
  170. C programmer, you will recognize some of this language and feel right
  171. at home.  (Don't worry... you don't have to be a C programmer to use MP!
  172. It will take a little practice, though.)
  173.  
  174.     MP understands NUMBERS (between 0 and 255) in:
  175.  
  176.     -    Base 10 (decimal or "normal" numbers)
  177.         Just type the number normally.
  178.         Example:    123
  179.  
  180.     -    Base 8 (octal)
  181.         Precede the number with a zero.
  182.         Example:    024
  183.  
  184.     -    Base 16 (hexadecimal)
  185.         Precede the number with an "H" or the symbol "0x".
  186.         If the number begins with A through F, you can skip the
  187.          above symbols.
  188.         Examples:    0x2A     H44    F7
  189.  
  190.     -    Base 2 (binary)
  191.         Precede the number with a "#".
  192.         Example:    #10010110
  193.  
  194.     All special symbols (such as "H", "0x", and the hexadecimal numbers
  195.     from A...F) are case-insensitive.  That means capital and small
  196.     letters are equivalent.
  197.  
  198. MP understands CHARACTERS as:
  199.  
  200.     -    Individual characters.
  201.         Enclose in single quotes, like 'x'.
  202.  
  203.     -    Character strings.
  204.         Enclose in double quotes, like "this is a string".
  205.  
  206.     C special characters (like '\n') are recognized both as individual
  207.     characters and in strings.
  208.  
  209.     If you type a RETURN in the middle of a string, it is interpreted
  210.     as a space character.  (If you want a real newline character, use
  211.     \n.)  If a string is too long to fit on your screen, break it into
  212.     2 strings (or more), each surrounded by double-quotes.
  213.  
  214.  
  215.     All of these numbers/characters are automatically converted into
  216. bytes.  As a result, you cannot specify a number with value greater than 
  217. 255 (base 10) or less than 0.  If you do, you will get an error message.
  218.  
  219.     MP also has a "comment" symbol.  This lets you type text that is
  220. ignored by MP.  Any text following a semicolon (";") is ignored until
  221. the end of the line.  (This is just like the Amiga CLI comment symbol.)
  222. (Of course, this does not occur if the semicolon is part of a character
  223. constant or string.)
  224.     Why is a comment symbol useful?  You can put text language commands
  225. in a file and send it to your MIDI instrument.  Comments allow you to 
  226. document the meaning of the contents of the file.  For example:
  227.  
  228.         ; Send a C major chord on MIDI channel 0
  229.         0x90 60 127 64 127 67 127
  230.  
  231.  
  232.     EVERY INDIVIDUAL NUMBER/CHARACTER/STRING/COMMENT THAT YOU TYPE
  233. MUST BE SEPARATED FROM ITS NEIGHBORS BY WHITESPACE (blanks, tabs, newlines).
  234. Yes, even comments.  This may change in a later version of the program.
  235.  
  236.  
  237. PRACTICING WITH THE TEXT LANGUAGE
  238.  
  239.     Type the command:
  240.  
  241.         1>  mp  -it  -ot
  242.  
  243. This tells MP to translate from text into text, totally bypassing MIDI.
  244. As you type in the text language, you will see your data interpreted by
  245. MP.  To end MP, type control-C (^C).
  246.  
  247.     When you feel comfortable with the text language, try sending some
  248. data to your synthesizer.  Type:
  249.  
  250.         1>  mp  -it  -om
  251.  
  252. Here is some data:
  253.  
  254.         H90 60 100
  255.  
  256. This tells the instrument to play Middle C (note 60) at volume (velocity)
  257. 100, assuming the instrument is on MIDI channel 0.  To turn o