< Previous PageNext Page > Hide TOC

Audio Codec

This chapter discusses audio codec development using the Audio Codec API. The section “Audio Codec Reference” describes the constants, data types, and functions that are relevant to audio codec development.

In this section:

Overview of Audio Codec
Audio Codec Reference

Overview of Audio Codec

Audio codecs are encoders and decoders provided by Apple or third-party developers for the purpose of compressing and decompressing audio streams into and from encoded formats. While codec use is encouraged, normal use should be performed through the “Audio Converter.”

Before developing an audio codec for Mac OS X, install the Core Audio SDK, available from http://developer.apple.com/audio/.

Of particular interest are the contents of /AudioCodecs/ACPublic/, in the installed SDK.

The ACCodec Class

ACCodec is an abstract class that defines the basic methods that an audio codec must implement. At the very least, all codecs must subclass ACCodec to provide basic services for those who wish to use the codec, based on standard methods of communication expected of them. However, two subclasses of ACCodec are provided, which implement many of this class’s abstract methods for your convenience.

The ACBaseCodec Class

ACBaseCodec is a subclass of ACCodec and provides many of the services needed by most codecs to interact with codec clients. Property management is fully implemented in ACBaseCodec but you may override it as needed. Also, this class provides format management for input and outputs, including getting and setting the number of input and output formats, and getting and setting the AudioStreamBasicDescription format information for inputs and outputs.

ACBaseCodec does not implement a buffer for the codec, however, and you must implement all methods pertaining to buffer usage, depending on your chosen buffer size and implementation.

When developing an audio codec, you must subclass ACBaseCodec.

The ACSimpleCodec Class

ACSimpleCodec, a subclass of ACBaseCodec, provides a ring buffer implementation with a variable buffer size providing for reallocation of the buffer. This class is provided as a convenience for you in cases where you don’t need a custom buffering scheme. When developing a codec, you don’t need to subclass ACSimpleCodec, so long as you provide a buffering scheme.

Miscellaneous Headers

Inside /AudioCodecs/ACPublic/ are other headers that need not be modified but are necessary for the operation of a codec, and therefore are included in order for the codec to operate properly:

• ACConditionalMacros.h. This header helps determine which system headers need to be included at compile time.

• ACCodecDispatch.h. An implementation of an audio codec component dispatch method.

• ACCodecDispatchTypes.h. Glue that helps ACCodecDispatch work properly on various platforms.

Audio Codec Reference

This reference section describes the methods that need to be implemented in order to deploy an audio codec component for Mac OS X.

Audio Codec Types

Defined Data Types

Typedefs are used for naming convenience, in an effort to make information stored in generic variables more easily recognizable. There are two typedefs in AudioCodec.h:

• typedef ComponentInstance AudioCodec

• typedef UInt32 AudioCodecPropertyID

Data Structures

AudioStreamLoudnessStatistics

Encapsulates various pieces of information with regards to the loudness of the stream currently in use.

typedef struct AudioStreamLoudnessStatistics {
Float64 mAveragePerceivedPowerCoefficient;
Float64 mMaximumPerceivedPowerCoefficient;
UInt64 mMaximumPerceivedPowerPacketOffset;
Float32 mPeakAmplitude;
UInt32 mReserved;
UInt64 mPeakAmplitudeSampleOffset;
} AudioStreamLoudnessStatistics;

Discussion

An instance of this structure is returned when the kAudioCodecPropertyCurrentLoudnessStatistics property is queried. The mAveragePercievedPowerCoefficient and mMaximumPercievedPowerCoefficient are a normalized value on a scale of 0 to 1, while mMaximumPerceivedPowerPacketOffset specifies the power’s offset. The mPeakAmplitude value is the largest sample value in the entire audio stream. mPeakAmplitudeSampleOffset is the number of the sample where the peak is found.

Availability

• Available in Mac OS X v10.3 through Mac OS X v10.4.

Declared In

AudioCodecPrimeInfo

Holds information about leading and following frames for a stream of data.

typedef struct AudioCodecPrimeInfo {
UInt32 leadingFrames;
UInt32 trailingFrames;
} AudioCodecPrimeInfo;

Discussion

Many times, an audio stream has audio data that fixes and appends the actual content that needs to be encoded or decoded, based on the codec’s implementation. This structure holds how many leading and trailing frames there are. A pointer to an instance of this structure is accessible via the kAudioCodecPrimeInfo property.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

