The volume can be set for either individual sound samples or the entire controller. To set it within the scope of the controller, call the AVController’s setVolume method.

[ av setVolume: 1.0 ]

The volume is a floating-point number from 0.0 to 1.0. Adjusting the volume on the controller level will cause a volume window to appear to the user. This is useful for handling mute requests and the like.

Setting the volume for an individual sound sample will be shown in the upcoming section "Audio Samples.”

To tell the controller to repeat a sound after it has finished playing, call setRepeatMode, passing an integer value as an argument.

[ av setRepeatMode: 1 ];

The repeat mode must be set after an item has begun playing. The valid repeat modes are as follows.

Although set on a controller level, only the current sample will be repeated—even if more than one sound sample is queued up to play.

The sample rate is the playback frequency sounds should be played at. This should match the frequency at which samples were originally recorded, and can be set either manually, using the setRate method shown here, or automatically by leaving the option alone.

NSError *err;
[ av setRate: 44100.0 error: &err ];
if (err != nil) {
    NSLog(@"The following error has occured: %@", err);
}

Many Celestial methods need to be able to report an error. The NSError class is used for this. NSError is similar to an NSString object, which is standard across both the iPhone and Mac OS X desktop operating systems. This class builds on the NSString base class and encapsulates additional information pertaining to error codes. More information about NSError and NSString can be found in the Cocoa reference available on the Apple Developer Connection web site.

An equalizer adjusts the relative volume of different frequencies to produce a clearer sound. Different equalizers improve the user’s experience for different types of recordings and music, and Apple uses a preset collection of equalizers heavily in iTunes and follow-up products. The iPhone supports 22 different equalizer presets that can be set using the setEQPreset method.

[ av setEQPreset: 0 ];

The default setting is to use no EQ, and if you’re only playing event sounds, there’s little reason to change this. If you’re playing a radio broadcast or writing a third-party player, however, the following table can be used to set the desired preset.

Muting the audio channel is as easy as sending a message to setMuted. This method applies not only to the sound currently playing, but also to every sound subsequently played through the controller object.

[ av setMuted: NO ];

URLs can also be played using the same AVItem class by specifying a URL instead of a file path.

AVItem *item = [ [ AVItem alloc ]
    initWithPath: @"http://path-to-sound-file" error: &err
];

This can be useful, but keep in mind that your application will require a network connection to play these sounds. A slow or lagged connection could also slow the application.

To set the volume for a specific sample, the AVItem’s setVolume method can be called. Unlike the controller’s method, using setVolume here will not affect the rest of the audio channel, nor will it display a volume change window to the user.

[ item setVolume: 0.5 ];

An individual sample also has its own EQ property, which can be set using the same table shown earlier. This sets the EQ of the sample only, and will remain in effect for as long as the object exists.

[ item setEQPreset: 0 ];

Once the object has been created, you can find the sample’s duration in seconds.

float duration = [ item duration ];

Once the desired audio object properties have been set, the object can now be attached to the audio controller for playing.

BOOL ok;
[ av setCurrentItem: item preservingRate:NO ];
ok = [ av play:nil ];

The Boolean return value from the play method will be true if the audio controller accepted your request to play the item. If another item is currently playing, it will reject your request and return NO.

To pause playing, call the controller’s pause method.

[ av pause ];

Because the Audio Toolbox framework uses low-level C interfaces, it has no concept of a class. There are many moving parts involved in setting up an audio queue, and to make our examples more understandable, all of the different variables used will be encapsulated into a single user-defined structure we call AQCallbackStruct.

typedef struct AQCallbackStruct {
    AudioQueueRef queue;
    UInt32 frameCount;
    AudioQueueBufferRef mBuffers[AUDIO_BUFFERS];
    AudioStreamBasicDescription mDataFormat;
} AQCallbackStruct;

The following components are grouped into this structure to service the audio framework:

Before the audio queue can be created, you have to initialize instances of these variables.

AQCallbackStruct aqc;
aqc.mDataFormat.mSampleRate = 44100.0;
aqc.mDataFormat.mFormatID = kAudioFormatLinearPCM;
aqc.mDataFormat.mFormatFlags = kLinearPCMFormatFlagIsSignedInteger
    | kAudioFormatFlagIsPacked;
