Audio Queue Services Reference

Framework	AudioToolbox/AudioToolbox.h
Declared in	AudioQueue.h

Overview

This document describes Audio Queue Services, a C programming interface in the Audio Toolbox framework, which is part of Core Audio.

An audio queue is a software object you use for recording or playing audio. An audio queue does the work of:

Connecting to audio hardware
Managing memory
Employing codecs, as needed, for compressed audio formats
Mediating playback or recording

Audio Queue Services enables you to record and play audio in linear PCM, in compressed formats (such as Apple Lossless and AAC), and in other formats for which users have installed codecs. Audio Queue Services also supports scheduled playback and synchronization of multiple audio queues and synchronization of audio with video.

Functions by Task

Controlling Audio Queues

Creating and Disposing of Audio Queues

Handling Audio Queue Buffers

Manipulating Audio Queue Parameters

Manipulating Audio Queue Properties

Handling Timing

Performing Offline Rendering

Functions

AudioQueueAddPropertyListener

Adds a property listener callback to an audio queue.

OSStatus AudioQueueAddPropertyListener (
   AudioQueueRef inAQ,
   AudioQueuePropertyID inID,
   AudioQueuePropertyListenerProc inProc,
   void *inUserData
);

Parameters

inAQ: The audio queue that you want to assign a property listener callback to.
inID: The ID of the property whose changes you want to respond to. See “Audio Queue Property Identifiers.”
inProc: The callback to be invoked when the property value changes.
inUserData: Custom data for the property listener callback.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Use this function to let your application respond to property value changes in an audio queue. For example, say your application’s user interface has a button that acts as a Play/Stop toggle switch. When an audio file has finished playing, the audio queue stops and the value of the kAudioQueueProperty_IsRunning property changes from true to false. You can use a property listener callback to update the button text appropriately.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueAllocateBuffer

Asks an audio queue object to allocate an audio queue buffer.

OSStatus AudioQueueAllocateBuffer (
   AudioQueueRef inAQ,
   UInt32 inBufferByteSize,
   AudioQueueBufferRef *outBuffer
);

Parameters

inAQ: The audio queue you want to allocate a buffer.
inBufferByteSize: The desired capacity of the new buffer, in bytes. Appropriate capacity depends on the processing you will perform on the data as well as on the audio data format.
outBuffer: On output, points to the newly allocated audio queue buffer.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Once allocated, the pointer to the audio queue buffer and the buffer’s capacity cannot be changed. The buffer’s size field, mAudioDataByteSize, which indicates the amount of valid data, is initially set to 0.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueAllocateBufferWithPacketDescriptions

Asks an audio queue object to allocate an audio queue buffer with space for packet descriptions.

AudioQueueAllocateBufferWithPacketDescriptions(
   AudioQueueRef           inAQ,
   UInt32                  inBufferByteSize,
   UInt32                  inNumberPacketDescriptions,
   AudioQueueBufferRef     *outBuffer
);

Parameters

inAQ: The audio queue you want to allocate a buffer.
inBufferByteSize: The desired data capacity of the new buffer, in bytes. Appropriate capacity depends on the processing you will perform on the data as well as on the audio data format.
inNumberPacketDescriptions: The desired size of the packet description array in the new audio queue buffer.
outBuffer: On output, points to the newly allocated audio queue buffer.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Use this function when allocating an audio queue buffer for use with a VBR compressed data format.

Availability

Available in OS X v10.6 and later.

Declared In

AudioQueue.h

AudioQueueCreateTimeline

Creates a timeline object for an audio queue.

OSStatus AudioQueueCreateTimeline (
   AudioQueueRef inAQ,
   AudioQueueTimelineRef *outTimeline
);

Parameters

inAQ: The audio queue to associate with the new timeline object.
outTimeLine: On output, the newly created timeline object.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Create a timeline object if you want to get timeline discontinuity information from an audio queue using the AudioQueueGetCurrentTime function.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueDeviceGetCurrentTime

Gets the current time of the audio hardware device associated with an audio queue.

OSStatus AudioQueueDeviceGetCurrentTime (
   AudioQueueRef inAQ,
   AudioTimeStamp *outTimeStamp
);

Parameters

inAQ: The audio queue whose associated audio device is to be queried.
outDeviceTime: On output, the current time of the audio hardware device associated with the audio queue. If the device is not running, the only valid field in the audio timestamp structure is mHostTime.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

This function returns a value whether or not the audio hardware device associated with the audio queue is running. The similar AudioDeviceGetCurrentTime function, declared in the AudioHardware.h header file, returns an error in this case.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueDeviceGetNearestStartTime

Gets the start time, for an audio hardware device, that is closest to a requested start time.

OSStatus AudioQueueDeviceGetNearestStartTime (
   AudioQueueRef inAQ,
   AudioTimeStamp *ioRequestedStartTime,
   UInt32 inFlags
);

Parameters

inAQ: The audio queue whose associated audio hardware device’s start time you want to get.
ioRequestedDeviceTime: On input, the requested start time. On output, the actual start time.
inFlags: Reserved for future use. Pass 0.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

This function asks an audio queue’s associated device for a start time to use for recording or playback. The time returned will be equal to or later than the requested start time, depending on device and system factors. For example, the start time might be shifted to allow for aligning buffer access. The device must be running to use this function.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueDeviceTranslateTime

Converts the time for an audio queue’s associated audio hardware device from one time base representation to another.

OSStatus AudioQueueDeviceTranslateTime (
   AudioQueueRef inAQ,
   const AudioTimeStamp *inTime,
   AudioTimeStamp *outTime
);

Parameters

inAQ: The audio queue associated with the device whose times are being translated.
inDeviceTime: The time to be translated.
outDeviceTime: On output, the translated time.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