Audio Codec Constants

Constants are used throughout the Audio Codec API to provide information required by the Component Manager in order to function or to work in conjunction with properties to describe a state or setting.

Component Identifiers

Identifies the codec for the Component Manager.

kAudioDecoderComponentType = ‘adec’

The identifier for a codec that translates data in some format into linear PCM. The subtype of this codec specifies the format of the incoming data.

kAudioEncoderComponentType = ‘aenc’

The identifier for a codec that translates data from linear PCM into the codec’s specified output format. The subtype of this codec specifies the format of the outgoing data.

kAudioUnityCodecComponentType = ‘acdc’

The identifier for a codec that translates data between different types of the same format. The subtype of this codec specifies the format ID of the format that is being converted between.

Quality Settings

Specify the relative quality of a codec. The values are arbitrary and are provided as a suggestion. You can add more quality setting constants, or ignore them.

kAudioCodecQuality_Max = 0x7F

The maximum value allowed for the codec.

kAudioCodecQuality_High = 0x60

A high quality setting.

kAudioCodecQuality_Medium = 0x40

A medium quality setting.

kAudioCodecQuality_Low = 0x20

A low quality setting.

kAudioCodecQuality_Min = 0

The minimum quality setting allowed for the codec.

These constants are used by the kAudioCodecPropertyQualitySetting property. They are arbitrary and are provided as a suggestion. You can add more quality setting constants or ignore them altogether.

Priming Selectors

Specify the priming method use.

kAudioCodecPrimeMethod_Pre = 0

The codec primes with the leading and trailing input frames.

kAudioCodecPrimeMethod_Normal = 1

The codec primes with the trailing input frames only; all leading frames are assumed to be silence.

kAudioCodecPrimeMethod_None = 2

The codec does not prime; both leading and trailing frames are assumed to be silent.

These constants are used with the kAudioCodecPrimeMethod property. The number of frames that are used in priming is stored in the AudioCodecPrimeInfo structure, which is accessible through the kAudioCodecPrimeInfo property.

Output Packet Status Constants

When using the ProduceOutputPackets() method to pull data through the codec, one of the parameters, outStatus, has a value that reflects the state of the encode or decode after the pull has occurred. These are the possible values:

kAudioCodecProduceOutputPacketFailure = 1

There was an error processing the data; check ioNumberPackets to see how many packets were processed.

kAudioCodecProduceOutputPacketSuccess = 2

The requested packets were processed successfully and to completion.

kAudioCodecProduceOutputPacketSuccessHasMore = 3

The requested packets were processed successfully, and there are more left to process.

kAudioCodecProduceOutputPacketNeedsMoreInputData = 4

There was not enough data to produce the requested number of packets; check ioNumberPackets to see how many were produced.

kAudioCodecProduceOutputPacketAtEOF = 5

An end-of-file was encountered during processing, and therefore the requested number of packets were not produced; check ioNumberPackets to see how many were produced.

Audio Codec Properties

The property management system keeps track of information about the codec’s operation, settings, and capabilities. These are used in conjunction with GetPropertyInfo, GetProperty, and SetProperty.

kAudioCodecPropertyNameCFString = 'lnam'

Returns a CFStringRef with the name of the codec’s format.

kAudioCodecPropertyManufacturerCFString = 'lmak'

Returns a CFStringRef with the name of the codec’s manufacturer.

kAudioCodecPropertyRequiresPacketDescription = 'pakd'

Returns a UInt32 where a value of 1 means that the codec requires an AudioStreamPacketDescription to be supplied with any data in the format. If 0 is returned, AudioStreamPacketDescription is not needed. This property is used primary in the AppendInputData method.

kAudioCodecPropertyPacketFrameSize = 'pakf'

Passes back a UInt32 that reflects the number of frames of audio data in each packet of data in the codec’s format. The value is for an encoder’s input or a decoder’s output. Note that this value may be queried only after a codec’s initialization.

kAudioCodecPropertyHasVariablePacketByteSizes = 'vpk?'

Returns a UInt32 where a value of 0 indicates that all of the packets in the codec’s format have the same byte size, whereas a value of 1 indicates that the packets vary in size.

kAudioCodecPropertyMaximumPacketByteSize = 'pakb'

