Audio Queue Services

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.

Topics

Controlling Audio Queues

AudioQueueStart

Begins playing or recording audio.

AudioQueuePrime

Decodes enqueued buffers in preparation for playback.

AudioQueueFlush

Resets an audio queue’s decoder state.

AudioQueueStop

Stops playing or recording audio.

AudioQueuePause

Pauses audio playback or recording.

AudioQueueReset

Resets an audio queue.

Creating and Disposing of Audio Queues

AudioQueueNewOutput

Creates a new playback audio queue object.

AudioQueueNewInput

Creates a new recording audio queue object.

AudioQueueDispose

Disposes of an audio queue.

Handling Audio Queue Buffers

AudioQueueAllocateBuffer

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

AudioQueueAllocateBufferWithPacketDescriptions

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

AudioQueueFreeBuffer

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

AudioQueueEnqueueBuffer

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

AudioQueueEnqueueBufferWithParameters

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

Manipulating Audio Queue Parameters

AudioQueueGetParameter

Gets an audio queue parameter value.

AudioQueueSetParameter

Sets a playback audio queue parameter value.

Manipulating Audio Queue Properties

AudioQueueGetProperty

Gets an audio queue property value.

AudioQueueSetProperty

Sets an audio queue property value.

AudioQueueGetPropertySize

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

AudioQueueAddPropertyListener

Adds a property listener callback to an audio queue.

AudioQueueRemovePropertyListener

Removes a property listener callback from an audio queue.

Handling Timing

AudioQueueCreateTimeline

Creates a timeline object for an audio queue.

AudioQueueDisposeTimeline

Disposes of an audio queue’s timeline object.

AudioQueueDeviceGetCurrentTime

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

AudioQueueDeviceGetNearestStartTime

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

AudioQueueDeviceTranslateTime

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

AudioQueueGetCurrentTime

Gets the current audio queue time.

Performing Offline Rendering

AudioQueueSetOfflineRenderFormat

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

AudioQueueOfflineRender

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

Callbacks

AudioQueueInputCallback

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

AudioQueueOutputCallback

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

AudioQueuePropertyListenerProc

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

Data Types

AudioQueueBuffer

Defines an audio queue buffer.

AudioQueueBufferRef

A pointer to an audio queue buffer.

AudioQueueRef

Defines an opaque data type that represents an audio queue.

AudioQueueTimelineRef

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

AudioQueueLevelMeterState

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

AudioQueueParameterEvent

Specifies an audio queue parameter and associated value.

AudioQueueParameterID

A UInt32 value that uniquely identifies an audio queue parameter.

AudioQueueParameterValue

A Float32 value for an audio queue parameter.

Constants

AudioQueuePropertyID

Identifiers for audio queue properties.

Audio Queue Parameters

Identifiers for audio queue parameters.

Hardware Codec Policy Keys

Indicates how an audio queue should choose between hardware and software implementations of a codec.

Result Codes

This table lists result codes defined for Audio Queue Services.

kAudioQueueErr_InvalidBuffer

The specified audio queue buffer does not belong to the specified audio queue.

kAudioQueueErr_BufferEmpty

The audio queue buffer is empty (that is, the mAudioDataByteSize field = 0).

kAudioQueueErr_DisposalPending

The function cannot act on the audio queue because it is being asynchronously disposed of.

kAudioQueueErr_InvalidProperty

The specified property ID is invalid.

kAudioQueueErr_InvalidPropertySize

The size of the specified property is invalid.

kAudioQueueErr_InvalidParameter

The specified parameter ID is invalid.

kAudioQueueErr_CannotStart

The audio queue has encountered a problem and cannot start.

kAudioQueueErr_InvalidDevice

The specified audio hardware device could not be located.

kAudioQueueErr_BufferInQueue

The audio queue buffer cannot be disposed of when it is enqueued.

kAudioQueueErr_InvalidRunState

The queue is running but the function can only operate on the queue when it is stopped, or vice versa.

kAudioQueueErr_InvalidQueueType

The queue is an input queue but the function can only operate on an output queue, or vice versa.

kAudioQueueErr_Permissions

You do not have the required permissions to call the function.

kAudioQueueErr_InvalidPropertyValue

The property value used is not valid.

kAudioQueueErr_PrimeTimedOut

During a call to the AudioQueuePrime function, the audio queue’s audio converter failed to convert the requested number of sample frames.

kAudioQueueErr_CodecNotFound

The requested codec was not found.

kAudioQueueErr_InvalidCodecAccess

The codec could not be accessed.

kAudioQueueErr_QueueInvalidated

In iOS, the audio server has exited, causing the audio queue to become invalid.

kAudioQueueErr_RecordUnderrun

During recording, data was lost because there was no enqueued buffer to store it in.

kAudioQueueErr_EnqueueDuringReset

During a call to the AudioQueueReset, AudioQueueStop, or AudioQueueDispose functions, the system does not allow you to enqueue buffers.

kAudioQueueErr_InvalidOfflineMode

The operation requires the audio queue to be in offline mode but it isn’t, or vice versa.

kAudioFormatUnsupportedDataFormatError

The playback data format is unsupported (declared in AudioFormat.h).