Optimizing Audio Unit User Experience in Logic Studio

Logic Studio is a powerful application suite which handles key aspects of music production ranging from composing, arranging, mixing, post production, and even on-stage performance. This document highlights a few key features of the audio unit standard that developers should pay particular attention on to ensure best user experience for their products across the entire palette of audio unit host applications in Logic Studio: Logic Pro 8, Soundtrack Pro 2, MainStage and WaveBurner.





Introduction

While code and behavior are widely shared among the applications in Logic Studio, each still specializes in certain tasks and therefore naturally provides a slightly different context in which your audio unit will live. This may make it worthwhile to thoroughly test your plug-ins across the various applications to ensure proper operation. Before turning to the Logic Studio applications though, we recommend to test your audio unit with AU Lab. Designed as the reference host for audio unit development, its Leopard version supports the majority of audio unit features described in this document.

Back to Top

Using auval

To ensure proper operation of each audio unit on a particular user system, the Logic Studio applications rely on the auval command line tool provided in Mac OS X, see Technical Note TN2204, 'Audio Unit Validation Using the auval Tool' for more information about this tool.

Each audio unit that is installed or updated will be validated and failures will be reported to the user.

Since Mac OS X 10.4, auval supports the kAudioUnitErr_Unauthorized error. When you develop a copy-protected audio unit, you use this error to distinguish an authorization failure from a validation error. The caller can then display an appropriate error message and allow for a validation retry after authorizing this copy of the plug-in.

Back to Top

Property Caching

Logic, Soundtrack Pro 2, MainStage, and WaveBurner cache certain information about the audio unit plug-ins installed in the system to speed up the launch process. This includes:

  • name, version, and ID triplet of the AU

  • status of validation with auval

  • I/O configuration capability information including kAudioUnitProperty_SupportedNumChannels, writability of kAudioUnitProperty_ElementCount, and default count & configuration of the elements, kAudioUnitProperty_SupportedChannelLayoutTags

  • The value of the kAudioUnitMigrateProperty_FromPlugin property

  • number of Carbon and Cocoa views (as determined by the size of the kAudioUnitProperty_GetUIComponentList and kAudioUnitProperty_CocoaUI properties)

If you are modifying code without increasing the version number of your audio unit, you'll need to rescan the audio unit manually in the Audio Unit Manager to make the applications recognize the changes. Alternatively, you can set an audio unit's version number to zero to force an automatic rescan at every application launch. You can use this technique while developing an audio unit, but must set an appropriate version number in the deployment build.

Back to Top

Audio Unit Views

All four audio unit host applications in Logic Studio use Cocoa to implement their interface. This means that custom Cocoa AU views will run natively in the apps, whereas custom Carbon views run inside an adaptor similar to the techniques described here: Technical Note TN2213, 'Audio Units: Embedding a Carbon View in a Cocoa Window'

Back to Top

Surround Sound

Logic Studio provides dedicated support for surround sound. If the audio processing implemented by your audio unit lends itself towards a surround-specific implementation, you should be looking into providing it in the future to enhance overall user experience.

If your audio processing doesn't use spatialization information or if it handles all channels independently, we recommend that you:

  1. Support any channel count, provided that the channel count is the same for input and output

  2. Do not support the channel layout (kAudioUnitProperty_AudioChannelLayout) property, because the audio unit does not do any semantic processing based on channel definition

Back to Top

External Control Surfaces

Logic and MainStage feature support for external control surfaces such as the Mackie Universal Pro and Euphonix MC Control/Mix and so on.

Note: While Soundtrack Pro 2 also supports control surfaces for mixing, you cannot currently edit effect parameters with a control surface.

MainStage allows for designing user-specific views for plug-ins with a limited number of parameters for easy access on stage. Both features depend on the parameters being exposed to the host via the kAudioUnitProperty_ParameterList property, so you should decide carefully which parameters to export.

When describing your exported parameters via kAudioUnitProperty_ParameterInfo, utilize the flags field of the AudioUnitParameterInfo struct to provide additional information about your parameters, such as kAudioUnitParameterFlag_NonRealTime to prevent a parameter from being automated, or kAudioUnitParameterFlag_ExpertMode to distinguish between the more important parameters and those that allow fora mere fine-tuning by advanced user. Also use kAudioUnitParameterFlag_HasClump together with kAudioUnitProperty_ParameterClumpName to group your parameters into meaningful sections.

Another important issue here is to make sure that if a parameter sets kAudioUnitParameterFlag_ValuesHaveStrings, not only should you support kAudioUnitProperty_ParameterStringFromValue (formerly known as kAudioUnitProperty_ParameterValueName) for that parameter, but also implement the reverse transformation via kAudioUnitProperty_ParameterValueFromString to allow the host application to translate user-entered text into a parameter value.

Many audio units still struggle to send proper notification whenever a parameter is changed due to user interaction in its custom UI. Please refer to Technical Note TN2104, 'Handling Audio Unit Events' to learn when and how the change notifications shall be posted according to the AU specifications.

Failure to send proper notifications will cause the automation system to not work properly (particularly when using touch mode to edit existing automation), and it can also break the settings compare button in Logic which allows to compare a modified setting against its original state.

Back to Top

Logic Studio's Audio Unit Property Reference

For your reference, here's a list of all properties used by the Logic Studio applications. Please check that you are supporting these properties as appropriate for your product.

  • I/O configuration

    kAudioUnitProperty_SupportedNumChannels
kAudioUnitProperty_ElementCount
kAudioUnitProperty_StreamFormat
kAudioUnitProperty_SupportedChannelLayoutTags
kAudioUnitProperty_AudioChannelLayout

  • Rendering

    kAudioUnitProperty_MaximumFramesPerSlice
kAudioUnitProperty_InPlaceProcessing
kAudioUnitProperty_OfflineRender
kAudioUnitProperty_SetRenderCallback
kAudioUnitProperty_HostCallbacks
kAudioUnitProperty_Latency
kAudioUnitProperty_TailTime

  • Persistence

    kAudioUnitProperty_FactoryPresets
kAudioUnitProperty_PresentPreset
kAudioUnitProperty_ClassInfo

  • Parameters

    kAudioUnitProperty_ParameterList
kAudioUnitProperty_ParameterInfo
kAudioUnitProperty_ParameterValueStrings
kAudioUnitProperty_ParameterClumpName
kAudioUnitProperty_ParameterStringFromValue
kAudioUnitProperty_ParameterValueFromString

  • User Interface

    kAudioUnitProperty_GetUIComponentList
kAudioUnitProperty_CocoaUI

  • Plug-in Migration (song import from Windows/OS 9 VST)

    kAudioUnitMigrateProperty_FromPlugin
kAudioUnitMigrateProperty_OldAutomation

  • New in Mac OS X 10.5

    kAudioUnitProperty_AUHostIdentifier
kAudioUnitProperty_ClassInfoFromDocument
kMusicDeviceProperty_DualSchedulingMode

Back to Top

Resources

Back to Top

Document Revision History

Date Notes
2009-04-23 First Version

Posted: 2009-04-23

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.