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

func AudioQueuePrime(AudioQueueRef, UInt32, UnsafeMutablePointer<UInt32>?)

Decodes enqueued buffers in preparation for playback.

func AudioQueueFlush(AudioQueueRef)

Resets an audio queue’s decoder state.

func AudioQueueStop(AudioQueueRef, Bool)

Stops playing or recording audio.

func AudioQueuePause(AudioQueueRef)

Pauses audio playback or recording.

Handling Timing

func AudioQueueDisposeTimeline(AudioQueueRef, AudioQueueTimelineRef)

Disposes of an audio queue’s timeline object.

func AudioQueueDeviceGetCurrentTime(AudioQueueRef, UnsafeMutablePointer<AudioTimeStamp>)

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

func AudioQueueDeviceGetNearestStartTime(AudioQueueRef, UnsafeMutablePointer<AudioTimeStamp>, UInt32)

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

func AudioQueueDeviceTranslateTime(AudioQueueRef, UnsafePointer<AudioTimeStamp>, UnsafeMutablePointer<AudioTimeStamp>)

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

Performing Offline Rendering

Callbacks

typealias AudioQueueInputCallback

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

typealias AudioQueueOutputCallback

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

typealias AudioQueuePropertyListenerProc

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

Data Types

struct AudioQueueBuffer

Defines an audio queue buffer.

typealias AudioQueueBufferRef

A pointer to an audio queue buffer.

typealias AudioQueueRef

Defines an opaque data type that represents an audio queue.

typealias AudioQueueTimelineRef

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

struct AudioQueueLevelMeterState

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

struct AudioQueueParameterEvent

Specifies an audio queue parameter and associated value.

typealias AudioQueueParameterID

A UInt32 value that uniquely identifies an audio queue parameter.

typealias AudioQueueParameterValue

A Float32 value for an audio queue parameter.

Constants

typealias 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.

var kAudioQueueErr_InvalidBuffer: OSStatus

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

var kAudioQueueErr_BufferEmpty: OSStatus

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

var kAudioQueueErr_DisposalPending: OSStatus

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

var kAudioQueueErr_InvalidProperty: OSStatus

The specified property ID is invalid.

var kAudioQueueErr_InvalidPropertySize: OSStatus

The size of the specified property is invalid.

var kAudioQueueErr_InvalidParameter: OSStatus

The specified parameter ID is invalid.

var kAudioQueueErr_CannotStart: OSStatus

The audio queue has encountered a problem and cannot start.

var kAudioQueueErr_InvalidDevice: OSStatus

The specified audio hardware device could not be located.

var kAudioQueueErr_BufferInQueue: OSStatus

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

var kAudioQueueErr_InvalidRunState: OSStatus

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

var kAudioQueueErr_InvalidQueueType: OSStatus

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

var kAudioQueueErr_Permissions: OSStatus

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

var kAudioQueueErr_InvalidPropertyValue: OSStatus

The property value used is not valid.

var kAudioQueueErr_PrimeTimedOut: OSStatus

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

var kAudioQueueErr_CodecNotFound: OSStatus

The requested codec was not found.

var kAudioQueueErr_InvalidCodecAccess: OSStatus

The codec could not be accessed.

var kAudioQueueErr_QueueInvalidated: OSStatus

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

var kAudioQueueErr_RecordUnderrun: OSStatus

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

var kAudioQueueErr_EnqueueDuringReset: OSStatus

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

var kAudioQueueErr_InvalidOfflineMode: OSStatus

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

var kAudioFormatUnsupportedDataFormatError: OSStatus

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