Creating Audio Unit Plugins with SuperCollider

In this post I’ll show you how to build Audio Unit Plugins programmed in SuperCollider using the AudioUnitBuilder. First of all, I want to refer to this excellent Tutorial, in which Abel Domingues explains in great detail how the whole Audio Unit architecture works and how the SuperCollider AU works. I would advise you to read this first, especially if you want detailed background knowledge. However, some things were not working for me out of the box and therefore I decided to share some problem solutions here.

My instructions were created with the following Setup:

    • Mac OS X Mountain Lion (10.8.4)
    • SuperCollider 3.5.1
    • Xcode 4.6.3 (4H1503)

Install Dependencies

First of all, the following software prerequisites need to be installed:

  1. Download and install SuperCollider 3.5.1 to a location of your choice.
  2. Download Xcode 4. This requires an Apple Developer Account. Unfortunately, the file is very large (1.7 GB). Install it and open it (make sure you don’t confuse it with your old Xcode, if you had one before)
  3. In Xcode, click on the Main Application Menu and go to Open Developer Tool -> More Developer Tools. Alternatively, you can go directly to this page. Download the Command Line Tools for Xcode and install them.
  4. Download the SuperCollider AU from here. It has to be extracted to ~/Library/Audio/Plug-Ins/Components.
  5. Open your SuperCollider and execute Quarks.gui. Install the AudioUnitBuilder Quark (you need to have an internet connection and SVN installed for that).

Adjust Paths in the AudioUnitBuilder Code

The current AudioUnitBuilder refers to some old paths, which have changed. In particular, the Rez executable is now in another location, as well as the Server Plugins. Both are now packaged into an .app Container. Open the AudioUnitBuilder Source Code (mark the classname and press Cmd+Y). Inside the file you see the classvar

1
classvar <>rez="/Developer/Tools/Rez"

which has to be changed to

1
classvar <>rez="/Applications/Xcode.app/Contents/Developer/Tools/Rez"

Next, look for the method copyPlugins (in the lower third of the class). The line

1
2
cmd = "grep  -e _"++ugens.asSequenceableCollection.join("_ -e _") + 
"_ plugins/*.scx";

must be changed to

1
2
cmd = "grep  -e _"++ugens.asSequenceableCollection.join("_ -e _") +
"_ SuperCollider.app/Contents/Resources/plugins/*.scx";

Don’t forget to recompile your library (Cmd+K) before you proceed.

Open An Example AU Specification

The AudioUnitBuilder comes with an example file called fedDelay.rtf. You find it in the Quark Installation Directory, which is ~/Application Support/SuperCollider/quarks/AudioUnitBuilder/examples. Open the file in SuperCollider.

To use the AudioUnitBuilder, you’ll need to specify the following:

  • Name of your Audio Unit
  • Component Type (\aumu, \aumx, \augn or \aufx, which stands for Instruments, Mixers, Generators or Effects, respectively)
  • Component Subtype (A four letter code identifying your plugin)
  • specs: A two-dimensional array specifying the parameters for your plugin
  • func: the function implementing the actual signal processing

Building the Audio Unit

At the end of the example file, you see the simple instructions needed to build your AU using the AudioUnitBuilder:

1
2
builder = AudioUnitBuilder.new(name, componentSubtype,func, specs, componentType);
builder.makeInstall;

Basically the things we have specified are passed in the constructor, and then the method makeInstall does the magic. Hm, but what does it do actually? It is a good idea to look into the source code to understand it. I will try to summarize it here shortly:

  1. The contents of SuperColliderAU.component are copied recursively to <yourPluginName>.component
  2. All plugins (Ugens) are deleted
  3. XML Property list files are created to configure the server running inside the AU and your plugin
  4. A Resource file is created based on a template (which is SuperColliderAU.rsrc in the quark directory). Some placeholders in that template are replaced using the sed Unix command. The resource is processed with the Rez tool delivered with Xcode.
  5. The DSP function you specified is compiled as SynthDef.
  6. The compiled SynthDef is copied to the synthdefs folder inside the AU.
  7. Plugins (UGens compiled as .scx files) needed for signal processing are copied from your SuperCollider installation to the AU.

To let the AudioUnitBuilder do all those things for you, you simply need to select the whole file and execute it. If you are lucky, you will get an output like

Created ~/Library/Audio/Plug-Ins/Components/fedDelay.component
an AudioUnitBuilder

