Table of Contents


MIDImyAPP

is a free programmable UNIX command-line tool (32/64bit Intel-based) for Mac OSX 10.5 or higher (old ppc version here) to remote your Mac and send user-defined MIDI events (including SysEx messages) triggered by any MIDI events sent on the MIDI bus.

For remoting your Mac you can specify any shell commands (a script [Shell, Ruby, Perl, Java, AppleScript, Python, etc.] or an UNIX command [open, say, etc.]) which will be executed if a defined MIDI event occured. It is also possible to send user-defined MIDI events triggerd by other MIDI events coming from the MIDI bus.

In addition MIDImyAPP is able to control basic functions of GarageBand (start MIDImyAPP with option -g):

MIDIMyApp also ships with two other command-line tools to play and stop a sound or MIDI file.

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.


1 Installation

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

download MIDImyAPP (93kB)


2 Usage

2.1 Start

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

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 XML Mac Property List file (plist) which can be edited with the “Property List Editor”, XCode (if installed), or a plain text editor.

The internal structure is quite simple:

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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>THE MIDI EVENT</key>
    <string>SHELL COMMAND</string>
</dict>
</plist>

Hints:

2.2.2 Sending of MIDI events

If MIDImyAPP starts it creates a so-called pipe named sendMIDI located in the MIDImyAPP directory. This allows other programs or scripts to send commands back to MIDImyAPP. Supported commands are:

2.2.2.1 MIDI send mode

As default MIDImyAPP makes usage of the coreMIDI function MIDIReceived() to send the passed event to the bus. This will exclude virtual MIDI devices as IAC (see Audio MIDI Setup). You can toggle that mode by using the program option -i or the run-time command i. In the so-called IAC mode MIDImyAPP send the passed event to all found destination by using coreMIDI’s MIDISend() function. Please make sure in Mac’s “Audio MIDI Setup” that the IAC device is ‘online’.

2.2.2.2 Example

From another Terminal you can execute this bash command:

echo m903c66 > ./sendMIDI

if the Terminal runs in the same directory as MIDImyAPP, ohterwise you have to specify the full absolute path to the pipe sendMIDI.

Hint mXX and wXX are also avaiable as run-time commands.

2.2.2.3 MIDImyAPP MIDI event header

If MIDIMyApp sends a MIDI event by using mXX it adds 4 bytes 0x00 in front of the event in order to be able to recognize that a received event was sent by MIDImyAPP itself and to avoid an eternal loop. This adding don’t change the actual event.

For instance, you specified that MIDI events 90XXXX should call a script which is changing the velocity and sending that changed event back to the MIDI bus then without header the sent MIDI event would trigger the 90XXXX again; instead MIDImyAPP sends 0000000090xxxx.

2.2.3 GarageBand commands

MIDImyAPP, if started with the command-line option -g creates an internal bridge to GarageBand in order to be able to execute some basic commands much faster. So far the supported commands which has to be used as SHELL COMMAND in the configuration file are:

2.2.3.1 Examples

2.2.4 Coding

2.2.4.1 General Workflow for static MIDI events:

2.2.4.2 General Workflow for MIDI events passing variables:

2.2.4.2.1 Passing one variable (last byte of MIDI event helds dynamic data)

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:

2.2.4.2.2 Passing two variable (the two last bytes of MIDI event held dynamic data)

2.2.5 Examples

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

2.2.6 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.7 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

2.3 Runtime Commands

The following runtime commands are available:


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


6 Appendix

6.1 play / stop utility

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