The device must be running for this function to provide a result. For an explanation of the various time base representations for an audio hardware device, see AudioTimeStamp in Core Audio Data Types Reference.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueDispose

Disposes of an audio queue.

OSStatus AudioQueueDispose (
   AudioQueueRef inAQ,
   Boolean inImmediate
);

Parameters

inAQ: The audio queue you want to dispose of.
inImmediate: If you pass true, the audio queue is disposed of immediately (that is, synchronously). If you pass false, disposal does not take place until all enqueued buffers are processed (that is, asynchronously).

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Disposing of an audio queue also disposes of its resources, including its buffers. After you call this function, you can no longer interact with the audio queue. In addition, the audio queue no longer invokes any callbacks.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueDisposeTimeline

Disposes of an audio queue’s timeline object.

OSStatus AudioQueueDisposeTimeline (
   AudioQueueRef inAQ,
   AudioQueueTimelineRef inTimeline
);

Parameters

inAQ: The audio queue associated with the timeline object you want to dispose of.
inTimeLine: The timeline object to dispose of.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Disposing of an audio queue automatically disposes of any associated resources, including a timeline object. Call this function only if you want to dispose of a timeline object and not the audio queue associated with it.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueEnqueueBuffer

Adds a buffer to the buffer queue of a recording or playback audio queue.

OSStatus AudioQueueEnqueueBuffer (
   AudioQueueRef                      inAQ,
   AudioQueueBufferRef                inBuffer,
   UInt32                             inNumPacketDescs,
   const AudioStreamPacketDescription *inPacketDescs
);

Parameters

inAQ

The audio queue that owns the audio queue buffer.

inBuffer

The audio queue buffer to add to the buffer queue.

inNumPacketDescs

The number of packets of audio data in the inBuffer parameter. Use a value of 0 for any of the following situations:

When playing a constant bit rate (CBR) format.
When the audio queue is a recording (input) audio queue.
When the buffer you are reenqueuing was allocated with the AudioQueueAllocateBufferWithPacketDescriptions function. In this case, your callback should describe the buffer’s packets in the buffer’s mPacketDescriptions and mPacketDescriptionCount fields.

inPacketDescs

An array of packet descriptions. Use a value of NULL for any of the following situations:

When playing a constant bit rate (CBR) format.
When the audio queue is an input (recording) audio queue.
When the buffer you are reenqueuing was allocated with the AudioQueueAllocateBufferWithPacketDescriptions function. In this case, your callback should describe the buffer’s packets in the buffer’s mPacketDescriptions and mPacketDescriptionCount fields.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Audio queue callbacks use this function to reenqueue buffers—placing them “last in line” in a buffer queue. A playback (or output) callback reenqueues a buffer after the buffer is filled with fresh audio data (typically from a file). A recording (or input) callback reenqueues a buffer after the buffer’s contents were written (typically to a file).

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueEnqueueBufferWithParameters

Adds a buffer to the buffer queue of a playback audio queue object, specifying start time and other settings.

OSStatus AudioQueueEnqueueBufferWithParameters (
   AudioQueueRef                       inAQ,
   AudioQueueBufferRef                 inBuffer,
   UInt32                              inNumPacketDescs,
   const AudioStreamPacketDescription  *inPacketDescs,
   UInt32                              inTrimFramesAtStart,
   UInt32                              inTrimFramesAtEnd,
   UInt32                              inNumParamValues,
   const AudioQueueParameterEvent      *inParamValues,
   const AudioTimeStamp                *inStartTime,
   AudioTimeStamp                      *outActualStartTime
);

Parameters

inAQ

The audio queue object that owns the audio queue buffer.

inBuffer

The audio queue buffer to add to the buffer queue. Before calling this function, the buffer must contain the audio data to be played.

inNumPacketDescs

The number of packets of audio data in the inBuffer parameter. Use a value of 0 for either of the following situations:

When playing a constant bit rate (CBR) format.
When the buffer you are reenqueuing was allocated with the AudioQueueAllocateBufferWithPacketDescriptions function. In this case, your callback should describe the buffer’s packets in the buffer’s mPacketDescriptions and mPacketDescriptionCount fields.

inPacketDescs

An array of packet descriptions. Use a value of NULL for either of the following situations:

When playing a constant bit rate (CBR) format.
When the buffer you are reenqueuing was allocated with the AudioQueueAllocateBufferWithPacketDescriptions function. In this case, your callback should describe the buffer’s packets in the buffer’s mPacketDescriptions and mPacketDescriptionCount fields.

inTrimFramesAtStart

The number of priming frames to skip at the start of the buffer.

inTrimFramesAtEnd

The number of frames to skip at the end of the buffer.

inNumParamValues

The number of audio queue parameter values pointed to by the inParamValues parameter. If you are not setting parameters, use 0.

inParamValues

An array of parameters to apply to an audio queue buffer. (In OS X v10.5, there is only one audio queue parameter, kAudioQueueParam_Volume.) If you are not setting parameters for the buffer, use NULL.

Assign parameter values before playback—they cannot be changed while a buffer is playing. Changes to audio queue buffer parameters take effect when the buffer starts playing.

inStartTime

The desired start time for playing the buffer. To specify a time relative to when the audio queue started, use the mSampleTime field of the AudioTimeStamp structure. Use NULL to indicate that the buffer should play as soon as possible—which may be after previously queued buffers finish playing.

Buffers play in the order they are enqueued (first in, first out). If multiple buffers are queued, the start times must be in ascending order or NULL; otherwise, an error occurs. This parameter specifies when audio data is to start playing, ignoring any trim frames specified in the inTrimFramesAtStart parameter.

outActualStartTime

On output, the time when the buffer will actually start playing.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

You can exert some control over the buffer queue with this function. You can assign audio queue settings that are, in effect, carried by an audio queue buffer as you enqueue it. Hence, settings take effect when an audio queue buffer begins playing.

