/*==================================================================================================
     File:       AudioUnit/AudioCodec.h

     Contains:   A component API for encoding/decoding audio data.

     Copyright:  (c) 1985-2008 by Apple, Inc., all rights reserved.

     Bugs?:      For bug reports, consult the following page on
                 the World Wide Web:

                     http://developer.apple.com/bugreporter/

==================================================================================================*/
#if !defined(__AudioCodec_h__)
#define __AudioCodec_h__

/*!
	@header AudioCodec
 
	This header defines the property sets and the public API for various audio codecs.

	<h2>Theory of Operation</h2>
 
	AudioCodec components translate audio data from one format to another. There
	are three kinds of AudioCodec components. Decoder components ('adec') 
	translate data that isn't in linear PCM into linear PCM formatted data. 
	Encoder components ('aenc') translate linear PCM data into some other format. 
	Unity codecs ('acdc') translate between different flavors of the same type 
	(e.g. 16 bit signed integer linear PCM into 32 bit floating point linear PCM).
 
	AudioCodec components are standard components and are managed by the Component
	Manager.
 
	Once an AudioCodec is found that implements the translation in question,
	it has to be set up to do the translation. This can be done by setting the
	appropriate properties or by calling AudioCodecInitialize. If the translation
	is specified by properties, AudioCodecInitialize still needs to be called
	prior to appending input data or producing output data.
 
	AudioCodecInitialize puts the codec into the "initialized" state. In this state,
	the format information for the translation cannot be changed. The codec
	has to be in the initialized state for AudioCodecAppendInputData and
	AudioCodecProduceOutputData to work. They will return kAudioCodecStateError
	if the codec isn't initialized.
 
	AudioCodecUninitialize will return the codec to the uninitialized state and
	release any allocated resources. The codec may then be configured freely. It is not
	necessary to call AudioCodecUninitialize prior to closing the codec.
 
	Once in the initialized state, the codec is ready to receive input and produce
	output using the AudioCodecAppendInputData and AudioCodecProduceOutputData
	routines. Input data can be fed into an encoder and some decoders in any size (even 
	byte by byte). Input data fed to a decoder should be in terms of whole packets in the 
	encoded format if the format is variable bit rate and is not self framing (e.g. MPEG-4 AAC). 
	Output data can only be produced in whole packet sizes. Both routines will return 
	the amount of data they consume/produce.
 
	AudioCodecProduceOutputData also returns a status code to the caller that
	indicates the result of the operation (success or failure) as well as the
	state of the input buffer.
	
	The combination of AppendInputData and ProduceOutputPackets can be thought of a "push-pull"
	model of data handling. First, the input data is pushed into the component and the 
	resulting output data gets pulled out of that same component.
 
	Basic Workflow
	1. Find the appropriate codec component
	2. Open the codec component
	3. Configure it (AudioCodecGetPropertyInfo, AudioCodecGetProperty, AudioCodecSetProperty)
	4. AudioCodecInitialize
	5. Loop
		a. AppendInputData (EOF is signaled by passing a 0-sized buffer)
		b. ProduceOutputPackets
	6. Close the codec component
	
 */

//=============================================================================

#include <TargetConditionals.h>
#include <Availability.h>

#if !defined(__COREAUDIO_USE_FLAT_INCLUDES__)
	#include <CoreAudio/CoreAudioTypes.h>
	#include <AudioUnit/AudioComponent.h>
#else
	#include "AudioComponent.h"
	#include "CoreAudioTypes.h"
#endif