If the codec’s format has a constant packet size, this value will be the number of bytes in a packet of the codec’s format; if the format has a variable bit rate, this value will be the number of bytes in the largest of the packets in the codec’s format.

kAudioCodecPropertyCurrentInputFormat = 'ifmt'

Returns an AudioStreamBasicDescription describing the current input format for the codec.

kAudioCodecPropertySupportedInputFormats = 'ifm#'

Returns an AudioStreamBasicDescription array describing the input formats supported by the codec.

kAudioCodecPropertyCurrentOutputFormat = 'ofmt'

Returns an AudioStreamBasicDescription describing the current output format for the codec.

kAudioCodecPropertySupportedOutputFormats = 'ofm#'

Returns an array of AudioStreamBasicDescription describing the output formats supported by the codec.

kAudioCodecPropertyMagicCookie = 'kuki'

Returns an untyped buffer of configuration data the codec requires to process the stream of data. Note that not every codec requires a magic cookie.

kAudioCodecPropertyInputBufferSize = 'tbuf'

Returns a UInt32 that contains the maximum input buffer size for the codec, in bytes.

kAudioCodecPropertyUsedInputBufferSize = 'ubuf'

Returns a UInt32 that contains the number of bytes currently in use in the buffer.

kAudioCodecPropertyIsInitialized = 'init'

Returns a UInt32 where a value of 0 means the codec is initialized, while any other value means the codec is initialized.

kAudioCodecPropertyCurrentTargetBitRate = 'brat'

A UInt32 containing the number of bits per second to aim for when encoding data. This property is only relevant to encoders.

kAudioCodecPropertyAvailableBitRates = 'brt#'

A UInt32 array containing the target bit rates supported by the encoder. Note that use of this property is deprecated in favor of kAudioCodecPropertyAvailableBitRateRange.

kAudioCodecPropertyCurrentInputSampleRate = 'cisr'

Passes back a Float64 containing current input sample rate in Hz.

kAudioCodecPropertyCurrentOutputSampleRate = 'cosr'

Passes back a Float64 containing current output sample rate in Hz.

kAudioCodecPropertyAvailableInputSampleRates = 'aisr'

Returns an array of AudioValueRange structures indicating the valid ranges for the input sample rate of the codec for the current bit rate.

kAudioCodecPropertyAvailableOutputSampleRates = 'aosr'

Returns an array of AudioValueRange structures indicating the valid ranges for the output sample rates of the codec for the current bit rate.

kAudioCodecPropertyQualitySetting = 'srcq'

Returns a value to indicate the relative value of the codec’s encoding or decoding quality; see “Quality Settings” for possible values.

kAudioCodecPropertyCurrentLoudnessStatistics = 'loud'

Passes back a reference to an AudioStreamLoudnessStatistics array that provides statistics about the loudness of each channel in the stream of data being processed by the codec. Note that this property can be queried only when the codec is initialized. Until data has actually moved through it, the values are all defaults.

kAudioCodecPropertyAvailableBitRateRange = 'abrt'

Returns an array of AudioValueRange structures that represents the target bit rates supported by the encoder.

kAudioCodecPropertyApplicableBitRateRange = 'brta'

Returns an array of AudioValueRange structures that represents the target bit rates supported by the encoder as it is currently configured.

kAudioCodecPropertyApplicableInputSampleRates = 'isra'

Returns an array of AudioValueRange structures that represents the valid ranges for the input sample rates of the codec for the current bit rate.

kAudioCodecPropertyApplicableOutputSampleRates = 'osra'

Returns an array of AudioValueRange structures that represents the valid ranges for the output sample rates of the codec for the current bit rate.

kAudioCodecPropertyMinimumNumberInputPackets = 'mnip'

Returns a UInt32 reflecting the minimum number of packets that need to be supplied to the codec.

kAudioCodecPropertyMinimumNumberOutputPackets = 'mnop'

Returns a UInt32 indicating the minimum number of output packets that need to be handled from the codec.

kAudioCodecPropertyZeroFramesPadded = 'pad0'

Returns a UInt32 indicating the number of zeroes (samples) that were appended to the last packet of input data to make it a complete packet.

kAudioCodecPropertyChannelLayout = 'cmap'

Returns an array of AudioChannelLayout structures that specifies the channel layout that the codec is using.

kAudioCodecPropertyAvailableChannelLayouts = 'cmp#'