This function applies only to playback. Recording audio queues do not take parameters and do not support variable bit rate (VBR) formats (which might require trimming).

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueFlush

Resets an audio queue’s decoder state.

OSStatus AudioQueueFlush (
   AudioQueueRef inAQ
);

Parameters

inAQ: The audio queue to flush.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Call AudioQueueFlush after enqueuing the last audio queue buffer to ensure that all buffered data, as well as all audio data in the midst of processing, gets recorded or played. If you do not call this function, stale data in the audio queue’s decoder may interfere with playback or recording of the next set of buffers.

Call this function before calling AudioQueueStop if you want to ensure that all enqueued data reaches the destination. If you call AudioQueueStop with the inImmediate parameter set to false, calling this function does nothing; under those conditions, AudioQueueStop calls this function.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueFreeBuffer

Asks an audio queue to dispose of an audio queue buffer.

OSStatus AudioQueueFreeBuffer (
   AudioQueueRef inAQ,
   AudioQueueBufferRef inBuffer
);

Parameters

inAQ: The audio queue that owns the audio queue buffer you want to dispose of.
inBuffer: The buffer to dispose of.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Disposing of an audio queue also disposes of its buffers. Call this function only if you want to dispose of a particular buffer while continuing to use an audio queue. You can dispose of a buffer only when the audio queue that owns it is stopped (that is, not processing audio data).

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueGetCurrentTime

Gets the current audio queue time.

OSStatus AudioQueueGetCurrentTime (
   AudioQueueRef inAQ,
   AudioQueueTimelineRef inTimeline,
   AudioTimeStamp *outTimeStamp,
   Boolean *outTimelineDiscontinuity
);

Parameters

inAQ

The audio queue whose current time you want to get.

inTimeline

The audio queue timeline object to which timeline discontinuities are reported. Use NULL if the audio queue does not have an associated timeline object.

outTime

On output, the current audio queue time. The mSampleTime field represents audio queue time in terms of the audio queue sample rate, relative to when the queue started or will start.

outTimelineDiscontinuity

On output, true if there has been a timeline discontinuity, or false if there has been no discontinuity. If the audio queue does not have an associated timeline object, this parameter is always NULL.

A timeline discontinuity may occur, for example, if the sample rate is changed for the audio hardware device associated with an audio queue.

Return Value

A result code. See “Audio Queue Result Codes.”

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueGetParameter

Gets an audio queue parameter value.

OSStatus AudioQueueGetParameter (
   AudioQueueRef inAQ,
   AudioQueueParameterID inParamID,
   AudioQueueParameterValue *outValue
);

Parameters

inAQ: The audio queue that you want to get a parameter value from.
inParamID: The ID of the parameter whose value you want to get. In OS X v10.5, audio queues have one parameter available: kAudioQueueParam_Volume, which controls playback gain. See “Audio Queue Parameters”
outValue: On output, points to the current value of the specified parameter.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

You can access the current parameter values for an audio queue at any time with this function. An audio queue parameter value is the sum of settings applied at buffer granularity, using the AudioQueueEnqueueBufferWithParameters function, and settings applied to the audio queue per se, using the AudioQueueSetParameter function.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueGetProperty

Gets an audio queue property value.

OSStatus AudioQueueGetProperty (
   AudioQueueRef inAQ,
   AudioQueuePropertyID inID,
   void *outData,
   UInt32 *ioDataSize
);

Parameters

inAQ: The audio queue that you want to get a property value from.
inID: The ID of the property whose value you want to get. See “Audio Queue Property Identifiers.”
outData: On output, the desired property value.
ioDataSize: On input, the maximum bytes of space the caller expects to receive. On output, the actual data size of the property value.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Before calling this function, you can use the AudioQueueGetPropertySize function to determine the size, in bytes, of the value of a specified property. Some properties have values of a specific size, as described in “Audio Queue Property Identifiers.”

Special Considerations

Some Core Audio property values are C types and others are Core Foundation objects.

If you call this function to retrieve a value that is a Core Foundation object, then this function—despite the use of “Get” in its name—duplicates the object. You are responsible for releasing the object, as described in “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueGetPropertySize

Gets the size of the value of an audio queue property.

OSStatus AudioQueueGetPropertySize (
   AudioQueueRef inAQ,
   AudioQueuePropertyID inID,
   UInt32 *outDataSize
);

Parameters

inAQ: The audio queue that has the property value whose size you want to get.
inID: The ID of the property value whose size you want to get. See “Audio Queue Property Identifiers.”
outDataSize: On output, the size of the requested property value.

Return Value

A result code. See “Audio Queue Result Codes.”

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueNewInput

Creates a new recording audio queue object.

OSStatus AudioQueueNewInput (
   const AudioStreamBasicDescription  *inFormat,
   AudioQueueInputCallback            inCallbackProc,
   void                               *inUserData,
   CFRunLoopRef                       inCallbackRunLoop,
   CFStringRef                        inCallbackRunLoopMode,
   UInt32                             inFlags,
   AudioQueueRef                      *outAQ
);

Parameters

inFormat: The compressed or uncompressed audio data format to record to. When recording to linear PCM, only interleaved formats are supported.
inCallbackProc: A callback function to use with the recording audio queue. The audio queue calls this function when the audio queue has finished filling a buffer. See AudioQueueInputCallback.
inUserData: A custom data structure for use with the callback function.
inCallbackRunLoop: The event loop on which the callback function pointed to by the inCallbackProc parameter is to be called. If you specify NULL, the callback is called on one of the audio queue’s internal threads.
inCallbackRunLoopMode: The run loop mode in which to invoke the callback function specified in the inCallbackProc parameter. Typically, you pass kCFRunLoopCommonModes or use NULL, which is equivalent. You can choose to create your own thread with your own run loops. For more information on run loops, see Run Loops and CFRunLoop Reference.
inFlags: Reserved for future use. Must be 0.
outAQ: On output, the newly created recording audio queue.

