AM/FM: Amiga Musicians' Freeware Magazine 5

home *** CD-ROM | disk | FTP | other *** search

/ AM/FM: Amiga Musicians' Freeware Magazine 5 / AM-FM 5.adf / utilities / MP / MP.DOC.pp / MP.DOC

Wrap

Text File | 1991-11-17 | 15.7 KB | 472 lines

MP: A MIDI Playground Author: Daniel J. Barrett, barrett@cs.jhu.edu. No Copyright: 100% Public Domain. Please share this program with others. Requirements: A Commodore Amiga. Optional: A MIDI Interface on your serial port. 1 or more MIDI instruments. (Without MIDI, this program is not very useful, except perhaps as a source code example for serial port programming and parsing input.) Legal stuff: Use this program entirely at your own risk. The author bears no responsibility for any damage or data loss you may incur through the use or misuse of this program. GETTING QUICK HELP At the command line, type: 1> mp ? TABLE OF CONTENTS Line Section =========================================================================== 18 Getting quick help 24 Table of contents 46 What is MP? 77 What is MP not? 84 MP concepts 118 A first exercise 132 Formal usage instructions for MP 162 The input text language 237 Practicing with the text language 264 Using the file input/output options to make new windows 277 Using redirection 306 Translating binary data to/from text 318 Using an alternate MIDI interface 359 Problems you may have with MP 425 Notes about the source code 457 Notes about the program's internals (and limitations) WHAT IS MP? Have you ever wanted to see what MIDI data your instrument is transmitting? Have you ever wanted to send your own MIDI data to your MIDI instrument? Then MP is for you!! MP (MIDI Playground) is a versatile tool for sending, receiving, and storing MIDI data. It has many uses: o Learning about MIDI. o Discovering your instrument's system exclusive data format. o Testing your instrument's MIDI capabilities. o Acting as a patch librarian. (VERY VERY basic, though.) o Helping you write MIDI software. Essentially, MP is a "translator" program that understands 3 data formats and translates between any pair: (1) English text (2) Binary data (3) MIDI data Formats (2) and (3) are really the same, but (2) is stored in files on your Amiga, and (3) is transmitted via your MIDI interface. WHAT IS MP NOT? MP is not a sequencer. It does not store any kind of timing information. MP simply sends and receives bytes in the order they are given. MP CONCEPTS Like I said, MP translates between text, binary data, and MIDI data. All you need to do is: (1) Choose a format for the input. (2) Choose a format for the output. (The input and output formats can be the same if you like.) (3) Run MP. For example, you can ask MP to use "text" as input and "MIDI" as output. This lets you type text in a very easy-to-learn language, and it immediately gets sent out as MIDI data. If you reverse these choices (input=MIDI, output=text), you can watch MIDI data appear on your screen in a simple but readable format. Another use would be to use "MIDI" as input and "binary" as output. This lets you press keys and buttons on your instrument, and have all the data stored in binary format in an Amiga file. To send the data back to the instrument, just use "binary" for input and "MIDI" for output! Yet another use is for MP to translate between binary data and readable text. This can help you to understand the contents of a binary MIDI file, or to create binary MIDI files by typing simple text commands. (Note: this facility will work with ANY binary files, not just those containing MIDI data.) You can also ask MP to translate from one format to the same format! For example, it can read MIDI data and "echo" it back to the sending instrument (translating MIDI to MIDI), copy binary files (translating binary to binary), or let you practice with its text language (text to text). A FIRST EXERCISE Let's ask MP to translate from MIDI into text. Make sure your MIDI synthesizer is hooked up properly to your Amiga. Type: 1> mp -im -ot (This asks MP to use MIDI input (-im) and text output (-ot).) Now go to your instrument and play notes, press buttons, turn dials, etc. You should see things appearing on your Amiga screen! To exit the program, type ^C (control-C) on the Amiga. FORMAL USAGE INSTRUCTIONS FOR MP MP's syntax is: 1> mp -i{tbm} -o{tbm} [-g infile] [-p outfile] The flags "-i" and "-o" are mandatory (they MUST appear, in any order). The flag "-i" represents input, and "-o" represents output. You also must fill in the "[choice]" specifying text, binary, or MIDI. The syntax is: t Text b Binary data m MIDI For example, to read text from the keyboard and send to MIDI: 1> mp -it -om To read MIDI data and convert it to text: 1> mp -ot -im If you would like to GET your input from a file (not the keyboard), you may specify a file name with the -g option. Similarly, the -p option allows you to PUT the output into a file (rather than the screen). The -g and -p options have no meaning, obviously, if your input and output are MIDI, respectively. THE INPUT TEXT LANGUAGE If you do not already know what MIDI code looks like (for example, hexadecimal 90 means "Note On, MIDI channel 0"), then this section might not be useful to you yet. But feel free to try! MP understands many different kinds of text input. To use the text input feature, you must learn a very simple syntax. If you are a C programmer, you will recognize some of this language and feel right at home. (Don't worry... you don't have to be a C programmer to use MP! It will take a little practice, though.) MP understands NUMBERS (between 0 and 255) in: - Base 10 (decimal or "normal" numbers) Just type the number normally. Example: 123 - Base 8 (octal) Precede the number with a zero. Example: 024 - Base 16 (hexadecimal) Precede the number with an "H" or the symbol "0x". If the number begins with A through F, you can skip the above symbols. Examples: 0x2A H44 F7 - Base 2 (binary) Precede the number with a "#". Example: #10010110 All special symbols (such as "H", "0x", and the hexadecimal numbers from A...F) are case-insensitive. That means capital and small letters are equivalent. MP understands CHARACTERS as: - Individual characters. Enclose in single quotes, like 'x'. - Character strings. Enclose in double quotes, like "this is a string". C special characters (like '\n') are recognized both as individual characters and in strings. If you type a RETURN in the middle of a string, it is interpreted as a space character. (If you want a real newline character, use \n.) If a string is too long to fit on your screen, break it into 2 strings (or more), each surrounded by double-quotes. All of these numbers/characters are automatically converted into bytes. As a result, you cannot specify a number with value greater than 255 (base 10) or less than 0. If you do, you will get an error message. MP also has a "comment" symbol. This lets you type text that is ignored by MP. Any text following a semicolon (";") is ignored until the end of the line. (This is just like the Amiga CLI comment symbol.) (Of course, this does not occur if the semicolon is part of a character constant or string.) Why is a comment symbol useful? You can put text language commands in a file and send it to your MIDI instrument. Comments allow you to document the meaning of the contents of the file. For example: ; Send a C major chord on MIDI channel 0 0x90 60 127 64 127 67 127 EVERY INDIVIDUAL NUMBER/CHARACTER/STRING/COMMENT THAT YOU TYPE MUST BE SEPARATED FROM ITS NEIGHBORS BY WHITESPACE (blanks, tabs, newlines). Yes, even comments. This may change in a later version of the program. PRACTICING WITH THE TEXT LANGUAGE Type the command: 1> mp -it -ot This tells MP to translate from text into text, totally bypassing MIDI. As you type in the text language, you will see your data interpreted by MP. To end MP, type control-C (^C). When you feel comfortable with the text language, try sending some data to your synthesizer. Type: 1> mp -it -om Here is some data: H90 60 100 This tells the instrument to play Middle C (note 60) at volume (velocity) 100, assuming the instrument is on MIDI channel 0. To turn off the note: H80 60 0 To end MP, type control-C (^C). USING THE FILE INPUT/OUTPUT OPTIONS TO MAKE NEW WINDOWS On the Amiga, you can specify a NEW WINDOW as a file, rather than an actual disk file. The syntax is found in your AmigaDOS manual, under the NewCLI or NewShell command. For example, to print your output in a 640x100 window, positioned at screen location (20,25), with window name "MP-IN", you would use: 1> mp ... -g "CON:20/25/640/100/MP-IN" ... Do similarly for output windows, but use -p instead of -g. USING REDIRECTION You can use the CLI's INPUT REDIRECTION symbol to get input from a file instead of from the keyboard. See your AmigaDOS manual for more details. The syntax is: < filename and it must appear immediately after the command name (MP). For example: 1> mp < infile -it -om to send text data (translated to MIDI) from the file "infile" to the MIDI instrument. Some sample input files are included with this program. You may also use the CLI's OUTPUT REDIRECTION symbol to send output to a file instead of to the screen. See your AmigaDOS manual for more details. The syntax is: > filename and it must appear immediately after the command name (MP). For example: 1> mp > outfile -im -ot to capture MIDI data (translated to text) into the file "outfile". TRANSLATING BINARY DATA TO/FROM TEXT Suppose you have a binary file that you want to translate to text. (It does not even have to be a MIDI data file!!) Just type: 1> mp < binaryFile -ib -ot If you prefer to save your text results in a file, type: 1> mp < binaryFile > textFile -ib -ot USING AN ALTERNATE MIDI INTERFACE By default, the MP assumes that your MIDI interface is connected to your Amiga's internal serial port. If this is not the case, you can override this by using an Amiga environment variable and the SetEnv command. (See your Amiga documentation for full details about SetEnv.) The name of the environment variable is MP_MIDI_DEVICE, and its value must be of the following format: 1) The name of the MIDI device driver, located in the DEVS: directory of your system disk. It should be something like "midi.device" or "serial2.device". 2) One colon character (':'). 3) The unit number for the device. If you have only 1 port using the device, your unit number is probably zero. Example: midi.device:2 Suppose you want to set up MP to use unit 3 the device "AltMidi.device". Type: 1> SetEnv MP_MIDI_DEVICE AltMidi.device:3 To check that the value was set correctly, type: 1> GetEnv MP_MIDI_DEVICE If you are using a MIDI interface attached to your internal serial, port, YOU MAY IGNORE ALL OF THIS STUFF. By default, MP uses unit 0 of the device "serial.device". I cannot guarantee that MP will work with whatever alternate device driver you choose. But I have tested the environment variable mechanism itself, and it works. PROBLEMS YOU MAY HAVE WITH MP I have tested these programs fairly well on my own equipment: Amiga 1000, Golden Hawk MIDI Gold interface, and an Oberheim Matrix-12. If the program doesn't work for you, first check: (?) Is the file "serial.device" in the DEVS: directory of your system disk? If not, MP will refuse to run, and you will see an error message like one of these: Cannot create a message port. Cannot create an extended I/O request. Cannot open the MIDI device. Cannot set the serial parameters. Boot your Amiga with an original Workbench disk and try again. (?) Are you running a version of the Amiga operating system that is older than 1.3? MP should work with some or all earlier versions, but I have not tested this. (?) Are your MIDI cables connected properly? Remember that MIDI OUT must always be connected to MIDI IN, and vice-versa. SYNTHESIZER COMPUTER ----------- -------- MIDI IN <-------------------> MIDI OUT MIDI OUT <-------------------> MIDI IN (?) Are you using the program correctly? Double-check the instructions above. (?) Are you running another program that uses the serial port, such as a communications program, printing program, or another MIDI program? If so, this other program may be using the serial port. (MP uses the serial port in "shared" mode so it doesn't hog the serial port.) Exit your other programs and try again. If it still doesn't work, reboot to make sure that your other programs didn't accidently leave the serial port "locked". Some programs allow you to "release" their hold on the serial port without exiting. (Example: Music-X.) This may be enough to allow MP to run. If you run MP with the "-im" format (input from MIDI), you cannot run MP a second time simultaneously. This is because the Amiga serial port initialization routines will fail if there is another program reading the serial port. (?) Are you running any other programs simultaneously with MP? It is possible that a badly-written program could interfere with the operation of other programs. Boot your Amiga with an original Workbench disk and try again. (?) Is your synthesizer turned on? Seriously. This has happened to me. :-) If you are doing everything right, then there may be a bug in the program. For example, MP should NEVER crash your Amiga. If you believe that there is a bug, please contact me (electronic mail is preferred). But first, try to reproduce the bug consistently. Can you find a particular set of actions, keystrokes, etc., that ALWAYS make the program crash? If you can, then I will be able to find the bug faster. NOTES ABOUT THE SOURCE CODE The file "text.c" contains a good example of using a finite automaton to read the text language and translate it into bytes. The code is fairly robust and easy to modify. For example, I was able to add "binary number" support in about 3 minutes, and "string" support in about 10 minutes. The theory of finite automata is extremely important for programmers, but it can seem very "theoretical" at first. Believe me, it helps you write correct programs that are easy to modify later. The file "serial.c" contains serial port code that you are welcome to use. The function "DoTheIO()" implements asynchronous I/O in a very multitasking-friendly way. The function "FastSerialRead()" is patterned after Commodore's recommended method for reading the serial port quickly. The method is documented in the AMIGA ROM KERNEL REFERENCE MANUAL: LIBRARIES AND DEVICES, for version 1.3 of the Amiga Operating System. The file "main.c" contains examples of using pointers to functions and pointers-to-pointers to functions. (The functions themselves are defined in "iofunctions.c".) The file "getopt.c" contains my version of the powerful and useful UNIX "getopt()" function. This gives the programmer a standard interface for reading command-line options (flags) from the user. I have used this file (unchanged) in a dozen programs. The "Makefile" is pretty generic. If you want to add a new file to the program, just append its name (and its object file's name) to the SRC and OBJ macros, and type "make". NOTES ABOUT THE PROGRAM'S INTERNALS (AND LIMITATIONS) MP uses a very inefficient method for sending MIDI data and reading/writing files: one byte at a time. This could definitely be made faster, but takes some cleverness (and some internal buffering). MP does read MIDI data very efficiently, though. This limitation is due to the byte-oriented nature of this program. Also, when the user is typing text, he/she wants immediate feedback from a MIDI device. I'm sure there is a better way to do this than my method. I did not build this program for large data transfers. It is mainly for transmitting small amounts of data for diagnostic purposes. This is why I have released the program before its I/O routines are improved.