OLD PPC VERSION 1.01

Table of Contents

• 1 Installation
• 2 Usage
  • 2.1 Start
  • 2.2 Configuration
    • 2.2.1 General Remarks
    • 2.2.2 Coding
      • 2.2.2.1 General Workflow for static MIDI events:
      • 2.2.2.2 General Workflow for MIDI events passing a variable:
    • 2.2.3 Examples
    • 2.2.4 The usage of other configuration files
    • 2.2.5 execMode
  • 2.3 Runtime Commands
• 3 Author
• 4 Copyright Notes
• 5 Release Notes
• 6 Appendix
  • 6.1 play / stop utility
  • 6.2 scpt Folder

MIDImyAPP^BETA

is a free programmable UNIX command-line tool for Mac OSX 10.4 and 10.5 (Tiger/Leopard intel or ppc) to execute any shell command (a script [Shell, Ruby, Perl, Java, AppleScript, Python, etc.], an UNIX command [open, say, etc.]) triggered by any MIDI event sent by a MIDI device. In other words MIDImyAPP can not only control other music devices but also other applications on your Mac.

For instance you can remote GarageBand:

• remote the transport buttons
• select next/previous track
• control pan and volume of a track
• control to master volume
• open an other song
• …

or to play/stop a sound file, to set the output volume of the Mac, or open an other application, or change the face of the selected word in your text editor to bold by a single MIDI event (programmable keyboard).

MIDImyAPP rescans the MIDI configuration for each change on the global MIDI settings automatically.

MIDImyAPP is written in Carbon-C++ entirely to decrease the latency time as much as possible. For live performances it is recommended to use at least a double-core Intel Mac with 2GHz.

Hint: Each AppleScript as shell command which begins with tell app will be executed internally to speed up the execution.

1 Installation

Simply download and decompress the ZIP archive to any location on your Mac.

download MIDImyAPP (100kB)

2 Usage

2.1 Start

MIDImyAPP is an UNIX shell command which runs in the Terminal.

• open the Terminal (in Application > Utilities)
• change the directory to MIDImyAPP
  • e.g.: cd ~/Desktop/MIDImyAPP
• type: ./MIDImyAPP and press ↩ RETURN
• to quit it press ^C (CTRL+C) or type x and press ↩ RETURN

An other option to start MIDImyAPP is to double-click at startMIDImyAPP from Finder.

If there is the need to run MIDImyAPP in the background you can double-click at startMIDImyAPPBG and close the Terminal afterwards. To stop MIDImyAPP double-click at stopMIDImyAPP

Once you invoked MIDImyAPP (not hidden) you should see the sent MIDI events in the Terminal window (a kind of MIDIlogger).

2.2 Configuration

2.2.1 General Remarks

Inside the MIDImyAPP folder there is a default configuration file called config.plist. This file is a standard Mac Property List file (plist) which can be edited with the “Property List Editor”. Simply double-click at it and the editor starts.

The internal structure is quite simple:

• first column (key) the MIDI event
• second column (class/type) always set it to “String”
• third column (value) the actual shell command which will be invoked for that MIDI event

If you open it in a text editor you will see:

Hints:

• this file must be saved as UTF-8 encoded (only relevant while editing in a text editor)
• you have to use HTML entities for these characters: instead < > & you have to write < > & (only relevant while editing in a text editor); all other ASCII characters are allowed including new_line
• do not change the internal structure, otherwise MIDImyAPP cannot parse it
• the SHELL COMMAND must be written by using ASCII characters only (although the plist file is UTF-8 encoded due to an internal of MIDImyAPP)
  • if there is the need to use non-ASCII characters (Unicode, accented characters like ü) you can write a script which will be called by MIDImyAPP
• the value (SHELL COMMAND) may not be empty, i.e. if you want to execute “nothing” you have to write at least one space

2.2.2 Coding

2.2.2.1 General Workflow for static MIDI events:

• invoke a MIDI event on your device
• look in the Terminal to get the MIDI code
• use exactly that code as KEY in the plist file
• specify the SHELL COMMAND as value for that KEY in the plist file
• save the file
• restart MIDImyAPP (or type r and press RETURN)

2.2.2.2 General Workflow for MIDI events passing a variable:

If you press for instance a key the velocity is passed as variable (last byte), if you control a slider, drawbar, or knob the actual value is passed as variable. To ignore or use that variable follow this workflow:

• invoke a MIDI event on your device
• look in the Terminal to get the MIDI code
• use exactly that code; replace the last two characters (byte) by XX as KEY in the plist file
• specify the SHELL COMMAND as value for that KEY in the plist file
  • if you want pass the variable value to the shell command use %@ as place holder
  • %@ will be replaced internally by the decimal value (in general 0-127)