Return Value

A result code. See “Audio Queue Result Codes.”

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueNewOutput

Creates a new playback audio queue object.

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

Parameters

inFormat: The data format of the audio to play. For linear PCM, only interleaved formats are supported. Compressed formats are also supported.
inCallbackProc: A callback function to use with the playback audio queue. The audio queue invokes the callback when the audio queue has finished acquiring a buffer. See AudioQueueOutputCallback.
inUserData: A custom data structure for use with the callback function.
inCallbackRunLoop: The event loop on which the callback function pointed to by the inCallbackProc parameter is to be called. If you specify NULL, the callback is invoked on one of the audio queue’s internal threads.
inCallbackRunLoopMode: The run loop mode in which to invoke the callback function specified in the inCallbackProc parameter. Typically, you pass kCFRunLoopCommonModes or use NULL, which is equivalent. You can choose to create your own thread with your own run loops. For more information on run loops, see Run Loops and CFRunLoop Reference.
inFlags: Reserved for future use. Must be 0.
outAQ: On output, the newly created playback audio queue object.

Return Value

A result code. See “Audio Queue Result Codes.”

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueOfflineRender

Exports audio to a buffer, instead of to a device, using a playback audio queue.

OSStatus AudioQueueOfflineRender (
   AudioQueueRef inAQ,
   const AudioTimeStamp *inTimestamp,
   AudioQueueBufferRef ioBuffer,
   UInt32 inNumberFrames
);

Parameters

inAQ: The playback audio queue.
inTimestamp: The time corresponding to the beginning of the current audio queue buffer. This function uses the mSampleTime field of the AudioTimeStamp data structure.
ioBuffer: On input, a buffer you supply to hold rendered audio data. On output, the rendered audio data, which you can then write to a file.
inRequestedFrames: The number of frames of audio to render.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

When you change a playback audio queue’s rendering mode to offline, using the AudioQueueSetOfflineRenderFormat function, you gain access to the rendered audio. You can then write the audio to a file, rather than have it play to external hardware such as a loudspeaker.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueuePause

Pauses audio playback or recording.

OSStatus AudioQueuePause (
   AudioQueueRef inAQ
);

Parameters

inAQ: The audio queue to pause.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Pausing an audio queue does not affect buffers or reset the audio queue. To resume playback or recording, call AudioQueueStart.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueuePrime

Decodes enqueued buffers in preparation for playback.

OSStatus AudioQueuePrime (
   AudioQueueRef inAQ,
   UInt32 inNumberOfFramesToPrepare,
   UInt32 *outNumberOfFramesPrepared
);

Parameters

inAQ: The audio queue to be primed.
inNumberOfFramesToPrepare: The number of frames to decode before returning. Pass 0 to decode all enqueued buffers.
outNumberOfFramesPrepared: On output, the number of frames actually decoded and prepared for playback. Pass NULL on input if you you are not interested in this information.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

This function decodes enqueued buffers in preparation for playback. It returns when at least the number of audio sample frames specified in inNumberOfFramesToPrepare are decoded and ready to play, or (if you pass 0 for the inNumberOfFramesToPrepare parameter), when all enqueued buffers are decoded.

To make a buffer of audio data ready to play, use AudioQueuePrime as follows:

Call AudioQueueEnqueueBuffer.
Call AudioQueuePrime.
Call AudioQueueStart.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueRemovePropertyListener

Removes a property listener callback from an audio queue.

OSStatus AudioQueueRemovePropertyListener (
   AudioQueueRef inAQ,
   AudioQueuePropertyID inID,
   AudioQueuePropertyListenerProc inProc,
   void *inUserData
);

Parameters

inAQ: The audio queue that you want to remove a property listener callback from.
inID: The ID of the property whose changes you no longer want to respond to. See “Audio Queue Property Identifiers.”
inProc: The callback to be removed.
inUserData: The same custom data for the property listener callback that you passed when calling AudioQueueAddPropertyListener.

Return Value

A result code. See “Audio Queue Result Codes.”

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueReset

Resets an audio queue.

OSStatus AudioQueueReset (
   AudioQueueRef inAQ
);

Parameters

inAQ: The audio queue to reset.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

This function immediately resets an audio queue, flushes any queued buffers (invoking callbacks as necessary), removes all buffers from previously scheduled use, and resets decoder and digital signal processing (DSP) state.

If you queue buffers after calling this function, processing does not begin until the decoder and DSP state of the audio queue are reset. This might create an audible discontinuity (or “glitch”).

This function is called automatically when you call AudioQueueStop.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueSetOfflineRenderFormat

Sets the rendering mode and audio format for a playback audio queue.

OSStatus AudioQueueSetOfflineRenderFormat (
   AudioQueueRef inAQ,
   const AudioStreamBasicDescription *inFormat,
   const AudioChannelLayout *inLayout
);

Parameters

inAQ

The playback audio queue whose rendering mode and audio format you want to set.

inFormat

The audio format for offline rendering. The format must be some sort of linear PCM. If the format has more than one channel, it must be interleaved. For more information on the AudioStreamBasicDescription structure, see Core Audio Data Types Reference.

Pass NULL to disable offline rendering and return the audio queue to normal output to an audio device.

inLayout

The channel layout for offline rendering. For more information on the AudioChannelLayout structure, see Core Audio Data Types Reference.

Pass NULL when using this function to disable offline rendering.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Use this function to set a playback audio queue to perform offline rendering, such as for export to an audio file. In offline rendering mode, a playback audio queue does not connect to external hardware.

