Audio-Unit-V3-Templates
A collection of templates for creating Audio Unit V3 in Xcode
About
This repository aims to collect together templates for creating Audio Unit v3 Plug-ins. Apple's API, though powerful, is nebulous at best and for the novice DSP engineer it is a bit much to take on. Apple's sample code and tutorial left me wanting, so here are a couple of complete Xcode projects to help you get started.
Each template listed will gradually include greater and greater complexity. A README can be found in each template folder
but here is a rough guide to get you started.
Apple Sample Code
To save time traipsing around the Apple Sample Code Archive, here are the links too available sample code for AUv2 and AUv3 code.
-
Creating Custom Audio Effects: AUv3 and macOS 10.15 only. An entirely swift approach.
-
Audio Unit Examples (AudioUnit Effect, Generator, Instrument, MIDI Processor and Offline)
Contributing
See Contributing documentation
Templates
AudioUnit V3 Template Basic
A bare bones template: Audio comes in, Audio Goes out. The DSP kernel is where you will want to focus your attention.
The process method of the DSPKernel class is where the sample by sample processing takes place (DSPKernel.hpp line 54).
You can ignore everything else for now
AudioUnitV3TemplateWithParameters
Exactly as it says, this is a template that includes a GUI slider object and a gain parameter. Adding in more should be a simple case of replicating the process of initiating and single parameter. There are some extra classes to pay attention to in this template
templateAUfxWithParametersAudioUnit.mm
This objective C class is what communicates with the DAW environment. The initWithComponentDescription method is where
the pointers to parameter values are set. Line 80 is a good place to start. There are a lot of pointers flying around
which does not help in comprehending the logic.
AudioUnitViewController.swift
This file is where you should head for any GUI work. GUI Elements (or "Views" in Apple parlance) can be added via the AudioUnitViewController.xib file. It is highly recommended you start off with a simple Swift based GUI project before delving into this. There are enough headaches to be had in Xcode and Swift without adding in a whole audio processing framework on top.
Troubleshooting
Common issues I have come across when building audio units.
Sanity check with the auval terminal command
Audio Unit is not visible after building
Take a look at the info.plist file, an XML file of info about your Audio Unit Try changing the 4 letter code. Try altering the manufacturer code as well.
Build Errors
'vector' file not found""_OBJC_CLASS_$_AVAudioFormat", referenced from:""_OBJC_CLASS_$_AVAudioPCMBuffer", referenced from:linker command failed with exit code 1 (use -v to see invocation)
Any of the above? Sounds like you have forgotten to link a library, most probably AVFoundation.
or your AudioUnit ObjectiveC++ file has the wrong extension. Change it to .mm
How do I install once I have built the AUv3?
AUv3s are a part of the PluginKit Eco system and information about it is pretty thin on the ground. Basically you will need to run your .app with the embedded .appex before it is registered by PluginKit. You can check your app is registered by
- Running
auval -ain Terminal and looking for your plugin.auval -a | grep FOUR_CHARACTER_MANU_CODEcan also help for big lists - Running
pluginkit -min Terminal and looking for your.appex's bundle identifier
Is there a nicer way to install it?
Not really, run the .app and your done. PluginKit applies to any embedded .appex so this method of installation makes sense for those, but is perhaps a little unusual to what audio plug-in users expect.
What can I do with my appex file?
Not much, your app needs something to embed in the first place. You can always import it into another xcode project. By itself, the appex is useless and you need to embed it in an app.
Building AUv3s with JUCE
Using JUCE to make an AUv3? See my post on Troubleshooting AUv3s on the Juce forums.
Links
References
Here are a couple of links to check out along your AUv3 travels
- Audio Units (AUv3) MIDI extension – Part 2: C++
- Mixing Objective-C, C++ and Objective-C++: an Updated Summary
- Brain Dump: v3 Audio Units
Suggestions are welcome for other helpful articles.
Github Repositories
Here is a selection of GitHub Repos that I found useful when making these templates.
You can also search GitHub by tag, so have a look at #auv3, #audio-units, #audio-unit, #audiounit for more examples.