Audio File Services

Overview

This document describes Audio File Services, a C programming interface that enables you to read or write a wide variety of audio data to or from disk or a memory buffer.

With Audio File Services you can:

  • Create, initialize, open, and close audio files

  • Read and write audio files

  • Optimize audio files

  • Work with user data and global information

Topics

Creating and Initializing Audio Files

AudioFileCreateWithURL

Creates a new audio file, or initializes an existing file, specified by a URL.

AudioFileInitializeWithCallbacks

Deletes the content of an existing file and assigns callbacks to the audio file object.

Opening and Closing Audio Files

AudioFileOpenURL

Open an existing audio file specified by a URL.

AudioFileOpenWithCallbacks

Opens an existing file with callbacks you provide.

AudioFileClose

Closes an audio file.

Reading and Writing Audio Files

AudioFileReadBytes

Reads bytes of audio data from an audio file.

AudioFileWriteBytes

Writes bytes of audio data to an audio file.

AudioFileReadPacketData

Reads packets of audio data from an audio file.

AudioFileReadPackets

Reads a fixed duration of audio data from an audio file.

Deprecated
AudioFileWritePackets

Writes packets of audio data to an audio data file.

Getting and Setting Audio File Properties

AudioFileGetProperty

Gets the value of an audio file property.

AudioFileGetPropertyInfo

Gets information about an audio file property, including the size of the property value and whether the value is writable.

AudioFileSetProperty

Sets the value of an audio file property

Working with User Data

AudioFileCountUserData

Gets the number of user data items with a specified ID in a file.

AudioFileGetUserDataSize

Gets the size of a user data item in an audio file.

AudioFileRemoveUserData

Removes a user data item from an audio file.

AudioFileSetUserData

Sets a user data item in an audio file.

AudioFileGetUserData

Gets a chunk from an audio file.

Working with Global Information

AudioFileGetGlobalInfoSize

Gets the size of a global audio file property.

AudioFileGetGlobalInfo

Copies the value of a global property into a buffer.

Optimizing Audio Files

AudioFileOptimize

Consolidates audio data and performs other internal optimizations of the file structure.

Audio File Macros

NumBytesToNumAudioFileMarkers

A macro that returns the number of audio file markers represented by a specified number of bytes.

NumAudioFileMarkersToNumBytes

A macro that returns the number of bytes corresponding to a specified number of audio file markers.

NextAudioFileRegion

Finds the next audio file region in a region list.

Deprecated Functions

Callbacks

AudioFile_ReadProc

Reads audio data when used in conjunction with the AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks functions.)

AudioFile_WriteProc

A callback for writing file data when used in conjunction with the AudioFileOpenWithCallbacks or AudioFileCreateWithURL functions.

AudioFile_GetSizeProc

Gets file data size.

AudioFile_SetSizeProc

Sets file data size.

Data Types

AudioFileID

An opaque data type that represents an audio file object.

AudioFilePropertyID

An audio file property identifier.

AudioFile_SMPTE_Time

A data structure for describing SMPTE (Society of Motion Picture and Television Engineers) time.

AudioFileMarker

Annotates a position in an audio file.

AudioFileMarkerList

A list of markers associated with an audio file, including their SMPTE time type, the number of markers, and the markers themselves.

AudioFileRegion

An audio file region specifies a segment of audio data.

AudioFileRegionList

A list of the audio file regions in a file.

AudioFilePacketTableInfo

Contains information about the number of valid frames in a file and where they begin and end.

Constants

AudioFileTypeID

Operating system constants that indicate the type of file to be written or a hint about what type of file to expect from data provided.

AudioFilePermissions

Flags for use with the AudioFileOpenURL and AudioFileOpen functions.

Audio File Loop Direction Constants

The playback direction of a looped segment of an audio file.

Audio File Marker Types

A type of marker within a file used in the mType field of the AudioFileMarker structure.

AudioFileRegionFlags

Flags that specify a playback direction for an AudioFileRegion structure.

Audio File Packet Translation Flags

Flag used with the mFlags field of the AudioBytePacketTranslation structure.

Info String Keys

Key values of properties to get and set using Audio File Services functions and provide a common way to get the same information out of several different kinds of files.

Audio File Properties

Properties used by the functions described in getting and setting pieces of data in audio files. See Working with Global Information for details.

Audio File Global Info Properties

Access these properties using the functions described in Working with Global Information.

Result Codes

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

kAudioFileUnspecifiedError

An unspecified error has occurred.

kAudioFileUnsupportedFileTypeError

The file type is not supported.

kAudioFileUnsupportedDataFormatError

The data format is not supported by this file type.

kAudioFileUnsupportedPropertyError

The property is not supported.

kAudioFileBadPropertySizeError

The size of the property data was not correct.

kAudioFilePermissionsError

The operation violated the file permissions. For example, an attempt was made to write to a file opened with the kAudioFileReadPermission constant.

kAudioFileNotOptimizedError

The chunks following the audio data chunk are preventing the extension of the audio data chunk. To write more data, you must optimize the file.

kAudioFileInvalidChunkError

Either the chunk does not exist in the file or it is not supported by the file.

kAudioFileDoesNotAllow64BitDataSizeError

The file offset was too large for the file type. The AIFF and WAVE file format types have 32-bit file size limits.

kAudioFileInvalidPacketOffsetError

A packet offset was past the end of the file, or not at the end of the file when a VBR format was written, or a corrupt packet size was read when the packet table was built.

kAudioFileInvalidFileError

The file is malformed, or otherwise not a valid instance of an audio file of its type.

kAudioFileOperationNotSupportedError

The operation cannot be performed. For example, setting the kAudioFilePropertyAudioDataByteCount constant to increase the size of the audio data in a file is not a supported operation. Write the data instead.

kAudioFileNotOpenError

The file is closed.

kAudioFilePositionError

Invalid file position.