#if defined(__cplusplus)
extern "C"
{
#endif


//=============================================================================
#pragma mark Types specific to AudioCodecs
//=============================================================================


typedef AudioComponentInstance	AudioCodec;
typedef UInt32					AudioCodecPropertyID;

/*!
    @struct AudioCodecMagicCookieInfo
 
	@abstract Structure holding the <em>magic cookie</em> information.
 
	@discussion Passed as input to AudioCodecGetProperty for kAudioCodecPropertyFormatList.
				The first four + sizeof(void *) bytes of the buffer pointed at by outPropertyData
				will contain this struct.
 
	@field mMagicCookieSize
        The size of the magic cookie
	@field mMagicCookie
        Generic const pointer to magic cookie
*/
struct AudioCodecMagicCookieInfo 
{
	UInt32			mMagicCookieSize;
	const void*		mMagicCookie;
};
typedef struct AudioCodecMagicCookieInfo	AudioCodecMagicCookieInfo;

//=============================================================================
#pragma mark AudioCodec Component Constants
//=============================================================================


#if !TARGET_OS_IPHONE
/*!
	@enum           AudioCodecComponentType
 
	@discussion     Collection of audio codec component types
 
	@constant		kAudioDecoderComponentType
					A codec that translates data in some other format into linear PCM.
					The component subtype specifies the format ID of the other format.
	@constant		kAudioEncoderComponentType
					A codec that translates linear PCM data into some other format
					The component subtype specifies the format ID of the other format
	@constant		kAudioUnityCodecComponentType
					A codec that translates between different flavors of the same format
					The component subtype specifies the format ID of this format.
*/
enum
{
	kAudioDecoderComponentType								= 'adec',	
	kAudioEncoderComponentType								= 'aenc',	
	kAudioUnityCodecComponentType							= 'acdc'
};
#endif

//=============================================================================
#pragma	mark Global Codec Properties

//	Used with the AudioCodecXXXXPropertyXXXX family of routines.
//	All Audio Codec properties are readable only.
//=============================================================================

/*!
	@enum		AudioCodecGlobalProperty

	@discussion	These properties reflect the capabilities of the underlying codec.
				The values of these properties are independent of the codec's internal
				state.
				
				These properties can be read at any time the codec is open.

	@constant	kAudioCodecPropertySupportedInputFormats
					An array of AudioStreamBasicDescription structs describing what formats 
					the codec supports for input data
	@constant	kAudioCodecPropertySupportedOutputFormats
					An array of AudioStreamBasicDescription structs describing what formats 
					the codec supports for output data
 	@constant	kAudioCodecPropertyAvailableInputSampleRates
					An array of AudioValueRange indicating the valid ranges for the
					input sample rate of the codec.
					Required for encoders.
					(see also kAudioCodecPropertyApplicableInputSampleRates)
	@constant	kAudioCodecPropertyAvailableOutputSampleRates
					An array of AudioValueRange indicating the valid ranges for the
					output sample rate of the codec.
					Required for encoders.
					(see also kAudioCodecPropertyApplicableOutputSampleRates)
	@constant	kAudioCodecPropertyAvailableBitRateRange
					An array of AudioValueRange that indicate the target bit rates
					supported by the encoder. This can be total bit rate or bit
					rate per channel as appropriate. 
					This property is only relevant to encoders.
					(see also kAudioCodecPropertyApplicableBitRateRange)
	@constant	kAudioCodecPropertyMinimumNumberInputPackets
					A UInt32 indicating the minimum number of input packets
					that need to be supplied to the codec. The actual input the
					codec accepts could be less than this.
					For most codecs this value will be 1.
	@constant	kAudioCodecPropertyMinimumNumberOutputPackets
					A UInt32 indicating the minimum number of output packets
					that need to be handled from the codec. The actual output
					might be less than this.
					For most codecs this value will be 1.
	@constant	kAudioCodecPropertyAvailableNumberChannels
					An array of UInt32 that specifies the number of channels the codec is
					capable of encoding or decoding to. 0xFFFFFFFF means any number
					of channels.
	@constant	kAudioCodecPropertyDoesSampleRateConversion
					A UInt32 indicating if the codec wants to do a sample rate conversion (if 
					necessary) because it can do it in a way that is meaningful for quality.
					Value is 1 if true, 0 otherwise.
	@constant	kAudioCodecPropertyAvailableInputChannelLayoutTags
					An array of AudioChannelLayoutTag that specifies what channel layouts the codec is
					capable of using on input.
	@constant	kAudioCodecPropertyAvailableOutputChannelLayoutTags
					An array of AudioChannelLayoutTag that specifies what channel layouts the codec is
					capable of using on output.
	@constant	kAudioCodecPropertyInputFormatsForOutputFormat
					An array of AudioStreamBasicDescription indicating what the codec supports
					for input data given an output format that's passed in as the first member of
					the array (and is overwritten on the reply). Always a subset of 
					kAudioCodecPropertySupportedInputFormats
	@constant	kAudioCodecPropertyOutputFormatsForInputFormat
					An array of AudioStreamBasicDescription indicating what the codec supports
					for output data given an input format that's passed in as the first member of
					the array (and is overwritten on the reply). Always a subset of 
					kAudioCodecPropertySupportedOutputFormats
	@constant	kAudioCodecPropertyFormatInfo
					Takes an AudioFormatInfo on input. This AudioformatInfo is validated either through
					the provided magic cookie or the AudioStreamBasicDescription and where applicable,
					wildcards are overwritten with default values.
*/
enum
{
	kAudioCodecPropertySupportedInputFormats				= 'ifm#',
	kAudioCodecPropertySupportedOutputFormats				= 'ofm#',
	kAudioCodecPropertyAvailableInputSampleRates			= 'aisr',
	kAudioCodecPropertyAvailableOutputSampleRates			= 'aosr',
	kAudioCodecPropertyAvailableBitRateRange				= 'abrt',
	kAudioCodecPropertyMinimumNumberInputPackets			= 'mnip',
	kAudioCodecPropertyMinimumNumberOutputPackets			= 'mnop',
	kAudioCodecPropertyAvailableNumberChannels				= 'cmnc',
	kAudioCodecPropertyDoesSampleRateConversion				= 'lmrc',
	kAudioCodecPropertyAvailableInputChannelLayoutTags		= 'aicl',
	kAudioCodecPropertyAvailableOutputChannelLayoutTags		= 'aocl',
	kAudioCodecPropertyInputFormatsForOutputFormat			= 'if4o',		
	kAudioCodecPropertyOutputFormatsForInputFormat			= 'of4i',
	kAudioCodecPropertyFormatInfo							= 'acfi'
};

//=============================================================================
#pragma	mark Instance Codec Properties

//	Used with the AudioCodecXXXXPropertyXXXX family of routines.
//=============================================================================

/*!
	@enum			AudioCodecInstanceProperty
 
	@discussion		Properties which can be set or read on an instance of the
					underlying audio codec. These properties are dependent on the 
					codec's current state. A property may be read/write or read
					only, depending on the data format of the codec.
					
					These properties may have different values depending on whether the
					codec is initialized or not. All properties can be read at any time
					the codec is open. However, to ensure the codec is in a valid 
					operational state and therefore the property value is valid the codec
					must be initialized at the time the property is read.
					
					Properties that are writable are only writable when the codec
					is not initialized.
 
	@constant		kAudioCodecPropertyInputBufferSize
						A UInt32 indicating the maximum input buffer size for the codec
						in bytes. 
						Not writable, but can vary on some codecs depending on the bit stream 
						format being handled.
	@constant		kAudioCodecPropertyPacketFrameSize
						A UInt32 indicating the number of frames of audio data encapsulated in each
						packet of data in the codec's format. For encoders, this is the
						output format. For decoders this is the input format.
						Formats with variable frames per packet should return a maximum value 
						for this property.
						Not writable.
	@constant		kAudioCodecPropertyHasVariablePacketByteSizes
						A UInt32 where 0 indicates that all packets in the codec's format
						have the same byte size (sometimes referred to as CBR codecs),
						and 1 indicates that they vary in size (sometimes referred to as 
						VBR codecs). The maximum size of a variable packet is up to 
						the one indicated in kAudioCodecPropertyMaximumPacketByteSize.
						Any codec that reports 1 for this property must be able to handle packet
						descriptions, though it does not have to require them.
						May be writable.
	@constant		kAudioCodecPropertyMaximumPacketByteSize
						A UInt32 indicating the maximum number of bytes a packet of data
						in the codec's format will be. If the format is constant bit rate,
						all packets will be this size. If it is variable bit rate, the packets
						will never exceed this size.
						This always refers to the encoded data, so for encoders it refers to the
						output data and for decoders the input data.
						Not writable.
	@constant		kAudioCodecPropertyCurrentInputFormat
						An AudioStreamBasicDescription describing the format the codec
						expects its input data in
						Almost always writable, but if the codec only supports one unique input format
						it does not have to be
	@constant		kAudioCodecPropertyCurrentOutputFormat
						An AudioStreamBasicDescription describing the format the codec
						provides its output data in
						Almost always writable, but if the codec only supports one unique output format
						it does not have to be
	@constant		kAudioCodecPropertyMagicCookie
						An untyped buffer of out of band configuration data the codec
						requires to process the stream of data correctly. The contents
						of this data is private to the codec. 
						Not all codecs have magic cookies. If a call to AudioCodecGetPropertyInfo
						returns a size greater than 0 then the codec may take one.
						Writable if present.
	@constant		kAudioCodecPropertyUsedInputBufferSize
						A UInt32 indicating the number of bytes in the codec's input
						buffer. The amount of available buffer space is	simply the
						answer from kAudioCodecPropertyInputBufferSize minus the answer
						from this property.
						Not writable.
	@constant		kAudioCodecPropertyIsInitialized
						A UInt32 where 0 means the codec is uninitialized and anything
						else means the codec is initialized. This should never be settable directly.
						Must be set by AudioCodecInitialize and AudioCodecUninitialize.
	@constant		kAudioCodecPropertyCurrentTargetBitRate
						A UInt32 containing the number of bits per second to aim for when encoding
						data. This property is usually only relevant to encoders, but if a decoder
						can know what bit rate it's set to it may report it.
						This property is irrelevant if the encoder is configured as kAudioCodecBitRateControlMode_Variable.
						Writable on encoders if supported.
	@constant		kAudioCodecPropertyCurrentInputSampleRate
						A Float64 containing the current input sample rate in Hz. No Default.
						May be writable. If only one sample rate is supported it does not have to be.
	@constant		kAudioCodecPropertyCurrentOutputSampleRate
						A Float64 containing the current output sample rate in Hz. No Default.
						May be writable. If only one sample rate is supported it does not have to be.
	@constant		kAudioCodecPropertyQualitySetting
						A UInt32 that sets the tradeoff between sound quality and CPU time consumption.
						The property value is between [0 - 0x7F].
						Some enum constants are defined below for convenience.
						Writable if supported.
	@constant		kAudioCodecPropertyApplicableBitRateRange
						An array of AudioValueRange indicating the target bit rates
						supported by the encoder in its current configuration.
						This property is only relevant to encoders.
						See also kAudioCodecPropertyAvailableBitRateRange.
						Not writable.
	@constant		kAudioCodecPropertyApplicableInputSampleRates
						An array of AudioValueRange indicating the valid ranges for the
						input sample rate of the codec for the current bit rate. 
						This property is only relevant to encoders.
						See also kAudioCodecPropertyAvailableInputSampleRates.
						Not writable.
	@constant		kAudioCodecPropertyApplicableOutputSampleRates
						An array of AudioValueRange indicating the valid ranges for the
						output sample rate of the codec for the current bit rate. 
						This property is only relevant to encoders.
						See also kAudioCodecPropertyAvailableOutputSampleRates.
						Not writable.
	@constant		kAudioCodecPropertyPaddedZeros
						A UInt32 indicating the number of zeros (samples) that were appended
						to the last packet of input data to make a complete packet encoding.
						Encoders only. No default.
						Not writable.
	@constant		kAudioCodecPropertyPrimeMethod
						A UInt32 specifying priming method.
						See enum below.
						May be writable. Some encoders offer the option of padding out the last packet, and this 
						may be set here.
	@constant		kAudioCodecPropertyPrimeInfo
						A pointer to an AudioCodecPrimeInfo struct.
						Not writable on encoders. On decoders this may be writable, telling the decoder to trim the
						first and/or last packet.
	@constant		kAudioCodecPropertyCurrentInputChannelLayout
						An AudioChannelLayout that specifies the channel layout that the codec is using for input.
						May be writable. If only one channel layout is supported it does not have to be.
	@constant		kAudioCodecPropertyCurrentOutputChannelLayout
						An AudioChannelLayout that specifies the channel layout that the codec is using for output.
						If settable on a encoder, it means the encoder can re-map channels
						May be writable. If only one channel layout is supported or the codec does no channel remapping
						(ie, output channel layout always equals the input channel layout) it does not have to be.
	@constant		kAudioCodecPropertySettings
						A CFDictionaryRef that lists both the settable codec settings and their values.
						Encoders only.
						Obviously this will be linked to many of the other properties listed herein and as such
						it potentially will cause synchronization problems. Therefore, when setting this property
						on an encoder a GetProperty should be done first to retrieve the current dictionary, 
						and only one setting within the dictionary should change with each SetProperty call, 
						as it is not guaranteed that changing one property will not have side effects.
						Writable if supported.
	@constant		kAudioCodecPropertyBitRateControlMode
						A UInt32 indicating which bit rate control mode will be applied to encoders that 
						can produce variable packet sizes (sometimes referred to as VBR encoders).
						Although the packet size may be variable, a constant bit rate can be maintained 
						over a transmission channel when decoding in real-time with a fixed end-to-end audio delay. 
						E.g., MP3 and MPEG-AAC use a bit reservoir mechanism to meet that constraint.
						See enum below. 
						Only needs to be settable if the codec supports multiple bit rate control strategies.
	@constant		kAudioCodecPropertyFormatList
						An array of AudioFormatListItem structs list all formats that can be handled by the decoder
						For decoders, takes a Magic Cookie that gets passed in on the GetProperty call. No default.
						On input, the outPropertyData parameter passed to GetProperty should begin with a 
						AudioCodecMagicCookieInfo struct which will be overwritten by the AudioFormatListItems 
						returned from the property. For encoders, returns a list of formats which will be in the
						bitstream. No input data required.
						Important note: this encoder property is only applicable to audio formats which are made of
						two or more layers where the base layers(s) can be decoded by systems which aren't capable of
						handling the enhancement layers. For example, a High Efficiency AAC bitstream which contains 
						an AAC Low Complexity base layer can be decoded by any AAC decoder.
	@constant		kAudioCodecPropertySoundQualityForVBR
						A UInt32 that sets a target sound quality level.
						Unlike kAudioCodecPropertyQualitySetting which is relevant to all BitRate Control Modes,
						this property only needs to be set by an encoder configured at kAudioCodecBitRateControlMode_Variable.
						The property value is between [0 - 0x7F].
						See also kAudioCodecPropertyQualitySetting
						Writable if supported.
    @constant		kAudioCodecPropertyDelayMode
                        A UInt32 specifying the delay mode. See enum below.                        
                        Encoders only, writable if supported.
 */
enum
{
	kAudioCodecPropertyInputBufferSize											= 'tbuf',
	kAudioCodecPropertyPacketFrameSize											= 'pakf',
	kAudioCodecPropertyHasVariablePacketByteSizes								= 'vpk?',
	kAudioCodecPropertyMaximumPacketByteSize									= 'pakb',
	kAudioCodecPropertyCurrentInputFormat										= 'ifmt',
	kAudioCodecPropertyCurrentOutputFormat										= 'ofmt',
	kAudioCodecPropertyMagicCookie												= 'kuki',
	kAudioCodecPropertyUsedInputBufferSize										= 'ubuf',
	kAudioCodecPropertyIsInitialized											= 'init',
	kAudioCodecPropertyCurrentTargetBitRate										= 'brat',
  	kAudioCodecPropertyCurrentInputSampleRate									= 'cisr',
  	kAudioCodecPropertyCurrentOutputSampleRate									= 'cosr',
	kAudioCodecPropertyQualitySetting											= 'srcq',
	kAudioCodecPropertyApplicableBitRateRange									= 'brta',	
	kAudioCodecPropertyApplicableInputSampleRates								= 'isra',	
	kAudioCodecPropertyApplicableOutputSampleRates								= 'osra',
	kAudioCodecPropertyPaddedZeros												= 'pad0',
	kAudioCodecPropertyPrimeMethod												= 'prmm',
	kAudioCodecPropertyPrimeInfo												= 'prim',
	kAudioCodecPropertyCurrentInputChannelLayout								= 'icl ',
	kAudioCodecPropertyCurrentOutputChannelLayout								= 'ocl ',
	kAudioCodecPropertySettings													= 'acs ',
	kAudioCodecPropertyFormatList												= 'acfl',
	kAudioCodecPropertyBitRateControlMode										= 'acbf',
	kAudioCodecPropertySoundQualityForVBR										= 'vbrq',
	kAudioCodecPropertyDelayMode                                                = 'dmod'
};


/*!
	@enum			AudioCodecQuality
 
	@discussion		Constants to be used with kAudioCodecPropertyQualitySetting
 
	@constant		kAudioCodecQuality_Max
	@constant		kAudioCodecQuality_High
	@constant		kAudioCodecQuality_Medium
	@constant		kAudioCodecQuality_Low
	@constant		kAudioCodecQuality_Min
*/
enum
{
	kAudioCodecQuality_Max		= 0x7F,
	kAudioCodecQuality_High		= 0x60,
	kAudioCodecQuality_Medium	= 0x40,
	kAudioCodecQuality_Low		= 0x20,
	kAudioCodecQuality_Min		= 0
};


/*!
	@enum			AudioCodecPrimeMethod
 
	@discussion		Constants to be used with kAudioCodecPropertyPrimeMethod.
 
	@constant		kAudioCodecPrimeMethod_Pre
						Primes with leading and trailing input frames
	@constant		kAudioCodecPrimeMethod_Normal
						Only primes with trailing (zero latency)
						leading frames are assumed to be silence
	@constant		kAudioCodecPrimeMethod_None
						Acts in "latency" mode
						both leading and trailing frames assumed to be silence
*/
enum
{
	kAudioCodecPrimeMethod_Pre 		= 0,
	kAudioCodecPrimeMethod_Normal 	= 1,
	kAudioCodecPrimeMethod_None 	= 2
};


/*!
	@enum			kAudioCodecPropertyBitRateControlMode
 
	@discussion		Constants defining various bit rate control modes
					to be used with kAudioCodecPropertyBitRateControlMode.
					These modes are only applicable to encoders that can produce
					variable packet sizes, such as AAC.

	@constant		kAudioCodecBitRateControlMode_Constant
						The encoder maintains a constant bit rate suitable for use over a transmission 
						channel when decoding in real-time with a fixed end-to-end audio delay.  
						Note that while a constant bit rate is maintained in this mode, the number of bits 
						allocated to encode each fixed length of audio data may be variable 
						(ie. packet sizes are variable).
						E.g., MP3 and MPEG-AAC use a bit reservoir mechanism to meet that constraint.
	@constant		kAudioCodecBitRateControlMode_LongTermAverage
						 The provided target bit rate is achieved over a long term average
						 (typically after the first 1000 packets). This mode is similar to 
						 kAudioCodecBitRateControlMode_Constant in the sense that the 
						 target bit rate will be maintained in a long term average. However, it does not 
						 provide constant delay when using constant bit rate transmission. This mode offers 
						 a better sound quality than kAudioCodecBitRateControlMode_Constant 
						 can, that is, a more efficient encoding is performed. 
	@constant		kAudioCodecBitRateControlMode_VariableConstrained
						Encoder dynamically allocates the bit resources according to the characteristics
						of the underlying signal. However, some constraints are applied in order to limit 
						the variation of the bit rate.
	@constant		kAudioCodecBitRateControlMode_Variable
						Similar to the VBR constrained mode, however the packet size is virtually unconstrained.
						The coding process targets constant sound quality, and the sound quality level is 
						set by kAudioCodecPropertySoundQualityForVBR.
						This mode usually provides the best tradeoff between quality and bit rate.
*/
enum
{
	kAudioCodecBitRateControlMode_Constant					= 0,
	kAudioCodecBitRateControlMode_LongTermAverage			= 1,
	kAudioCodecBitRateControlMode_VariableConstrained		= 2,
	kAudioCodecBitRateControlMode_Variable					= 3,
};

/*!
    @enum			AudioCodecDelayMode
 
    @discussion		Constants defining various delay modes to be used with kAudioCodecPropertyDelayMode.
                    The resulting priming frames are reflected in the kAudioCodecPropertyPrimeInfo property.
                    Note that for layered streams like aach and aacp, the priming information always refers
                    to the base layer.
    @constant		kAudioCodecDelayMode_Compatibility
                        In compatibility delay mode, the resulting priming corresponds to the default value defined by the
                        underlying codecs. For aac this number equals 2112 regardless of the sample rate and other settings.
    @constant		kAudioCodecDelayMode_Minimum
                        Sets the encoder, where applicable, in it's lowest possible delay mode. Any additional delays, like the one
                        introduced by filters/sample rate converters etc, aren't compensated by the encoder.
    @constant		kAudioCodecDelayMode_Optimal
                        In this mode, the resulting bitstream has the minimum amount of priming necessary for the decoder.
                        For aac this number is 1024 which corresponds to exactly one packet.
 */
enum
{
    kAudioCodecDelayMode_Compatibility  = 0,
    kAudioCodecDelayMode_Minimum        = 1,
    kAudioCodecDelayMode_Optimal        = 2
};

/*!
	@struct			AudioCodecPrimeInfo 
 
	@discussion		Specifies the number of leading and trailing empty frames
					which have to be inserted.
 
	@field			leadingFrames
						An unsigned integer specifying the number of leading empty frames
	@field			trailingFrames
						An unsigned integer specifying the number of trailing empty frames 
*/
typedef struct AudioCodecPrimeInfo 
{
	UInt32		leadingFrames;
	UInt32		trailingFrames;
} AudioCodecPrimeInfo;


//=============================================================================
#pragma mark -
#pragma mark Constants for kAudioCodecPropertySettings
//=============================================================================

#define kAudioSettings_TopLevelKey		"name"
#define kAudioSettings_Version			"version"
#define kAudioSettings_Parameters 		"parameters"
#define kAudioSettings_SettingKey		"key"
#define kAudioSettings_SettingName 		"name"
#define kAudioSettings_ValueType 		"value type"
#define kAudioSettings_AvailableValues	"available values"
#define kAudioSettings_LimitedValues	"limited values"
#define kAudioSettings_CurrentValue 	"current value"
#define kAudioSettings_Summary 			"summary"
#define kAudioSettings_Hint 			"hint"
#define kAudioSettings_Unit 			"unit"


/*!
	@enum			AudioSettingsFlag
 
	@discussion		Constants to be used with kAudioSettings_Hint
					in the kAudioCodecPropertySettings property dictionary.
					Indicates any special characteristics of each parameter within the dictionary, 

	@constant		kAudioSettingsFlags_ExpertParameter
						If set, then the parameter is an expert parameter.
	@constant		kAudioSettingsFlags_InvisibleParameter
						If set, then the parameter should not be displayed. 
	@constant		kAudioSettingsFlags_MetaParameter
						If set, then changing this parameter may affect the values of other parameters. 
						If not set, then this parameter can be set without affecting the values of other parameters.
	@constant		kAudioSettingsFlags_UserInterfaceParameter
						If set, then this is only a user interface element and not reflected in the codec's bit stream.
*/
enum {
	kAudioSettingsFlags_ExpertParameter			= (1L << 0),
	kAudioSettingsFlags_InvisibleParameter		= (1L << 1),
	kAudioSettingsFlags_MetaParameter			= (1L << 2),
	kAudioSettingsFlags_UserInterfaceParameter	= (1L << 3)
};


//=============================================================================
#pragma mark -
#pragma mark Status values returned from the AudioCodecProduceOutputPackets routine
//=============================================================================
/*!
	@enum			AudioCodecProduceOutputPacketStatus
 
	@discussion		Possible return status
 
	@constant		kAudioCodecProduceOutputPacketFailure
						Couldn't complete the request due to an error. It is possible
						that some output data was produced. This is reflected in the value
						returned in ioNumberPackets. 
	@constant		kAudioCodecProduceOutputPacketSuccess
						The number of requested output packets was produced without incident
						and there isn't any more input data to process
	@constant		kAudioCodecProduceOutputPacketSuccessHasMore
						The number of requested output packets was produced and there is
						enough input data to produce at least one more packet of output data
	@constant		kAudioCodecProduceOutputPacketNeedsMoreInputData
						There was insufficient input data to produce the requested
						number of output packets, The value returned in ioNumberPackets
						holds the number of output packets produced.
	@constant		kAudioCodecProduceOutputPacketAtEOF
						The end-of-file marker was hit during the processing. Fewer
						than the requested number of output packets may have been
						produced. Check the value returned in ioNumberPackets for the
						actual number produced. Note that not all formats have EOF
						markers in them. 
*/
enum
{
	kAudioCodecProduceOutputPacketFailure					= 1,		
	kAudioCodecProduceOutputPacketSuccess					= 2,	
	kAudioCodecProduceOutputPacketSuccessHasMore			= 3,		
	kAudioCodecProduceOutputPacketNeedsMoreInputData		= 4,		
	kAudioCodecProduceOutputPacketAtEOF						= 5		
};


//=============================================================================
#pragma mark -
#pragma mark Selectors for the component routines
//=============================================================================
/*!
	@enum			AudioCodecSelectors
 
	@discussion		Allows selection of component routines supported the the AudioCodec API
					Used by the Component Manager.
 
	@constant		kAudioCodecGetPropertyInfoSelect
	@constant		kAudioCodecGetPropertySelect
	@constant		kAudioCodecSetPropertySelect
	@constant		kAudioCodecInitializeSelect
	@constant		kAudioCodecUninitializeSelect
	@constant		kAudioCodecAppendInputDataSelect
	@constant		kAudioCodecProduceOutputDataSelect
	@constant		kAudioCodecResetSelect
	@constant		kAudioCodecAppendInputBufferListSelect
	@constant		kAudioCodecProduceOutputBufferListSelect
*/
enum
{
	kAudioCodecGetPropertyInfoSelect						= 0x0001,
	kAudioCodecGetPropertySelect							= 0x0002,
	kAudioCodecSetPropertySelect							= 0x0003,
	kAudioCodecInitializeSelect								= 0x0004,
	kAudioCodecUninitializeSelect							= 0x0005,
	kAudioCodecAppendInputDataSelect						= 0x0006,
	kAudioCodecProduceOutputDataSelect						= 0x0007,
	kAudioCodecResetSelect									= 0x0008,
	kAudioCodecAppendInputBufferListSelect					= 0x0009,
	kAudioCodecProduceOutputBufferListSelect				= 0x000A
};


//=============================================================================
#pragma mark -
#pragma mark Errors
//=============================================================================
/*!
	@enum			AudioCodecErrors
 
	@discussion		Possible errors returned by audio codec components
 
	@constant		kAudioCodecNoError
	@constant		kAudioCodecUnspecifiedError
	@constant		kAudioCodecUnknownPropertyError
	@constant		kAudioCodecBadPropertySizeError
	@constant		kAudioCodecIllegalOperationError
	@constant		kAudioCodecUnsupportedFormatError
	@constant		kAudioCodecStateError
	@constant		kAudioCodecNotEnoughBufferSpaceError
*/
enum
{
	kAudioCodecNoError								= 0,
	kAudioCodecUnspecifiedError						= 'what',
	kAudioCodecUnknownPropertyError					= 'who?',
	kAudioCodecBadPropertySizeError					= '!siz',
	kAudioCodecIllegalOperationError				= 'nope',
	kAudioCodecUnsupportedFormatError				= '!dat',
	kAudioCodecStateError							= '!stt',
	kAudioCodecNotEnoughBufferSpaceError			= '!buf'
};


//=============================================================================
#pragma mark -
#pragma mark Codec Property Management
//=============================================================================

/*!
	@function		AudioCodecGetPropertyInfo
 
	@discussion		Retrieve information about the given property. The outSize argument
					will return the size in bytes of the current value of the property.
					The outWritable argument will return whether or not the property
					in question can be changed.
 
	@param			inCodec
						An AudioCodec instance
	@param			inPropertyID
						Property ID whose value should be read
	@param			outSize
						Size in bytes of the property
	@param			outWritable
						Flag indicating wether the underlying property can be modified or not 
 
	@result			The OSStatus value
*/
extern OSStatus
AudioCodecGetPropertyInfo(	AudioCodec				inCodec,
							AudioCodecPropertyID	inPropertyID,
							UInt32*					outSize,
							Boolean*				outWritable)		__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0);


