Extended Audio File Services Reference

Overview

Extended Audio File Services provides simplified audio file access, combining features of Audio File Services and Audio Converter Services. It provides a unified interface for reading and writing compressed as well as linear PCM audio files.

Functions by Task

Managing Extended Audio File Objects

• ExtAudioFileCreateWithURL
• ExtAudioFileDispose
• ExtAudioFileOpenURL
• ExtAudioFileWrapAudioFileID

Configuring Properties for Extended Audio File Objects

• ExtAudioFileGetProperty
• ExtAudioFileGetPropertyInfo
• ExtAudioFileSetProperty

Reading and Writing Audio Data

• ExtAudioFileRead
• ExtAudioFileSeek
• ExtAudioFileTell
• ExtAudioFileWrite
• ExtAudioFileWriteAsync

Deprecated Functions

• ExtAudioFileCreateNew
• ExtAudioFileOpen

Functions

ExtAudioFileCreateNew

Deprecated. Use the ExtAudioFileCreateWithURL function instead.

   ExtAudioFileCreateNew(
   const struct FSRef                 *inParentDir,
   CFStringRef                        inFileName,
   AudioFileTypeID                    inFileType,
   const AudioStreamBasicDescription  *inStreamDesc,
   const AudioChannelLayout           *inChannelLayout,
   ExtAudioFileRef                    *outExtAudioFile
);

ExtAudioFileCreateWithURL

Creates a new audio file and associates it with a new extended audio file object.

OSStatus ExtAudioFileCreateWithURL (
   CFURLRef                          inURL,
   AudioFileTypeID                   inFileType,
   const AudioStreamBasicDescription *inStreamDesc,
   const AudioChannelLayout          *inChannelLayout,
   UInt32                            inFlags,
   ExtAudioFileRef                   *outExtAudioFile
);

ExtAudioFileDispose

Disposes of an extended audio file object and closes the associated file.

OSStatus ExtAudioFileDispose (
   ExtAudioFileRef inExtAudioFile
);

ExtAudioFileGetProperty

Gets a property value from an extended audio file object.

OSStatus ExtAudioFileGetProperty (
   ExtAudioFileRef         inExtAudioFile,
   ExtAudioFilePropertyID  inPropertyID,
   UInt32                  *ioPropertyDataSize,
   void                    *outPropertyData
);

ExtAudioFileGetPropertyInfo

Gets information about an extended audio file object property.

OSStatus ExtAudioFileGetPropertyInfo (
   ExtAudioFileRef         inExtAudioFile,
   ExtAudioFilePropertyID  inPropertyID,
   UInt32                  *outSize,
   Boolean                 *outWritable
);

ExtAudioFileOpen

Deprecated. Use the ExtAudioFileOpenURL function instead.

   ExtAudioFileOpen (
   const struct FSRef  *inFSRef,
   ExtAudioFileRef     *outExtAudioFile
);

ExtAudioFileOpenURL

Opens an existing audio file for reading, and associates it with a new extended audio file object.

OSStatus ExtAudioFileOpenURL (
   CFURLRef         inURL,
   ExtAudioFileRef  *outExtAudioFile
);

ExtAudioFileRead

Performs a synchronous, sequential read operation on an audio file.

OSStatus ExtAudioFileRead (
   ExtAudioFileRef  inExtAudioFile,
   UInt32           *ioNumberFrames,
   AudioBufferList  *ioData
);

ExtAudioFileSeek

Seeks to a specified frame in a file.

OSStatus ExtAudioFileSeek (
   ExtAudioFileRef  inExtAudioFile,
   SInt64           inFrameOffset
);

ExtAudioFileSetProperty

Sets a property value for an extended audio file object.

OSStatus ExtAudioFileSetProperty (
   ExtAudioFileRef         inExtAudioFile,
   ExtAudioFilePropertyID  inPropertyID,
   UInt32                  inPropertyDataSize,
   const void              *inPropertyData
);