Returns an array of AudioChannelLayout structures array that contains the channel layouts the codec is capable of using.

kAudioCodecPrimeMethod = 'prmm'

Passes back a kAudioCodecPrimeMethod constant specifying the priming method currently used by the codec. See “Priming Selectors” for possible values.

kAudioCodecPrimeInfo = 'prim'

Uses a pointer to an instance of AudioCodecPrimeInfo to specify the leading and trailing number of frames used in priming.

Base Classes

There are three classes provided in the Audio Codec SDK, located in /AudioCodecs/ACPublic/, one of which must be subclassed when developing a codec: ACCodec, ACBaseCodec, and ACSimpleCodec. It is strongly advised that the developer subclass ACBaseCodec over ACCodecwhen developing an audio codec, since it provides many of the property and format management feature required of an audio codec. Note that abstract methods that exist in ACCodec must be implemented in subclasses of ACBaseCodec and ACSimpleCodec.

ACCodec

ACCodec defines the basic methods which any audio codec must implement to be used in Mac OS X. Most of the methods belonging to ACCodec are abstract, since they need to customized by the codec developer for the codec being implemented. Please note that many of these methods are implemented by ACBaseCodec and ACSimpleCodec.

Construction and Destruction

Constructors and destructors should be implemented for the codec as needed, and should at least allocate the needed buffer space for the codec and deallocate the space upon the codec’s destruction.

Property Management

These methods provide access to the property management system, which keeps track of various pieces of information about the codec. Their implementation is required since other components in Core Audio rely on their existence. Note that ACBaseCodec contains implementations of these methods that are adequate for most uses.

GetPropertyInfo

Passes back the size of the property data belonging to inPropertyID, and its writable state.

virtual void GetPropertyInfo(
AudioCodecPropertyID inPropertyID,
UInt32& outSize,
bool& outWritable
) = 0

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.1.

Declared In

GetProperty

Passes the property data belonging to inPropertyID into outPropertyData.

virtual void GetProperty(
AudioCodecPropertyID inPropertyID,
UInt32& ioPropertyDataSize,
void* outPropertyData
) = 0

Availability

• Available in Mac OS X v10.0 and later.

Declared In

SetProperty

Takes inPropertyData and sets it to the property data belonging to inPropertyID.

virtual void SetProperty(
AudioCodecPropertyID inPropertyID,
UInt32 inPropertyDataSize,
const void* inPropertyData
) = 0

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Data Handling

The Data Handling methods deal with getting data into, processed, and out of the audio codec. All of these methods are abstract and must be implemented by subclasses of ACCodec.

Initialize

Specifies the input and output formats for the data coming into and going out of the codec, as well as the magic cookie for the data currently being encoded or decoded.

virtual void Initialize(
const AudioStreamBasicDescription* inInputFormat,
const AudioStreamBasicDescription* inOutputFormat,
const void* inMagicCookie,
UInt32 inMagicCookieByteSize
) = 0

Discussion

When a codec is initialized, all of its properties should be locked, so that they may not be changed during the encoding or decoding. Note that a codec may be used only after it is initialized.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Uninitialize

Unlocks the codec, so that its properties may be altered.

virtual void Uninitialize() = 0

Discussion

An audio codec that has been uninitialized may not be used to encode or decode data, since its properties may be altered at any time.

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.1.

Declared In

AppendInputData

Passes in data to placed in the buffer for encoding or decoding.

virtual void AppendInputData(
const void* inInputData,
UInt32& ioInputDataByteSize,
UInt32& ioNumberPackets,
const AudioStreamPacketDescription* inPacketDescription
) = 0

Discussion

Here, inInputData is the data that should be put in the input buffer, and the rest of the parameters describe the size and nature of the data.

ProduceOutputPackets

Runs the codec and returns encoded or decoded data.

virtual UInt32 ProduceOutputPackets(
void* outOutputData,
UInt32& ioOutputDataByteSize,
UInt32& ioNumberPackets,
AudioStreamPacketDescription* outPacketDescription
UInt32& outStatus,
) = 0

Discussion

Calling ProduceOutputPackets() should pull ioNumberPackets from the buffer, encode or decoded them, and place them in outOutputData. The value of outStatus should be based on the kAudioCodecProduceOutputPacket set of enumerated values, informing the caller if the encode or decode failed, was a success, was a success and has more to encode or decode, was partially successful, yet needed more input, or was at the end of the file.