/*!
	@function		AudioCodecGetProperty
 
	@discussion		Retrieve the indicated property data. On input, ioDataSize has the size
					of the data pointed to by outPropertyData. On output, ioDataSize will contain
					the amount written.
 
	@param			inCodec
						An AudioCodec instance
	@param			inPropertyID
						Property ID whose value should be read
	@param			ioPropertyDataSize
						Size in bytes of the property data
	@param			outPropertyData
						Pointer to the property data buffer

	@result			The OSStatus value
*/
extern OSStatus
AudioCodecGetProperty(	AudioCodec				inCodec,
						AudioCodecPropertyID	inPropertyID,
						UInt32*					ioPropertyDataSize,
						void*					outPropertyData)		__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0);


/*!
	@function		AudioCodecSetProperty

	@discussion		Set the indicated property data.
 
	@param			inCodec
						An AudioCodec instance
	@param			inPropertyID
						Property ID whose value should be changed
	@param			inPropertyDataSize
						Size in bytes of the property data
	@param			inPropertyData
						Pointer to the property data buffer
 
	@result			The OSStatus value
*/
extern OSStatus
AudioCodecSetProperty(	AudioCodec				inCodec,
						AudioCodecPropertyID	inPropertyID,
						UInt32					inPropertyDataSize,
						const void*				inPropertyData)			__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0);