ExtAudioFileTell

Gets an audio file’s read/write position.

OSStatus ExtAudioFileTell (
   ExtAudioFileRef  inExtAudioFile,
   SInt64           *outFrameOffset
);

ExtAudioFileWrapAudioFileID

Wraps an audio file object in an extended audio file object.

OSStatus ExtAudioFileWrapAudioFileID (
   AudioFileID      inFileID,
   Boolean          inForWriting,
   ExtAudioFileRef  *outExtAudioFile
);

ExtAudioFileWrite

Performs a synchronous, sequential write operation on an audio file.

OSStatus ExtAudioFileWrite (
   ExtAudioFileRef        inExtAudioFile,
   UInt32                 inNumberFrames,
   const AudioBufferList  *ioData
);

ExtAudioFileWriteAsync

Perform an asynchronous, sequential write operation on an audio file.

OSStatus ExtAudioFileWriteAsync (
   ExtAudioFileRef        inExtAudioFile,
   UInt32                 inNumberFrames,
   const AudioBufferList  *ioData
);

Data Types

ExtAudioFileRef

An opaque structure representing an extended audio file object.

typedef struct OpaqueExtAudioFile *ExtAudioFileRef;

ExtAudioFilePropertyID

An audio file object property identifier.

typedef UInt32 ExtAudioFilePropertyID;

Constants

Property Identifiers for Extended Audio File Objects

enum {
   kExtAudioFileProperty_FileDataFormat       = 'ffmt',
   kExtAudioFileProperty_FileChannelLayout    = 'fclo',
   kExtAudioFileProperty_ClientDataFormat     = 'cfmt',
   kExtAudioFileProperty_ClientChannelLayout  = 'cclo',
   kExtAudioFileProperty_CodecManufacturer    = 'cman',
   
   // read-only properties:
   kExtAudioFileProperty_AudioConverter       = 'acnv',
   kExtAudioFileProperty_AudioFile            = 'afil',
   kExtAudioFileProperty_FileMaxPacketSize    = 'fmps',
   kExtAudioFileProperty_ClientMaxPacketSize  = 'cmps',
   kExtAudioFileProperty_FileLengthFrames     = '#frm',
   
   // read/write properties:
   kExtAudioFileProperty_ConverterConfig      = 'accf',
   kExtAudioFileProperty_IOBufferSizeBytes    = 'iobs',
   kExtAudioFileProperty_IOBuffer             = 'iobf',
   kExtAudioFileProperty_PacketTable          = 'xpti'
};

Constants

kExtAudioFileProperty_FileDataFormat

A file’s data format. Value is a read-only AudioStreamBasicDescription struct.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_FileChannelLayout

A file’s channel layout. Value is a read/write AudioChannelLayout struct.

When writing, the channel layout is written to the file, if the format specified in the kExtAudioFileProperty_FileDataFormat property supports the layout. If the format does not support the layout, the channel layout is still interpreted as the destination layout when performing conversion from the client channel layout, if any.

When reading, the specified layout overrides the one read from the file, if one is present in the file.

You must set this property before setting the application audio data format or application channel layout in the extended audio file object.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_ClientDataFormat

The audio stream format for your application. Value is a read/write AudioStreamBasicDescription struct.

The format must be linear PCM (specified by the kAudioFormatLinearPCM constant from the CoreAudioTypes.h header file). You must set this property to allow encoding or decoding of a non-PCM file data format. You can set this property on PCM files to specify the data format to use in your read and write calls.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_ClientChannelLayout

The audio channel layout for your application. Value is a read/write AudioChannelLayout struct.

This property’s value specifies the channel layout of the buffers in an AudioBufferList list that you pass to the ExtAudioFileRead and ExtAudioFileWrite functions. This layout may be different from the file’s channel layout, in which case the extended audio file object’s underlying audio converter performs remapping. This property must be set after setting the kExtAudioFileProperty_ClientDataFormat property, and the number of channels in the two layouts must match.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_CodecManufacturer

