home *** CD-ROM | disk | FTP | other *** search
/ Audio 4.94 - Over 11,000 Files / audio-11000.iso / amiga / midi / md11wtch.lha / midiwatcher / midiwatcher.doc < prev    next >
Encoding:
Text File  |  1993-08-15  |  9.3 KB  |  201 lines
  1. ============================================================================
  2.  
  3.                         MidiWatcher v1.1 by Ed Mackey
  4.  
  5. ============================================================================
  6.  
  7. Yes folx, another one of my silly trinkets appears on the net ;-).
  8.  
  9. MidiWatcher is for people with MIDI keyboards.  It requires the midi.library
  10. v2 or higher by Bill Barton (not included).  It should run under almost any
  11. version of the Amiga's OS.
  12.  
  13.   New for v1.1:  Failure programs (see below).  Also, improved -d debug
  14.                  mode, various bug fixes, tries to find if MidiWatcher
  15.                  is already running and exit it, etc.  Also I decided to
  16.                  release source code with this version.  Good luck trying
  17.                  to read it!!  ;-)
  18.                  **** Old save files from v1.0 still work fine!! ****
  19.  
  20. Basically, this program sits in the background and watches your MIDI IN port
  21. for certain tunes.  When it recognizes a tune, it runs a program.
  22.  
  23. For instance, if I need my directory utility up, I can do one of three
  24. things:  (1) I can search through subdirectories for its icon (takes too
  25. much time and is boring), (2) I can press a ToolManager hotkey (takes much
  26. less time but is still boring), or (3) I can reach over and play a little
  27. jingle on my MIDI keyboard, and up pops MegaD.  The third choice is clearly
  28. much more fun than either of the others ;-).
  29.  
  30. This program should be run from the CLI.  I suppose it would also run from
  31. Workbench if you did not need to pass any parameters to it.  Personally,
  32. I recommend putting it in your user-startup file.  If you type
  33. midiwatcher ?
  34. you will see:
  35.  
  36.     MidiWatcher v1.1 by Ed Mackey.  Watch MIDI keyboard for tunes.
  37.     Usage: midiwatcher [-i source] [-f savefile] [-r] [-d]
  38.       -i selects a MidiIn source, defaults to MidiIn
  39.       -f selects a tune save file, defaults to S:midiwatch
  40.       -r turns on RECORD mode and adds a tune to file -f
  41.       -d turns on DEBUG mode (playback only) to see your tunes go.
  42.  
  43. Here is a more complete description of the options:
  44.  
  45. Well actually, -i is already described as much as it needs to be.  See the
  46. DOCs for midi.library to learn more about MIDI sources.  Note that ALL 16
  47. channels of your MIDI source will be monitored as if they were all one
  48. channel.  I realize this is somewhat uncool for some people, but remember
  49. this program is only a trinket.  You can also filter out MIDI channels with
  50. a midi.library patch bay type program.  Send me email if you want this
  51. changed.
  52.  
  53. -f selects a filename for the database of tunes to be recognized.  See -r
  54.  
  55. -d is DEBUG mode, so you can watch MidiWatcher trying to recognize tunes.
  56.  
  57. -r puts MidiWatcher in RECORD mode.  When in this mode, MidiWatcher saves
  58. every note it sees until you press CTRL-C.  It then writes to the savefile
  59. something that looks like this:
  60.  
  61.     # Your comments go here (such as name of tune)...
  62.     # You may wish to insert a colon (":") at the point of no return...
  63.     $3c 37 36 37 38 37 3b 3c 
  64.     #### Success program...
  65.     @PLAY
  66.     *id midi_event
  67.     >echo "Tune recognized"
  68.     #### Failure program...
  69.     +PLAY
  70.     !id midi_fail
  71.     ]echo "You passed the colon, and then blew it!!"
  72.  
  73. Only, you know, flush left because it is not in a DOC file.  :-)
  74. The save file will be appended to if it already exists, and created
  75. otherwise.  You should then edit this file with a text editor.  Here is
  76. what the lines mean:
  77.  
  78. # is a comment line.  Just write the name of the tune or whatever here.
  79.  
  80. $ has some hex numbers which you should not change.  These are the note
  81. numbers extracted from MIDI NoteOn messages during your recording.  Note
  82. there is no tempo or chord information here, just a sequence of NoteOns.
  83. I don't recommend playing chords unless you can start the individual
  84. notes of the chord in a certain order all the time.  I told you this
  85. program was a trinket, didn't I?
  86.  
  87. @ This is an optional line for people with ARexx.  It specifies an ARexx
  88. port, and as you know, ARexx port names are case-sensitive.
  89.  
  90. * This is an optional line for people with ARexx.  It contains a string
  91. to send as an ARexx message to the port named by the @ line.  Note that
  92. both the @ and * lines must be included for either to have an effect.
  93. People without ARexx should delete all @ and * lines.
  94. When a tune with an ARexx message is recognized, the message is prepared
  95. and sent.  MidiWatcher then continues normal processing _without_ waiting
  96. for the message to return.  However, if you send MidiWatcher a CTRL-C
  97. or a QUIT command (explained later), MidiWatcher will wait for all sent
  98. ARexx messages to return before quitting.
  99.  
  100. > This line specifies a CLI command to execute.  This line can be omitted
  101. only if both the @ and * lines are present and no CLI command is needed.
  102. (Unless you really _want_ a tune that does nothing... ??)
  103. Note that unlike ARexx messages, the CLI command will prevent MidiWatcher
  104. from running until the command's completion.  This should always be
  105. avoided like this:
  106. >run <NIL: >NIL: (your path & program name here)
  107. This use of the "run" command will make sure that MidiWatcher can keep
  108. multitasking with your newly-started program.
  109.  
  110. Note that if both an ARexx message and a CLI command are specified for
  111. a given tune, the ARexx message will be sent first, and the CLI command
  112. will be executed immediately after the message is sent.  As you can see
  113. from the example, I use this with Upd to play sound effects and launch
  114. programs at the same time, each time a tune is recognized.
  115.  
  116. ----------------------------------------------------------------------------
  117.                              Failure Programs
  118. ----------------------------------------------------------------------------
  119.  
  120. + ARexx port:    just like "@", but for failure programs.
  121. ! ARexx message: just like "*", but for failure programs.
  122. ] CLI command:   just like ">", but for failure programs.
  123.  
  124. "Failure Programs" are a new feature of MidiWatcher v1.1.  Let's say you
  125. insert a colon in your line of notes, so it looks like this:
  126.  
  127.     $3c 37 36 37 38 37:3b 3c 
  128.  
  129.            The colon ^^^ tells MidiWatcher that if the user gets this far
  130. in the song, he/she really is trying to play this particular song.  If
  131. he/she messes up, anytime after the colon, MidiWatcher will run the failure
  132. program specified by the "+", "!", and/or "]" line(s).
  133.  
  134. In the above example, the colon is between the 6th and 7th notes.  So, if
  135. the user messes up any of the first six notes, nothing happens.  If the user
  136. plays all eight notes correctly, the usual action(s) are taken ("@", "*",
  137. ">").  BUT, if the user plays the first _six_ notes correctly, and then gets
  138. the 7th or 8th _wrong_, the "failure program" ("+", "!", "]") will be run.
  139.  
  140. The usefulness of this is about the same level as the usefulness of anything
  141. else in this program:  If you start to play a tune, and then screw it up,
  142. you can have your machine shout at you, "STUPID!!  YOU SO STUPID!!!!"
  143. You can get a lovely sound sample of this from Weird Al's movie "UHF".
  144. ("You get over there and spin the Wheel of Fish!!")
  145.  
  146. ============================================================================
  147.  
  148.                            The ARexx Port
  149.  
  150. ============================================================================
  151.  
  152. Aha.  Not expecting that one were you?
  153.  
  154. Well, this program has an ARexx port of it's own, called MIDIWATCHER.
  155. It currently understands three commands, and these commands must
  156. always appear in UPPER CASE (sorry guys):
  157.  
  158.     SUSPEND    - Release the MidiIn (and hence the serial port, unless some
  159.                  other program is using MIDI), and just sit in the
  160.                  background until further notice.  Returning ARexx messages
  161.                  sent by tunes are still freed.  If MidiWatcher was already
  162.                  in suspend mode, this command is ignored.
  163.  
  164.     RESUME     - Leave SUSPEND mode if MidiWatcher was in it.  MIDI and your
  165.                  serial port are again tied up.
  166.  
  167.     QUIT       - Same as sending MidiWatcher's CLI process a CTRL-C.
  168.                  Deallocates MIDI, waits for any ARexx messages sent by
  169.                  tunes to come home, and exits (in that order ;-).
  170.                  Should work even in SUSPEND mode (I hope).
  171.  
  172. This port is NOT available in RECORD [-r] mode (it's not needed then).
  173.  
  174. I suppose you could have a tune that caused MidiWatcher to send an ARexx
  175. message to itself.  This would not cause a problem (but of course a
  176. RESUME message would be useless, as MidiWatcher could not be in SUSPEND
  177. mode in the first place if it was sending messages).
  178.  
  179. NOTE:  If the serial port is not available to midi.library when
  180.        MidiWatcher is run or when MidiWatcher receives a RESUME
  181.        command, MidiWatcher will have a cow and act like you pushed
  182.        CTRL-C.  I suppose I should fix this.... nah....
  183.  
  184. Anyway, I added this ARexx port as an afterthought, so that I could have
  185. my terminal program use SUSPEND to grab the serial port and RESUME when
  186. it was done.
  187.  
  188. ============================================================================
  189.  
  190. Have fun with your new trinket.  Don't take this program too seriously,
  191. I only wrote it because I needed a short break from my senior project.
  192. I disclaim responsibility for any blah blah blah whatever.
  193. If you like this program send me money blah blah blah whatever.
  194.  
  195. Have fun!!
  196.                                      --Ed.
  197.  
  198.       Ed Mackey           BBS:  Somerton Telecomm II, (215) 464-6775
  199.       PO Box 475          IRC:  LineNoise
  200.       Wayne, PA 19087     Internet email:  emackey@BIX.com
  201.