But if something goes wrong, here are some of my solutions and debugging tips:

  • I got “Error running Rez” on the console which I traced down to an inclusion problem in the resource file. If you open  SuperColliderAU.rsrc file in a text editor, you’ll see the inclusion #include <CoreServices/CoreServices.r> which could not be resolved. The solution is to install the Xcode Command Line Tools, as described above.
  • You can debug the commands executed in the Builder by changing .systemCmd calls to .postln.systemCmd.
  • You can inspect the files created during the building process by changing mv commands to cp commands. This way all files can be reviewed in the quarks/AudioUnitBuilder directory.
  • Check the contents of the .component target file by browsing it in the Finder (right click -> Show Package Contents).
  • My working Audio Unit has a size of about 2 MB. If it is significantly smaller, that you might forgot to put the SuperColliderAU.component as skeleton AU into your Plug-Ins/Components folder.

The working AU should contain

  • Contents/MacOS/SuperColliderAU
  • Resources/plugins/(some .scx files)
  • Resources/pluginSpec.plist
  • Resources/serverConfig.plist
  • Resources/SuperColliderAU.rsrc
  • Resources/synthdefs/fedDelay.scsyndef

Alright? Then let’s validate our AudioUnit.

Audio Unit Validation

Apple developed a tool called auval to validate Audio Units. This is very useful for debugging, as you see error message from the SuperCollider server during the validation process.

Open a terminal window and execute

1
auval -v aufx FEDL SCAU

This will start the validation process for the plugin identified by a triple. The three parameters are component type, component subtype and manufacturer. Read the output if you find any error messages like “SynthDef not found”. If this is the case, then you most likely used the wrong SuperCollider version. To be compatible with the server shipped in the AU, the AudioUnitBuilder must be executed with SuperColldier 3.5.1.

Try Out Your Audio Unit

If validation passed successfully, you can use your AU in any AU-compatible audio environment. For example you can download the Audio Tools for Xcode from the Apple Developer page. It contains an App called AU Lab, which you can use to test your plugin. Here is how you insert the AU as effect:

selectAUAnd this is the generated UI to control the plugin:

fedDelayAUControlsSo this is it. I hope you got your AU running and have lots of fun coding you own AUs with SuperCollider 🙂