The manufacturer of the codec to be used by the extended audio file object. Value is a read/write UInt32.

You must specify this property before setting the kExtAudioFileProperty_ClientDataFormat property, which in turn triggers the creation of the codec. Use this property in iOS to choose between a hardware or software encoder, by specifying kAppleHardwareAudioCodecManufacturer or kAppleSoftwareAudioCodecManufacturer.

Available in OS X v10.7 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_AudioConverter

The audio converter object associated with the extended audio file object, if a converter is associated. Value is a read-only AudioConverterRef object.

If you alter any properties of the converter—the bit rate, for instance—you must then set the kExtAudioFileProperty_ConverterConfig property. When you do so, using a NULL configuration is sufficient. Setting that property ensure that the output file’s data format is consistent with the format being produced by the converter.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_AudioFile

The audio file object associated with the extended audio file object. Value is a read-only AudioFileID object.

Available in OS X v10.5 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_FileMaxPacketSize

The file data format’s maximum packet size, in bytes. Value is a read-only UInt32.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_ClientMaxPacketSize

Your application audio data format's maximum packet size, in bytes. Value is a read-only UInt32.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_FileLengthFrames

The associated audio file’s length in sample frames. Value is an SInt64. For a PCM file, the value is read/write. For a non-PCM file, the value is read-only.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_ConverterConfig

The configuration of the extended audio file object’s associated audio converter, as specified by the kAudioConverterPropertySettings property. Value is a read/write CFArray object.

Set this property’s value to NULL to force resynchronization of the converter’s output format with the file’s data format.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_IOBufferSizeBytes

The size of the buffer that the extended audio file object’s associated audio converter uses to read or write the associated audio file. Value is a read/write UInt32.

This property has a value only when there is an underlying audio converter object present.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_IOBuffer

An audio data buffer. Value is a read/write void* value.

This property’s value points to the memory that the extended audio file object uses for disk I/O when converting between the application and file data formats. You may want your application to share this memory among multiple extended audio file objects. If so, you can set this property to point to a buffer you specify—pass a pointer to a pointer when calling the ExtAudioFileSetProperty function. After setting this property, your application must then set the kExtAudioFileProperty_IOBufferSizeBytes property.

Available in OS X v10.4 and later.

Declared in ExtendedAudioFile.h.

kExtAudioFileProperty_PacketTable

This property can be used to override the priming and remainder information in an audio file, and also to retrieve the current priming and remainder frames information for an extended audio file object. If the underlying file type does not provide packet table information, attempting to get the value of this property returns an error.

By setting this property with a nonnegative number (which may be the value 0), you override the corresponding settings for the values contained in the file. If you use a value of -1 for either the priming or remainder frames, the extended audio file object uses the corresponding value stored in the file.

Retrieving the value of this property always retrieves the value the extended audio file object is using, whether derived from the file or from your override.

To determine the value in the file, use the kAudioFilePropertyPacketTableInfo property as described in Audio File Services Reference.

When the property is set, only the remaining and priming values are used. Set the mNumberValidFrames field of the AudioFilePacketTableInfo struct to zero. For example, a file encoded using AAC may have 2112 samples of priming at the start of the file and a remainder of 823 samples at the end. When an extended audio file object returns decoded samples to you, it trims off the <priming num samples> at the start of the file, and trims off the <remainder num samples> at the end. It gets these numbers initially from the file. A common use case for overriding this would be to set the priming and remainder samples to 0. In this example, you would retrieve an additional 2112 samples of silence from the start of the file and 823 samples of silence at the end of the file (silence, because the encoders use silence to pad out these priming and remainder samples).

Available in OS X v10.7 and later.

Declared in ExtendedAudioFile.h.

Result Codes

This table lists result codes defined for Extended Audio File Services.