Mac Developer Library

Developer

AudioToolbox Framework Reference Extended Audio File Services Reference

Options
Deployment Target:

On This Page
Language:

Extended Audio File Services Reference

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

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

    Declaration

    Swift

    func ExtAudioFileCreateWithURL(_ inURL: CFURL!, _ inFileType: AudioFileTypeID, _ inStreamDesc: UnsafePointer<AudioStreamBasicDescription>, _ inChannelLayout: UnsafePointer<AudioChannelLayout>, _ inFlags: UInt32, _ outExtAudioFile: UnsafeMutablePointer<ExtAudioFileRef>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func ExtAudioFileDispose(_ inExtAudioFile: ExtAudioFileRef) -> OSStatus

    Objective-C

    OSStatus ExtAudioFileDispose ( ExtAudioFileRef inExtAudioFile );

    Parameters

    inExtAudioFile

    The extended audio file object to close.

    Return Value

    A result code.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func ExtAudioFileOpenURL(_ inURLRef: CFURL!, _ outExtAudioFile: UnsafeMutablePointer<ExtAudioFileRef>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func ExtAudioFileWrapAudioFileID(_ inFileID: AudioFileID, _ inForWriting: Boolean, _ outExtAudioFile: UnsafeMutablePointer<ExtAudioFileRef>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

  • Gets a property value from an extended audio file object.

    Declaration

    Swift

    func ExtAudioFileGetProperty(_ inExtAudioFile: ExtAudioFileRef, _ inPropertyID: ExtAudioFilePropertyID, _ ioPropertyDataSize: UnsafeMutablePointer<UInt32>, _ outPropertyData: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

  • Gets information about an extended audio file object property.

    Declaration

    Swift

    func ExtAudioFileGetPropertyInfo(_ inExtAudioFile: ExtAudioFileRef, _ inPropertyID: ExtAudioFilePropertyID, _ outSize: UnsafeMutablePointer<UInt32>, _ outWritable: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

  • Sets a property value for an extended audio file object.

    Declaration

    Swift

    func ExtAudioFileSetProperty(_ inExtAudioFile: ExtAudioFileRef, _ inPropertyID: ExtAudioFilePropertyID, _ inPropertyDataSize: UInt32, _ inPropertyData: UnsafePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func ExtAudioFileRead(_ inExtAudioFile: ExtAudioFileRef, _ ioNumberFrames: UnsafeMutablePointer<UInt32>, _ ioData: UnsafeMutablePointer<AudioBufferList>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

  • Seeks to a specified frame in a file.

    Declaration

    Swift

    func ExtAudioFileSeek(_ inExtAudioFile: ExtAudioFileRef, _ inFrameOffset: Int64) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

    See Also

    ExtAudioFileTell

  • Gets an audio file’s read/write position.

    Declaration

    Swift

    func ExtAudioFileTell(_ inExtAudioFile: ExtAudioFileRef, _ outFrameOffset: UnsafeMutablePointer<Int64>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

    See Also

    ExtAudioFileSeek

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

    Declaration

    Swift

    func ExtAudioFileWrite(_ inExtAudioFile: ExtAudioFileRef, _ inNumberFrames: UInt32, _ ioData: UnsafePointer<AudioBufferList>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func ExtAudioFileWriteAsync(_ inExtAudioFile: ExtAudioFileRef, _ inNumberFrames: UInt32, _ ioData: UnsafePointer<AudioBufferList>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

  • Deprecated. Use the ExtAudioFileCreateWithURL function instead.

    Declaration

    Objective-C

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

    Parameters

    inParentDir

    The directory in which to create the new file.

    inFileName

    The name of the new file.

    inFileType

    The type of file to create. This is a constant from AudioToolbox/AudioFile.h, e.g. kAudioFileAIFFType. Note that this is not an HFSTypeCode.

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

    outExtAudioFile

    On output, a newly allocated extended audio file object.

    Return Value

    A result code.

    Discussion

    Creates a new audio file.

    If the file to be created is in a compressed format, it is permissible for the sample rate in inStreamDesc to be 0, since in all cases, the file's encoding AudioConverter may produce audio at a different sample rate than the source. The file will be created with the audio format actually produced by the encoder.

    Special Considerations

    This function is deprecated. Use the ExtAudioFileCreateWithURL function instead.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.6.

  • Deprecated. Use the ExtAudioFileOpenURL function instead.

    Declaration

    Objective-C

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

    Parameters

    inFSRef

    The audio file to read.

    outExtAudioFile

    On exit, a newly allocated ExtAudioAudioFileRef.

    Return Value

    A result code.

    Discussion

    Allocates a new ExtAudioFileRef for reading an existing audio file.

    Special Considerations

    This function is deprecated. Use the ExtAudioFileOpenURL function instead.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.6.

Data Types

  • An opaque structure representing an extended audio file object.

    Declaration

    Swift

    typealias ExtAudioFileRef = COpaquePointer

    Objective-C

    typedef struct OpaqueExtAudioFile *ExtAudioFileRef;

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

  • An audio file object property identifier.

    Declaration

    Swift

    typealias ExtAudioFilePropertyID = UInt32

    Objective-C

    typedef UInt32 ExtAudioFilePropertyID;

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in OS X v10.4 and later.

Constants

  • Declaration

    Swift

    var kExtAudioFileProperty_FileDataFormat: Int { get } var kExtAudioFileProperty_FileChannelLayout: Int { get } var kExtAudioFileProperty_ClientDataFormat: Int { get } var kExtAudioFileProperty_ClientChannelLayout: Int { get } var kExtAudioFileProperty_CodecManufacturer: Int { get } var kExtAudioFileProperty_AudioConverter: Int { get } var kExtAudioFileProperty_AudioFile: Int { get } var kExtAudioFileProperty_FileMaxPacketSize: Int { get } var kExtAudioFileProperty_ClientMaxPacketSize: Int { get } var kExtAudioFileProperty_FileLengthFrames: Int { get } var kExtAudioFileProperty_ConverterConfig: Int { get } var kExtAudioFileProperty_IOBufferSizeBytes: Int { get } var kExtAudioFileProperty_IOBuffer: Int { get } var kExtAudioFileProperty_PacketTable: Int { get }

    Objective-C

    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

      kExtAudioFileProperty_FileDataFormat

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

      Available in OS X v10.4 and later.

    • kExtAudioFileProperty_FileChannelLayout

      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.

    • kExtAudioFileProperty_ClientDataFormat

      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.

    • kExtAudioFileProperty_ClientChannelLayout

      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.

    • kExtAudioFileProperty_CodecManufacturer

      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.

    • kExtAudioFileProperty_AudioConverter

      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.

    • kExtAudioFileProperty_AudioFile

      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.

    • kExtAudioFileProperty_FileMaxPacketSize

      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.

    • kExtAudioFileProperty_ClientMaxPacketSize

      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.

    • kExtAudioFileProperty_FileLengthFrames

      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.

    • kExtAudioFileProperty_ConverterConfig

      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.

    • kExtAudioFileProperty_IOBufferSizeBytes

      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.

    • kExtAudioFileProperty_IOBuffer

      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.

    • kExtAudioFileProperty_PacketTable

      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.

Result Codes

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