MidiBridge is a tool that allows you to interconnect all MIDI inputs and outputs and manage MIDI event streams on your iOS device. Use MidiBridge to:

• Connect your external MIDI interface (Line6 Midi Mobilizer, IK Multimedia iRig MIDI, Akai SynthStation 25 or iOS supported USB MIDI device) wirelessly over wi-fi to a computer or iOS device that supports CoreMIDI networking.
• Interconnect any of the above with other apps that support virtual CoreMIDI.
• Filter events separately on each input and output.
• Clone events from an input to multiple outputs.
• Split events from an input to multiple outputs.
• Merge events from multiple inputs to one or more outputs.
• Transform events (remapping, keyboard split, velocity scale) on any input or output.
• Microtune events from H-Pi keyboards.
• Manage user defined scenes.
• Issue program changes manually or in conjunction with scenes.
• Define complex event transformations like overlapping splits or multiple note/controller zones.

IMPORTANT - before you dive into using MidiBridge please, please read the following section that explains how to connect inputs to outputs. Also, please take note that for best latency and throughput you will probably want to disable event visualisation (details here) after setting up.

MidiBridge has 5 tabs at the bottom of the screen:

	Interfaces, which shows all the MIDI ports in the system and is where you connect inputs to outputs and set port filters and names.
	Scenes, which allows you to define and recall MidiBridge configurations from the application or via MIDI program change message.
	Preferences, which allows you to configure options and connect to CoreMIDI wireless hosts.
	Applications, which allows you fast switch to other MIDI/audio applications if installed, or explore other fast-switchable/CoreMIDI apps that may be of interest.
	Instructions, your user guide - which you are now reading.

• Understanding MidiBridge
• Understanding MidiBridge Modules
• Understanding Scenes
• Understanding the Stream Byter

     Interfaces

On the interfaces tab, you will find a set of MIDI inputs and outputs that have been detected by the app. Inputs are on the left and outputs are on the right. If your iOS device is running iOS version 4.2 or greater then you will have CoreMIDI support. CoreMIDI network inputs and outputs have a wi-fi symbol embedded in them for easy identification. CoreMidi virtual inputs and outputs have a virtual cable logo embedded in them also. When the app starts, network CoreMIDI is enabled to permit incoming connections from other hosts.

Each port (input or output) has three touchable areas:

To connect inputs to outputs you do the following:

1. Choose an input that you wish to connect from. It will change to a green colour to show it has been selected.
2. Now touch one or more outputs to connect that output to the currently selected input. A green line from the input to the output will be shown to indicate that the two are connected.
3. Touch the orignally selected input (or another input) to deselect that input.

The same procedure works in reverse if you wish to select an output and connect a number of inputs to it. To break a connection you simply repeat the above on a pair of inputs and outputs that are already connected.

Also, when you select a port, all connections to that port are highlighted, so, if you want to see which ports an input or output is connected to you just touch that port. Remember to touch it again to deselect it.

When MIDI events pass through a port (received on an input or sent from an output), the port will flash briefly. The flashing can be disabled from the Preferences window.

MidiBridge keeps track of the MIDI interfaces it sees and the connections made between them and will restore any connections that were made previously.

Where a port has a double-tap icon , then double-tapping that port will fast-switch to that running application.

Naming of ports

Port Modules

To access the module menu of a port, simply touch the button.

The module menu lists all modules for that input or output in the order in which they will process events. Each module lists its name, a description of what it does (in yellow) or the name of any preset loaded (green/red) for that module. A module is active if it has a tick in the left tickbox; touch the module to engage or bypass a module. To configure a module, press its accessory disclosure button.

The modules available in this version of MidiBridge are:

• Event Filter - block/allow filtering of events. There is one of these at the start of each module chain and another separate one at the end.
• Stream Byter - create user defined rules for matching and transforming any MIDI message (except sysex)
• Program Changer - issue program change messages from MidiBridge either manually or via scene change.
• Note Mapper - remap any MIDI note to any other and transpose MIDI notes
• Note Splitter - Keyboard split across channels
• H-Pi Microtuner - Support for H-Pi keyboards (on input ports only)
• Velocity Curve - Velocity scaling
• Velocity Splitter - Velocity split across channels
• Holy Mapper - Allows the interdependent mapping of controllers and channels.

When one or more modules is enabled on a port, then a badge 'On' is displayed on the port on the Interfaces page to remind you that the port has active modules. In addition, if any module blocks an event, then this badge will flash (instead of the port) to show you an event was received but was not passed on.

Module Presets

At the top of every module's configuration panel is an expandable/collapsable picker for managing preset configurations of that module - ie. presets.

Use the 'On' and 'Bypass' buttons to enable or bypass the module.

Use the small white down-arrow to expand the panel to load factory or user saved presets for that module. The arrow changes to an up-arrow when the picker is expanded. Touch this to collapse the picker again.

If a preset is loaded, its name will appear under the 'Current Preset' label. If the preset name is in green, then the configuration of the module has not been modified since the preset was loaded. If the name is in red, then the module's configuration has been changed from the preset. If no preset is loaded, then a message inviting you to expand the picker to manage presets is displayed instead.

Once the picker is expanded you can now load an existing preset by selecting it with the wheel and pressing the 'Load' button. This will automatically enable the module if necessary.

A special preset '-- Reset --' is also available. Loading this preset will set the module to a default factory state (and bypassed).

To save the current module configuration to a preset that you can reload into the module again, press ther 'Save' button and you will be prompted to name your new preset. If a preset is already loaded, then that preset's name will be pre-populated in the preset name field for you. If you save to a pre-existing preset name, then the old preset will be overwritten with the current configuration.

To delete a preset, select it in the picker and then hold down the 'Save' button for about 3 seconds and then release the button.

Event Filter

The Event Filter module allows you to filter out (or in) certain types of MIDI events from passing through the module.

Note! When a filter is activated for the first time, the default setting is to block no events (pass-thru)

This section describes each control and how it affects the module:

• Mode

  The filter operates in one of two modes:

  Allow mode specifies that events which match the event types/channels specified below are used. All events that do not match the event types/channel matrix settings will be ignored. This type of filter is generally used to focus in on a particular type of event stream.

  Block mode specifies that all events received are allowed unless they match the event types/channel matrix settings. This type of filter is generally used to exclude unwanted events from the capture/midi thru.

• Drum Remap (deprecated in 1.4)

  This option is no longer present in this version of MidiBridge. Instead, you use the Note Splitter module (a preset mapping channel 10 to 1 is included as a factory preset) to remap channel 10 to another channel for use in apps like Sample Tank.

• Channel Matrix

  The channel matrix (shown below) allows you to choose the channels that are to be used in the filtering process. You select/deselect channels by touching them. In itself the channel matrix does not specify the events to filter, but is used in conjunction with the Event Type switches described in the next section.

  
  
• Event Type On/Off

  Below the channel matrix are the event types that can be used by the filter. The event types that can be filtered are as follows:

  • Note On/Off - Note On, Note Off messages
  • Aftertouch - Channel pressure, Aftertouch messages
  • Controller - Channel Controller, Pitchwheel messages
  • Program Change - Program Change messages
  • Sysex - System Exclusive messages
  • Time/Song - MIDI Time Code, Song Position/Select messages

  Touch each of these event type buttons to toggle their inclusion (or not) in the filter.

  In addition, note, aftertouch, controller and program change event types can be also checked against the channel matrix by toggling the mini channel matrix button to the right of each of these types.

  If the matrix button for an event type is not selected then all channels for that event type are included in the filter.

  

  By way of example, the above two pictures show that Note On/Off messages are to be included in the (Allow) filter and that only those note on/off events that are sent on the channel specified in the channel matrix (1 and 2) will be considered. Aftertouch messages will not be considered at all.