//=============================================================================
#pragma mark -
#pragma mark Codec Data Handling Routines
//=============================================================================

/*!
	@function		AudioCodecInitialize
 
	@discussion		This call will allocate any buffers needed and otherwise set the codec
					up to perform the indicated translation. If an argument is NULL, any
					previously set properties will be used for preparing the codec for work.
					Note that this routine will also validate the format information as useable.
 
	@param			inCodec
						An AudioCodec instance
	@param			inInputFormat
						Pointer to an input format structure
	@param			inOutputFormat
						Pointer to an output format structure
	@param			inMagicCookie
						Pointer to the magic cookie
	@param			inMagicCookieByteSize
						Size in bytes of the magic cookie
  
	@result			The OSStatus value
*/
extern OSStatus
AudioCodecInitialize(	AudioCodec							inCodec,
						const AudioStreamBasicDescription*	inInputFormat,
						const AudioStreamBasicDescription*	inOutputFormat,
						const void*							inMagicCookie,
						UInt32								inMagicCookieByteSize)
																		__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0);


/*!
	@function		AudioCodecUninitialize
  
	@discussion		This call will move the codec from the initialized state back to the
					uninitialized state. The codec will release any resources it allocated
					or claimed in AudioCodecInitialize.
 
	@param			inCodec
						An AudioCodec instance
 
	@result			The OSStatus value
*/
extern OSStatus
AudioCodecUninitialize(AudioCodec inCodec)								__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0);


