Overview

“Simple” effect units operate on individual audio samples without considering one audio sample’s relationship to another, and without using a processing buffer. You build such an effect unit in this chapter, further simplified by leaving out some advanced audio unit features: a custom view and custom properties.

Simple effect units can do very basic DSP, such as:

• Change level

• Add tremolo

Monaural tremolo is a continuous wavering produced by varying an audio channel’s gain at low frequency, on the order of a few Hertz. This figure illustrates monaural tremolo that varies from full gain to silence:

Stereo tremolo is similar but involves continuous left/right panning at a low frequency.

In this chapter you design and build a monaural tremolo effect that uses the generic view. The steps, described in detail in the following sections, are:

1. Install the Core Audio development kit if you haven't already done so.

2. Perform some design work, including:

   • Specify the sort of DSP your audio unit will perform

   • Design the parameter interface

   • Design the factory preset interface

   • Determine the configuration information for your audio unit bundle, such as the subtype and manufacturer codes, and the version number

3. Create and configure the Xcode project.

4. Implement your audio unit:

   • Implement the parameter and preset interfaces.

   • Implement signal processing—the heart of your audio unit.

5. Finally, validate and test your audio unit.

Your development environment for building any audio unit—simple or otherwise—should include the pieces described under Required Tools for Audio Unit Development in the Introduction. You do not need to refer to the Xcode documentation or the Core Audio SDK documentation to complete the tasks in this chapter.

Install the Core Audio Development Kit

1. If you haven’t already done so, install the most recent Core Audio SDK. It is part of the Xcode Tools installation on the OS X DVD. You can also download it from Apple’s developer website at this location:

   http://developer.apple.com/sdk/

   The Core Audio SDK installer places C++ superclasses, example Xcode projects, and documentation at this location on your system:

   /Developer/Examples/CoreAudio

   The SDK also installs Xcode project templates for audio units at this location on your system:

   /Library/Application Support/Apple/Developer Tools/Project Templates/

2. After you have installed the SDK, confirm that Xcode recognizes the audio unit templates, as follows:

   • Launch Xcode and then choose File > New Project.

   • In the Assistant window, confirm that there is an Audio Units group.

   

   Having confirmed the presence of the Audio Units template group, click Cancel, and then quit Xcode.

Specify the Function of Your Audio Unit

With tools in place, you begin your development of an effect unit by describing its digital signal processing. In this case, you specify an audio unit that provides monaural tremolo at a user selectable rate. You’ll implement the DSP later, but establishing a bird’s eye view up front lets you narrow down the implementation steps.

Next, pick an audio unit type based on the function the audio unit will perform. Look through the various types of standard audio units in the AUComponent.h file in the Audio Unit framework. Also, refer to the descriptions of types in Audio Unit Specification. The kAudioUnitType_Effect, with four-character code of 'aufx', looks appropriate for this purpose.

Design the Parameter Interface

In this section you work out the parameter portion of the programmatic interface between your audio unit and its view. End users will vary these parameters to control your audio unit in real time.

First, specify which sound attributes you’d like the user to be able to control. For this project, use the following:

• Tremolo frequency—the number of tremolo cycles per second.

• Tremolo depth—the mix between the input signal and the signal with tremolo applied. At a depth of 0%, there is no tremolo effect. At a depth of 100%, the effect ranges from full amplitude to silence.

• Tremolo waveform—the shape of the tremolo effect, such as sine wave or square wave.

Second, specify for each parameter:

• User interface name as it appears in the audio unit view

• Programmatic name, also called the parameter ID, used in the GetParameterInfo method in the audio unit implementation file

• Unit of measurement, such as gain, decibels, or hertz

• Minimum value

• Maximum value

• Default value

The following tables specify the parameter design. You'll use most of these values directly in your code. Specifying a "Description" is for your benefit while developing and extending the audio unit. You can reuse the description later in online help or a user guide.

It's easy to add, delete, and refine parameters later. For example, if you were creating an audio level adjustment parameter, you might start with a linear scale and later change to a logarithmic scale. For the tremolo unit you're building, you might later decide to add additional tremolo waveforms.

Design the Factory Presets

Now that you’ve specified the parameters, you can specify interesting combinations of settings, or factory presets. For the tremolo unit, specify two factory presets. These two, invented for this tutorial, provide two easily distinguishable effects:

Collect Configuration Information for the Audio Unit Bundle

Now determine your audio unit bundle’s configuration information, such as name and version number. You enter this information into your project’s source files, as described later in Set Your Company Name in Xcode. Here's what you determine and collect up front:

• Audio unit bundle English name, such as Tremolo Unit. Host applications will display this name to let users pick your audio unit.

• Audio unit programmatic name, such as TremoloUnit. You’ll use this to name your Xcode project, which in turn uses this name for your audio unit’s main class.

• Audio unit bundle version number, such as 1.0.2.

• Audio unit bundle brief description, such as "Tremolo Unit version 1.0, copyright © 2006, Angry Audio." This description appears in the Version field of the audio unit bundle’s Get Info window in the Finder.

• Audio unit bundle subtype, a four-character code that provides some indication (to a person) of what your audio unit does. For this audio unit, use 'tmlo'.

• Company English name, such as Angry Audio. This string appears in the audio unit generic view.

• Company programmatic name, such as angryaudio. You’ll use this string in the reverse domain name-style identifier for your audio unit.

• Company four-character code, such as 'Aaud'.

  You obtain this code from Apple, as a “creator code,“ by using the Data Type Registration page. For the purposes of this example, for our fictitious company named Angry Audio, we'll use 'Aaud'.

• Reverse domain name identifier, such as com.angryaudio.audiounit.TremoloUnit. The Component Manager will use this name when identifying your audio unit.

• Custom icon, for display in the Cocoa generic view—optional but a nice touch. This should be a so-called "Small" icon as built with Apple’s Icon Composer application, available on your system in the /Developer/Applications/Utilities folder.

Set Your Company Name in Xcode

Set your company name in Xcode (with Xcode not running) if you haven't already done so. Enter the following command in Terminal on one line:

defaults write com.apple.Xcode PBXCustomTemplateMacroDefinitions '{ORGANIZATIONNAME = "Angry Audio";}'

Now that you have set this so called “expert” preference, Xcode places your company’s name in the copyright notice in the source files of any new project.

Create and Configure the Project

Now you create and configure an Xcode project for your audio unit. This section may seem long—it includes many steps and screenshots—but after you are familiar with the configuration process you can accomplish it in about five minutes.

Launch Xcode and follow these steps:

1. Choose File > New Project

2. In the New Project Assistant dialog, choose the Audio Unit Effect template and click Next.

3. Name the project TremoloUnit and specify a project directory. Then click Finish.

Xcode creates the project files for your audio unit and the Xcode project window opens.

At this point, Xcode has used the audio unit project template file to create a subclass of the AUEffectBase class. Your custom subclass is named according to the name of your project. You can find your custom subclass’s implementation file, TremoloUnit.cpp, in the AU Source group in the Xcode Groups & Files pane, shown next.

In later steps, you'll edit methods in your custom subclass to override the superclass’s methods. TremoloUnit.cpp also contains a couple of methods from the AUKernelBase helper class; these are the methods that you later modify to perform digital signal processing.

4. With the AU Source group open as shown in the previous step, click TremoloUnitVersion.h. Then click the Editor toolbar button, if necessary, to display the text editor. There are three values to customize in this file: kTremoloUnitVersion, TremoloUnit_COMP_SUBTYPE, and TremoloUnit_COMP_MANF.

Scroll down in the editing pane to the definitions of TremoloUnit_COMP_SUBTYPE and TremoloUnit_COMP_MANF. Customize the subtype field with the four-character subtype code that you've chosen. In this example, 'tmlo' indicates (to developers and users) that the audio unit lets a user add tremolo.

Also customize the manufacturer name with the unique four-character string that identifies your company.

Now set the version number for the audio unit. In the TremoloUnitVersion.h file, just above the definitions for subtype and manufacturer, you’ll see the definition statement for the kTremoloUnitVersion constant. By default, the template sets this constant’s value to 1.0.0, as represented by the hexadecimal number 0x00010000. Change this, if you like. See Audio Unit Identification for how to construct the hexadecimal version number.

Save the TremoloUnitVersion.h file.

5. Click the TremoloUnit.r resource file in the "Source/AU Source" group in the Groups & Files pane. There are two values to customize in this file: NAME and DESCRIPTION.

• NAME is used by the generic view to display both your company name and the audio unit name

• DESCRIPTION serves as the menu item for users choosing your audio unit from within a host application.

To work correctly with the generic view, the value for NAME must follow a specific pattern:

<company name>: <audio unit name>

For this example, use:

Angry Audio: Tremolo Unit