aqc.mDataFormat.mBytesPerPacket = 4;
aqc.mDataFormat.mFramesPerPacket = 1;
aqc.mDataFormat.mBytesPerFrame = 4;
aqc.mDataFormat.mChannelsPerFrame = 2;
aqc.mDataFormat.mBitsPerChannel = 16;
aqc.frameCount = 735;

In this example, we prepare a structure for 16-bit (two bytes per sample) stereo sound (two channels) with a sample rate of 44 Khz (44,100). Our output sample will be provided in the form of two two-byte short integers, hence four total bytes per frame (two bytes for the left and right channel, each).

The sample rate and frame size dictate how often the iPhone will ask for more sound. With a frequency of 44,100 samples per second, we can make our application sync the sound every 60th of a second by defining a frame size of 735 samples (44,100/60 = 735).

The format we’ll be providing in this example is PCM (raw data), but 27 different formats are available.

Once the audio queue’s properties have been defined, a new audio queue object can be provisioned. The AudioQueueNewOutput function is responsible for provisioning an output channel and attaching it to the queue. The prototype function looks like this:

AudioQueueNewOutput(
    const AudioStreamBasicDescription *inFormat,
    AudioQueueOutputCallback          inCallbackProc,
    void *                            inUserData,
    CFRunLoopRef                      inCallbackRunLoop,
    CFStringRef                       inCallbackRunLoopMode,
    UInt32                            inFlags,
    AudioQueueRef *                   outAQ);

and can be broken down as follows:

An actual call to this function, using the audio queue structure created earlier, looks like this:

AudioQueueNewOutput(&aqc.mDataFormat,
    AQBufferCallback,
    &aqc,
    NULL,
    kCFRunLoopCommonModes,
    0,
    &aqc.queue);

In this example, the name of the callback function was specified as AQBufferCallback. This function will be created in the next few sections. It is the function that will be responsible for taking sound output from your application and copying it to a sound buffer.

A sound buffer contains sound data in transit to the output device. Going back to our box-on-a-conveyor-belt concept, the buffer is the box that carries your sound to the speakers. If you don’t have enough sound to fill the box, it ends up going to the speakers incomplete, which could lead to gaps in the audio. The more boxes you have, the more sound you can queue up in advance to avoid running out (or running slow). The downside is that it also takes longer for the sound at the speaker end to catch up to the sound coming from the application. This could be problematic if the character in your game jumps, but the user doesn’t hear it until after he’s landed.

When the sound is ready to start, sound buffers are created and primed with the first frames of the your application’s sound output. The minimum number of buffers needed to start playback on an Apple desktop is only one, but on the iPhone it is three. In applications that might cause high CPU usage, it may be appropriate to use even more buffers to prevent under-runs. To prepare the buffers with the first frames of sound data, each buffer is primed in the order it is created. This means by the time you prime the buffers, you’d better have some sound to fill them with.

#define AUDIO_BUFFERS 3

unsigned long bufferSize;

bufferSize = aqc.frameCount * aqc.mDataFormat.mBytesPerFrame;
for (i=0; i<AUDIO_BUFFERS; i++) {
    AudioQueueAllocateBuffer(aqc.queue,
        bufferSize, &aqc.mBuffers[i]);
    AQBufferCallback (&aqc, aqc.queue, aqc.mBuffers[i]);
}

When this code executes, the audio buffers are filled with the first frames of sound data from your application. The queue is now ready to be activated, which turns on the conveyor belt sending the sound buffers to the speakers. As this occurs, the buffers are emptied of their contents (no, memory isn’t zeroed) and the boxes come back around the conveyor belt for a refill.

AudioQueueStart(aqc.queue, NULL);

Later on, when you’re ready to turn off the sound queue, just use the AudioQueueDispose function, and everything stops:

AudioQueueDispose(aqc.queue, true);

