diff --git a/README.md b/README.md new file mode 100644 index 0000000..1368a8b --- /dev/null +++ b/README.md @@ -0,0 +1,228 @@ +MIDI Patchbay (Version 1.0.2) +============================= + +MIDI patchbay lets you hook up your various pieces of MIDI software and +hardware and pass MIDI data between them, applying assorted filters on the way. +Things like key splits, MIDI channel remapping, transposition, etc. are +made very simple. + +* [License](#license) +* [Requirements](#requirements) +* [Using MIDI Patchbay](#usage) +* [Known Problems](#problems) +* [Future Additions](#future) +* [Credits](#credits) +* [Version History](#history) + +License +----------------------------- + +This software is distributed under the terms of [Pete's Public +License](License.html). It's free (as in beer) but the license sets out a few restrictions on +its distribution and modification. + +If you use it I only ask for one thing: +[send me an e-mail](#mailto:pete@notahat.com). Tell me what +you use it for, anything you like and don't like, anything you'd like +to see in future versions, etc. + +For other ways to reward me for producing this, see[my web site](#http://www.notahat.com/software/). + +Requirements +--------------------------------------- + +* Mac OS X 10.2 or later +* A MIDI interface with OS X drivers +* Other MIDI software such as a sequencer or soft synth + +If you're looking for MIDI interface drivers or audio and MIDI applications +for Mac OS X, check out my [links page](#http://pete.yandell.com/links/). + + +Using MIDI Patchbay +--------------------------------------- + +Each MIDI Patchbay document window is divided into two parts: a patch list +on the left and a set of patch controls on the right. + +### The Patch List + +Each patch in the list represents a connection +between a MIDI input and MIDI output. The patch's input is shown on +the left of the arrow and the patch's output on the right. + +Below each patch's +arrow is a description of the data passed by the patch and +any filters that are applied to the data. + +Each patch also has a checkbox that can be used to enable or disable it. + +New patches can be created with the *Add patch* button. MIDI Patchbay +tries to create new patches intelligently based on the currently selected +patch. + + +### The Patch Controls + +The patch controls configure the input, output and filters for the +currently selected patch. + +The MIDI input and output for the patch can be selected from the +appropriate popup menus. As well as the MIDI interfaces connected to your +system, you can use the *Edit virtual inputs/outputs...* options to create +inputs and outputs that will be visible to other MIDI software. + +Under the various tabs are options allowing you to filter the MIDI data +for the currently selected patch. + + +### Example: Creating a Keyboard Split + +* Create a new MIDI Patchbay document +* Select the first patch in the list on the left +* From the *MIDI Input* popup menu choose your MIDI interface +* From the *MIDI Output* popup menu, select *Edit virtual outputs...* +* Create a new output named *Example output* and click *OK* +* Select *Example output* in the *MIDI Output* popup menu +* In the *Channels* tab, check the *Remap all data to MIDI channel:* +button and choose channel 1 +* In the *Notes* tab, check the *Only allow notes in the range:* button +and slide the lower slider until the note A4 is selected +* Click the *Add Patch* button. Note that the new patch created is +intelligently based on the currently selected patch and already has +the other half of the keyboard selected as its range of filtered notes +and has its traffic remapped to channel 2. +* Open your favourite synth software and select *Example Output* as +its MIDI input + +Now any notes up to A4 will be sent your synth software's MIDI channel 1 +and notes above A4 will go to channel 2. + + +Known Problems +------------------------------------- + +### Creating a MIDI routing loop can crash OS X + +For example, creating a patch that receives from and sends to the one +IAC bus is a bad idea. As soon as MIDI data gets sent to that IAC bus the +entire computer will lock up. + +You also have to be careful not to create indirect loops, as can +easily happen with Logic. + + +### Using MIDI Patchbay with Logic + +Using MIDI Patchbay with Logic can crash the computer, but the problem +is easily worked around. + +If you open a default song in Logic it will open with a MIDI track +enabled as MIDI thru. The default MIDI instrument is set to *all* +for the OUT port. + +If your MIDI Patchbay document contains a patch that routes from a +virtual input to a virtual output, this creates a MIDI routing loop. +Logic sends instrument settings into this loop at song-open and, hence, +a crash occurs. + +You can work around it by first disabling the patches in MIDI Patchbay, +opening Logic and turning off MIDI Thru, and then re-enabling the patches +in MIDI Patchbay. + + +### MIDI and Classic + +Some people have reported problems when trying to use Classic and +a MIDI interface simultaneously. It seems that Classic will try to grab +control of USB devices. When using this software, you should make sure +that Classic is not running. + + +### Deleting virtual inputs and outputs + +Sometimes trying to delete a virtual input or output will give you +a message saying that the input or output is in use by a patch and can't +be deleted even when it isn't. Saving, closing and re-opening the +document will fix this. + + +Future Additions +------------------------------------- + +This is what's currently on my to do list for MIDI Patchbay in rough order +of priority: + +* Additional filters: + * remapping of controller messages + * bank select/program change messages + * pitch bend data + * mod wheel data + * sysex data + * delay MIDI data (build your own arpeggiator!) + * transpose within a key (magic harmonies!) +* Copy and paste of patches +* Grouping of patches and assigning of keyboard/MIDI event +shortcuts to enable or disable groups for live use +* Spiffier interface which takes up less screen space and +has neat ways of doing things like keyboard splits or +arpeggiation + +Credits +---------------------------------- + +The software was designed and written by +[Pete Yandell](mailto:pete@notahat.com) + +Thanks to Kevan Staples for generously donating the MIDI Patchbay icon. + +Many, many thanks to Kurt Revis both for writing +[MIDI Monitor](http://www.snoize.com/MIDIMonitor), without which testing +this thing would have been a nightmare, and for answering a million of my questions. +Without his help I would have struggled over the code for a lot longer. + +Version History +------------------------------------- + +### Version 1.0.2 (???) + +* Added an icon generously provided by Kevan Staples. + +### Version 1.0.1 (13 January 2004) + +* Fixed bugs to do with handling of MIDI devices on OS X 10.3 +* Fixed a major bug with undo handling that caused deleted patches +to invisibly hang around and keep working in certain circumstances +* The default patch in an empty document will no longer use IAC bus +endpoints in order to avoid creating potential MIDI routing loops +* Text in the patch list gets an ellipsis on the end when truncated + +### Version 1.0 (1 February 2003) + +* Patch sets can be saved and loaded +* Undo works +* External device names as configured in Audio MIDI Setup are used when available +* The interface now uses tabs, is a lot more compact and allows windows to be resized +* Middle C is now displayed as C4 (rather than C5) + +### Version 0.2 (29 June 2002) + +* Virtual MIDI inputs and outputs can now be edited +* OS X 10.1.5 is now required, as this fixes a couple of MIDI bugs which were causing grief, particularly with realtime data + +* A switch to allow MIDI clock/realtime data through patches has been added +* The MIDI channel filtering controls now work +* The window now remembers its position between application restarts +* Up and down arrow keys work in the list of patches +* Patches can now be deleted +* Creating a new patch from a patch with a range filter set and an +upper note of G10 no longer causes errors + +### Version 0.1 (21 February 2002) + +* initial release + +*** + +*Copyright © 2003-2004 [Peter Yandell](mailto:pete@notahat.com).* All Rights Reserved. +