Event Filters can be used to split events from one input into multiple outputs. Simply connect the input to the outputs and then set an 'allow' filter on each output (or block filter) to allow only the desired channels for that output to be forwarded.

With keyboard controllers (or other devices) that send active sense messages, you may find that blocking TimeSong events on that input (and thus filtering out active sense) will improve performance.

Stream Byter new in 1.5

In response to the many varied requests we get for unusual event transformations, we have developed this module to give users unparalleled flexibility. Some of the things you can do with the Stream Byter are:

• Map any MIDI event to any other MIDI event (not sysex) including type, channel and value.
• Create up to 128 non-contiguous zones per channel.
• Create overlapping zones.
• Split controller messages into channelised zones.
• Use note events to change MidiBridge scenes.
• More precise blocking of events than the event filter.

This is hardly an exhaustive list, but with flexibility comes some complexity, and to use the Stream Byter you do need an understanding of the MIDI protocol, but fear not, as because it is possible to paste rules from an email, we can help by designing rulesets for what you are trying to achieve and email them to you.

We have also produced a detailed tutorial for creating Stream Byter rulesets (on our website) and you can also post queries about this (and of course anything MidiBridge related) on our support forum, again, see our website.

The Stream Byter panel contains an editable text window for you to define rules to match and act on MIDI events. One rule per line is permitted and you can comment your rules by preceding your commentary with a '#' symbol.

Once you have entered your rules, you press the 'Install Rules' button which checks your rules for validity. If any rules are incorrect, these are marked with 'ERR' and are commented out. To fix a rule with an error, simply edit the line (no need to remove the '#ERR' part!) and press the 'Install Rules' button to try again.

Each rule consiste of two clauses, separated by one '=' sign.

The clause to the left of the '=' is the input clause where you specify which MIDI events are to be considered.

The clause to the right of the '=' is the output clause where you specify what happens to an event when it matches the input clause.

You can also specify flags at the end of the output clause:

• +C - clone the incoming message and apply the output clause to the clone.
• +B - block the incoming message if it matches the input clause

Both input and output clauses are constructed by 1,2 or 3 separate hex bytes depending upon the nature of the rule. Here are some simple examples:

You can also specify wildcards and ranges in the incoming clause:

• The value 'N' in the first nibble of the first byte represents note on and note offs (ie. 8 or 9)
• The value 'X' in the first nibble of the first byte represents all event types.
• The value 'X' in the second nibble of the first byte represents any channel.
• The value 'XX' for the second or third bytes represent any value (00-7F)

Here are some examples of wildcards:

You'll note that you can use 'X' and 'XX' wildcards in the output clause. This signifies that the incoming corresponding value of the event is to be preserved.

You can specify ranges of values using the '-' sign inbetween low and high values. Examples:

These examples are quite simple and are to provide a foundation for writing more useful real-world rules. Again, please do look at our tutorial, post to our forum or email us if you would like help in creating custom rules for your requirements. There is no doubt that this module is not for the beginner.

Finally, some caveats to be aware of when writing rules:

• Rules are evaluated top to bottom and the results of each rule are fed into the next (unless the clone flag is set).
• sysex messages are not supported.

Program Changer new in 1.5

The Program Changer module allows you to issue Program Change messages on a per-channel basis. You can issue changes manually or have all program changes stored issued automatically on a scene change.

All 16 MIDI channels are listed separately and you setup which program change message (0-127/off) will be transmitted on each channel.

To send a program change message manually, press the '>>>' button for the corresponding channel.

However, where the Program Changer becomes more useful is when it is used in conjunction with the scenes feature. By saving all your program changes in a scene, when that scene is recalled, the program changes will get issued immediately. That way, you can have external modules or apps (that honour program change messages) be configured to the desired preset for the particular scene.

Be aware that program change messages are issued directly and do not pass through any modules.

Note Mapper

The Note Mapper module remaps any MIDI note event to a different note event. This module can be used to remap drum machines/instruments to different notes that might be expected by another device or app, for example an XG drum set to Nanostudio's TRG. Additionally, you can use this module to transpose all notes (NB. after they have been mapped) up or down a number of semitones.

