Audio File Stream Services Reference

Overview

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:

1. Create a new audio file stream parser by calling the AudioFileStreamOpen function. Pass pointers to your callback functions for audio data and metadata (AudioFileStream_PacketsProc and AudioFileStream_PropertyListenerProc). The AudioFileStreamOpen function gives you a reference to the new parser.

2. Acquire some streamed data. Call the AudioFileStreamParseBytes function when you have data to pass to the parser. Send the data to the parser sequentially and, if possible, without gaps.

   1. When the parser acquires a usable buffer of audio data, it invokes your audio data callback. Your callback can then play the data, write it to a file, or otherwise process it.

   2. When the parser acquires metadata, it invokes your property callback—which in turn can obtain the property value by calling the AudioFileStreamGetPropertyInfo and AudioFileStreamGetProperty functions.

3. When finished parsing a stream, call the AudioFileStreamClose function to close and deallocate the parser.

Audio File Stream Services supports the following audio data types:

• AIFF

• AIFC

• WAVE

• CAF

• NeXT

• ADTS

• MPEG Audio Layer 3

• AAC

Functions by Task

Opening Audio File Streams

• AudioFileStreamOpen

Supplying Data to the Parser

• AudioFileStreamParseBytes

Seeking Packets in the Data Stream

• AudioFileStreamSeek

Working with Data Stream Property Information

• AudioFileStreamGetPropertyInfo
• AudioFileStreamGetProperty
• AudioFileStreamSetProperty

Closing an Audio File Stream

• AudioFileStreamClose

Functions

AudioFileStreamClose

Closes and deallocates the specified audio file stream parser.

OSStatus AudioFileStreamClose (
   AudioFileStreamID inAudioFileStream
);

AudioFileStreamGetProperty

Retrieves the value of the specified property.

OSStatus AudioFileStreamGetProperty (
   AudioFileStreamID          inAudioFileStream,
   AudioFileStreamPropertyID  inPropertyID,
   UInt32                     *ioPropertyDataSize,
   void                       *outPropertyData
);

AudioFileStreamGetPropertyInfo

Retrieves information about a property value.

OSStatus AudioFileStreamGetPropertyInfo (
   AudioFileStreamID          inAudioFileStream,
   AudioFileStreamPropertyID  inPropertyID,
   UInt32                     *outPropertyDataSize,
   Boolean                    *outWritable
);

AudioFileStreamOpen

Creates and opens a new audio file stream parser.

OSStatus  AudioFileStreamOpen (
   void                                  *inClientData,
   AudioFileStream_PropertyListenerProc  inPropertyListenerProc,
   AudioFileStream_PacketsProc           inPacketsProc,
   AudioFileTypeID                       inFileTypeHint,
   AudioFileStreamID                     *outAudioFileStream
);

AudioFileStreamParseBytes

Passes audio file stream data to the parser.

OSStatus AudioFileStreamParseBytes (
   AudioFileStreamID  inAudioFileStream,
   UInt32             inDataByteSize,
   const void         *inData,
   UInt32             inFlags
);

AudioFileStreamSeek

Provides a byte offset for a specified packet in the data stream.

OSStatus AudioFileStreamSeek (
   AudioFileStreamID  inAudioFileStream,
   SInt64             inAbsolutePacketOffset,
   SInt64             *outAbsoluteByteOffset,
   UInt32             *ioFlags
);

AudioFileStreamSetProperty

Sets the value of the specified property.

OSStatus AudioFileStreamSetProperty (
   AudioFileStreamID          inAudioFileStream,
   AudioFileStreamPropertyID  inPropertyID,
   UInt32                     inPropertyDataSize,
   const void                 *inPropertyData
);

Callbacks by Task

Processing Property Values

• AudioFileStream_PropertyListenerProc

Handling Packets of Audio File Stream Data

• AudioFileStream_PacketsProc

Callbacks

AudioFileStream_PacketsProc

Invoked by an audio file stream parser when it finds audio data in the audio file stream.

typedef void (*AudioFileStream_PacketsProc) (
   void                          *inClientData,
   UInt32                        inNumberBytes,
   UInt32                        inNumberPackets,
   const void                    *inInputData,
   AudioStreamPacketDescription  *inPacketDescriptions
);

If you named your function MyAudioFileStream_PacketsProc, you would declare it like this:

void MyAudioFileStream_PacketsProc (
   void                          *inClientData,
   UInt32                        inNumberBytes,
   UInt32                        inNumberPackets,
   const void                    *inInputData,
   AudioStreamPacketDescription  *inPacketDescriptions
);

AudioFileStream_PropertyListenerProc

Invoked by an audio file stream parser when it finds a property value in the audio file stream.