12 thoughts on “Creating Audio Unit Plugins with SuperCollider

  1. I’ve been trying to compile adio nits in sc3 in macosx montain lion following the steps described on yor ttorial.. with a few differences

    I was rnning 10.8 and now 10.8.5
    Mac OS X Mountain Lion (10.8.4)

    I tried both 3.5.1 and 3.6.5 with the old and new ide
    SuperCollider 3.5.1

    I am sing xcode 4.6.1
    Xcode 4.6.3 (4H1503)

    done
    Download and install SuperCollider 3.5.1 to a location of your choice.

    4.6.1 bt done
    Download Xcode 4. This requires an Apple Developer Account. Unfortunately, the file is very large (1.7 GB). Install it and open it (make sure you don’t confuse it with your old Xcode, if you had one before)

    done
    In Xcode, click on the Main Application Menu and go to Open Developer Tool -> More Developer Tools. Alternatively, you can go directly to this page. Download the Command Line Tools for Xcode and install them.

    done
    Download the SuperCollider AU from here. It has to be extracted to ~/Library/Audio/Plug-Ins/Components.

    some troble doing it via sc3.. so I did it manally.. downloaded all the qarks.. and installed them separately in each one of the sc3 versions
    Open your SuperCollider and execute Quarks.gui. Install the AudioUnitBuilder Quark (you need to have an internet connection and SVN installed for that).

    done
    The current AudioUnitBuilder refers to some old paths, which have changed. In particular, the Rez executable is now in another location, as well as the Server Plugins. Both are now packaged into an .app Container. Open the AudioUnitBuilder Source Code (mark the classname and press Cmd+Y). Inside the file you see the classvar

    when I go to compile.. no matter the version of sc3 that I se.. I get the following error message:

    Execution warning: Class ‘DOMDocument’ not found
    ERROR: Message ‘new’ not understood.
    RECEIVER:
    nil
    ARGS:
    PATH: /Library/Application Support/SuperCollider/Extensions/quarks/AudioUnitBuilder/examples/binMachine.rtf
    CALL STACK:
    DoesNotUnderstandError:reportError 0xc0882d0
    arg this =
    Nil:handleError 0xdc84430
    arg this = nil
    arg error =
    Thread:handleError 0xdcb96d0
    arg this =
    arg error =
    Object:throw 0xc29b7d0
    arg this =
    Object:doesNotUnderstand 0xc2dc9e0
    arg this = nil
    arg selector = ‘new’
    arg args = [*0]
    AudioUnitBuilder:makePluginSpec 0xdcc9180
    arg this =
    var domDoc = nil
    var plist = nil
    var dict = nil
    var paramArray = nil
    var plistFile = nil
    var source = nil
    var sourceNode = nil
    AudioUnitBuilder:init 0xd0fb150
    arg this =
    arg aName = “binMachine”
    arg aSubtype = “BIM1”
    arg aFunc =
    arg someSpecs = [*24]
    arg aType = ‘aumf’
    0xdcc17a0
    var name = “binMachine”
    var func =
    var specs = [*24]
    var componentSubtype = “BIM1″
    var builder = nil
    Interpreter:interpretPrintCmdLine 0xdcc5bc0
    arg this =
    var res = nil
    var func =
    var code = ”

    var name, func, specs, com…”
    var doc =
    Process:interpretPrintCmdLine 0xc355eb0
    arg this =
    For advice: [http://supercollider.sf.net/wiki/index.php/DoesNotUnderstandError#new]

    I gess that the problem is not with compiling the library, becase I get something like this

    empty
    compiling class library…
    NumPrimitives = 851
    compiling dir: ‘/Applications/SuperCollider/SuperCollider.app/Contents/Resources/SCClassLibrary’
    RESULT = 0
    compiling dir: ‘/Library/Application Support/SuperCollider/Extensions’
    pass 1 done
    numentries = 1036224 / 16126812 = 0.064
    6081 method selectors, 2652 classes
    method table size 8272240 bytes, big table size 64507248
    Number of Symbols 14347
    Byte Code Size 489901
    compiled 485 files in 2.18 seconds

    Info: 18 methods are currently overwritten by extensions. To see which, execute:
    MethodOverride.printAll

    compile done
    Help tree read from cache in 0.010339987999942 seconds
    Class tree inited in 0.04 seconds
    RESULT = 0
    Welcome to SuperCollider 3.5.1, type cmd-d for help

    another thing i tried to do was rnning the class, in the spercollider content sclibraryextensions, something like that.. bt it also doesn’t rn.

    the file i am trying to compile is one of the examples of the class.. please send me the class yo are rnning and tell me how can I possibly solve this..

    thanks in advance
    tiago morais morgado

    • Hi, the problem is that the XML Quark is not installed. DOMDocument is a class contained in that Quark. When this class is used at runtime only, you will not discover the error when the library is compiled. Try installing the XML Quark using Quarks.gui.

      • Sorry, for taking time to answer.

        First of all I am really appreciated for the feedback. I installed XML class in SC3, and tried to make it to compile one of the examples. I got the following error

        Error copying ~/Library/Audio/Plug-Ins/Components/SuperColliderAU.component
        Created ~/Library/Audio/Plug-Ins/Components/binMachine.component
        an AudioUnitBuilder

        I first had the idea that there was a possibility that the fact that I had a PT operative system cold setting problems in the path. In fact, I have the version indicated in the article above of this specific component.. Even bearing this in mind I cannot make that compile. I get the indicated error. And the compiled component is not created contrary to what was excepted. if yo have an idea of what might be wrong I deeply appreciate that feedback. thanks in advance

  2. Hello David,
    Thanks for your great tutorial on building AU plugins …
    All very nice and clear, except I am getting the same “Error running Rez an AudioUnitBuilder” tho I already have Xcode command line tools installed.

    I actually ran through these instructions first in SC 3.6 and the component built (suggesting cmdln tools worked fine) – tho SynthDef not found, as you point out.

    Could you elucidate what the #include you mention means? Trying to think of other reasons that Rez might not work …

    Many thanks for this great work.

    Alice

  3. Hey,
    Great tutorial! With some struggling I got one the examples build. But if I load it into logic the sound passes the plugin but no processing is happening. Did you heard of this problem?

    Kind Regards,

    Sipke

    • Hi Sipke, did you use the exact SuperCollider version as indicated? It should be SuperCollider 3.5.1. With newer versions it will not work properly since they are not compatible with the skeleton AU.

  4. I’m running OS 10.10

    I’ve been trying to make this example work, and here is what I’ve found:

    1) SuperCollider builds the component as a 32-bit AU. So as apple is dropping support for 32-bit AUs it’s going to be bad.
    2) auval-tool now scans for 64-bit AUs by default, so you have to put an extra argument: auval -32 -v aufx FEDL SCAU
    3) Even after using auval i couldn’t see the component in AU Lab (ver 2.3.1), which indicates that it no longer supports 32-bit AUs.

    Is it possible for superCollider to build a 64-bit AU?
    If not, i guess that’s going to be the end of AUBuilder for superCollider eventually.

Leave a Reply

Your email address will not be published. Required fields are marked *