/*!
	@function		AudioCodecAppendInputData
 
	@discussion		Append as much of the given data in inInputData to the codec's input buffer as possible
					and return in ioInputDataByteSize the amount of data used.
 
					The inPacketDescription argument is an array of AudioStreamPacketDescription
					structs that describes the packet layout. The number of elements in this array
					is indicated on input by ioNumberPackets. On return, this number indicates the number
					of packets consumed.
 
					Note also in this case that it is an error to supply less than a full packet
					of data at a time.
 
	@param			inCodec
						An AudioCodec instance
	@param			inInputData
						A const pointer to the input data
	@param			ioInputDataByteSize
						The size in bytes of the input data in inInputData on input,
						the number of bytes consumed on output
	@param			ioNumberPackets
						The number of packets
	@param			inPacketDescription
						The packet description pointer
 
	@result			The OSStatus value
*/
extern OSStatus
AudioCodecAppendInputData(	AudioCodec							inCodec,
							const void*							inInputData,
							UInt32*								ioInputDataByteSize,
							UInt32*								ioNumberPackets,
							const AudioStreamPacketDescription*	inPacketDescription)
																		__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0);


/*!
	@function		AudioCodecProduceOutputPackets

	@discussion		Produce as many output packets as requested and the amount of input data
					allows for. The outStatus argument returns information about the codec's
					status to allow for proper data management. See the constants above for
					the possible values that can be returned.
 
					The outPacketDescription argument is an array of AudioStreamPacketDescription
					structs that describes the packet layout returned in outOutputData. This
					argument is optional. Pass NULL if this information is not to be returned.
					Note that this information is only provided when the output format isn't
					linear PCM.

					Note that decoders will always only produce linear PCM data in multiples of
					the number frames in a packet of the encoded format (as returned by
					kAudioCodecPropertyPacketFrameSize). Encoders will consume this many frames
					of linear PCM data to produce a packet of their format.
 
	@param			inCodec
						The AudioCodec instance
	@param			outOutputData
						Pointer to the output data buffer
	@param			ioOutputDataByteSize
						A pointer to the size
	@param			ioNumberPackets
						number of input/output packets
	@result			The OSStatus value
*/
extern OSStatus
AudioCodecProduceOutputPackets(	AudioCodec						inCodec,
								void*							outOutputData,
								UInt32*							ioOutputDataByteSize,
								UInt32*							ioNumberPackets,
								AudioStreamPacketDescription*	outPacketDescription,
								UInt32*							outStatus)
																		__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0);