Note Mapper and many other modules allow you to select values using a 'selector' widget:

The minus button decrements the value in the grey box, and the plus button increments this value. You can also enter a value via the keyboard by touching the grey area.

To remap one MIDI note to another, you first select the incoming MIDI note you wish to map using the left selector widget. You then use the right selector widget to select the note that the incoming note should be remapped to. Repeat this for as many mappings as you need.

The number in the selector widgets for note numbers refers to the decimal MIDI notes ranging from 0 to 127. The note name (starting from C-2 for note 0 and ascending to G8 for 127) is shown above the selector widget.

To add global transposition of notes passing through this module use the Note Transpose selector widget to set a transpose value in semitones.

At the bottom of the screen is an out/in indicator matrix which provides an overall picture of the current mappings. If a note is remapped then a red bar on the 'In' axis corresponding to the Out value on the Out axis is displayed. If no mapping takes place for a note, then the bar is green. This graphic is an indicator only. Touching it has no effect.

Note Splitter

The Note Splitter module allows you to define a keyboard split point (note based) and then have notes that fall on the lower split be mapped to one MIDI channel while notes on the upper split can be mapped to a different channel.

You set the split point by using the Split Point selector widget or touching the keyboard at the bottom of the panel:

The lower split is marked in green on the keyboard and the upper split is marked in red. The lower split includes the note at the split point. If you set the split point to zero, then the lower split is disabled entirely and only the upper split is in effect. This setting is used when you want to remap all notes to a particular channel.

For both the lower and upper splits you set the desired MIDI channel using the two selector widgets. You may also select 'off' as the MIDI channel for a split, in which case the note is blocked and not passed

H-Pi Microtuner

The controls are as follows:

• MIDI Channel Engage/Disengage - retuned notes are sent to multiple channels in a round-robin fashion. To remove a MIDI channel from the pool of output channels, touch the relevant channel number so it is grey in colour and no notes will be sent on that channel. The most common use is to eliminate channel 10 (drum sounds).
• Note Stealing - the maximum polyphony of retuned notes is the number of engaged channels (above). If the polyphony is exceeded, the note stealing option tells MidiBridge how to handle the situation. If this option is 'On', then the least recently played note will turn off and the new note will take its place. If set to 'Off' then when polyphony is exhausted no new notes will sound until already held notes are released.
• Note Velocity - This sets the velocity of all outgoing notes to a fixed level. If this is set to zero, then the velocity of the original note is used.

The 'Init Pitchbend' button sends pitchbend initialisation messages on all engaged channels to all connected interfaces. This action sets the pitch bend range to one semitone. Note, this initialisation also occurs when a new device is connected/seen or if you navigate away from the H-Pi Microtuner panel.

Velocity Curve

The Velocity Curve module allows you to apply scaling of the note velocities as they pass through the module.

You can draw using your finger a curve or line on the plot to set a curve, and then use the selector widgets to refine your curve. In essence, the module maps the velocity of a note to a different velocity based on the incoming velocity.

Velocity values are specified in MIDI decimal values from 1 to 127 (as velocity zero means note off)

Velocity Splitter

The Velocity Splitter operates in a similar fashion to the Note Splitter, but the velocity of the note determines the destination channel.

You can specify a split point using the top selector widget or touch the green/red area to set the velocity split point.

Notes less than the split point velocity will be sent to the channel specified in the Lower Split selector while notes higher than the split point will send to the Upper Split channel.

Here also, you may also select 'off' as the MIDI channel for a split, in which case the note is blocked and not passed

Holy Mapper

Not a religious reference but named after the customer who suggested this, the Holy Mapper maps controllers and channels interdependently.

In other words you can map controller X on channel Y to controller X1 on channel Y1.

Simply use the left selector widgets to select the incoming controller/channel combination you wish to map and then adjust the corresponding output controller and channel to suit.

