Extended Audio File Services Reference

Framework
AudioToolbox/AudioToolbox.h
Declared in
ExtendedAudioFile.h

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

Configuring Properties for Extended Audio File Objects

Reading and Writing Audio Data

Functions

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
);
Parameters
inURL

The URL of the new audio file.

inFileType

The type of file to create, specified as a constant from the Built-In Audio File Types enumeration.

inStreamDesc

The format of the audio data to be written to the file.

inChannelLayout

The channel layout of the audio data. If non-null, this must be consistent with the number of channels specified by the inStreamDesc parameter.

inFlags

Flags for creating or opening the file. If the kAudioFileFlags_EraseFile flag is set, it erases an existing file. If the flag is not set, the function fails fails if the URL points to an existing file.

outExtAudioFile

On output, a newly allocated extended audio file object.

Return Value

A result code.

Discussion

If the file to be created is in a compressed format, you may set the sample rate in the inStreamDesc parameter to 0. In all cases, the extended file object’s encoding converter may produce audio at a different sample rate than the source. The file will be created with the audio format produced by the encoder.

Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

ExtAudioFileDispose

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

OSStatus ExtAudioFileDispose (
   ExtAudioFileRef inExtAudioFile
);
Parameters
inExtAudioFile

The extended audio file object to close.

Return Value

A result code.

Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

ExtAudioFileGetProperty

Gets a property value from an extended audio file object.

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

The extended audio file object to get a property value from.

inPropertyID

The property whose value you want.

ioPropertyDataSize

On input, the size of the memory pointed to by the outPropertyData parameter. On output, the size of the property value.

outPropertyData

On output, the property value you wanted to get.

Return Value

A result code.

Special Considerations

Some Core Audio property values are C types and others are Core Foundation objects.

If you call this function to retrieve a value that is a Core Foundation object, then this function—despite the use of “Get” in its name—duplicates the object. You are responsible for releasing the object, as described in “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

ExtAudioFileGetPropertyInfo

Gets information about an extended audio file object property.

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

The extended audio file object to get property information from.

inPropertyID

The property you want information about.

outSize

On output, the size of the property value in bytes. Can be NULL on output.

outWritable

On output, a Boolean value indicating whether the property value is writable (true means writable). Can be NULL on output.

Return Value

A result code.

Availability
  • Available in iOS 2.1 and later.
Related Sample Code
Declared In
ExtendedAudioFile.h

ExtAudioFileOpenURL

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

OSStatus ExtAudioFileOpenURL (
   CFURLRef         inURL,
   ExtAudioFileRef  *outExtAudioFile
);
Parameters
inURLRef

The audio file to read.

outExtAudioFile

On output, a newly allocated extended audio file object.

Return Value

A result code.

Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

ExtAudioFileRead

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

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

The extended audio file object that represents the file you want to read.

ioNumberFrames

On input, the number of frames to read from the file. On output, the number of frames actually read. Fewer frames may be read than were requested. For example, the supplied buffers may not be large enough to accommodate the requested data. If 0 frames are returned, end-of-file was reached.

ioData

One or more buffers into which the audio data is read.

Return Value

A result code.

Discussion

If the extended audio file object has an application data format, then the object’s converter converts the file data to the application format.

This function works only on a single thread. If you want your application to read an audio file on multiple threads, use Audio File Services instead.

Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

ExtAudioFileSeek

Seeks to a specified frame in a file.

OSStatus ExtAudioFileSeek (
   ExtAudioFileRef  inExtAudioFile,
   SInt64           inFrameOffset
);
Parameters
inExtAudioFile

The extended audio file object that represents the file you are working with.

inFrameOffset

The desired seek position, in sample frames, relative to the beginning of the file. Seek position is specified in the sample rate and frame count of the file’s audio data format—not your application’s audio data format.

Return Value

A result code.

Discussion

Sets the file’s read position to the specified sample frame number. A subsequent call to the ExtAudioFileRead function returns samples from precisely this location, even if it is located in the middle of a packet.

Ensure that the file you are seeking in is open for reading only. This function’s behavior with files open for writing is undefined.

Availability
  • Available in iOS 2.1 and later.
Related Sample Code
Declared In
ExtendedAudioFile.h

ExtAudioFileSetProperty

Sets a property value for an extended audio file object.

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

The extended audio file object to set a property value on.

inPropertyID

The property whose value you want to set.

inPropertyDataSize

The size of the property value, in bytes.

inPropertyData

The value you want to apply to the specified property.

Return Value

A result code.

Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

ExtAudioFileTell

Gets an audio file’s read/write position.

OSStatus ExtAudioFileTell (
   ExtAudioFileRef  inExtAudioFile,
   SInt64           *outFrameOffset
);
Parameters
inExtAudioFile