If you have set your company name using the Xcode expert preference as described earlier, it will already be in place in the NAME variable for this project; to follow this example, all you need to do is add a space between Tremolo and Unit in the audio unit name itself.

The Xcode template provides a default value for DESCRIPTION. If you customize it, keep it short so that the string works well with pop-up menus. The figure shows a customized DESCRIPTION.

As you can see in the figure, the resource file uses a #include statement to import the Version header file that you customized in step 4, TremoloUnitVersion.h. The resource file uses values from that header file to define some variables such as component subtype (COMP_SUBTYPE) and manufacturer (COMP_MANUF).

Save the TremoloUnit.r resource file.

6. Open the Resources group in the Groups & Files pane in the Xcode project window, and click on the InfoPlist.strings file.

Using the editor, customize the value for CFBundleGetInfoString using the value you’ve chosen for the audio unit brief description. The figure provides an example. This string appears in the Version field of the audio unit bundle’s Get Info window in the Finder. Save the InfoPlist.strings file.

7. Open the Targets group in the Groups & Files pane in the Xcode project window. Double-click the audio unit bundle, which has the same name as your project—in this case, TremoloUnit.

The Target Info window opens. Click the Properties tab.

In the Target Info window’s Properties tab, provide values for Identifier, Creator, Version, and, optionally, a path to a Finder icon file for the bundle that you place in the bundle’s Resources folder.

The audio unit bundle identifier field should follow the pattern:

com.<company_name>.audiounit.<audio_unit_name>

For this example, use the identifier:

com.angryaudio.audiounit.TremoloUnit

For the Creator value, use the same four-character string used for the manufacturer field in step 4.

Xcode transfers all the information from the Properties tab into the audio unit bundle’s Info.plist file. You can open the Info.plist file, if you'd like to inspect it, directly from this dialog using the "Open Info.plist as File" button at the bottom of the window.