App Selector

This module allows you to bind incoming MIDI messages that will cause a fast-switch to an OMAC compliant app. While MidiBridge is running in the background, if it sees an incoming message on the port that is configured with this module, it initiates a switch to the selected app. For this to work, the current app in the foreground must have implemented the latest OMAC fast-switch features. All of Audeonic's MIDI apps are fully compliant. Fully compliant apps are marked with an asterisk. As more devs implement the updated OMAC switching, more apps will get the stars. If you do switch to an app that is not starred, then the initial switch to that app will work, but further MIDI switches will no longer be possible until a fully compliant app is switched into the foreground manually.

To use this, first you need to know the MIDI messages that your device sends for the key/button that you want to use. We suggest MidiVision as a suitable candidate for capturing the MIDI messages. You then select the app (or next/prev - bit more about that in a moment) and enter in the MIDI message in spaced hex byte format (just like MidiVision spits out). Now, when MidiBridge receives that specific message it will cause a fast-switch to the selected app.

The Next/Previous entries in the picker wheel are special in that they are not apps, but will cause a cycle between all the apps that have MIDI messages configured in the order the messages were configured (or reverse order). ie. Specify a message for the first app you want to appear in the cycle, then the next and so on until the last.

Some sample presets for switching between Audeonic's apps are included as factory presets:

• Audeonic Synthstation 25 - pressing buttons Synth 1-3 select MidiBridge, MidiVision and FreEWI. Pressing the Prev/Next buttons cycle through the apps.
• Audeonic Oxygen 49 - pressing buttons C18-C20 select MidiBridge, MidiVision and FreEWI. Pressing the C21/22 buttons cycle through the apps.
• Audeonic TouchOSC - you can download the template for TouchOSC from the Audeonic site. The template has separate buttons for our apps as well as Next/Prev buttons

We will have updated our 'Understanding MidiBridge Modules' guide at the Audeonic website by the time you read this, which will provide more detailed information and some extra examples.

CoreMIDI Wireless Networking

One of the core features of MidiBridge is the ability to connect externally connected MIDI devices to remote CoreMIDI hosts via wi-fi from your iOS device. Here are some important things you should know:

• When MidiBridge starts, it allows incoming connections from any host on UDP port 5004 on the local network. You can initiate a CoreMIDI network connection from a Mac, PC (with appropriate software) or another iOS device running a CoreMIDI supported app (or even another MidiBridge app to interconnect two MIDI devices wirelessly).

• Your iOS device can be connected to more than one remote host at the same time. In which case, all MIDI events from any networked host will be received by MidiBridge and all networked hosts will receive events sent to the network output.

• MidiBridge can initiate one network connection to another host (see Preferences)

• When one or more remote hosts are connected, the port wi-fi icon will be highlighted yellow and the badge on the Interfaces tab bar will show the total number of remote hosts connected to your device.

Also, there is (currently) no logic for dealing with held notes, so if notes are being held to a connected output and that output is broken on scene change then you will get stuck notes.

• Enable/Disable Inputs (default: All enabled)

  Pressing this button will bring up a separate panel from where you can choose to have MidiBridge disable or enable any of the input ports detected in your device. If an input is disabled, no events will be processed from that input and the input port on the Interfaces tab will be darkened.

• Jitter/Sync Latency (default: 0 ms)

  With a value of zero, MidiBridge will pass an event to the routed outputs as fast as possible and it is best to use this value when playing live. However, for sequences or time based traffic, increasing this value (250ms works well) will delay the event and tell the system to play the event at the relative time at which it was received on each input and thus syncing the event streams without any jitter.

• Run in Background (default: 15 minutes)

  If this option is set to a positive value, then MidiBridge will continue processing MIDI when the app is backgrounded. Naturally, this can reduce battery life if there are many apps running. Note, that if no MIDI data is received for the specified time, MidiBridge will suspend (and inform you via notification) to preserve battery life. Setting this option to zero will disable backgrounding entirely and MidiBridge will exit upon a press of the Home button.

  Background processing of MIDI data on the original Line6 Midi Mobilizer and the Akai Synthstation 25 only works with iOS5. Previous versions of iOS will disconnect the accessory when an app is backgrounded. Note that MidiBridge will remain in the background indefinitely if the iDevice is not on battery power (ie. being charged)