Reset

Clears out the codec’s input buffer and returns any state info to its initial settings.

virtual void Reset() = 0

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Component Support

An audio codec is a Component, and therefore, needs to be accessible from the Component Manager in order for an application to use it. These methods perform duties that Components must perform in order to be used.

Register

Registers the audio codec with the Component Manager.

virtual bool Register() const

Discussion

This method is provided in ACCodec and usually does not need to be overridden; however, Register() is virtual, should this be necessary.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

GetVersion

Returns the version number of the codec.

virtual UInt32 GetVersion() const

Discussion

This method should be overridden to reflect the version number of the codec; however, this is not required of the codec, only recommended.

ACBaseCodec

ACBaseCodec is provided as a base for building new audio codec components. It provides all of the Property Management features required of an audio codec, as well as most Format Management methods. Use of ACBaseCodec is encouraged when the audio codec being developed has its own custom buffering scheme, and would not benefit from the ring buffer already provided for in ACSimpleCodec.

Construction and Destruction

Constructors and destructors should be developed as needed, and may allocate the needed buffer space for the codec. Also, AddInputFormat and AddOutputFormat should be called from a constructor to set up descriptions for the codec’s supported formats.

Property Management

These methods are required of an audio codec and are implemented for developer convenience in ACBaseCodec. While overriding these methods is possible, it is usually not necessary.

GetPropertyInfo

Takes in an AudioCodecPropertyID, and, by reference, passes back the size of the property data, and a flag telling if the property is writable.

virtual void GetPropertyInfo(
AudioCodecPropertyID inPropertyID,
UInt32& outPropertyDataSize,
bool& outWritable
)

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.1.

Declared In

GetProperty

Takes in a AudioCodecPropertyID, the property data size (attained using GetPropertySize()), and a void pointer for the resulting data.

virtual void GetProperty(
AudioCodecPropertyID inPropertyID,
UInt32& ioPropertyDataSize,
void* outPropertyData)

Discussion

inPropertyID corresponds to any of the properties listed in the Audio Codec Properties section. For the outPropertyData parameter, pass in a void pointer, and the data promised for the property will be passed back into the pointer, typecast to the appropriate type.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

SetProperty

Takes in the AudioCodecPropertyID of the property to be set, the size of the data to be set, and a void pointer to the data.

virtual void SetProperty(
AudioCodecPropertyID inPropertyID,
UInt32 inPropertyDataSize,
const void* inPropertyData
)

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Data Handling

These methods are used for initialization, uninitialization, and like-minded methods for a codec. Many of these methods may be left as implemented in ACBaseCodec, but may be overridden as needed. Note that some methods are abstract, meaning that, in an ACBaseCodec subclass, they must be implemented.

IsInitialized

Returns the value of mIsInitialized, which should be set in Initialize() and Uninitialize().

bool IsInitialized() const { return mIsInitialized; }

Initialize

Passes in an input and output format, the codec’s magic cookie, and the cookie’s size.

virtual void Initialize(
const AudioStreamBasicDescription* inInputFormat,
const AudioStreamBasicDescription* inOutputFormat,
const void* inMagicCookie,
UInt32 inMagicCookieByteSize)

Discussion

The purpose of Initialize() is to provide a mechanism for the codec user to specify the formats of the incoming and outgoing data, the proper data for the magic cookie, and the size of the magic cookie. Initializing a codec should lock it so that none of its attributes maybe changed. Note that encoding and decoding should only commence after the codec is initialized

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Uninitialize

Unlocks the codec, so that its attributes may be modified.

virtual void Uninitialize()

Discussion

Note that no encoding or decoding should be allowed when an audio codec is uninitialized.

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.1.

Declared In

Reset

Clears out the codec’s buffer and returns it to the post-initialized state.

virtual void Reset()

Availability

• Available in Mac OS X v10.0 and later.

Declared In

GetInputBufferSize

Returns the current input buffer size as a UInt32.

virtual UInt32 GetInputBufferByteSize() const = 0

Discussion

This abstract method must be implemented by any subclass of ACBasicCodec, since the return value is dependant on the buffer size used in the buffer scheme implemented by the developer.

GetUsedInputBufferSize

Returns a UInt32 which reflects how much of the input buffer is currently filled up.