You can also use this function to restore an audio queue to normal rendering mode by passing NULL in the inFormat and inLayout parameters.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueSetParameter

Sets a playback audio queue parameter value.

OSStatus AudioQueueSetParameter (
   AudioQueueRef inAQ,
   AudioQueueParameterID inParamID,
   AudioQueueParameterValue inValue
);

Parameters

inAQ: The playback audio queue that you want to set a parameter value on.
inParamID: The ID of the parameter you want to set. In OS X v10.5, audio queues have one parameter available: kAudioQueueParam_Volume, which controls playback gain. See “Audio Queue Parameters.”
inValue: The parameter value to set.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

Use this function to change the settings for a playback audio queue directly. Changes take effect immediately. To set playback gain at the granularity of an audio queue buffer, use the AudioQueueEnqueueBufferWithParameters function.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueSetProperty

Sets an audio queue property value.

OSStatus AudioQueueSetProperty (
   AudioQueueRef inAQ,
   AudioQueuePropertyID inID,
   const void *inData,
   UInt32 inDataSize
);

Parameters

inAQ: The audio queue that you want to set a property value on.
inID: The ID of the property whose value you want to set. See “Audio Queue Property Identifiers.”
inData: The property value to set.
inDataSize: The size of the property data.

Return Value

A result code. See “Audio Queue Result Codes.”

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueStart

Begins playing or recording audio.

OSStatus AudioQueueStart (
   AudioQueueRef inAQ,
   const AudioTimeStamp *inStartTime
);

Parameters

inAQ

The audio queue to start.

inDeviceStartTime

The time at which the audio queue should start.

To specify a start time relative to the timeline of the associated audio device, use the mSampleTime field of the AudioTimeStamp structure. Use NULL to indicate that the audio queue should start as soon as possible.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

If the associated audio device is not already running, this function starts it.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

AudioQueueStop

Stops playing or recording audio.

OSStatus AudioQueueStop (
   AudioQueueRef inAQ,
   Boolean inImmediate
);

Parameters

inAQ: The audio queue to stop.
inImmediate: If you pass true, stopping occurs immediately (that is, synchronously). If you pass false, the function returns immediately, but the audio queue does not stop until its queued buffers are played or recorded (that is, the stop occurs asynchronously). Audio queue callbacks are invoked as necessary until the queue actually stops.

Return Value

A result code. See “Audio Queue Result Codes.”

Discussion

This function resets an audio queue, stops the audio hardware associated with the queue if it is not in use by other audio services, and stops the audio queue. When recording, this function is typically invoked by a user. When playing back, a playback audio queue callback should call this function when there is no more audio to play.

Availability

Available in OS X v10.5 and later.

Related Sample Code

AudioQueueTools

Declared In

AudioQueue.h

Callbacks by Task

Handling Audio Queue Buffers for Recording and Playback

Defining a Property Listener

Callbacks

AudioQueueInputCallback

Called by the system when a recording audio queue has finished filling an audio queue buffer.

typedef void (*AudioQueueInputCallback) (
   void                                *inUserData,
   AudioQueueRef                       inAQ,
   AudioQueueBufferRef                 inBuffer,
   const AudioTimeStamp                *inStartTime,
   UInt32                              inNumberPacketDescriptions,
   const AudioStreamPacketDescription  *inPacketDescs
);

If you name your callback function MyAudioQueueInputCallback, you would declare it like this:

void MyAudioQueueInputCallback (
   void                                *inUserData,
   AudioQueueRef                       inAQ,
   AudioQueueBufferRef                 inBuffer,
   const AudioTimeStamp                *inStartTime,
   UInt32                              inNumberPacketDescriptions,
   const AudioStreamPacketDescription  *inPacketDescs
);

Parameters

inUserData: The custom data you’ve specified in the inUserData parameter of the AudioQueueNewInput function. Typically, this includes format and state information for the audio queue.
inAQ: The recording audio queue that invoked the callback.
inBuffer: An audio queue buffer, newly filled by the recording audio queue, containing the new audio data your callback needs to write.
inStartTime: The sample time for the start of the audio queue buffer. This parameter is not used in basic recording.
inNumberPacketDescriptions: The number of packets of audio data sent to the callback in the inBuffer parameter. When recording in a constant bit rate (CBR) format, the audio queue sets this parameter to NULL.
inPacketDescs: For compressed formats that require packet descriptions, the set of packet descriptions produced by the encoder for audio data in the inBuffer parameter. When recording in a CBR format, the audio queue sets this parameter to NULL.

Discussion

You specify a recording audio queue callback when calling the AudioQueueNewInput function. The callback is invoked each time its recording audio queue has filled an audio queue buffer with fresh audio data. Typically, your callback writes the data to a file or other buffer, and then reenqueues the audio queue buffer to receive more data.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueOutputCallback

Called by the system when an audio queue buffer is available for reuse.

typedef void (*AudioQueueOutputCallback) (
   void                 *inUserData,
   AudioQueueRef        inAQ,
   AudioQueueBufferRef  inBuffer
);

If you name your callback function MyAudioQueueOutputCallback, you would declare it like this:

void MyAudioQueueOutputCallback (
   void                 *inUserData,
   AudioQueueRef        inAQ,
   AudioQueueBufferRef  inBuffer
);

Parameters

inUserData: The custom data you’ve specified in the inUserData parameter of the AudioQueueNewOutput function. Typically, this includes data format and state information for the audio queue.
inAQ: The playback audio queue that invoked the callback.
inBuffer: An audio queue buffer, newly available to fill because the playback audio queue has acquired its contents.

Discussion

This callback function is invoked each time its associated playback audio queue has acquired the data from an audio queue buffer, at which point the buffer is available for reuse. The newly-available buffer is sent to this callback in the inBuffer parameter. Typically, you write this callback to:

Fill the newly-available buffer with the next set of audio data from a file or other buffer.
Reenqueue the buffer for playback. To reenqueue a buffer, use the AudioQueueEnqueueBuffer or AudioQueueEnqueueBufferWithParameters function.

To associate this callback with a playback audio queue, provide a reference to the callback as you are creating the audio queue. See the inCallbackProc parameter of the AudioQueueNewOutput function.

When the system invokes this callback, you cannot assume that the audio data from the newly-available buffer has been played. For a description of how to check that a sound has finished playing, read the Discussion for the AudioQueuePropertyListenerProc callback function.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueuePropertyListenerProc

Called by the system when a specified audio queue property changes value.

typedef void (*AudioQueuePropertyListenerProc) (
   void                  *inUserData,
   AudioQueueRef         inAQ,
   AudioQueuePropertyID  inID
);

If you name your callback function MyAudioQueuePropertyListenerProc, you would declare it like this:

void MyAudioQueuePropertyListenerProc (
   void                  *inUserData,
   AudioQueueRef         inAQ,
   AudioQueuePropertyID  inID
);

Parameters

inUserData: The custom data you’ve specified in the inUserData parameter of the AudioQueueAddPropertyListener function.
inAQ: The recording or playback audio queue that invoked the callback.
inID: The ID of the property whose value changes you want to observe.

Discussion

Install this callback in an audio queue by calling the AudioQueueAddPropertyListener function. For example, say you want your application to be notified, after you call the AudioQueueStop function with the inImmedate parameter set to false, that audio has finished playing. Perform these steps:

Define this property listener callback function to listen for changes to the kAudioQueueProperty_IsRunning property.
Install this callback, using the AudioQueueAddPropertyListener function, in the playback audio queue that you want to monitor.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

Data Types

AudioQueueBuffer

Defines an audio queue buffer.

typedef struct AudioQueueBuffer {
   const UInt32                 mAudioDataBytesCapacity;
   void                         *const mAudioData;
   UInt32                       mAudioDataByteSize;
   void                         *mUserData;
   const UInt32                 mPacketDescriptionCapacity;
   AudioStreamPacketDescription *const mPacketDescriptions;
   UInt32                       mPacketDescriptionCount;
} AudioQueueBuffer;
typedef AudioQueueBuffer *AudioQueueBufferRef;

Fields

mAudioDataBytesCapacity: The size of the audio queue buffer, in bytes. This size is set when an buffer is allocated and cannot be changed.
mAudioData: The audio data owned the audio queue buffer. The buffer address cannot be changed.
mAudioDataByteSize: The number of bytes of valid audio data in the audio queue buffer’s mAudioData field, initially set to 0. Your callback must set this value for a playback audio queue; for recording, the recording audio queue sets the value.
mUserData: The custom data structure you specify, for use by your callback function, when creating a recording or playback audio queue.
mPacketDescriptionCapacity: The maximum number of packet descriptions that can be stored in the mPacketDescriptions field.
mPacketDescriptions: An array of AudioStreamPacketDescription structures for the buffer.
mPacketDescriptionCount: The number of valid packet descriptions in the buffer. You set this value when providing buffers for playback. The audio queue sets this value when returning buffers from a recording queue.

Discussion

Each audio queue has an associated set of audio queue buffers. To allocate a buffer, call the AudioQueueAllocateBuffer function. To dispose of a buffer, call the AudioQueueFreeBuffer function.

If using a VBR compressed audio data format, you may want to instead use the AudioQueueAllocateBufferWithPacketDescriptions function. This function allocates a buffer with additional space for packet descriptions. The mPacketDescriptionCapacity, mPacketDescriptions, and mPacketDescriptionCount fields may only be used with buffers allocated with AudioQueueAllocateBufferWithPacketDescriptions.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueBufferRef

A pointer to an audio queue buffer.

typedef AudioQueueBuffer *AudioQueueBufferRef;

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueRef

Defines an opaque data type that represents an audio queue.

typedef struct OpaqueAudioQueue *AudioQueueRef;

Discussion

An audio queue is a software object you use for recording or playing audio in OS X. It does the work of:

Connecting to audio hardware
Managing memory
Employing codecs, as needed, for compressed audio formats
Mediating recording or playback

You create, use, and dispose of audio queues using the functions described in “Audio Queue Functions.”

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueTimelineRef

Defines an opaque data type that represents an audio queue timeline object.

typedef struct OpaqueAudioQueueTimeline *AudioQueueTimelineRef;

Discussion

You can use a timeline object to observe time discontinuities in the audio hardware device associated with an audio queue. A discontinuity is, for example, a period of silence when sound was expected. Causes of discontinuities include changes in device state or data processing overloads. See Technical Q&A 1467, CoreAudio Overload Warnings. You query a timeline object by passing it as a parameter to the AudioQueueGetCurrentTime function.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueLevelMeterState

Specifies the current level metering information for one channel of an audio queue..

typedef struct AudioQueueLevelMeterState {
   Float32     mAveragePower;
   Float32     mPeakPower;
};  AudioQueueLevelMeterState;

Fields

mAveragePower: The audio channel's average RMS power.
mPeakPower: The audio channel's peak RMS power.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueParameterEvent

Specifies an audio queue parameter and associated value.

struct AudioQueueParameterEvent {
   AudioQueueParameterID     mID;
   AudioQueueParameterValue  mValue;
};  typedef struct AudioQueueParameterEvent AudioQueueParameterEvent;

Fields

mID: The parameter.
mValue: The value of the specified parameter.

Discussion

You use this structure with the AudioQueueEnqueueBufferWithParameters function. See that function, and “Audio Queue Parameters,” for more information.

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueParameterID

A UInt32 value that uniquely identifies an audio queue parameter.

typedef UInt32 AudioQueueParameterID;

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

