2.x-3.x Migration Guide

Along with a variety of workflow improvements including launching into the background, the main new addition in Audiobus 3 is MIDI routing.

You can now send, filter and receive MIDI just like you can with audio, using the three new classes:

Here's what you need to do to update your existing Audiobus 2 integration to Audiobus 3.

1. Replace Audiobus 2 SDK

First you need to download the Audiobus 3 SDK. Simply replace the previous Audiobus 2 SDK with the new one.

Additionally you need to link libz.tbd to your project, from your app target's "Link Binary With Libraries" build phase.

2. Rename ABSenderPort, ABFilterPort and ABReceiverPort

Audiobus 3 clearly distinguishes between audio and MIDI ports. Therefore you need to rename all occurrences of ABSenderPort, ABFilterPort and ABReceiverPort to ABAudioSenderPort, ABAudioFilterPort and ABAudioReceiverPort, respectively.

If you want to save time, the migrateAudiobus3.py script (also contained in the Audiobus SDK folder) will perform all required renaming for you. Here's how to use it:

  1. Make a backup of your current source folder
  2. Open the Terminal application
  3. Change into the folder containing migrateAudiobus3.py (e.g. the Audiobus 3 SDK folder)
  4. Enter python migrateAudiobus3.py YOURSOURCEFOLDER
  5. Compile and check for errors

3. Create A New Version On The Audiobus Registry

To ease the integration of the Audiobus SDK we have introduced a new API key format. With the help of the new API key we are now able to check if the ports declared in your app match the ports declared in the Audiobus registry. If this is not the case a detailed error message is printed to the console, helping you to identify and fix the issue as quickly as possible. To update the API key of your app please follow these steps:

  1. Increase the version number of the Audio Components in your app's Info.plist file.
  2. Open the Audiobus Developer Center, and open your app's registration there.
  3. Scroll down and click the green "Add Version" button.
  4. Access the compiled version of your app's Info.plist:
    1. Build your app, and find the built version in the "Products" area within Xcode.
    2. Right-click your app, and select "Show in Finder".
    3. Right-click your app in Finder, and select "Show Package Contents". Find Info.plist within this folder.
  5. Drag and drop your app's compiled Info.plist file in the field provided for it on the Audiobus Developer Center.
  6. Press "Submit".
  7. You will receive a new API key. Instantiate ABAudiobusController with that new key.
  8. Run your app and check the console output for any error messages.

4. Disable Core MIDI when Necessary

If your app interacts with Core MIDI directly, then it's important that you disable any Core MIDI functionality in your app when connected to Audiobus. This will prevent your app from receiving Core MIDI events twice, once via Audiobus and once from the Core MIDI system itself.

Please read and implement the chapter Disable Core MIDI in the MIDI guide. Audiobus will tell you when to enable and disable sending and receiving Core MIDI.

5. Hide Inter-App Audio Transport Panel

If your app shows an Inter-App Audio transport panel, you will need to hide it while participating in an Audiobus session. See Show and hide Inter-App Audio Transport Panel in the audio integration guide for more info.

6. Inter-App Audio Hosts: Do not show Audiobus' hidden sender ports

Audiobus provides a number of hidden intermediate sender ports. These ports are only used internally by the Audiobus SDK. If your app is an Inter-App Audio host you should hide these ports in the list of available Inter-App Audio nodes. For more information read the section entitled If your app is an IAA host, do not show Audiobus' hidden sender ports in the audio integration guide.

7. Hosts, Audiobus 2 and Audiobus 3 behave differently

There are some important differences between the way inputs and filters are connected to outputs. If your app offers an ABAudioReceiverPort, please read the chapter Differences between Audiobus 2 and Audiobus 3.