When finished, close the Info.plist file (if you've opened it) or close the Target Info window.

8. Now configure the Xcode project’s build process to copy your audio unit bundle to the appropriate location so that host applications can use it.

In the project window, disclose the Products group and the Targets group, as shown in the figure, so that you can see the icon for the audio unit bundle itself (TremoloUnit.component) as well as the build phases (under Targets/TremoloUnit).

9. Now add a new build phase. Right-click (or control-click) the final build phase for TremoloUnit and choose Add > New Build Phase > New Copy Files Build Phase.

The new Copy Files build phase appears at the end of the list, and a dialog opens, titled Copy Files Phase for "TremoloUnit" Info.

Change the Destination pop-up to Absolute Path, as shown in the figure.

Enter the absolute destination path for the built audio unit bundle in the Full Path field.

You can use either of the valid paths for audio unit bundles, as described in Audio Unit Installation and Registration. With the full path entered, close the dialog.

Now drag the TremoloUnit.component icon from the Products group to the new build phase.

You can later change the Copy Files location, if you want, by double clicking the gray Copy Files build phase icon. Alternatively, click the Copy Files icon and then click the Info button in the toolbar.

At this point, you have have the makings for a working audio unit. You have not yet customized it to do whatever it is that you’ll have it do (in our present case, to provide a single-channel tremolo effect). It’s a good idea to ensure that you can build it without errors, that you can validate it with the auval tool, and that you can use it in a host application. Do this in the next step.

10. Build the project. You can do this in any of the standard ways: click the Build button in the toolbar, or choose Build from the Build button's menu, or choose Build > Build from the main menu, or type command-B.

If everything is in order, your project will build without error.

The copy files build phase that you added in the previous step ensures that a copy of the audio unit bundle gets placed in the appropriate location for the Component Manager to find it when a host application launches. The next step ensures that is so, and lets you test that it works in a host application.

Test the Unmodified Audio Unit

To test the newly built audio unit, use the AU Lab application:

• Use the auval tool to verify that OS X recognizes your new audio unit bundle

• Launch the AU Lab application

• Configure AU Lab to test your new audio unit, and test it

Apple’s Core Audio team provides AU Lab in the /Developer/Applications/Audio folder, along with documentation. You do not need to refer to AU Lab’s documentation to complete this task. The auval command-line tool is part of a standard OS X installation.

1. In Terminal, enter the command auval -a. If OS X recognizes your new audio unit bundle, you see a listing similar to this one:

If your Xcode project builds without error, but you do not see the new audio unit bundle in the list reported by the auval tool, double check that you’ve entered the correct path in the Copy Files phase, as described in step 8 of Set Your Company Name in Xcode.

2. Launch AU Lab and create a new AU Lab document. Unless you’ve configured AU Lab to use a default document style, the Create New Document window opens. If AU Lab was already running, choose File > New to get this window.

Ensure that the configuration matches the settings shown in the figure: Built-In Audio for the Audio Device, Line In for the Input Source, and Stereo for Output Channels. Leave the window’s Inputs tab unconfigured; you will specify the input later. Click OK.

A new AU Lab window opens, showing the output channel you specified.

3. Choose Edit > Add Audio Unit Generator. A dialog opens from the AU Lab window to let you specify the generator unit to serve as the audio source.

In the dialog, ensure that the AUAudioFilePlayer unit is selected in the Generator pop-up. To follow this example, change the Group Name to Player. Click OK.

The AU Lab window now shows a stereo input track. In addition, an inspector window has opened for the player unit. If you close the inspector, you can reopen it by clicking the rectangular "AU" button near the top of the Player track.

4. Add an audio file to the Audio Files list in the player inspector window. Do this by dragging the audio file from the Finder, as shown. Putting an audio file in the player inspector window lets you send audio through the new audio unit. Just about any audio file will do, although a continuous tone is helpful for testing.

Now AU Lab is configured and ready to test your audio unit.

5. Click the triangular menu button in the first row of the Effects section in the Player track, as shown in the figure.

A menu opens, listing all the audio units available on your system, arranged by category and manufacturer. There is an Angry Audio group in the pop-up, as shown in the next figure.

Choose your new audio unit from the Effects first row pop-up.

AU Lab opens your audio unit’s Cocoa generic view, which appears as a utility window.

The generic view displays your audio unit’s interface as it comes directly from the parameter and property definitions supplied by the Xcode template. The template defines an audio unit that provides level adjustment. Its view, built by the AU Lab host application, features a Gain control. You modify the view in a later step in this task by changing your audio unit’s parameter definitions.

Refer to Table 3-1 for information on where you define each user interface element for the generic view.

6. Click the Play button in the AUAudioFilePlayer inspector to send audio through the unmodified audio unit. This lets you ensure that audio indeed passes through the audio unit. Vary the slider in the generic view, as you listen to the audio, to ensure that the parameter is working.

7. Save the AU Lab document for use later, giving it a name such as “Tremolo Unit Test.trak”. You will use it in the final section of this chapter, Test your Completed Audio Unit.

Next, you'll define your tremolo effect unit’s parameter interface to give a user control over tremolo rate, depth, and waveform.

Implement the Parameter Interface

Up to this point in developing your audio unit, you have touched very little code. Here, you define the audio unit parameters by editing the source files for the audio unit custom subclass: TremoloUnit.h and TremoloUnit.cpp.

To define audio unit parameters you do three things:

• Name the parameters and give them values in the custom subclass’s header file

• Add statements to the audio unit’s constructor method to set up the parameters when the audio unit is instantiated

• Override the GetParameterInfo method from the SDK’s AUBase class, in the custom subclass’s implementation file, to define the parameters

The code you implement here does not make use of the parameters, per se. It is the DSP code that you implement later, in Implement Signal Processing, that makes use of the parameters. Here, you are simply defining the parameters so that they will appear in the audio unit generic view and so that they’re ready to use when you implement the DSP code.

#pragma mark ____TremoloUnit Parameter Constants

static CFStringRef kParamName_Tremolo_Freq      = CFSTR ("Frequency");    // 1

static const float kDefaultValue_Tremolo_Freq   = 2.0;                    // 2

static const float kMinimumValue_Tremolo_Freq   = 0.5;                    // 3

static const float kMaximumValue_Tremolo_Freq   = 20.0;                   // 4

static CFStringRef kParamName_Tremolo_Depth     = CFSTR ("Depth");        // 5

static const float kDefaultValue_Tremolo_Depth  = 50.0;

static const float kMinimumValue_Tremolo_Depth  = 0.0;

static const float kMaximumValue_Tremolo_Depth  = 100.0;

static CFStringRef kParamName_Tremolo_Waveform  = CFSTR ("Waveform");     // 6

static const int kSineWave_Tremolo_Waveform     = 1;

static const int kSquareWave_Tremolo_Waveform   = 2;

static const int kDefaultValue_Tremolo_Waveform = kSineWave_Tremolo_Waveform;

// menu item names for the waveform parameter

static CFStringRef kMenuItem_Tremolo_Sine       = CFSTR ("Sine");         // 7

static CFStringRef kMenuItem_Tremolo_Square     = CFSTR ("Square");       // 8

// parameter identifiers

enum {                                                                    // 9

    kParameter_Frequency  = 0,

    kParameter_Depth      = 1,

    kParameter_Waveform   = 2,

    kNumberOfParameters   = 3

};

TremoloUnit::TremoloUnit (AudioUnit component) : AUEffectBase (component) {

    CreateElements ();

    Globals () -> UseIndexedParameters (kNumberOfParameters);

    SetParameter (                                       // 1

        kParameter_Frequency,

        kDefaultValue_Tremolo_Freq

    );

    SetParameter (                                       // 2

        kParameter_Depth,

        kDefaultValue_Tremolo_Depth

    );

    SetParameter (                                       // 3

        kParameter_Waveform,

        kDefaultValue_Tremolo_Waveform

    );

    #if AU_DEBUG_DISPATCHER

        mDebugDispatcher = new AUDebugDispatcher (this);

    #endif

}

#pragma mark ____Parameters

ComponentResult TremoloUnit::GetParameterInfo (

        AudioUnitScope          inScope,

        AudioUnitParameterID    inParameterID,

        AudioUnitParameterInfo  &outParameterInfo

) {

    ComponentResult result = noErr;

    outParameterInfo.flags =    kAudioUnitParameterFlag_IsWritable        // 1

                                | kAudioUnitParameterFlag_IsReadable;

    if (inScope == kAudioUnitScope_Global) {                              // 2

        switch (inParameterID) {

            case kParameter_Frequency:                                    // 3

                AUBase::FillInParameterName (

                    outParameterInfo,

                    kParamName_Tremolo_Freq,

                    false

                );

                outParameterInfo.unit =                                   // 4

                    kAudioUnitParameterUnit_Hertz;

                outParameterInfo.minValue =                               // 5

                        kMinimumValue_Tremolo_Freq;

                outParameterInfo.maxValue =                               // 6

                        kMaximumValue_Tremolo_Freq;

                outParameterInfo.defaultValue =                           // 7

                        kDefaultValue_Tremolo_Freq;

                outParameterInfo.flags                                    // 8

                        |= kAudioUnitParameterFlag_DisplayLogarithmic;

                break;

            case kParameter_Depth:                                        // 9

                AUBase::FillInParameterName (

                    outParameterInfo,

                    kParamName_Tremolo_Depth,

                    false

                );

                outParameterInfo.unit =                                   // 10

                    kAudioUnitParameterUnit_Percent;

                outParameterInfo.minValue =

                    kMinimumValue_Tremolo_Depth;

                outParameterInfo.maxValue =

                    kMaximumValue_Tremolo_Depth;

                outParameterInfo.defaultValue =

                     kDefaultValue_Tremolo_Depth;

                break;

            case kParameter_Waveform:                                     // 11

                AUBase::FillInParameterName (

                    outParameterInfo,

                    kParamName_Tremolo_Waveform,

                    false

                );

                outParameterInfo.unit =                                   // 12

                    kAudioUnitParameterUnit_Indexed;

                outParameterInfo.minValue =

                    kSineWave_Tremolo_Waveform;

                outParameterInfo.maxValue =

                    kSquareWave_Tremolo_Waveform;

                outParameterInfo.defaultValue =

                    kDefaultValue_Tremolo_Waveform;

                break;

            default:

                result = kAudioUnitErr_InvalidParameter;

                break;

        }

    } else {

        result = kAudioUnitErr_InvalidParameter;

    }

    return result;

}

ComponentResult TremoloUnit::GetParameterValueStrings (

    AudioUnitScope          inScope,

    AudioUnitParameterID    inParameterID,

    CFArrayRef              *outStrings

) {

    if ((inScope == kAudioUnitScope_Global) &&             // 1

        (inParameterID == kParameter_Waveform)) {

        if (outStrings == NULL) return noErr;              // 2

        CFStringRef strings [] = {                         // 3

            kMenuItem_Tremolo_Sine,

            kMenuItem_Tremolo_Square

        };

        *outStrings = CFArrayCreate (                      // 4

            NULL,

            (const void **) strings,

            (sizeof (strings) / sizeof (strings [0])),     // 5

            NULL

        );

        return noErr;

    }

    return kAudioUnitErr_InvalidParameter;

}

Implement the Factory Presets Interface

Next, you define the audio unit factory presets, again by editing the source files for the audio unit custom subclass, TremoloUnit.h and TremoloUnit.cpp.

The steps, described in detail below, are:

• Name the factory presets and give them values.

• Modify the TremoloUnit class declaration by adding method signatures for handling factory presets.

• Edit the audio unit’s constructor method to set a default factory preset.

• Override the GetPresets method to set up a factory presets array.

• Override the NewFactoryPresetSet method to define the factory presets.

#pragma mark ____TremoloUnit Factory Preset Constants

static const float kParameter_Preset_Frequency_Slow = 2.0;    // 1

static const float kParameter_Preset_Frequency_Fast = 20.0;   // 2

static const float kParameter_Preset_Depth_Slow     = 50.0;   // 3

static const float kParameter_Preset_Depth_Fast     = 90.0;   // 4

static const float kParameter_Preset_Waveform_Slow            // 5

    = kSineWave_Tremolo_Waveform;

static const float kParameter_Preset_Waveform_Fast            // 6

    = kSquareWave_Tremolo_Waveform;

enum {

    kPreset_Slow    = 0,                                      // 7

    kPreset_Fast    = 1,                                      // 8

    kNumberPresets  = 2                                       // 9

};

static AUPreset kPresets [kNumberPresets] = {                 // 10

    {kPreset_Slow, CFSTR ("Slow & Gentle")},

    {kPreset_Fast, CFSTR ("Fast & Hard")}

};

static const int kPreset_Default = kPreset_Slow;              // 11

#pragma mark ____TremoloUnit

class TremoloUnit : public AUEffectBase {

public:

    TremoloUnit (AudioUnit component);

...

    virtual ComponentResult GetPresets (       // 1

        CFArrayRef        *outData

    ) const;

    virtual OSStatus NewFactoryPresetSet (     // 2

        const AUPreset    &inNewFactoryPreset

    );

protected:

...

};

TremoloUnit::TremoloUnit (AudioUnit component) : AUEffectBase (component) {

    CreateElements ();

    Globals () -> UseIndexedParameters (kNumberOfParameters);

    // code for setting default values for the audio unit parameters

    SetAFactoryPresetAsCurrent (                    // 1

        kPresets [kPreset_Default]

    );

    // boilerplate code for debug dispatcher

}

#pragma mark ____Factory Presets

ComponentResult TremoloUnit::GetPresets (                     // 1

    CFArrayRef *outData

) const {

    if (outData == NULL) return noErr;                        // 2

    CFMutableArrayRef presetsArray = CFArrayCreateMutable (   // 3

        NULL,

        kNumberPresets,

        NULL

    );

    for (int i = 0; i < kNumberPresets; ++i) {                // 4

        CFArrayAppendValue (

            presetsArray,

            &kPresets [i]

        );

    }

    *outData = (CFArrayRef) presetsArray;                     // 5

    return noErr;

}

OSStatus TremoloUnit::NewFactoryPresetSet (                         // 1

    const AUPreset &inNewFactoryPreset

) {

    SInt32 chosenPreset = inNewFactoryPreset.presetNumber;          // 2

    if (                                                            // 3

        chosenPreset == kPreset_Slow ||

        chosenPreset == kPreset_Fast

    ) {

        for (int i = 0; i < kNumberPresets; ++i) {                  // 4

            if (chosenPreset == kPresets[i].presetNumber) {

                switch (chosenPreset) {                             // 5

                    case kPreset_Slow:                              // 6

                        SetParameter (                              // 7

                            kParameter_Frequency,

                            kParameter_Preset_Frequency_Slow

                        );

                        SetParameter (                              // 8

                            kParameter_Depth,

                            kParameter_Preset_Depth_Slow

                        );

                        SetParameter (                              // 9

                            kParameter_Waveform,

                            kParameter_Preset_Waveform_Slow

                        );

                        break;

                    case kPreset_Fast:                             // 10

                        SetParameter (

                            kParameter_Frequency,

                           kParameter_Preset_Frequency_Fast

                        );

                        SetParameter (

                            kParameter_Depth,

                            kParameter_Preset_Depth_Fast

                        );

                        SetParameter (

                            kParameter_Waveform,

                            kParameter_Preset_Waveform_Fast

                        );

                        break;

                }

                SetAFactoryPresetAsCurrent (                        // 11

                    kPresets [i]

                );

                return noErr;                                       // 12

            }

        }

    }

    return kAudioUnitErr_InvalidProperty;                           // 13

}

Implement Signal Processing

With the parameter and preset code in place, you now get to the heart of the matter: the digital signal processing code. As described in Synthesis, Processing, and Data Format Conversion Code, the DSP performed by an n-to-n channel effect unit takes place in the AUKernelBase class, a helper class for the AUEffectBase class. Refer to Processing: The Heart of the Matter for more on how DSP works in audio units.

To implement signal processing in an n-to-n channel effect unit, you override two methods from the AUKernelBase class:

• The Process method, which performs the signal processing

• The Reset method, which returns the audio unit to its pristine, initialized state

Along the way, you make changes to the default TremoloUnitKernel class declaration in the TremoloUnit.h header file, and you modify the TremoloUnitKernel constructor method in TremoloUnit.cpp.

class TremoloUnit : public AUEffectBase

{

public:

    TremoloUnit(AudioUnit component);

...

protected:

    class TremoloUnitKernel : public AUKernelBase {

        public:

            TremoloUnitKernel (AUEffectBase *inAudioUnit); // 1

            virtual void Process (

                const Float32    *inSourceP,

                Float32          *inDestP,

                UInt32           inFramesToProcess,

                UInt32           inNumChannels,   // equal to 1

                bool             &ioSilence

        );

        virtual void Reset();

        private:

            enum     {kWaveArraySize = 2000};             // 2

            float    mSine [kWaveArraySize];              // 3

            float    mSquare [kWaveArraySize];            // 4

            float    *waveArrayPointer;                   // 5

            Float32  mSampleFrequency;                    // 6

            long     mSamplesProcessed;                   // 7

            enum     {sampleLimit = (int) 10E6};          // 8

            float    mCurrentScale;                       // 9

            float    mNextScale;                          // 10

    };

};

#pragma mark ____TremoloUnitEffectKernel

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

//    TremoloUnit::TremoloUnitKernel::TremoloUnitKernel()

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TremoloUnit::TremoloUnitKernel::TremoloUnitKernel (AUEffectBase *inAudioUnit) :

    AUKernelBase (inAudioUnit), mSamplesProcessed (0), mCurrentScale (0) // 1

{

    for (int i = 0; i < kWaveArraySize; ++i) {                           // 2

        double radians = i * 2.0 * pi / kWaveArraySize;

        mSine [i] = (sin (radians) + 1.0) * 0.5;

    }

    for (int i = 0; i < kWaveArraySize; ++i) {                           // 3

        double radians = i * 2.0 * pi / kWaveArraySize;

        radians = radians + 0.32;

        mSquare [i] =

            (

                sin (radians) +

                0.3 * sin (3 * radians) +

                0.15 * sin (5 * radians) +

                0.075 * sin (7 * radians) +

                0.0375 * sin (9 * radians) +

                0.01875 * sin (11 * radians) +

                0.009375 * sin (13 * radians) +

                0.8

            ) * 0.63;

    }

    mSampleFrequency = GetSampleRate ();                                 // 4

}

void TremoloUnit::TremoloUnitKernel::Process (                        // 1

    const Float32   *inSourceP,                                       // 2

    Float32         *inDestP,                                         // 3

    UInt32          inSamplesToProcess,                               // 4

    UInt32          inNumChannels,                                    // 5

    bool            &ioSilence                                        // 6

) {

    if (!ioSilence) {                                                 // 7

        const Float32 *sourceP = inSourceP;                           // 8

        Float32  *destP = inDestP,                                    // 9

                 inputSample,                                         // 10

                 outputSample,                                        // 11

                 tremoloFrequency,                                    // 12

                 tremoloDepth,                                        // 13

                 samplesPerTremoloCycle,                              // 14

                 rawTremoloGain,                                      // 15

                 tremoloGain;                                         // 16

        int      tremoloWaveform;                                     // 17

        tremoloFrequency = GetParameter (kParameter_Frequency);       // 18

        tremoloDepth     = GetParameter (kParameter_Depth);           // 19

        tremoloWaveform  =

            (int) GetParameter (kParameter_Waveform);                 // 20

        if (tremoloWaveform != kSineWave_Tremolo_Waveform             // 21

            && tremoloWaveform != kSquareWave_Tremolo_Waveform)

                tremoloWaveform = kSquareWave_Tremolo_Waveform;

        if (tremoloWaveform == kSineWave_Tremolo_Waveform)  {         // 22

            waveArrayPointer = &mSine [0];

        } else {

            waveArrayPointer = &mSquare [0];

        }

        if (tremoloFrequency < kMinimumValue_Tremolo_Freq)            // 23

            tremoloFrequency = kMinimumValue_Tremolo_Freq;

        if (tremoloFrequency > kMaximumValue_Tremolo_Freq)

            tremoloFrequency = kMaximumValue_Tremolo_Freq;

        if (tremoloDepth     < kMinimumValue_Tremolo_Depth)           // 24

            tremoloDepth     = kMinimumValue_Tremolo_Depth;

        if (tremoloDepth     > kMaximumValue_Tremolo_Depth)

            tremoloDepth     = kMaximumValue_Tremolo_Depth;

        samplesPerTremoloCycle = mSampleFrequency / tremoloFrequency; // 25

        mNextScale = kWaveArraySize / samplesPerTremoloCycle;         // 26

        // the sample processing loop ////////////////

        for (int i = inSamplesToProcess; i > 0; --i) {                // 27

            int index =                                               // 28

                static_cast<long>(mSamplesProcessed * mCurrentScale) %

                    kWaveArraySize;

            if ((mNextScale != mCurrentScale) && (index == 0)) {      // 29

                mCurrentScale = mNextScale;

                mSamplesProcessed = 0;

            }

            if ((mSamplesProcessed >= sampleLimit) && (index == 0))   // 30

                mSamplesProcessed = 0;

            rawTremoloGain = waveArrayPointer [index];                // 31

            tremoloGain       = (rawTremoloGain * tremoloDepth -      // 32

                                tremoloDepth + 100.0) * 0.01;

            inputSample       = *sourceP;                             // 33

            outputSample      = (inputSample * tremoloGain);          // 34

            *destP            = outputSample;                         // 35

            sourceP           += 1;                                   // 36

            destP             += 1;                                   // 37

            mSamplesProcessed += 1;                                   // 38

        }

    }

}

void TremoloUnit::TremoloUnitKernel::Reset() {

    mCurrentScale        = 0;                    // 1

    mSamplesProcessed    = 0;                    // 2

}

Implement the Tail Time Property

Finally, to ensure that your audio unit plays well in host applications, implement the tail time property, kAudioUnitProperty_TailTime.

To do this, simply state in your TremoloUnit class definition that your audio unit supports the property by changing the return value of the SupportsTail method to true.

Listing 5-14  Implementing the tail time property (TremoloUnit.h)

virtual bool SupportsTail () {return true;}

Given the nature of the DSP your audio unit performs, its tail time is 0 seconds—so you don’t need to override the GetTailTime method. In the AUBase superclass, this method reports a tail time of 0 seconds, which is what you want your audio unit to report.

Validate your Completed Audio Unit

Now you’ve implemented all of the code for the tremolo unit project. Build the project and correct any errors you see. Then use the auval tool to validate your audio unit.

1. In Terminal, enter the command to validate the tremolo unit. This consists of the auval command name followed by the -v flag to invoke validation, followed by the type, subtype, and manufacturer codes that identify the tremolo unit. The complete command for this audio unit is:

auval -v aufx tmlo Aaud

If everything is in order, auval should report that your new audio unit is indeed valid. The figure shows the last bit of the log created by auval:

Test your Completed Audio Unit

Your audio unit is ready for you to test in a host application. Apple recommends the AU Lab application for audio unit testing. You may also want to test your audio unit in other hosts. This section describes testing with AU Lab. Follow these steps:

1. Open the AU Lab document that you saved from the Test the Unmodified Audio Unit section. If you don’t have that document, run through the steps in that section again to set up AU Lab for testing your audio unit.

2. Your completed audio unit appears with the generic view as shown in the figure:

(You may need to quit and reopen AU Lab for your completed audio unit’s view to appear.)

Notice the sliders for the Frequency and Depth parameters, the pop-up menu for the Waveform parameter, and the default preset displayed in the Factory Presets pop-up menu.

3. Click the Play button in the AUAudioFilePlayer utility window. If everything is in order, the file you have selected in the player will play through your audio unit and you’ll hear the tremolo effect.

4. Experiment with the range of effects available with the tremolo unit: adjust the Frequency, Depth, and Waveform controls while listening to the output from AU Lab.

5. In the presets menu toward the upper right of the generic view, choose Show Presets.

The presets drawer opens.

Disclose the presets in the Factory group and verify that the presets that you added to your audio unit, using the NewFactoryPresetSet method, are present. Double-click a preset to load it.

You can add user presets to the audio unit as follows:

• Set the parameters as desired

• In the presets menu, choose Save Preset As

• In the dialog that appears, enter a name for the preset.