AudioQueueParameterValue

A Float32 value for an audio queue parameter.

typedef Float32 AudioQueueParameterValue;

Availability

Available in OS X v10.5 and later.

Declared In

AudioQueue.h

Constants

Audio Queue Property Identifiers

Identifiers for audio queue properties.

enum {
   kAudioQueueProperty_IsRunning               = 'aqrn',
   kAudioQueueDeviceProperty_SampleRate        = 'aqsr',
   kAudioQueueDeviceProperty_NumberChannels    = 'aqdc',
   kAudioQueueProperty_CurrentDevice           = 'aqcd',
   kAudioQueueProperty_MagicCookie             = 'aqmc',
   kAudioQueueProperty_MaximumOutputPacketSize = 'xops',
   kAudioQueueProperty_StreamDescription       = 'aqft',
   kAudioQueueProperty_ChannelLayout           = 'aqcl',
   kAudioQueueProperty_EnableLevelMetering     = 'aqme',
   kAudioQueueProperty_CurrentLevelMeter       = 'aqmv',
   kAudioQueueProperty_CurrentLevelMeterDB     = 'aqmd',
   kAudioQueueProperty_DecodeBufferSizeFrames  = 'dcbf',
   kAudioQueueProperty_ConverterError          = 'qcve'
};
typedef UInt32 AudioQueuePropertyID;

Constants

kAudioQueueProperty_IsRunning

Value is a read-only UInt32 value indicating whether or not the audio queue is running. A nonzero value means running; 0 means stopped. A notification is sent when the associated audio queue starts or stops, which may occur sometime after the AudioQueueStart or AudioQueueStop function is called.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueDeviceProperty_SampleRate

Value is a read-only Float64 value representing the sampling rate of the audio hardware device associated with an audio queue.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueDeviceProperty_NumberChannels

Value is a read-only UInt32 value representing the number of channels in the audio hardware device associated with an audio queue.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_CurrentDevice

Value is a read-write CFStringRef object representing the unique identifier (UID) of the audio hardware device associated with an audio queue.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_MagicCookie

Value is a read/write void pointer to a block of memory, which you set up, containing an audio format magic cookie. If the audio format you are playing or recording to requires a magic cookie, you must set a value for this property before enqueuing any buffers.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_MaximumOutputPacketSize

Value is a read-onlyUInt32 value that is the size, in bytes, of the largest single packet of data in the output format. Primarily useful when encoding VBR compressed data.

Available in OS X v10.6 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_StreamDescription

Value is a read-only AudioStreamBasicDescription structure, indicating an audio queue’s data format. Primarily useful for obtaining a complete ASBD when recording, in cases where you initially specify a sample rate of 0.

Available in OS X v10.6 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_ChannelLayout

Value is a read/write AudioChannelLayout structure that describes an audio queue channel layout. The number of channels in the layout must match the number of channels in the audio format. This property is typically not used in the case of one or two channel audio. For more than two channels (such as in the case of 5.1 surround sound), you may need to specify a channel layout to indicate channel order, such as left, then center, then right.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_EnableLevelMetering

Value is a read/write UInt32 value that indicates whether audio level metering is enabled for an audio queue. 0 = metering off, 1 = metering on.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_CurrentLevelMeter

Value is a read-only array of AudioQueueLevelMeterState structures, one array element per audio channel. The member values in the structure are in the range 0 (for silence) to 1 (indicating maximum level).

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_CurrentLevelMeterDB

Value is a read-only array of AudioQueueLevelMeterState structures, one array element per audio channel. The member values in the structure are in decibels.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_DecodeBufferSizeFrames

Value is a read/write UInt32 value that is the size of the buffer into which a playback (output) audio queue decodes buffers. A larger buffer provides more reliability and better long-term performance at the expense of memory and decreased responsiveness in some situations.

Available in OS X v10.6 and later.

Declared in AudioQueue.h.

kAudioQueueProperty_ConverterError

Value is a read-only UInt32 value that indicates the most recent error (if any) encountered by the audio queue’s internal encoding/decoding process.

Available in OS X v10.8 and later.

Declared in AudioQueue.h.

Discussion

To receive a notification that a specific audio queue property has changed:

Define a property listener callback, referencing the desired audio queue property ID. Base the callback on the AudioQueuePropertyListenerProc callback function declaration.
Assign the callback to an audio queue using the AudioQueueAddPropertyListener function.
When you get a property-changed notification, call the AudioQueueGetProperty function to get the current value of the property.

Declared In

AudioQueue.h

Audio Queue Parameters

Identifiers for audio queue parameters.

enum {
   kAudioQueueParam_Volume          = 1
   kAudioQueueParam_PlayRate        = 2,
   kAudioQueueParam_Pitch           = 3,
   kAudioQueueParam_VolumeRampTime  = 4,
   kAudioQueueParam_Pan             = 13
};
typedef UInt32 AudioQueueParameterID;

Constants

kAudioQueueParam_Volume

The linearly scaled gain for the audio queue, in the range 0.0 through 1.0. A value of 1.0 (the default) indicates unity gain. A value of 0.0 indicates zero gain, or silence.

Available in OS X v10.5 and later.

Declared in AudioQueue.h.

kAudioQueueParam_PlayRate

The playback rate for the audio queue, in the range 0.5 through 2.0. A value of 1.0 (the default) specifies that the audio queue should play at its normal rate.

This parameter is usable only if the time-pitch processor is enabled.

Available in OS X v10.6 and later.

Declared in AudioQueue.h.

kAudioQueueParam_Pitch

The number of cents to pitch-shift the audio queue’s playback, in the range -2400 through 2400 cents (where 1200 cents corresponds to one musical octave.)

This parameter is usable only if the time/pitch processor is enabled.

Available in OS X v10.6 and later.

Declared in AudioQueue.h.

