Audio File Stream Services Reference

Audio File Stream Services provides the interface for parsing streamed audio files—in which only a limited window of data is available at a time.

Audio file streams, by nature, are not random access. When you request data from a stream, earlier data might no longer be accessible and later data might not yet be available. In addition, the data you obtain (and then provide to a parser) might include partial packets. To parse streamed audio data, then, a parser must remember data from partially satisfied requests, and must be able to wait for the remainder of that data. In other words, a parser must be able to suspend parsing as needed and then resume where it left off.

To use a parser, you pass data from a streamed audio file, as you acquire it, to the parser. When the parser has a complete packet of audio data or a complete property, it invokes a callback function. Your callbacks then process the parsed data—such as by playing it or writing it to disk.

Here, in outline form, is a typical usage pattern for an audio file stream parser:

Parameters

inClientData

A pointer to a value or structure to be passed to your callback functions.

inPropertyListenerProc

Your property-listener callback. Whenever the parser finds the value of a property in the data stream, it calls your property listener with the property ID. You can then call the AudioFileStreamGetPropertyInfo and AudioFileStreamGetProperty functions to get the value of the property.

An audio file type hint. If the audio file stream that you intend to pass to the parser is of a type that the parser cannot easily or uniquely determine from the data (such as ADTS or AC3), you can use this parameter to indicate the type. Possible values are listed in the Built-In Audio File Types enumeration in Audio File Services Reference.

If you do not know the audio file type, pass 0.

outAudioFileStream

On output, an opaque object representing the audio file stream parser. This object is referred to in this document as the audio file stream parser ID. You need to pass this ID in to other functions in the Audio File Stream API.

Return Value

Discussion

Streamed audio file data is expected to be passed to the parser in the same sequence in which it appears in the audio file, from the beginning of the audio file stream, without gaps. However, if you called the AudioFileStreamSeek function, the parser assumes that the data passed to the AudioFileStreamParseBytes function starts from the byte offset returned by the AudioFileStreamSeek function.

When you provide data to the parser, the parser looks for property data and audio data packets and, when it has data ready, calls your AudioFileStream_PropertyListenerProc and AudioFileStream_PacketsProc callback functions to process the data. You should provide at least more than a single packet’s worth of audio file data, but it is better to provide a few packets to a few seconds data at a time.

Parameters

The ID of the parser to which you wish to provide a byte offset. The parser ID is returned by the AudioFileStreamOpen function.

inAbsolutePacketOffset

The number of packets from the beginning of the file of the packet whose byte offset you wish to have returned.

outAbsoluteByteOffset

On output, the absolute byte offset of the packet whose offset you specify in the inAbsolutePacketOffset parameter. For audio file formats that do not contain packet tables, the returned offset may be an estimate.

ioFlags

On output, if the outAbsoluteByteOffset parameter returns an estimate, this parameter returns the constant kAudioFileStreamSeekFlag_OffsetIsEstimated. Currently, no input flags are defined for this call.

On input, the size of the buffer in the outPropertyData parameter. Call the AudioFileStreamGetPropertyInfo function to obtain the size of the property value. On output, the number of bytes of the property value returned.

Parameters

The value you provided in the inClientData parameter when you called the AudioFileStreamOpenfunction.

inAudioFileStream

The ID of the audio file stream parser that invoked the callback. The parser ID is returned by the AudioFileStreamOpen function.

inPropertyID

The four-character ID of the property that the parser found in the audio file data stream. See Audio File Stream Properties for possible values.

ioFlags

On input, if the kAudioFileStreamPropertyFlag_PropertyIsCached value is set, the parser is caching the property value. If not, on output you can set the kAudioFileStreamPropertyFlag_CacheProperty flag to cause the parser to cache the value. See Audio File Stream Flags.

Discussion

When the parser calls your property listener, check the ioFlags value to see if the property value is being cached. If not, you can call the AudioFileStreamGetPropertyInfo and AudioFileStreamGetProperty functions to obtain the value of the property from inside the property listener, or you can set the kAudioFileStreamPropertyFlag_CacheProperty flag on return to cause the parser to cache the value.

In some cases when you call the AudioFileStreamGetProperty function from inside the property listener, because of boundaries in the input data, the parser returns the result code “kAudioFileStreamError_DataUnavailable” indicating the value is not yet available. When unavailable data is requested from within the property listener, the parser begins caching the property value and calls the property listener again when the property value is available. If the kAudioFileStreamPropertyFlag_PropertyIsCached flag is not set, this is your only opportunity to get the value of the property, as the data is disposed of when the property listener callback returns.

Discussion

For constant-bit-rate (CBR) audio data, your callback is typically called with as much data as you passed to the AudioFileStreamParseBytes function. At times, however, only a single packet might be passed because of boundaries in the input data. For variable-bit-rate (VBR) audio data, your callback might be called several times for each time you called the AudioFileStreamParseBytes function.