The extended audio file object that represents the file you are working with.

outFrameOffset

On output, the file's current read/write position in sample frames. Read/write position is specified in the sample rate and frame count of the file’s audio data format—not your application’s audio data format.

Return Value

A result code.

Availability
  • Available in iOS 2.1 and later.
Related Sample Code
Declared In
ExtendedAudioFile.h

ExtAudioFileWrapAudioFileID

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

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

The audio file object to wrap.

inForWriting

Use true if you intend to write to the audio file, false otherwise.

outExtAudioFile

On output, a newly allocated extended audio file object.

Return Value

A result code.

Discussion

Allocates a new extended audio file object that wraps an existing audio file object. Your application is responsible for keeping the audio file object open until the extended audio file object is disposed.

Availability
  • Available in iOS 2.1 and later.
Related Sample Code
Declared In
ExtendedAudioFile.h

ExtAudioFileWrite

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

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

The extended audio file object that represents the file to write to.

inNumberFrames

The number of frames to write.

ioData

The buffer(s) from which audio data is written to the file.

Return Value

A result code.

Discussion

If the extended audio file object has an application data format, then the object’s converter converts the data in the ioData parameter to the file data format.

Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

ExtAudioFileWriteAsync

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

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

The extended audio file object that represents the file you want to write to.

inNumberFrames

The number of frames to write.

ioData

The buffer(s) from which audio data is written to the file.

Return Value

A result code.

Discussion

Writes the provided buffer list to an internal ring buffer and notifies an internal thread to perform the write at a later time. The first time this function is called, allocations may be performed. You can call this function with 0 frames and a NULL buffer in a non-time-critical context to initialize the asynchronous mechanism. Once initialized, subsequent calls are very efficient and do not take locks. This technique may be used to write to a file from a realtime thread.

Your application must not mix synchronous and asynchronous writes to the same file.

Pending writes are not guaranteed to be flushed to disk until the ExtAudioFileDispose function is called.

Errors may occur after this call has returned. Such errors may be returned from subsequent calls to this function.

Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

Data Types

ExtAudioFileRef

An opaque structure representing an extended audio file object.

typedef struct OpaqueExtAudioFile *ExtAudioFileRef;
Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

ExtAudioFilePropertyID

An audio file object property identifier.

typedef UInt32 ExtAudioFilePropertyID;
Availability
  • Available in iOS 2.1 and later.
Declared In
ExtendedAudioFile.h

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 iOS 2.1 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 iOS 2.1 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 iOS 2.1 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 iOS 2.1 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 iOS 4.0 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 iOS 2.1 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 iOS 2.1 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 iOS 2.1 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 iOS 2.1 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 iOS 2.1 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 iOS 2.1 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 iOS 2.1 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 iOS 2.1 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 iOS 4.0 and later.

Declared in ExtendedAudioFile.h.

Result Codes

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

Result CodeValueDescription
kExtAudioFileError_CodecUnavailableInputConsumed-66559

The ExtAudioFileWrite function was interrupted and the last buffer that you provided was successfully written to disk.

For additional information, refer to “Hardware-Assisted Codecs and Audio Interruptions” in Audio Session Programming Guide.

Available in iOS 3.1 and later.

kExtAudioFileError_CodecUnavailableInputNotConsumed-66560

The ExtAudioFileWrite function was interrupted and the last buffer that you provided was not successfully written to disk.

For additional information, refer to “Hardware-Assisted Codecs and Audio Interruptions” in Audio Session Programming Guide.

Available in iOS 3.1 and later.

kExtAudioFileError_InvalidProperty -66561

Available in iOS 2.1 and later.

kExtAudioFileError_InvalidPropertySize -66562

Available in iOS 2.1 and later.

kExtAudioFileError_NonPCMClientFormat -66563

Available in iOS 2.1 and later.

kExtAudioFileError_InvalidChannelMap -66564

The number of channels does not match the specified format.

Available in iOS 2.1 and later.

kExtAudioFileError_InvalidOperationOrder -66565

Available in iOS 2.1 and later.

kExtAudioFileError_InvalidDataFormat -66566

Available in iOS 2.1 and later.

kExtAudioFileError_MaxPacketSizeUnknown -66567

Available in iOS 2.1 and later.

kExtAudioFileError_InvalidSeek -66568

An attempt to write, or an offset, is out of bounds.

Available in iOS 2.1 and later.

kExtAudioFileError_AsyncWriteTooLarge -66569

Available in iOS 2.1 and later.

kExtAudioFileError_AsyncWriteBufferOverflow-66570

An asynchronous write operation could not be completed in time.

Available in iOS 2.1 and later.