virtual UInt32 GetUsedInputBufferByteSize() const = 0

Discussion

This abstract method must be implemented by any subclass of ACBasicCodec.

ReallocateInputBuffer

Resizes the buffer to inInputBufferSize.

virtual void ReallocateInputBuffer(UInt32 inInputBufferByteSize) = 0

Discussion

For codecs which implement user-definable input buffer sizes, ReallocateInputBuffer() is a mechanism which allows for resizing of the input buffer.

Format Management

This portion of ACBaseCodec focuses on keeping track of the formats that a codec can decode and encode. If should be noted that while none of these methods are declared abstract, it would be advantageous to override some of them; conversely, some of these methods are not virtual, so what ACBasicCodec implements for them is adequate.

GetNumberSupportedInputFormats

Counts and returns the number of formats that the codec supports.

UInt32 GetNumberSupportedInputFormats() const

GetSupportedInputFormats

Passes back an array of the supported input formats for this codec.

void GetSupportedInputFormats(
AudioStreamBasicDescription* outInputFormats,
UInt32& ioNumberInputFormats
) const

Discussion

After the number of supported formats is acquired, it should be used in this method, which will pass back an AudioStreamBasicDescription array which contains the descriptions of all of the supported input formats. ioNumberInputFormats is also passed back as a check to ensure that the correct number of formats were returned.

GetCurrentInputFormat

Passes back an AudioStreamBasicDescription with the current input format information in it.

void GetCurrentInputFormat(AudioStreamBasicDescription& outInputFormat)

SetCurrentInputFormat

Takes an AudioStreamBasicDescription and sets it to be the current input format.

virtual void SetCurrentInputFormat(
const AudioStreamBasicDescription& inInputFormat
)

Discussion

Setting a codec’s input format is performed by calling this method and passing it an instance of AudioStreamBasicDescription, configured to the proper format. Note that ACBasicCodec provides a method for setting the current input format for the codec, but that this may need to be overridden based on the implemented codec’s capabilities.

GetNumberSupportedOutputFormats

Counts and returns the number of supported output formats.

UInt32 GetNumberSupportedOutputFormats() const

GetSupporedOutputFormats

Passes back and array of the supported output formats.

void GetSupportedOutputFormats(
AudioStreamBasicDescription* outOutputFormats,
UInt32& ioNumberOutputFormats
) const

Discussion

The value of outOutputFormats is an AudioStreamBasicDescription array. The input for ioNumberOutputFormats should be the result of GetNumberSupportedOutFormats(), and its output will be the actual number of AudioStreamBasicDescription instances in outOutputFormats.

GetCurrentOutputFormat

Passes back a description of the current output format.

void GetCurrentOutputFormat(AudioStreamBasicDescription& outOutputFormat)

SetCurrentOutputFormat

Sets the output format to inOutputFormat.

virtual void SetCurrentOutputFormat(
const AudioStreamBasicDescription& inOutputFormat
)

Discussion

This method is declared as virtual, so that it may be modified as needed to adjust to the needs of different codecs.

GetMagicCookieByteSize

Returns the size of the current magic cookie.

virtual UInt32 GetMagicCookieByteSize() const

Discussion

If the codec implements a magic cookie, it is strongly advised that the codec developer override this method, since each codec’s magic cookie has its own size.

GetMagicCookie

Extracts the magic cookie from the codec.

virtual void GetMagicCookie(
void* outMagicCookieData,
UInt32& ioMagicCookieDataByteSize
) const

Discussion

This method is virtual and should be overridden based on the codec’s requirements for magic cookies.

SetMagicCookie

Sets the magic cookie for the codec.

virtual void SetMagicCookie(
const void* outMagicCookieData,
UInt32 inMagicCookieDataByteSize
)

Discussion

This method is virtual and should be overridden based on the codec’s requirements for magic cookies.

AddInputFormat

Adds inInputFormat to the mInputFormatList.

void AddInputFormat(const AudioStreamBasicDescription& inInputFormat)

Discussion

This method is provided for the subclass’s constructor, so that the developer may supply input format information. This is then used by other methods in the Property Management system.

AddOutputFormat

Adds inOutputFormat to the mOutputFormatList.

void AddOutputFormat(const AudioStreamBasicDescription& inIOutputFormat)

Discussion

This method is provided for the subclass’s constructor, so that the developer may supply input format information. This is then used by other methods in the Property Management system.