kAudioQueueParam_VolumeRampTime

The number of seconds over which a volume change is ramped.

For example, to fade from unity gain down to silence over the course of 1 second, set this parameter to 1 and then set the kAudioQueueParam_Volume parameter to 0.

Available in OS X v10.7 and later.

Declared in AudioQueue.h.

kAudioQueueParam_Pan

The stereo panning position of a source. For a monophonic source, panning is determined as follows:

–1 = hard left
0 = center
+1 = hard right

For a stereophonic source, this parameter affects the left/right balance. For a multichannel source, this parameter has no effect.

Available in OS X v10.7 and later.

Declared in AudioQueue.h.

Discussion

These parameters apply only to playback audio queues. You can set a playback audio queue parameter in one of two ways:

Set the value to take effect immediately using the AudioQueueSetParameter function.
Schedule a value to take effect when a particular audio queue buffer plays. You supply the parameter when you enqueue the buffer. The new value is applied to the audio queue that owns the buffer when that buffer is rendered.

The AudioQueueGetParameter function always returns the current value of the parameter for an audio queue.

Declared In

AudioQueue.h

Result Codes

This table lists result codes defined for Audio Queue Services.

Result Code	Value	Description
`kAudioQueueErr_InvalidBuffer`	-66687	The specified audio queue buffer does not belong to the specified audio queue. Available in OS X v10.5 and later.
`kAudioQueueErr_BufferEmpty`	-66686	The audio queue buffer is empty (that is, the `mAudioDataByteSize` field = `0`). Available in OS X v10.5 and later.
`kAudioQueueErr_DisposalPending`	-66685	The function cannot act on the audio queue because it is being asynchronously disposed of. Available in OS X v10.5 and later.
`kAudioQueueErr_InvalidProperty`	-66684	The specified property ID is invalid. Available in OS X v10.5 and later.
`kAudioQueueErr_InvalidPropertySize`	-66683	The size of the specified property is invalid. Available in OS X v10.5 and later.
`kAudioQueueErr_InvalidParameter`	-66682	The specified parameter ID is invalid. Available in OS X v10.5 and later.
`kAudioQueueErr_CannotStart`	-66681	The audio queue has encountered a problem and cannot start. Available in OS X v10.5 and later.
`kAudioQueueErr_InvalidDevice`	-66680	The specified audio hardware device could not be located. Available in OS X v10.5 and later.
`kAudioQueueErr_BufferInQueue`	-66679	The audio queue buffer cannot be disposed of when it is enqueued. Available in OS X v10.5 and later.
`kAudioQueueErr_InvalidRunState`	-66678	The queue is running but the function can only operate on the queue when it is stopped, or vice versa. Available in OS X v10.5 and later.
`kAudioQueueErr_InvalidQueueType`	-66677	The queue is an input queue but the function can only operate on an output queue, or vice versa. Available in OS X v10.5 and later.
`kAudioQueueErr_Permissions`	-66676	You do not have the required permissions to call the function. Available in OS X v10.6 and later.
`kAudioQueueErr_InvalidPropertyValue`	-66675	The property value used is not valid. Available in OS X v10.6 and later.
`kAudioQueueErr_PrimeTimedOut`	-66674	During a call to the `AudioQueuePrime` function, the audio queue’s audio converter failed to convert the requested number of sample frames. Available in OS X v10.6 and later.
`kAudioQueueErr_CodecNotFound`	-66673	The requested codec was not found. Available in OS X v10.6 and later.
`kAudioQueueErr_InvalidCodecAccess`	-66672	The codec could not be accessed. Available in OS X v10.7 and later.
`kAudioQueueErr_QueueInvalidated`	-66671	In iPhone OS, the audio server has exited, causing the audio queue to become invalid. Available in OS X v10.7 and later.
`kAudioQueueErr_RecordUnderrun`	-66668	During recording, data was lost because there was no enqueued buffer to store it in. Available in OS X v10.8 and later.
`kAudioQueueErr_EnqueueDuringReset`	-66632	During a call to the `AudioQueueReset`, `AudioQueueStop`, or `AudioQueueDispose` functions, the system does not allow you to enqueue buffers. Available in OS X v10.6 and later.
`kAudioQueueErr_InvalidOfflineMode`	-66626	The operation requires the audio queue to be in offline mode but it isn’t, or vice versa. To use offline mode or to return to normal mode, use the `AudioQueueSetOfflineRenderFormat` function. Available in OS X v10.7 and later.
`kAudioFormatUnsupportedDataFormatError`	1718449215 = ‘fmt?’	The playback data format is unsupported (declared in `AudioFormat.h`). Available in OS X v10.3 and later.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Audio Queue Services Reference

Overview

Functions by Task

Controlling Audio Queues

Creating and Disposing of Audio Queues

Handling Audio Queue Buffers

Manipulating Audio Queue Parameters

Manipulating Audio Queue Properties

Handling Timing

Performing Offline Rendering

Functions

AudioQueueAddPropertyListener

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

AudioQueueAllocateBuffer

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

AudioQueueAllocateBufferWithPacketDescriptions

Parameters

Return Value

Discussion

Availability

See Also

Declared In

AudioQueueCreateTimeline

Parameters

Return Value

Discussion

Availability

See Also

Declared In

AudioQueueDeviceGetCurrentTime

Parameters

Return Value

Discussion

Availability

See Also

Declared In

AudioQueueDeviceGetNearestStartTime

Parameters

Return Value

Discussion

Availability

See Also

Declared In

AudioQueueDeviceTranslateTime

Parameters

Return Value

Discussion

Availability

Declared In

AudioQueueDispose

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

AudioQueueDisposeTimeline

Parameters

Return Value

Discussion

Availability

See Also

Declared In

AudioQueueEnqueueBuffer

Parameters

Return Value

Discussion