typedef void (*AudioFileStream_PropertyListenerProc) (
   void                         *inClientData,
   AudioFileStreamID            inAudioFileStream,
   AudioFileStreamPropertyID    inPropertyID,
   UInt32                       *ioFlags
);

If you named your function MyAudioFileStream_PropertyListenerProc, you would declare it like this:

void MyAudioFileStream_PropertyListenerProc (
   void                        *inClientData,
   AudioFileStreamID           inAudioFileStream,
   AudioFileStreamPropertyID   inPropertyID,
   UInt32                      *ioFlags
);

Data Types

AudioFileStreamPropertyID

Uniquely identifies an audio file stream property.

typedef UInt32 AudioFileStreamPropertyID;

AudioFileStreamID

Defines an opaque data type that represents an audio file stream parser.

typedef struct OpaqueAudioFileStreamID  *AudioFileStreamID;

Constants

Audio File Stream Flags

Flags set by the property listener callback and the AudioFileStreamParseBytes function.

enum {
   kAudioFileStreamPropertyFlag_PropertyIsCached  = 1,
   kAudioFileStreamPropertyFlag_CacheProperty     = 2,
   kAudioFileStreamParseFlag_Discontinuity        = 1,
   kAudioFileStreamSeekFlag_OffsetIsEstimated     = 1
};

Constants

kAudioFileStreamPropertyFlag_PropertyIsCached

This flag is set when the callback AudioFileStream_PropertyListenerProc is invoked in the case that the value of the property has been cached and can be obtained later.

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.

Declared in AudioFileStream.h.

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.

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

kAudioFileStreamParseFlag_Discontinuity

Pass this flag to the AudioFileStreamParseBytes function to signal a discontinuity in the audio data.

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.

Declared in AudioFileStream.h.

kAudioFileStreamSeekFlag_OffsetIsEstimated

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

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

Audio File Stream Properties

Audio file stream properties contain information that you can use to help interpret the audio data in a stream.

enum {
   kAudioFileStreamProperty_ReadyToProducePackets    = 'redy',
   kAudioFileStreamProperty_FileFormat               = 'ffmt',
   kAudioFileStreamProperty_DataFormat               = 'dfmt',
   kAudioFileStreamProperty_FormatList               = 'flst',
   kAudioFileStreamProperty_MagicCookieData          = 'mgic',
   kAudioFileStreamProperty_AudioDataByteCount       = 'bcnt',
   kAudioFileStreamProperty_AudioDataPacketCount     = 'pcnt',
   kAudioFileStreamProperty_MaximumPacketSize        = 'psze',
   kAudioFileStreamProperty_DataOffset               = 'doff',
   kAudioFileStreamProperty_ChannelLayout            = 'cmap',
   kAudioFileStreamProperty_PacketToFrame            = 'pkfr',
   kAudioFileStreamProperty_FrameToPacket            = 'frpk',
   kAudioFileStreamProperty_PacketToByte             = 'pkby',
   kAudioFileStreamProperty_ByteToPacket             = 'bypk',
   kAudioFileStreamProperty_PacketTableInfo          = 'pnfo',
   kAudioFileStreamProperty_PacketSizeUpperBound     = 'pkub',
   kAudioFileStreamProperty_AverageBytesPerPacket    = 'abpp',
   kAudioFileStreamProperty_BitRate                  = 'brat'
};

Constants

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.

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_FileFormat

A UInt32 four-character code that identifies the audio data format. For a list of audio format IDs, see “Audio Data Format IDs” in Core Audio Data Types Reference.

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_DataFormat

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.

Declared in AudioFileStream.h.

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.

Declared in AudioFileStream.h.

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.

Declared in AudioFileStream.h.

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.

Declared in AudioFileStream.h.

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.

Declared in AudioFileStream.h.

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.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_DataOffset

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

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_ChannelLayout

An AudioChannelLayout structure. For details, see Core Audio Data Types Reference.

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_PacketToFrame

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.

Declared in AudioFileStream.h.

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.

Declared in AudioFileStream.h.

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.

Declared in AudioFileStream.h.

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.

Available in OS X v10.6 and later.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_PacketTableInfo

An AudioFilePacketTableInfo structure. For more information on the audio file packet table info structure, see Audio File Services Reference.

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_PacketSizeUpperBound

A UInt32 value indicating the theoretical maximum packet size in the streamed file. This value is useful for determining minimum buffer sizes, for example.

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_AverageBytesPerPacket

A Float64 value indicating the average bytes per packet. For CBR and files with packet tables, this number will be exact. Otherwise, it is a running average of packets parsed.

Available in OS X v10.6 and later.

Declared in AudioFileStream.h.

kAudioFileStreamProperty_BitRate

A UInt32 value indicating the bit rate of a stream in bits per second.

Available in OS X v10.5 and later.

Declared in AudioFileStream.h.

Result Codes

This table lists the result codes defined for Audio File Stream Services.