If this flag is not set, get the value of the property from within this callback or set the kAudioFileStreamPropertyFlag_CacheProperty flag to instruct the parser to begin caching the property data. Otherwise, the value will not be available after the callback returns.

Available in OS X v10.5 and later.

kAudioFileStreamPropertyFlag_CacheProperty

kAudioFileStreamPropertyFlag_CacheProperty

A property listener sets this flag to instruct the parser to cache the property value so that it remains available after the callback returns.

Any partial packet straddling a buffer boundary is discarded to avoid having the parser call your callback with a corrupt packet. After a discontinuity occurs, the AudioFileStreamSeek function might return approximate values for some data formats.

Available in OS X v10.5 and later.

kAudioFileStreamSeekFlag_OffsetIsEstimated

kAudioFileStreamSeekFlag_OffsetIsEstimated

This flag is returned by the AudioFileStreamSeek function if the byte offset is only an estimate.

Constants

kAudioFileStreamProperty_ReadyToProducePackets

kAudioFileStreamProperty_ReadyToProducePackets

A UInt32 value that is 0 until the parser has parsed up to the beginning of the audio data. Once the parser has reached the audio data, the value of this property is set to 1, at which point all the audio file stream properties that can be known are known.

An AudioStreamBasicDescription structure describing the format of the audio data in the stream. For more information on audio stream basic descriptions, see Core Audio Data Types Reference.

Available in OS X v10.5 and later.

kAudioFileStreamProperty_FormatList

kAudioFileStreamProperty_FormatList

To support formats such as AAC with SBR where an encoded data stream can be decoded to multiple destination formats, this property returns an array of AudioFormatListItem structures (declared in AudioFormat.h)—one for each of the destination formats. The default behavior is to return an AudioFormatListItem structure that has the same AudioStreamBasicDescription structure as that returned by the kAudioFileStreamProperty_DataFormat property.

Available in OS X v10.5 and later.

kAudioFileStreamProperty_MagicCookieData

kAudioFileStreamProperty_MagicCookieData

A pointer (void *) to a magic cookie. For audio file types that require a magic cookie before packets can be written to a file, you should get this property value before calling the AudioFileWriteBytes or AudioFileWritePackets functions.

Available in OS X v10.5 and later.

kAudioFileStreamProperty_AudioDataByteCount

kAudioFileStreamProperty_AudioDataByteCount

A UInt64 value indicating the number of bytes of audio data in the streamed file. This property is valid only if the number of bytes for the entire stream is known from the data parsed in the header. For some kinds of streams this property may have no value.

Available in OS X v10.5 and later.

kAudioFileStreamProperty_AudioDataPacketCount

kAudioFileStreamProperty_AudioDataPacketCount

A UInt64 value indicating the number of packets of audio data in the streamed file.

Available in OS X v10.5 and later.

kAudioFileStreamProperty_MaximumPacketSize

kAudioFileStreamProperty_MaximumPacketSize

A UInt32 value indicating the maximum packet size of the data in the streamed file.

Available in OS X v10.5 and later.

kAudioFileStreamProperty_DataOffset

kAudioFileStreamProperty_DataOffset

An SInt64 value indicating the byte offset in the streamed file at which the audio data starts.

Obtains the frame number corresponding to a packet number. Pass an AudioFramePacketTranslation structure with the mPacket field filled in, and a value in the mFrame field is returned on output. (The mFrameOffsetInPacket field of the AudioFramePacketTranslation structure is ignored.) For more information on the audio frame packet translation structure, see Audio File Services Reference.

Available in OS X v10.5 and later.

kAudioFileStreamProperty_FrameToPacket

kAudioFileStreamProperty_FrameToPacket

Obtains the packet number corresponding to a frame number. Pass an AudioFramePacketTranslation structure with the mFrame field filled in, and values in the mPacket and mFrameOffsetInPacket fields are returned on output. For more information on the audio frame packet translation structure, see Audio File Services Reference.

Available in OS X v10.5 and later.

kAudioFileStreamProperty_PacketToByte

kAudioFileStreamProperty_PacketToByte

Obtains the byte number corresponding to a packet number. Pass an AudioBytePacketTranslation structure with the mPacket field filled in, and a value is returned in the mByte field. The mByteOffsetInPacket field of the AudioBytePacketTranslation structure is ignored. If the mByte value is an estimate, then the kBytePacketTranslationFlag_IsEstimate value will be set in the mFlags field.

Available in OS X v10.6 and later.

kAudioFileStreamProperty_ByteToPacket

kAudioFileStreamProperty_ByteToPacket

Obtains the packet number corresponding to a byte number. Pass an AudioBytePacketTranslation structure with the mByte field filled in, and values are returned in the mPacket and mByteOffsetInPacket fields. If the mPacket value is an estimate, then the kBytePacketTranslationFlag_IsEstimate value will be set in the mFlags field.