--- name: "libfaad" section: "3" platform: "linux" package: "libfaad-dev" version: "2.11.2-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/libfaad" --- # libfaad(3) C library for AAC Decoding ## NAME libfaad - C library for AAC Decoding ## SYNOPSIS ``` #include char NEAACDECAPI *NeAACDecGetErrorMessage(unsigned char errcode); unsigned long NEAACDECAPI NeAACDecGetCapabilities(void); NeAACDecHandle NEAACDECAPI NeAACDecOpen(void); NeAACDecConfigurationPtr NEAACDECAPI NeAACDecGetCurrentConfiguration( NeAACDecHandle hDecoder); unsigned char NEAACDECAPI NeAACDecSetConfiguration( NeAACDecHandle hDecoder, NeAACDecConfigurationPtr config); /* Init the library based on info from the AAC file (ADTS/ADIF) */ long NEAACDECAPI NeAACDecInit( NeAACDecHandle hDecoder, unsigned char *buffer, unsigned long buffer_size, unsigned long *samplerate, unsigned char *channels); /* Init the library using a DecoderSpecificInfo */ char NEAACDECAPI NeAACDecInit2( NeAACDecHandle hDecoder, unsigned char *pBuffer, unsigned long SizeOfDecoderSpecificInfo, unsigned long *samplerate, unsigned char *channels"); /* Init the library for DRM */ char NEAACDECAPI NeAACDecInitDRM( NeAACDecHandle *hDecoder, unsigned long samplerate, unsigned char channels); void NEAACDECAPI NeAACDecPostSeekReset( NeAACDecHandle hDecoder, long frame"); void NEAACDECAPI NeAACDecClose(NeAACDecHandle hDecoder); void NEAACDECAPI *NeAACDecDecode( NeAACDecHandle hDecoder, NeAACDecFrameInfo *hInfo, unsigned char *buffer, unsigned long buffer_size); void NEAACDECAPI *NeAACDecDecode2( NeAACDecHandle hDecoder, NeAACDecFrameInfo *hInfo, unsigned char *buffer, unsigned long buffer_size, void **sample_buffer, unsigned long sample_buffer_size); char NEAACDECAPI NeAACDecAudioSpecificConfig( unsigned char *pBuffer, unsigned long buffer_size, mp4AudioSpecificConfig *mp4ASC); ``` **For normal use link it with the linker option -lfaad.** **For Digital Radio Mondiale link it with the linker option -lfaad\_drm.** ## DESCRIPTION **NeAACDecGetErrorMessage** **char NEAACDECAPI \*NeAACDecGetErrorMessage(unsigned char errcode);** **Convert an error code to text.** **NeAACDecGetCapabilities** **unsigned long NEAACAPI NeAACDecGetCapabilities(void);** **This function returns the capabilities of the decoder in a 32 bit** **unsigned integer.** **The bits that are set in the 32 bit unsigned integer define with which** **capabilities the library has been compiled.** **The following capabilities are defined:** **#define LC\_DEC\_CAP (1\<\<0) /\* Can decode LC \*/** **#define MAIN\_DEC\_CAP (1\<\<1) /\* Can decode MAIN \*/** **#define LTP\_DEC\_CAP (1\<\<2) /\* Can decode LTP \*/** **#define LD\_DEC\_CAP (1\<\<3) /\* Can decode LD \*/** **#define ERROR\_RESILIENCE\_CAP (1\<\<4) /\* Can decode ER \*/** **#define FIXED\_POINT\_CAP (1\<\<5) /\* Fixed point \*/** **This function can be called anytime.** **NeAACDecOpen** **Returns a handle to a decoder context.** **NeAACDecClose** **Closes a decoder context that has been opened by NeAACDecOpen.** **NeAACDecGetCurrentConfiguration** **NeAACDecConfigurationPtr NEAACAPI** **NeAACDecGetCurrentConfiguration(NeAACDecHandle hDecoder);** **Returns the current decoder library configuration.** **NeAACDecSetConfiguration** **Sets a new configuration structure for the decoder library.** **Return values:** **NeAACDecInit** **long NEAACAPI NeAACDecInit(NeAACDecHandle hDecoder, unsigned char** **\*buffer, unsigned long buffer\_size, unsigned long \*samplerate, unsigned** **char \*channels);** **Initialises the decoder library using information from the AAC file.** **The buffer parameter should hold a small part of the AAC file, so that** **the initialization can be done based on the ADTS or ADIF header.** **Buffer can also be NULL, but then default initialization parameters will** **be used.** **Return values:** **\< 0 – Error** **\>= 0 – Number of bytes read.** **This amount of bytes should be skipped by the program using the decoder** **library.** **This function fills the samplerate and channels parameters with the** **detected values.** **NeAACDecInit2** **char NEAACAPI NeAACDecInit2(NeAACDecHandle hDecoder, unsigned char** **\*pBuffer, unsigned long SizeOfDecoderSpecificInfo, unsigned long** **\*samplerate, unsigned char \*channels);** **Initialises the decoder library based on an AudioSpecificConfig as found** **inside a MP4 file.** **Return values:** **\< 0 – Error** **0 - OK** **This function fills the samplerate and channels parameters with the** **detected values.** **NeAACDecInitDRM** **char NEAACDECAPI NeAACDecInitDRM(NeAACDecHandle \*hDecoder, unsigned long samplerate, unsigned char channels);** **Initialises the decoder library for Digital Radio Mondiale using the specified sample rate** **and a DRM specific channel configuration.** **Return values:** **\< 0 – Error** **0 - OK** **Values for the channel configuration:** **#define DRMCH\_MONO 1** **#define DRMCH\_STEREO 2** **#define DRMCH\_SBR\_MONO 3** **#define DRMCH\_SBR\_STEREO 4** **#define DRMCH\_SBR\_PS\_STEREO 5** **NeAACDecDecode** **void\* NEAACAPI NeAACDecDecode(NeAACDecHandle hDecoder, NeAACDecFrameInfo** **\*hInfo, unsigned char \*buffer, unsigned long buffer\_size);** **Decodes the AAC data passed in buffer.** **Returns a pointer to a sample buffer or NULL.** **Info about the decoded frame is filled in in the NeAACDecFrameInfo** **structure.** **This structure holds information about errors during decoding, number of** **sample, number of channels and samplerate.** **The returned buffer contains the channel interleaved samples of the** **frame.** **NeAACDecDecode2** **void NEAACDECAPI \*NeAACDecDecode2(NeAACDecHandle hDecoder,**\ **NeAACDecFrameInfo \*hInfo,**\ **unsigned char \*buffer,**\ **unsigned long buffer\_size,**\ **void \*\*sample\_buffer,**\ **unsigned long sample\_buffer\_size);** **NeAACDecAudioSpecificConfig** **char NEAACDECAPI NeAACDecAudioSpecificConfig(unsigned char \*pBuffer,**\ **unsigned long buffer\_size,**\ **mp4AudioSpecificConfig \*mp4ASC);** **Structures** **typedef struct NeAACDecConfiguration** **{** **unsigned char defObjectType;** **unsigned long defSampleRate;** **unsigned char outputFormat;** **unsigned char downMatrix;** **unsigned char useOldADTSFormat;** **} NeAACDecConfiguration, \*NeAACDecConfigurationPtr;** **Members:** **defObjectType: determines the default object type assumed when the** **library is initialized without any data from the AAC file (eg: when NULL** **is passed as buffer in NeAACDecInit()).** **Can be any of the following values:** **#define MAIN 1 /\* MAIN \*/** **#define LC 2 /\* Low Complexity (default) \*/** **#define SSR 3 /\* Scalable SampleRate \*/** **#define LTP 4 /\* Long Term Predition \*/** **#define HE\_AAC 5 /\* High Efficiency (SBR) \*/** **#define ER\_LC 17 /\* Error Resilient Low Complexity \*/** **#define ER\_LTP 19 /\* Error Resilient Long Term Prediction \*/** **#define LD 23 /\* Low Delay \*/** **#define DRM\_ER\_LC 27 /\* special object type for DRM only if linking with -lfaad\_drm \*/** **defSampleRate: determines the default samplerate assumed when the** **library is initialized.** **Default value is 44100.** **outputFormat: determines the output format returned by the decoder** **library.** **Can be any of the following values:** **#define FAAD\_FMT\_16BIT 1 /\* 16 bit integers \*/** **#define FAAD\_FMT\_24BIT 2 /\* 24 bit values packed in 32 bit integers \*/** **#define FAAD\_FMT\_32BIT 3 /\* 32 bit integers \*/** **#define FAAD\_FMT\_FLOAT 4 /\* single precision floating point \*/** **#define FAAD\_FMT\_DOUBLE 5 /\* double precision floating point \*/** **downMatrix: determines whether a 5.1 channel AAC file should be** **downmatrixed to 2 channel output (value: 1) or whether the output should** **stay as 5.1 channels (value: 0).** **useOldADTSFormat: determines whether the decoder should assume the** **currently defined 56 bit ADTS header (value: 0) or the 58 bit ADTS** **header (value: 1) defined in previous versions of the AAC standard.** **This value should normally always stay at the value 0, it only exists to** **provide playback capabilities for people that have AAC files with the** **old header format.** **All current encoders should output the new ADTS format.** **NeAACDecFrameInfo** **This structure is returned after decoding a frame and provides info** **about the decoded frame.** **typedef struct NeAACDecFrameInfo** **{** **unsigned long bytesconsumed;** **unsigned long samples;** **unsigned char channels;** **unsigned char error;** **unsigned long samplerate;** **unsigned char sbr;** **unsigned char object\_type;** **unsigned char header\_type;** **unsigned char num\_front\_channels;** **unsigned char num\_side\_channels;** **unsigned char num\_back\_channels;** **unsigned char num\_lfe\_channels;** **unsigned char channel\_position\[64\];** **unsigned char ps;** **} NeAACDecFrameInfo;** **Members:** **bytesconsumed: the number of bytes consumed for decoding this frame.** **samples: the number of audio samples in this frame.** **Each channel is counted separately.** **So when a single channel has 1024 samples and the file has 2 channels,** **this value will be 2\*1024 = 2048.** **channels: number of audio channels in this frame** **error: contains an error value if an error occurred, 0 otherwise.** **samplerate: the samplerate of the frame.** **sbr: tells whether sbr is used in this file or not.** **Can contain any of the following values:** **#define NO\_SBR 0 /\* no SBR used in this file \*/** **#define SBR\_UPSAMPLED 1 /\* upsampled SBR used \*/** **#define SBR\_DOWNSAMPLED 2 /\* downsampled SBR used \*/** **#define NO\_SBR\_UPSAMPLED 3 /\* no SBR used, but file is upsampled by a** **factor 2 anyway \*/** **object\_type: contains the object type of the AAC file.** **Can be any of the values as defined in 1.9.1.** **header\_type: contains the header type of the file that is being decoded.** **Can contain any of the following values:** **#define RAW 0 /\* No header \*/** **#define ADIF 1 /\* single ADIF header at the beginning of the** **file \*/** **#define ADTS 2 /\* ADTS header at the beginning of each frame \*/** **num\_front\_channels, num\_side\_channels, num\_back\_channels,** **num\_lfe\_channels: each of these values contain the number of channels of** **a certain type.** **channel\_position\[64\]: contains the position of each of the channels that** **is returned by the frame decode function.** **Can contain any of the following values:** **#define FRONT\_CHANNEL\_CENTER (1)** **#define FRONT\_CHANNEL\_LEFT (2)** **#define FRONT\_CHANNEL\_RIGHT (3)** **#define SIDE\_CHANNEL\_LEFT (4)** **#define SIDE\_CHANNEL\_RIGHT (5)** **#define BACK\_CHANNEL\_LEFT (6)** **#define BACK\_CHANNEL\_RIGHT (7)** **#define BACK\_CHANNEL\_CENTER (8)** **#define LFE\_CHANNEL (9)** **#define UNKNOWN\_CHANNEL (0)** **ps: PS not used (0) or used (1).** **API usage** **The following pseudo-code describes how and in which order to use the** **different library functions.** **unsigned long cap = NeAACDecGetCapabilities();** **// Check if decoder has the needed capabilities** **// Open the library** **NeAACDecHandle hAac = NeAACDecOpen();** **// Get the current config** **NeAACDecConfigurationPtr conf = NeAACDecGetCurrentConfiguration(hAac);** **//** **// If needed change some of the values in conf** **//** **// Set the new configuration** **NeAACDecSetConfiguration(hAac, conf);** **// Initialise the library using one of the initialization functions** **char err = NeAACDecInit2(hAac, asc, asc\_size, &samplerate, &channels);** **if (err != 0)** **{** **//** **// Handle error** **//** **}** **// Loop until decoding finished** **do {** **//** **// Put next frame in buffer** **//** **// Decode the frame in buffer** **samplebuffer = NeAACDecDecode(hAac, &hInfo, buffer,** **buffer\_size);** **if ((hInfo.error == 0) && (hInfo.samples \> 0))** **{** **//** **// do what you need to do with the decoded samples** **//** **} else if (hInfo.error != 0) {** **//** **// Some error occurred while decoding this frame** **//** **}** **} while (more data available);** **NeAACDecClose(hAac);** ## SEE ALSO **libfaad\_drm**(3), **libfaac**(3). ## AUTHOR Menno Bakker \