extern OSStatus
AudioCodecAppendInputBufferList(	AudioCodec							inCodec,
									const AudioBufferList *				inBufferList,
									UInt32*								ioNumberPackets,
									const AudioStreamPacketDescription*	inPacketDescription,
									UInt32*								outBytesConsumed)
																		__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);

extern OSStatus
AudioCodecProduceOutputBufferList(	AudioCodec						inCodec,
									AudioBufferList *				ioBufferList,
									UInt32*							ioNumberPackets,
									AudioStreamPacketDescription*	outPacketDescription,
									UInt32*							outStatus)
																		__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);

/*!
	@function		AudioCodecReset

	@discussion		Flushes all the data in the codec and clears the input buffer. Note that
					the formats, and magic cookie will be retained so they won't need to be
					set up again to decode the same data.
 
	@param			inCodec The audio codec descriptor
 
	@result			the OSStatus value
*/
extern OSStatus
AudioCodecReset(AudioCodec inCodec)										__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0);

//=====================================================================================================================
typedef OSStatus
(*AudioCodecGetPropertyInfoProc)(void *self, AudioCodecPropertyID inPropertyID, UInt32 *outSize, Boolean *outWritable);

typedef OSStatus
(*AudioCodecGetPropertyProc)(void *self, AudioCodecPropertyID inPropertyID, UInt32 *ioPropertyDataSize, 
								void *outPropertyData);