The audio queue is now running, and every 60th of a second, the application is asked to fill a new sound buffer with data. What hasn’t been explained yet is how this happens. After a buffer is emptied and is ready to be refilled, the audio queue calls the callback function you specified as the second argument to AudioQueueNewOutput. This callback function is where the application does its work; it fills the box that carries your output sound to the speakers. You have to call it before starting the queue in order to prime the sound buffers with some initial sound. The queue then calls the function each time a buffer needs to be refilled. When called, you’ll fill the audio queue buffer that is passed in by copying the latest sound frame from your application—in our example, 735 samples.

static void AQBufferCallback(
    void *aqc,
    AudioQueueRef inQ,
    AudioQueueBufferRef outQB)
{

The callback structure you created at the very beginning, aqc, is passed as a user-defined argument, followed by pointers to the audio queue itself and the audio queue buffer to be filled.

    AQCallbackStruct *inData = (AQCallbackStruct *)aqc;

Because the AQCallbackStruct structure is considered user data, it’s supplied to the callback function as a void pointer, and needs to be cast back to an AQCallbackStruct structure (here, named inData) before it can be accessed. This code grabs a pointer to the raw audio data inside the buffer so that the application can write its sound into it.

    short *CoreAudioBuffer = (short *) outOB->mAudioData;

The CoreAudioBuffer variable represents the space inside the sound buffer where your application’s raw samples will be copied at every sync. Your application will need to maintain a type of “record needle” to keep track of what sound has already been sent to the audio queue.

    if (inData->frameCount > 0) {

The frameCount variable is the number of frames that the buffer is expecting to see. This should be equivalent to the frameCount that was supplied in the AQCallbackStruct structure—in our example, 735.

        outQB->mAudioDataByteSize = 4 * inData->frameCount;

This is where you tell the buffer exactly how much data it’s going to get: a packing list for the box. The total output buffer size should be equivalent to the size of both stereo channels (two bytes per channel = four bytes) multiplied by the number of frames sent (735).

        for(i = 0 ; i < inData->frameCount * 2; i += 2) {
            CoreAudioBuffer[i]   =  (  LEFT CHANNEL DATA );
            CoreAudioBuffer[i+1] =  ( RIGHT CHANNEL DATA );
        }

Here, the callback function steps through each output frame in the buffer and copies the data from what will be your application’s outputted sound into CoreAudioBuffer. Because the left and right channels are interleaved, the loop will have to account for this by skipping in increments of two.

        AudioQueueEnqueueBuffer(inQ, outQB, 0, NULL);
   } /* if (inData->frameCount > 0) */
} /* AQBufferCallback */

Finally, once the frame has been copied into the sound buffer, it’s placed back onto the play queue.

Audio Toolbox lives in C land, while Celestial requires an Objective-C context. To merge the two worlds, a global variable is the easiest way to allow the two to communicate data. In this example, this global variable is called _volume.

Celestial delegates volume and ringer control to the AVSystemController class. To read the volume from Celestial, create an instance of this:

NSString *audioDeviceName;
float _volume;
AVSystemController *avs =
    [ AVSystemController sharedAVSystemController ];
[ avs getActiveCategoryVolume: &_volume andName: &audioDeviceName ];

When the getActiveCategoryVolume method is notified, it sets the value of _volume to the current volume in the range 0.0 through 1.0. This will be seen automatically by the Audio Toolbox code, provided _volume is a global variable, and cause future sample frames to be multiplied by the new value.

Using the getActiveCategoryVolume method as a one-time read is useful for setting the output volume when the program starts, but won’t change anything if the volume is adjusted while using the application. To accomplish this, add an observer to the application. The observer monitors specific system events and notifies the given method when the event occurs.

    [ [ NSNotificationCenter defaultCenter ] addObserver: self
        selector:@selector(volumeChange:)
        name: @"AVSystemController_SystemVolumeDidChangeNotification"
        object: avs ];

This code sets a method named volumeChange as the observer for system volume changes. The volumeChange method is then defined in the calling class:

- (void)volumeChange:(NSNotification *)notification {
    AVSystemController *avsc = [ notification object ];
    NSString *audioDeviceName;
    [ avsc getActiveCategoryVolume:&_volume
          andName:&audioDeviceName ];
}

When the volumeChange method is notified, an AVSystemController object is passed in with the notification. This object is then used to reread the volume into _volume, where it will be picked up by the AQBufferCallback function feeding the audio queue.