Audiobus provides a system where apps can define actions that can be triggered by users from other apps, via the Audiobus Connection Panel or from within Audiobus Remote.
You can use a set of built-in system triggers (see triggerWithSystemType:block: and ABTriggerSystemType), or create your own.
Use of Triggers
Triggers are designed to provide limited remote-control functionality over Audiobus apps. If your app has functions that may be usefully activated from a connected app, then you should expose them using the Audiobus triggers mechanism.
Triggers can appear within the Audiobus Connection Panel, or within Audiobus Remote running on another device, depending on how they are added. Use ABAudiobusController's addTrigger: method to add Connection Panel triggers, and addRemoteTrigger: to add Audiobus Remote triggers.
Apps should only provide a small number of Connection Panel triggers - no more than four - to avoid cluttering up the Audiobus Connection Panel interface. Remote Triggers may be more numerous, due to the extra available screen space within Audiobus Remote.
Your app should only provide triggers that are relevant to the current state. Take, for example, an app that has the capability of behaving as an Audiobus input and an output. If the app presents a "Record" trigger, but is currently acting as an input to another Audiobus app, this may lead to confusion: the app is serving in an audio generation role, not an audio consumption role, and consequently a "Record" function is not relevant to the current state.
You can add and remove triggers at any time, so you should make use of this functionality to only offer users relevant actions.
Creating a Trigger
Whenever possible, you should use a built-in trigger type, accessible via triggerWithSystemType:block: .
If you must create a custom trigger, then you can create a button trigger with ABButtonTrigger's buttonTriggerWithTitle:icon:block: .
Note that icons should be an image of no greater than 80x80 pixels, and will be used as a mask to draw a styled button. If you do not provide 'selected' or 'alternate' state icons or colours for a toggle button, then the same icon will be drawn with a default style to indicate the state change.
When you create a trigger, you provide a block to perform when the trigger is activated remotely. The block accepts two arguments: the trigger, and a set of your app's ports to which the app from which the trigger was activated is connected. This port set will typically be just one port, but may be multiple ports.
You may wish to use the ports set to determine what elements within your app to apply the result of the trigger to. For example, if your trigger is ABTriggerTypeRecordToggle, and the connected port refers to one track of a multi-track recording app, then you may wish to begin recording this track.
If you are implementing a two-state trigger, such as ABTriggerTypeRecordToggle, ABTriggerTypePlayToggle or a custom trigger with multiple states, you should update the trigger state as appropriate, when the state to which it refers changes.
Note that you can also update the icon of custom triggers at any time. The user interface across all connected devices and apps will be updated accordingly.
Have a look at the Trigger recipe and the "AB Receiver" and "AB Filter" sample apps for examples.
System triggers are automatically ordered as follows: ABTriggerTypeRewind, ABTriggerTypePlayToggle, ABTriggerTypeRecordToggle.
Remote Triggers
Audiobus Remote supports a new class of trigger which allows you to define extended functionality, without cluttering up the Audiobus Connection Panel.
When you add a trigger via ABAudiobusController's addRemoteTrigger: method, the trigger will appear only within Audiobus Remote.
You may listen for particular control events (UIControlEventTouchDown and UIControlEventTouchUpInside) by registering a block using each trigger's addBlock:forRemoteControlEvents: method.
Use these facilities for providing access to extra functions in your app, such as:
- Individually toggling tracks or triggering samples,
- Switching between patches,
- Jumping to particular time offsets in a track,
- Manipulating effect parameters,
- Playing chords
You may also define a matrix of triggers using addRemoteTriggerMatrix:rows:cols: , which suits uses such as drum sample pads. Use these sparingly, however, as Audiobus Remote is able to make better use of available screen space with triggers added via addRemoteTrigger: instead.
See the "AB Sender" sample app for a demo implementation of Remote Triggers in a matrix.