typedef OSStatus
(*AudioCodecSetPropertyProc)(void *self, AudioCodecPropertyID inPropertyID, UInt32 inPropertyDataSize, 
								const void *inPropertyData);

typedef OSStatus
(*AudioCodecInitializeProc)(void *self, const AudioStreamBasicDescription *inInputFormat, 
								const AudioStreamBasicDescription *inOutputFormat, const void *inMagicCookie, 
								UInt32 inMagicCookieByteSize);

typedef OSStatus
(*AudioCodecUninitializeProc)(void *self);

typedef OSStatus
(*AudioCodecAppendInputDataProc)(void *self, const void *inInputData, UInt32 *ioInputDataByteSize, UInt32 *ioNumberPackets, 
								const AudioStreamPacketDescription *inPacketDescription);

typedef OSStatus
(*AudioCodecProduceOutputPacketsProc)(void *self, void *outOutputData, UInt32 *ioOutputDataByteSize, UInt32 *ioNumberPackets, 
								AudioStreamPacketDescription *outPacketDescription, UInt32 *outStatus);

typedef OSStatus
(*AudioCodecResetProc)(void *self);

typedef OSStatus
(*AudioCodecAppendInputBufferListProc)(void *self, const AudioBufferList *ioBufferList, UInt32 *inNumberPackets, 
								const AudioStreamPacketDescription *inPacketDescription, UInt32 *outBytesConsumed);

typedef OSStatus
(*AudioCodecProduceOutputBufferListProc)(void *self, AudioBufferList *ioBufferList, UInt32 *ioNumberPackets, 
								AudioStreamPacketDescription *outPacketDescription, UInt32 *outStatus);


//=====================================================================================================================
#pragma mark -
#pragma mark Deprecated Properties

/*!
    @enum		AudioCodecProperty
    @deprecated
 
    @constant	kAudioCodecPropertyMinimumDelayMode
                    A UInt32 equal 1 sets the encoder, where applicable, in it's lowest possible delay mode. An encoder
                    may prepend zero valued samples to the input signal in order to make additional delays, like e.g.
                    from a filter, coincide on a block boundary. This operation, however, results in an increased
                    encoding/ decoding delay which may be undesired and turned off with this property.
                    Use the kAudioCodecPropertyDelayMode property instead with the value set to kAudioCodecDelayMode_Minimum
*/
enum
{
	kAudioCodecPropertyMinimumDelayMode                 = 'mdel'
};

/*!
	@enum		AudioCodecProperty
	@deprecated	in version 10.7

	@constant	kAudioCodecPropertyNameCFString
					The name of the codec component as a CFStringRef. The CFStringRef
					retrieved via this property must be released by the caller.
	@constant	kAudioCodecPropertyManufacturerCFString
					The manufacturer of the codec as a CFStringRef. The CFStringRef 
					retrieved via this property must be released by the caller.
	@constant	kAudioCodecPropertyFormatCFString
					The name of the codec's format as a CFStringRef. The CFStringRef
					retrieved via this property must be released by the caller.

*/
enum
{
	kAudioCodecPropertyNameCFString						= 'lnam',
	kAudioCodecPropertyManufacturerCFString				= 'lmak',
	kAudioCodecPropertyFormatCFString					= 'lfor'
};		