ACSimpleCodec

ACSimpleCodec builds upon the foundation laid in ACBaseCodec by providing a simple ring buffer implementation. Subclassing from ACSimpleCodec is not required, but when the implemented codec does not require a custom buffering scheme, using ACSimpleCodec is recommended.

Construction and Destruction

The ACSimpleCodec constructor takes in the size that the ring buffer should be, in bytes, and allocates the appropriate space in memory. The destructor deallocates the buffer, and should be called from any subclass’s destructor.

Data Handling

ACSimpleCodec inherits all of the format and property management methods from ACBaseCodec, and so the only methods that need overridding for ACSimpleCodec are those pertaining to Data Handling; that is, those that deal with taking in and outputting converted data.

Initialize

Sets the codec’s input format, output format, and its current magic cookie.

virtual void Initialize(
const AudioStreamBasicDescription* inInputFormat,
const AudioStreamBasicDescription* inOutputFormat,
const void* inmagicCookie,
UInt32 inmagicCookieByteSize
) = 0

Discussion

This method initializes the codec, meaning that is locks down the input and output formats, as well as the magic cookie for the buffer that is about to be encoded. It also locks all of the codecs properties, so that they may not be altered during a conversion. Encoding and decoding should be possible only when the codec is initialized. Note that this method is declared as abstract, meaning that it must be overridden by any subclass of ACSimpleCodec; this is due to varying magic cookie implementations.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Uninitialize

Unlocks the codec so that its formats and properties may be altered.

virtual void Uninitialize()

Discussion

This method is virtual, meaning that it may be overridden as needed in subclasses of ACSimpleCodec.

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.1.

Declared In

Reset

Clears the codec’s buffer and returns the codec to the post-initialization state.

virtual void Reset()

Discussion

This method is virtual, meaning that it may be overridden as needed in subclasses of ACSimpleCodec.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

AppendInputData

Takes a buffer of data in, along with its format description and size information.

virtual void AppendInputData(
const void* inInputData,
UInt32& ioInputDataByteSize,
UInt32& ioNumberPackets,
const AudioStreamPacketDescription* inPacketDescription
)

Discussion

Note that this method is virtual, meaning that while ACSimpleCodec provides this service, it may be overridden if the codec requires it.

GetInputBufferSize

Returns the size of the codec’s buffer.

virtual UInt32 GetInputBufferByteSize() const

Discussion

Note that this method is virtual, meaning that while ACSimpleCodec provides this service, it may be overridden if the codec requires it.

GetUsedInputBufferSize

Returns the size of the codec’s buffer currently in filled.

virtual UInt32 GetUsedInputBufferByteSize() const

Discussion

Note that this method is virtual, meaning that while ACSimpleCodec provides this service, it may be overridden if the codec requires it.

ConsumeInputData

Runs inConsumedByteSize amount of data through the codec.

void ConsumeInputData(UInt32 inConsumedByteSize)

Discussion

This method should be called from within the codec’s ProduceOutputPackets().

GetInputBufferStart

Returns the current start position of the buffer.

Byte* GetInputBufferStart() const {
return mInputBuffer + mInputBufferStart;
}

GetInputBufferContiguousByteSize

Returns the amount of the buffer left to process.

UInt32 GetInputBufferContiguousByteSize() const {
return (mInputBufferStart <= mInputBufferEnd)
? (mInputBufferEnd - mInputBufferStart)
: (mInputBufferByteSize - mInputBufferStart)
}

ReallocateInputBuffer

Resizes the buffer to a new size.

virtual void ReallocateInputBuffer(UInt32 inInputBufferByteSize)

Discussion

Calling this method wipes the buffer contents before it resizes it. Note that this method is virtual, so it may be overridden as needed.

Audio Codec Result Codes

These constants define errors that Audio Codec methods can return when processing data.

kAudioCodecNoError = 0,

kAudioCodecUnspecifiedError = 'what',

kAudioCodecUnknownPropertyError = 'who?',

kAudioCodecBadPropertySizeError ='!siz',

kAudioCodecIllegalOperationError = 'nope',

kAudioCodecUnsupportedFormatError = '!dat',

kAudioCodecStateError ='!stt',

kAudioCodecNotEnoughBufferSpaceError = '!buf'

< Previous PageNext Page > Hide TOC