• Visual Events (default: On)

  Switching this on will cause ports (or filter badges) to flash briefly as event data is processed. Turn this off to gain more performance and reduced latency.

• Scene Channel (default: All)

  This is the MIDI channel (or omni/off) that MidiBridge will react to by changing scenes when a MIDI program change message is received on any of MidiBridge's enabled input ports. Setting to 'off' will disable scene changes via MIDI message entirely.

---

     Applications

The Applications page (or floating panel on the iPad) allows you to fast switch to installed apps or explore virtual MIDI compatible apps that are known to work well with MidiBridge.

Touching an installed app (app has a tick in the box) will launch that app or fast-switch to that app if it is already running.

If an app is not installed, then you can explore details about that app by touching it. If it has a video showing its use you will be able to view that also and subsequently view the app in the App Store. If the app has no video, then touching the app will allow you to view it in the App Store directly.

On the iPad you can drag the floating panel anywhere on the screen that suits.

Known limitations and issues

This section describes some of the known issues and limitations of MidiBridge.

Sysex with CoreMIDI Network/Virtual - Currently individual SysEx messages greater than 1010 bytes are truncated/lost when sent to a CoreMIDI network or virtual output. Similarly, any sysex message greater than 256 bytes received by a CoreMIDI network or virtual input is truncated. In both of these cases MidiBridge discards the (now useless) truncated data and warns you it has had to do this via a 'once-per-session' dialog. This is an Apple iOS issue (presumably the iOS CoreMIDI network driver has a bug).

Akai Synthstation support - Both the inbuilt keyboard and the external MIDI interface are available in MidiBridge as two seperate port pairs. Connecting the keyboard input port to the external output port will result in doubled up notes.

Also, the SynthStation25 does not have the ability to timestamp and schedule events, so the jitter/sync option is not applicable with the SynthStation25 and events will be passed on as quickly as possible if you are sending output to the SynthStation25 external interface.

Memory Usage - Usually when MidiBridge runs, it uses about 12Mb of memory on the device. However, this can increase if the user accesses module configurations, as the app needs to load in the views to support these.

If memory is at a premium, it is suggested that once the modules are configured, you press the home button to send MidiBridge to the background and then terminate it using the double-tap on home task manager. Restart MidiBridge and it will revert to the configuration it had prior to being terminated but only use 12Mb of memory.

Other Audeonic Apps

We'd like to mention our other iOS apps which may be of interest to you. Touch the app icon to view in the App Store

MidiVision

A MIDI event monitor with colour-coded messages, filtering and midi-thru.

Sponsored by

Finally, Thanks To

Rick Dangerous of Phongemeinschaft who started the ball rolling by suggesting an enhancement to MidiVision to allow him to play wirelessly using an iPod.

Line6 Midi Mobilizer Team

Akai Professional

IK Multimedia

Aaron Hunt for all his help with H-Pi Instruments support. See H-Pi Instruments for details on these extraordinary keyboards.

The Velocity curves were created by Breeze: he suggests you use these as examples and starting points for your own.

Sean from iosmusician.com for suggesting switching apps via MIDI messages.

Tab bar icons by Joseph Wain www.glyphish.com, used under Creative Commons Attribution 3.0 United States License.

You, for downloading (and presumably purchasing) this application. We hope it will be useful to you. Please do take time to review it in the App Store for others. If you have any suggestions for improvements, have found bugs, want to vent your spleen or even need an app developer, please contact us at apps@audeonic.com or visit www.audeonic.com.

---

HTML handcrafted in vi by Audeonic Apps in Dublin, Ireland
Version 1.5 © 2013 Audeonic Apps