/*!
	@enum		AudioCodecProperty
	@deprecated	in version 10.5
 
	@constant	kAudioCodecPropertyRequiresPacketDescription
					A UInt32 where a non-zero value indicates that the format the codec implements
					requires that an AudioStreamPacketDescription array must be supplied with any data
					in that format. Note that this implies that data must also be handled strictly in
					packets. For a decoder, this applies to input data. For an encoder, it applies to
					output data, which means that the encoder will be filling out provided packet descriptions
					on output.
					A decoder must be able to handle packet descriptions even if it does not require them.
					An encoder does not have to fill out packet descriptions if it does not require them.
					Redundant due to kAudioCodecPropertyHasVariablePacketByteSizes. Codecs with variable-sized 
					packets must handle packet descriptions while codecs with constant-sized packets do not 
					have to.
	@constant	kAudioCodecPropertyAvailableBitRates
					An array of UInt32 that indicates the target bit rates
					supported by the encoder. This property is only relevant to
					encoders. Replaced with kAudioCodecPropertyAvailableBitRateRange
	@constant	kAudioCodecExtendFrequencies
					A UInt32 indicating whether an encoder should extend its cutoff frequency
					if such an option exists. 0 == extended frequencies off, 1 == extended frequencies on
					e.g. some encoders normally cut off the signal at 16 kHz but can encode up to 20 kHz if 
					asked to.
					Redundant.
	@constant	kAudioCodecUseRecommendedSampleRate
					For encoders that do sample rate conversion, a UInt32 indicating whether or
					not the encoder is using the recommended sample rate for the given input. 
					A value of 0 indicates it isn't, 1 indicates it is.
					This property is read only and indicates whether or not a user has explicitly set an output 
					sample rate.
					Redundant as 0.0 for a sample rate means let the codec decide.
	@constant	kAudioCodecOutputPrecedence
					For encoders that do sample rate conversion, a UInt32 indicating whether the
					bit rate, sample rate, or neither have precedence over the other. See enum below.
					Redundant because precedence is implicitly set by either providing a non-zero bit rate or 
					sample rate and setting the other to zero (which allows the encoder to choose any applicable rate). 
					If both values are set to non-zero, neither value has precedence.
	@constant	kAudioCodecDoesSampleRateConversion
					Renamed to kAudioCodecPropertyDoesSampleRateConversion
	@constant	kAudioCodecBitRateFormat
					Renamed to kAudioCodecPropertyBitRateControlMode
	@constant	kAudioCodecInputFormatsForOutputFormat
					Renamed to kAudioCodecPropertyInputFormatsForOutputFormat
	@constant	kAudioCodecOutputFormatsForInputFormat
					Renamed to kAudioCodecPropertyOutputFormatsForInputFormat
	@constant	kAudioCodecPropertyInputChannelLayout
					Renamed to kAudioCodecPropertyCurrentInputChannelLayout
	@constant	kAudioCodecPropertyOutputChannelLayout
					Renamed to kAudioCodecPropertyCurrentOutputChannelLayout
	@constant	kAudioCodecPropertyZeroFramesPadded
					Renamed to kAudioCodecPropertyPaddedZeros
 */
enum
{
	kAudioCodecPropertyRequiresPacketDescription			= 'pakd',
	kAudioCodecPropertyAvailableBitRates					= 'brt#',
	kAudioCodecExtendFrequencies							= 'acef',
	kAudioCodecUseRecommendedSampleRate						= 'ursr',
	kAudioCodecOutputPrecedence								= 'oppr',
	kAudioCodecBitRateFormat								= kAudioCodecPropertyBitRateControlMode,
	kAudioCodecDoesSampleRateConversion						= kAudioCodecPropertyDoesSampleRateConversion,
	kAudioCodecInputFormatsForOutputFormat					= kAudioCodecPropertyInputFormatsForOutputFormat,
	kAudioCodecOutputFormatsForInputFormat					= kAudioCodecPropertyOutputFormatsForInputFormat,
	kAudioCodecPropertyInputChannelLayout					= kAudioCodecPropertyCurrentInputChannelLayout,
	kAudioCodecPropertyOutputChannelLayout					= kAudioCodecPropertyCurrentOutputChannelLayout,
	kAudioCodecPropertyAvailableInputChannelLayouts			= kAudioCodecPropertyAvailableInputChannelLayoutTags,
	kAudioCodecPropertyAvailableOutputChannelLayouts		= kAudioCodecPropertyAvailableOutputChannelLayoutTags,	
	kAudioCodecPropertyZeroFramesPadded						= kAudioCodecPropertyPaddedZeros
};

/*!
	@enum		AudioCodecBitRateFormat

	@deprecated	in version 10.5

	@discussion	Constants to be used with kAudioCodecBitRateFormat.
					This is deprecated. 
					Use kAudioCodecPropertyBitRateControlMode instead.
 
	@constant	kAudioCodecBitRateFormat_CBR is mapped to kAudioCodecBitRateControlMode_Constant
	@constant	kAudioCodecBitRateFormat_ABR is mapped to kAudioCodecBitRateControlMode_LongTermAverage
	@constant	kAudioCodecBitRateFormat_VBR is mapped to kAudioCodecBitRateControlMode_VariableConstrained
 */
enum
{	
	kAudioCodecBitRateFormat_CBR 	=	kAudioCodecBitRateControlMode_Constant,
	kAudioCodecBitRateFormat_ABR 	=	kAudioCodecBitRateControlMode_LongTermAverage,
	kAudioCodecBitRateFormat_VBR 	=	kAudioCodecBitRateControlMode_VariableConstrained
};

/*!
	@enum		AudioCodecOutputPrecedence

	@deprecated	in version 10.5

	@discussion	Constants to be used with kAudioCodecOutputPrecedence
 
	@constant	kAudioCodecOutputPrecedenceNone
					Change in the bit rate or the sample rate are constrained by
					the other value.
	@constant	kAudioCodecOutputPrecedenceBitRate
					The bit rate may be changed freely,
					adjusting the sample rate if necessary
	@constant	kAudioCodecOutputPrecedenceSampleRate
					The sample rate may be changed freely,
					adjusting the bit rate if necessary
 */
enum
{
	kAudioCodecOutputPrecedenceNone			= 0,
	kAudioCodecOutputPrecedenceBitRate		= 1,
	kAudioCodecOutputPrecedenceSampleRate 	= 2
};

/*!
	@typedef	MagicCookieInfo
 
	@deprecated	in version 10.5
 
	@discussion	renamed to AudioCodecMagicCookieInfo 
 */
typedef struct AudioCodecMagicCookieInfo MagicCookieInfo;

/*!
	@enum		AudioCodecSettingsHint
 
	@deprecated	in version 10.4
 
	@discussion	Constants to be used with kAudioSettings_Hint.
				This is deprecated.
				Use	AudioSettingsFlag instead.
 
	@constant	kHintBasic
	@constant	kHintAdvanced
	@constant	kHintHidden
 */
enum
{
	kHintBasic		= 0,
	kHintAdvanced	= 1,
	kHintHidden		= 2
};

#if defined(__cplusplus)
}
#endif

#endif	//	__AudioCodec_h__