• save the file
• restart MIDImyAPP (or type r and press RETURN)

2.2.3 Examples

• the release of key A5 on MIDI channel 4 should open the PDF file “test.pdf”:

  • MIDI event: 935D00 := MIDI channel 4, Note A5 off
  • KEY: 935D00 SHELL COMMAND: open "test.pdf"

• the hitting of key A5 on channel 4 should open the movie file “test.mov”:

  • MIDI event: 935D.. := as .. the velocity is passed (hex 01 to FF)
  • KEY: 935DXX SHELL COMMAND: open "test.mov"
    • If you release A5 that command will execute again. To prevent this set KEY: 935D00 to " "

• the hitting of key A5 on channel 4 should open a text document (TextEdit) containing the velocity times 100 plus the text “ speed”:

  • MIDI event: 935D.. := as .. the velocity is passed (hex 01 to FF)
  • KEY: 935DXX SHELL COMMAND: echo "`perl -e 'print @%*100'` speed" | open -f

• the hitting of key A5 on channel 4 should play the sound file “test.aif” (inside the MIDImyAPP folder) looped with the volume given by the passed velocity and stop it on release A5:

  • MIDI event: 935D.. := as .. the velocity is passed (hex 01 to FF)
  • KEY: 935DXX SHELL COMMAND: ./play -l -v %@ test.aif
  • KEY: 935D00 SHELL COMMAND: ./stop test.aif
    • for play and stop see Appendix

• the slider sending on channel 1 and CC 28 should control the master volume of “GarageBand”:

  • MIDI event: B01C.. := as .. the value is passed (hex 01 to FF := 0 to 127 decimal)

  • KEY: B01CXX SHELL COMMAND: osascript -e "tell app \"GarageBand\" to set master volume of the first song to (%@/127)"

    This works but it is rather slow. MIDImyAPP can execute any AppleScript beginning with “tell app” internally for speed, thus better is:

  • KEY: B01CXX SHELL COMMAND: tell app "GarageBand" to set master volume of the first song to (%@/127)"

Hint Have a look at the config.plist shipped with MIDImyAPP for further examples.

2.2.4 The usage of other configuration files

The configuration file config.plist will be used as default. MIDImyAPP accepts the option -p FILE to load an other configuration file. To use for instance the configuration file “My first gig.plist” located on the Desktop start MIDImyAPP from Terminal via:

./MIDImyAPP -p "$HOME/Desktop/My first gig.plist"

2.2.5 execMode

It is possible to use MIDImyAPP as slave to send each MIDI event to an other script or file. In that mode MIDImyAPP does not make usage of a configuration file.

Examples

• ./MIDImyAPP -e "echo %@ >> ~/events.txt"
  will append each event to the file ~/events.txt

• ./MIDImyAPP -e "echo %@ > ~/midi_pipe"
  will send each event to the named pipe ~/midi_pipe (useful if a script is listening on that pipe to do something with these events)

2.3 Runtime Commands

The following runtime commands are available:

• e
  • open the current configuration file with the default application (“Property List Editor”)
• h
  • print help
• p
  • pause or resume MIDImyAPP
• r
  • reload the current configuration file
• s
  • rescan MIDI devices (automatically done if MIDI configuration was changed)
• v
  • toggle the verbose mode
• x
  • exit MIDImyAPP

3 Author

     Hans-Jörg Bibiko   mail＠bibiko.de, bibiko＠eva.mpg.de
  

4 Copyright Notes

MIDImyAPP is totally free. The only condition is to give feedback about usability, bugs, suggestions, etc.

5 Release Notes

• version 1.01 (Jan 21, 2009)
  • runtime commands included
  • apply MIDI configuration changes automatically (no restart necessary)
• version 1.0 (Jan 15, 2009)
  • first release

6 Appendix

6.1 play / stop utility

Inside the MIDImyAPP folder there are two tiny command-line utilities play and stop.

• ./play {-l -v VOL} SOUND_FILE plays a passed sound file

  • -l play as loop
  • -v VOL play with the volume VOL (0-127)
  • SOUND_FILE (aif, aiff, aifc, caf, wav, mid, mp3, m4a, m4p, ulw, snd, au)

• ./stop SOUND_FILE stops the SOUND_FILE which is playing back by ./play

  • ./stop only works inside the configuration file and if ./play was called (literally)

6.2 scpt Folder

In that folder you find some useful AppleScripts for controlling “GarageBand” and others.