1 2 /* ----------------------------------------------------------------------------------------------------------- 3 Software License for The Fraunhofer FDK AAC Codec Library for Android 4 5 Copyright 1995 - 2012 Fraunhofer-Gesellschaft zur Frderung der angewandten Forschung e.V. 6 All rights reserved. 7 8 1. INTRODUCTION 9 The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software that implements 10 the MPEG Advanced Audio Coding ("AAC") encoding and decoding scheme for digital audio. 11 This FDK AAC Codec software is intended to be used on a wide variety of Android devices. 12 13 AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient general perceptual 14 audio codecs. AAC-ELD is considered the best-performing full-bandwidth communications codec by 15 independent studies and is widely deployed. AAC has been standardized by ISO and IEC as part 16 of the MPEG specifications. 17 18 Patent licenses for necessary patent claims for the FDK AAC Codec (including those of Fraunhofer) 19 may be obtained through Via Licensing (www.vialicensing.com) or through the respective patent owners 20 individually for the purpose of encoding or decoding bit streams in products that are compliant with 21 the ISO/IEC MPEG audio standards. Please note that most manufacturers of Android devices already license 22 these patent claims through Via Licensing or directly from the patent owners, and therefore FDK AAC Codec 23 software may already be covered under those patent licenses when it is used for those licensed purposes only. 24 25 Commercially-licensed AAC software libraries, including floating-point versions with enhanced sound quality, 26 are also available from Fraunhofer. Users are encouraged to check the Fraunhofer website for additional 27 applications information and documentation. 28 29 2. COPYRIGHT LICENSE 30 31 Redistribution and use in source and binary forms, with or without modification, are permitted without 32 payment of copyright license fees provided that you satisfy the following conditions: 33 34 You must retain the complete text of this software license in redistributions of the FDK AAC Codec or 35 your modifications thereto in source code form. 36 37 You must retain the complete text of this software license in the documentation and/or other materials 38 provided with redistributions of the FDK AAC Codec or your modifications thereto in binary form. 39 You must make available free of charge copies of the complete source code of the FDK AAC Codec and your 40 modifications thereto to recipients of copies in binary form. 41 42 The name of Fraunhofer may not be used to endorse or promote products derived from this library without 43 prior written permission. 44 45 You may not charge copyright license fees for anyone to use, copy or distribute the FDK AAC Codec 46 software or your modifications thereto. 47 48 Your modified versions of the FDK AAC Codec must carry prominent notices stating that you changed the software 49 and the date of any change. For modified versions of the FDK AAC Codec, the term 50 "Fraunhofer FDK AAC Codec Library for Android" must be replaced by the term 51 "Third-Party Modified Version of the Fraunhofer FDK AAC Codec Library for Android." 52 53 3. NO PATENT LICENSE 54 55 NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without limitation the patents of Fraunhofer, 56 ARE GRANTED BY THIS SOFTWARE LICENSE. Fraunhofer provides no warranty of patent non-infringement with 57 respect to this software. 58 59 You may use this FDK AAC Codec software or modifications thereto only for purposes that are authorized 60 by appropriate patent licenses. 61 62 4. DISCLAIMER 63 64 This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright holders and contributors 65 "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, including but not limited to the implied warranties 66 of merchantability and fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 67 CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary, or consequential damages, 68 including but not limited to procurement of substitute goods or services; loss of use, data, or profits, 69 or business interruption, however caused and on any theory of liability, whether in contract, strict 70 liability, or tort (including negligence), arising in any way out of the use of this software, even if 71 advised of the possibility of such damage. 72 73 5. CONTACT INFORMATION 74 75 Fraunhofer Institute for Integrated Circuits IIS 76 Attention: Audio and Multimedia Departments - FDK AAC LL 77 Am Wolfsmantel 33 78 91058 Erlangen, Germany 79 80 www.iis.fraunhofer.de/amm 81 amm-info (at) iis.fraunhofer.de 82 ----------------------------------------------------------------------------------------------------------- */ 83 84 /**************************** MPEG-4 HE-AAC Encoder ************************** 85 86 Initial author: M. Lohwasser 87 ******************************************************************************/ 88 89 /** 90 * \file aacenc_lib.h 91 * \brief FDK AAC Encoder library interface header file. 92 * 93 \mainpage Introduction 94 95 \section Scope 96 97 This document describes the high-level interface and usage of the ISO/MPEG-2/4 AAC Encoder 98 library developed by the Fraunhofer Institute for Integrated Circuits (IIS). 99 100 The library implements encoding on the basis of the MPEG-2 and MPEG-4 AAC Low-Complexity 101 standard, and depending on the library's configuration, MPEG-4 High-Efficiency AAC v2 and/or AAC-ELD standard. 102 103 All references to SBR (Spectral Band Replication) are only applicable to HE-AAC or AAC-ELD versions 104 of the library. All references to PS (Parametric Stereo) are only applicable to HE-AAC v2 105 versions of the library. 106 107 \section encBasics Encoder Basics 108 109 This document can only give a rough overview about the ISO/MPEG-2 and ISO/MPEG-4 AAC audio coding 110 standard. To understand all the terms in this document, you are encouraged to read the following documents. 111 112 - ISO/IEC 13818-7 (MPEG-2 AAC), which defines the syntax of MPEG-2 AAC audio bitstreams. 113 - ISO/IEC 14496-3 (MPEG-4 AAC, subparts 1 and 4), which defines the syntax of MPEG-4 AAC audio bitstreams. 114 - Lutzky, Schuller, Gayer, Krämer, Wabnik, "A guideline to audio codec delay", 116th AES Convention, May 8, 2004 115 116 MPEG Advanced Audio Coding is based on a time-to-frequency mapping of the signal. The signal is 117 partitioned into overlapping portions and transformed into frequency domain. The spectral components 118 are then quantized and coded. \n 119 An MPEG-2 or MPEG-4 AAC audio bitstream is composed of frames. Contrary to MPEG-1/2 Layer-3 (mp3), the 120 length of individual frames is not restricted to a fixed number of bytes, but can take on any length 121 between 1 and 768 bytes. 122 123 124 \page LIBUSE Library Usage 125 126 \section InterfaceDescription API Files 127 128 All API header files are located in the folder /include of the release package. All header files 129 are provided for usage in C/C++ programs. The AAC encoder library API functions are located at 130 aacenc_lib.h. 131 132 In binary releases the encoder core resides in statically linkable libraries called for example 133 libAACenc.a/libFDK.a (LINUX) or FDK_fastaaclib.lib (MS Visual C++) for the plain AAC-LC core encoder 134 and libSBRenc.a (LINUX) or FDK_sbrEncLib.lib (MS Visual C++) for the SBR (Spectral Band 135 Replication) and PS (Parametric Stereo) modules. 136 137 \section CallingSequence Calling Sequence 138 139 For encoding of ISO/MPEG-2/4 AAC bitstreams the following sequence is mandatory. Input read and output 140 write functions as well as the corresponding open and close functions are left out, since they may be 141 implemented differently according to the user's specific requirements. The example implementation in 142 main.cpp uses file-based input/output. 143 144 -# Call aacEncOpen() to allocate encoder instance with required \ref encOpen "configuration".\n 145 \dontinclude main.cpp 146 \skipline hAacEncoder = 147 \skipline aacEncOpen 148 -# Call aacEncoder_SetParam() for each parameter to be set. AOT, samplingrate, channelMode, bitrate and transport type are \ref encParams "mandatory". 149 \code 150 ErrorStatus = aacEncoder_SetParam(hAacEncoder, parameter, value); 151 \endcode 152 -# Call aacEncEncode() with NULL parameters to \ref encReconf "initialize" encoder instance with present parameter set. 153 \skipline aacEncEncode 154 -# Call aacEncInfo() to retrieve a configuration data block to be transmitted out of band. This is required when using RFC3640 or RFC3016 like transport. 155 \dontinclude main.cpp 156 \skipline encInfo 157 \skipline aacEncInfo 158 -# Encode input audio data in loop. 159 \skip Encode as long as 160 \skipline do 161 \until { 162 Feed \ref feedInBuf "input buffer" with new audio data and provide input/output \ref bufDes "arguments" to aacEncEncode(). 163 \skipline aacEncEncode 164 \until ; 165 Write \ref writeOutData "output data" to file or audio device. \skipline while 166 -# Call aacEncClose() and destroy encoder instance. 167 \skipline aacEncClose 168 169 \section encOpen Encoder Instance Allocation 170 171 The assignment of the aacEncOpen() function is very flexible and can be used in the following way. 172 - If the amount of memory consumption is not an issue, the encoder instance can be allocated 173 for the maximum number of possible audio channels (for example 6 or 8) with the full functional range supported by the library. 174 This is the default open procedure for the AAC encoder if memory consumption does not need to be minimized. 175 \code aacEncOpen(&hAacEncoder,0,0) \endcode 176 - If the required MPEG-4 AOTs do not call for the full functional range of the library, encoder modules can be allocated selectively. 177 \verbatim 178 ------------------------------------------------------ 179 AAC | SBR | PS | MD | FLAGS | value 180 -----+-----+-----+----+-----------------------+------- 181 X | - | - | - | (0x01) | 0x01 182 X | X | - | - | (0x01|0x02) | 0x03 183 X | X | X | - | (0x01|0x02|0x04) | 0x07 184 X | - | - | X | (0x01 |0x10) | 0x11 185 X | X | - | X | (0x01|0x02 |0x10) | 0x13 186 X | X | X | X | (0x01|0x02|0x04|0x10) | 0x17 187 ------------------------------------------------------ 188 - AAC: Allocate AAC Core Encoder module. 189 - SBR: Allocate Spectral Band Replication module. 190 - PS: Allocate Parametric Stereo module. 191 - MD: Allocate Meta Data module within AAC encoder. 192 \endverbatim 193 \code aacEncOpen(&hAacEncoder,value,0) \endcode 194 - Specifying the maximum number of channels to be supported in the encoder instance can be done as follows. 195 - For example allocate an encoder instance which supports 2 channels for all supported AOTs. 196 The library itself may be capable of encoding up to 6 or 8 channels but in this example only 2 channel encoding is required and thus only buffers for 2 channels are allocated to save data memory. 197 \code aacEncOpen(&hAacEncoder,0,2) \endcode 198 - Additionally the maximum number of supported channels in the SBR module can be denoted separately.\n 199 In this example the encoder instance provides a maximum of 6 channels out of which up to 2 channels support SBR. 200 This encoder instance can produce for example 5.1 channel AAC-LC streams or stereo HE-AAC (v2) streams. 201 HE-AAC 5.1 multi channel is not possible since only 2 out of 6 channels support SBR, which saves data memory. 202 \code aacEncOpen(&hAacEncoder,0,6|(2<<8)) \endcode 203 \n 204 205 \section bufDes Input/Output Arguments 206 207 \subsection allocIOBufs Provide Buffer Descriptors 208 In the present encoder API, the input and output buffers are described with \ref AACENC_BufDesc "buffer descriptors". This mechanism allows a flexible handling 209 of input and output buffers without impact to the actual encoding call. Optional buffers are necessary e.g. for ancillary data, meta data input or additional output 210 buffers describing superframing data in DAB+ or DRM+.\n 211 At least one input buffer for audio input data and one output buffer for bitstream data must be allocated. The input buffer size can be a user defined multiple 212 of the number of input channels. PCM input data will be copied from the user defined PCM buffer to an internal input buffer and so input data can be less than one AAC audio frame. 213 The output buffer size should be 6144 bits per channel excluding the LFE channel. 214 If the output data does not fit into the provided buffer, an AACENC_ERROR will be returned by aacEncEncode(). 215 \dontinclude main.cpp 216 \skipline inputBuffer 217 \until outputBuffer 218 All input and output buffer must be clustered in input and output buffer arrays. 219 \skipline inBuffer 220 \until outBufferElSize 221 Allocate buffer descriptors 222 \skipline AACENC_BufDesc 223 \skipline AACENC_BufDesc 224 Initialize input buffer descriptor 225 \skipline inBufDesc 226 \until bufElSizes 227 Initialize output buffer descriptor 228 \skipline outBufDesc 229 \until bufElSizes 230 231 \subsection argLists Provide Input/Output Argument Lists 232 The input and output arguments of an aacEncEncode() call are described in argument structures. 233 \dontinclude main.cpp 234 \skipline AACENC_InArgs 235 \skipline AACENC_OutArgs 236 237 \section feedInBuf Feed Input Buffer 238 The input buffer should be handled as a modulo buffer. New audio data in the form of pulse-code- 239 modulated samples (PCM) must be read from external and be fed to the input buffer depending on its 240 fill level. The required sample bitrate (represented by the data type INT_PCM which is 16, 24 or 32 241 bits wide) is fixed and depends on library configuration (usually 16 bit). 242 243 \dontinclude main.cpp 244 \skipline WAV_InputRead 245 \until ; 246 After the encoder's internal buffer is fed with incoming audio samples, and aacEncEncode() 247 processed the new input data, update/move remaining samples in input buffer, simulating a modulo buffer: 248 \skipline outargs.numInSamples>0 249 \until } 250 251 \section writeOutData Output Bitstream Data 252 If any AAC bitstream data is available, write it to output file or device. This can be done once the 253 following condition is true: 254 \dontinclude main.cpp 255 \skip Valid bitstream available 256 \skipline outargs 257 258 \skipline outBytes>0 259 260 If you use file I/O then for example call mpegFileWrite_Write() from the library libMpegFileWrite 261 262 \dontinclude main.cpp 263 \skipline mpegFileWrite_Write 264 265 \section cfgMetaData Meta Data Configuration 266 267 If the present library is configured with Metadata support, it is possible to insert meta data side info into the generated 268 audio bitstream while encoding. 269 270 To work with meta data the encoder instance has to be \ref encOpen "allocated" with meta data support. The meta data mode must be be configured with 271 the ::AACENC_METADATA_MODE parameter and aacEncoder_SetParam() function. 272 \code aacEncoder_SetParam(hAacEncoder, AACENC_METADATA_MODE, 0-2); \endcode 273 274 This configuration indicates how to embed meta data into bitstrem. Either no insertion, MPEG or ETSI style. 275 The meta data itself must be specified within the meta data setup structure AACENC_MetaData. 276 277 Changing one of the AACENC_MetaData setup parameters can be achieved from outside the library within ::IN_METADATA_SETUP input 278 buffer. There is no need to supply meta data setup structure every frame. If there is no new meta setup data available, the 279 encoder uses the previous setup or the default configuration in initial state. 280 281 In general the audio compressor and limiter within the encoder library can be configured with the ::AACENC_METADATA_DRC_PROFILE parameter 282 AACENC_MetaData::drc_profile and and AACENC_MetaData::comp_profile. 283 \n 284 285 \section encReconf Encoder Reconfiguration 286 287 The encoder library allows reconfiguration of the encoder instance with new settings 288 continuously between encoding frames. Each parameter to be changed must be set with 289 a single aacEncoder_SetParam() call. The internal status of each parameter can be 290 retrieved with an aacEncoder_GetParam() call.\n 291 There is no stand-alone reconfiguration function available. When parameters were 292 modified from outside the library, an internal control mechanism triggers the necessary 293 reconfiguration process which will be applied at the beginning of the following 294 aacEncEncode() call. This state can be observed from external via the AACENC_INIT_STATUS 295 and aacEncoder_GetParam() function. The reconfiguration process can also be applied 296 immediately when all parameters of an aacEncEncode() call are NULL with a valid encoder 297 handle.\n\n 298 The internal reconfiguration process can be controlled from extern with the following access. 299 \code aacEncoder_SetParam(hAacEncoder, AACENC_CONTROL_STATE, AACENC_CTRLFLAGS); \endcode 300 301 302 \section encParams Encoder Parametrization 303 304 All parameteres listed in ::AACENC_PARAM can be modified within an encoder instance. 305 306 \subsection encMandatory Mandatory Encoder Parameters 307 The following parameters must be specified when the encoder instance is initialized. 308 \code 309 aacEncoder_SetParam(hAacEncoder, AACENC_AOT, value); 310 aacEncoder_SetParam(hAacEncoder, AACENC_BITRATE, value); 311 aacEncoder_SetParam(hAacEncoder, AACENC_SAMPLERATE, value); 312 aacEncoder_SetParam(hAacEncoder, AACENC_CHANNELMODE, value); 313 \endcode 314 Beyond that is an internal auto mode which preinitizializes the ::AACENC_BITRATE parameter 315 if the parameter was not set from extern. The bitrate depends on the number of effective 316 channels and sampling rate and is determined as follows. 317 \code 318 AAC-LC (AOT_AAC_LC): 1.5 bits per sample 319 HE-AAC (AOT_SBR): 0.625 bits per sample 320 HE-AAC v2 (AOT_PS): 0.5 bits per sample 321 \endcode 322 323 \subsection channelMode Channel Mode Configuration 324 The input audio data is described with the ::AACENC_CHANNELMODE parameter in the 325 aacEncoder_SetParam() call. It is not possible to use the encoder instance with a 'number of 326 input channels' argument. Instead, the channelMode must be set as follows. 327 \code aacEncoder_SetParam(hAacEncoder, AACENC_CHANNELMODE, value); \endcode 328 The parameter is specified in ::CHANNEL_MODE and can be mapped from the number of input channels 329 in the following way. 330 \dontinclude main.cpp 331 \skip CHANNEL_MODE chMode = MODE_INVALID; 332 \until return 333 334 \subsection encQual Audio Quality Considerations 335 The default encoder configuration is suggested to be used. Encoder tools such as TNS and PNS 336 are activated by default and are internally controlled (see \ref BEHAVIOUR_TOOLS). 337 338 There is an additional quality parameter called ::AACENC_AFTERBURNER. In the default 339 configuration this quality switch is deactivated because it would cause a workload 340 increase which might be significant. If workload is not an issue in the application 341 we recommended to activate this feature. 342 \code aacEncoder_SetParam(hAacEncoder, AACENC_AFTERBURNER, 1); \endcode 343 344 345 \section audiochCfg Audio Channel Configuration 346 The MPEG standard refers often to the so-called Channel Configuration. This Channel Configuration is used for a fixed Channel 347 Mapping. The configurations 1-7 are predefined in MPEG standard and used for implicit signalling within the encoded bitstream. 348 For user defined Configurations the Channel Configuration is set to 0 and the Channel Mapping must be explecitly described with an appropriate 349 Program Config Element. The present Encoder implementation does not allow the user to configure this Channel Configuration from 350 extern. The Encoder implementation supports fixed Channel Modes which are mapped to Channel Configuration as follow. 351 \verbatim 352 -------------------------------------------------------------------- 353 ChannelMode | ChCfg | front_El | side_El | back_El | lfe_El 354 -----------------+--------+----------+----------+----------+-------- 355 MODE_1 | 1 | SCE | | | 356 MODE_2 | 2 | CPE | | | 357 MODE_1_2 | 3 | SCE, CPE | | | 358 MODE_1_2_1 | 4 | SCE, CPE | | SCE | 359 MODE_1_2_2 | 5 | SCE, CPE | | CPE | 360 MODE_1_2_2_1 | 6 | SCE, CPE | | CPE | LFE 361 -------------------------------------------------------------------- 362 - SCE: Single Channel Element. 363 - CPE: Channel Pair. 364 - SCE: Low Frequency Element. 365 \endverbatim 366 367 Moreover, the Table describes all fixed Channel Elements for each Channel Mode which are assigned to a speaker arrangement. The 368 arrangement includes front, side, back and lfe Audio Channel Elements.\n 369 This mapping of Audio Channel Elements is defined in MPEG standard for Channel Config 1-7. The Channel assignment for MODE_1_1, 370 MODE_2_2 and MODE_2_1 is used from the ARIB standard. All other configurations are defined as suggested in MPEG.\n 371 In case of Channel Config 0 or writing matrix mixdown coefficients, the encoder enables the writing of Program Config Element 372 itself as described in \ref encPCE. The configuration used in Program Config Element refers to the denoted Table.\n 373 Beside the Channel Element assignment the Channel Modes are resposible for audio input data channel mapping. The Channel Mapping 374 of the audio data depends on the selected ::AACENC_CHANNELORDER which can be MPEG or WAV like order.\n 375 Following Table describes the complete channel mapping for both Channel Order configurations. 376 \verbatim 377 --------------------------------------------------------------------------------- 378 ChannelMode | MPEG-Channelorder | WAV-Channelorder 379 -----------------+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 380 MODE_1 | 0 | | | | | | | | 0 | | | | | | | 381 MODE_2 | 0 | 1 | | | | | | | 0 | 1 | | | | | | 382 MODE_1_2 | 0 | 1 | 2 | | | | | | 2 | 0 | 1 | | | | | 383 MODE_1_2_1 | 0 | 1 | 2 | 3 | | | | | 2 | 0 | 1 | 3 | | | | 384 MODE_1_2_2 | 0 | 1 | 2 | 3 | 4 | | | | 2 | 0 | 1 | 3 | 4 | | | 385 MODE_1_2_2_1 | 0 | 1 | 2 | 3 | 4 | 5 | | | 2 | 0 | 1 | 4 | 5 | 3 | | 386 --------------------------------------------------------------------------------- 387 \endverbatim 388 389 The denoted mapping is important for correct audio channel assignment when using MPEG or WAV ordering. The incoming audio 390 channels are distributed MPEG like starting at the front channels and ending at the back channels. The distribution is used as 391 described in Table concering Channel Config and fix channel elements. Please see the following example for clarification. 392 393 \verbatim 394 Example: MODE_1_2_2_1 - WAV-Channelorder 5.1 395 ------------------------------------------ 396 Input Channel | Coder Channel 397 --------------------+--------------------- 398 2 (front center) | 0 (SCE channel) 399 0 (left center) | 1 (1st of 1st CPE) 400 1 (right center) | 2 (2nd of 1st CPE) 401 4 (left surround) | 3 (1st of 2nd CPE) 402 5 (right surround) | 4 (2nd of 2nd CPE) 403 3 (LFE) | 5 (LFE) 404 ------------------------------------------ 405 \endverbatim 406 407 408 \section suppBitrates Supported Bitrates 409 410 The FDK AAC Encoder provides a wide range of supported bitrates. 411 The minimum and maximum allowed bitrate depends on the Audio Object Type. For AAC-LC the minimum 412 bitrate is the bitrate that is required to write the most basic and minimal valid bitstream. 413 It consists of the bitstream format header information and other static/mandatory information 414 within the AAC payload. The maximum AAC framesize allowed by the MPEG-4 standard 415 determines the maximum allowed bitrate for AAC-LC. For HE-AAC and HE-AAC v2 a library internal 416 look-up table is used. 417 418 A good working point in terms of audio quality, sampling rate and bitrate, is at 1 to 1.5 419 bits/audio sample for AAC-LC, 0.625 bits/audio sample for HE-AAC and 0.5 bits/audio sample 420 for HE-AAC v2. For example for one channel with a sampling frequency of 48 kHz, the range from 421 48 kbit/s to 72 kbit/s achieves reasonable audio quality for AAC-LC. 422 423 For HE-AAC and HE-AAC v2 the lowest possible audio input sampling frequency is 16 kHz because then the 424 AAC-LC core encoder operates in dual rate mode at its lowest possible sampling frequency, which is 8 kHz. 425 HE-AAC v2 requires stereo input audio data. 426 427 The following table lists the supported bitrates for AAC-LC, HE-AAC and HE-AAC v2 encoding depending 428 on input sampling frequency ("Hz") and number of input channels ("chan"). The minimum and maximum 429 allowed bitrate ("BR Min", "BR Max") is given in bits per second. 430 In case the desired combination of bitrate and sampling frequency is not available ("NA") for HE-AAC or 431 HE-AAC v2 then the encoder will automatically switch to AAC-LC and give a command line warning. 432 Please note that in HE-AAC or HE-AAC v2 mode the encoder supports much higher bitrates than are 433 appropriate for HE-AAC or HE-AAC v2. For example, at a bitrate of more than 64 kbit/s for a stereo 434 audio signal at 44.1 kHz it usually makes sense to use AAC-LC, which will produce better audio 435 quality at that bitrate than HE-AAC or HE-AAC v2. 436 437 438 \verbatim 439 Config AAC-LC HE-AAC (SBR) HE-AACv2 (SBR+PS) 440 441 Hz chan BR Min BR Max BR Min BR Max BR Min BR Max 442 443 8000 1 758 48000 NA NA NA NA 444 11025 1 1045 66150 NA NA NA NA 445 12000 1 1137 72000 NA NA NA NA 446 16000 1 1516 96000 8000 48000 NA NA 447 22050 1 2089 132300 8000 64000 NA NA 448 24000 1 2274 144000 8000 64000 NA NA 449 32000 1 3032 192000 8000 64000 NA NA 450 44100 1 4178 264576 8000 64000 NA NA 451 48000 1 4547 288000 12000 64000 NA NA 452 64000 1 6063 384000 24000 160000 NA NA 453 88200 1 8355 529200 24000 160000 NA NA 454 96000 1 9094 576000 24000 160000 NA NA 455 ----------------------------------------------------------------------------------- 456 8000 2 1071 96000 NA NA NA NA 457 11025 2 1476 132300 NA NA NA NA 458 12000 2 1606 144000 NA NA NA NA 459 16000 2 2141 192000 16000 96000 8000 48000 460 22050 2 2951 264600 16000 128000 8000 64000 461 24000 2 3211 288000 16000 128000 8000 64000 462 32000 2 4282 384000 16000 128000 8000 64000 463 44100 2 5900 529152 16000 128000 8000 64000 464 48000 2 6422 576000 16000 128000 12000 64000 465 64000 2 8563 768000 32000 256000 24000 160000 466 88200 2 11801 1058400 32000 256000 24000 160000 467 96000 2 12844 1152000 32000 256000 24000 160000 468 ----------------------------------------------------------------------------------- 469 8000 3 1383 144000 NA NA NA NA 470 11025 3 1906 198450 NA NA NA NA 471 12000 3 2075 216000 NA NA NA NA 472 16000 3 2766 288000 26667 120000 NA NA 473 22050 3 3812 396900 26667 160000 NA NA 474 24000 3 4149 432000 26667 160000 NA NA 475 32000 3 5532 576000 26667 160000 NA NA 476 44100 3 7623 793728 26667 160000 NA NA 477 48000 3 8297 864000 29996 160000 NA NA 478 64000 3 11063 1152000 59996 400000 NA NA 479 88200 3 15246 1587600 59996 400000 NA NA 480 96000 3 16594 1728000 59996 400000 NA NA 481 ----------------------------------------------------------------------------------- 482 8000 4 1696 192000 NA NA NA NA 483 11025 4 2337 264600 NA NA NA NA 484 12000 4 2543 288000 NA NA NA NA 485 16000 4 3391 384000 40000 160000 NA NA 486 22050 4 4673 529200 40000 213330 NA NA 487 24000 4 5086 576000 40000 213330 NA NA 488 32000 4 6782 768000 40000 213330 NA NA 489 44100 4 9345 1058304 40000 213330 NA NA 490 48000 4 10172 1152000 40000 213330 NA NA 491 64000 4 13563 1536000 80000 533330 NA NA 492 88200 4 18691 2116800 80000 533330 NA NA 493 96000 4 20344 2304000 80000 533330 NA NA 494 ----------------------------------------------------------------------------------- 495 8000 5 2008 240000 NA NA NA NA 496 11025 5 2768 330750 NA NA NA NA 497 12000 5 3012 360000 NA NA NA NA 498 16000 5 4016 480000 43244 184612 NA NA 499 22050 5 5535 661500 43244 246152 NA NA 500 24000 5 6024 720000 43244 246152 NA NA 501 32000 5 8032 960000 43244 246152 NA NA 502 44100 5 11068 1322880 43244 246152 NA NA 503 48000 5 12047 1440000 46140 246152 NA NA 504 64000 5 16063 1920000 92296 615384 NA NA 505 88200 5 22137 2646000 92296 615384 NA NA 506 96000 5 24094 2880000 92296 615384 NA NA 507 ----------------------------------------------------------------------------------- 508 8000 5.1 2321 240000 NA NA NA NA 509 11025 5.1 3198 330750 NA NA NA NA 510 12000 5.1 3481 360000 NA NA NA NA 511 16000 5.1 4641 480000 45715 199990 NA NA 512 22050 5.1 6396 661500 45715 266658 NA NA 513 24000 5.1 6961 720000 45715 266658 NA NA 514 32000 5.1 9282 960000 45715 266658 NA NA 515 44100 5.1 12790 1322880 45715 266658 NA NA 516 48000 5.1 13922 1440000 49982 266658 NA NA 517 64000 5.1 18563 1920000 99982 666658 NA NA 518 88200 5.1 25582 2646000 99982 666658 NA NA 519 96000 5.1 27844 2880000 99982 666658 NA NA 520 521 \endverbatim \n 522 523 \section reommendedConfig Recommended Sampling Rate and Bitrate Combinations 524 525 The following table provides an overview of recommended encoder configuration parameters 526 which we determined by virtue of numerous listening tests. 527 528 \subsection reommendedConfigLC AAC-LC, HE-AAC, HE-AACv2. 529 \verbatim 530 ----------------------------------------------------------------------------------- 531 Audio Object Type | Bit Rate Range | Supported | Preferred | No. of 532 | [bit/s] | Sampling Rates | Sampl. | Chan. 533 | | [kHz] | Rate | 534 | | | [kHz] | 535 -------------------+------------------+-----------------------+------------+------- 536 AAC LC + SBR + PS | 8000 - 11999 | 22.05, 24.00 | 24.00 | 2 537 AAC LC + SBR + PS | 12000 - 17999 | 32.00 | 32.00 | 2 538 AAC LC + SBR + PS | 18000 - 39999 | 32.00, 44.10, 48.00 | 44.10 | 2 539 AAC LC + SBR + PS | 40000 - 56000 | 32.00, 44.10, 48.00 | 48.00 | 2 540 -------------------+------------------+-----------------------+------------+------- 541 AAC LC + SBR | 8000 - 11999 | 22.05, 24.00 | 24.00 | 1 542 AAC LC + SBR | 12000 - 17999 | 32.00 | 32.00 | 1 543 AAC LC + SBR | 18000 - 39999 | 32.00, 44.10, 48.00 | 44.10 | 1 544 AAC LC + SBR | 40000 - 56000 | 32.00, 44.10, 48.00 | 48.00 | 1 545 AAC LC + SBR | 16000 - 27999 | 32.00, 44.10, 48.00 | 32.00 | 2 546 AAC LC + SBR | 28000 - 63999 | 32.00, 44.10, 48.00 | 44.10 | 2 547 AAC LC + SBR | 64000 - 128000 | 32.00, 44.10, 48.00 | 48.00 | 2 548 -------------------+------------------+-----------------------+------------+------- 549 AAC LC + SBR | 64000 - 69999 | 32.00, 44.10, 48.00 | 32.00 | 5, 5.1 550 AAC LC + SBR | 70000 - 159999 | 32.00, 44.10, 48.00 | 44.10 | 5, 5.1 551 AAC LC + SBR | 160000 - 319999 | 32.00, 44.10, 48.00 | 48.00 | 5, 5.1 552 AAC LC + SBR | 320000 - 640000 | 64.00, 88.20, 96.00 | 96.00 | 5, 5.1 553 -------------------+------------------+-----------------------+------------+------- 554 AAC LC | 8000 - 15999 | 11.025, 12.00, 16.00 | 12.00 | 1 555 AAC LC | 16000 - 23999 | 16.00 | 16.00 | 1 556 AAC LC | 24000 - 31999 | 16.00, 22.05, 24.00 | 24.00 | 1 557 AAC LC | 32000 - 55999 | 32.00 | 32.00 | 1 558 AAC LC | 56000 - 160000 | 32.00, 44.10, 48.00 | 44.10 | 1 559 AAC LC | 160001 - 288000 | 48.00 | 48.00 | 1 560 -------------------+------------------+-----------------------+------------+------- 561 AAC LC | 16000 - 23999 | 11.025, 12.00, 16.00 | 12.00 | 2 562 AAC LC | 24000 - 31999 | 16.00 | 16.00 | 2 563 AAC LC | 32000 - 39999 | 16.00, 22.05, 24.00 | 22.05 | 2 564 AAC LC | 40000 - 95999 | 32.00 | 32.00 | 2 565 AAC LC | 96000 - 111999 | 32.00, 44.10, 48.00 | 32.00 | 2 566 AAC LC | 112000 - 320001 | 32.00, 44.10, 48.00 | 44.10 | 2 567 AAC LC | 320002 - 576000 | 48.00 | 48.00 | 2 568 -------------------+------------------+-----------------------+------------+------- 569 AAC LC | 160000 - 239999 | 32.00 | 32.00 | 5, 5.1 570 AAC LC | 240000 - 279999 | 32.00, 44.10, 48.00 | 32.00 | 5, 5.1 571 AAC LC | 280000 - 800000 | 32.00, 44.10, 48.00 | 44.10 | 5, 5.1 572 ----------------------------------------------------------------------------------- 573 \endverbatim \n 574 575 \subsection reommendedConfigLD AAC-LD, AAC-ELD, AAC-ELD with SBR. 576 \verbatim 577 ----------------------------------------------------------------------------------- 578 Audio Object Type | Bit Rate Range | Supported | Preferred | No. of 579 | [bit/s] | Sampling Rates | Sampl. | Chan. 580 | | [kHz] | Rate | 581 | | | [kHz] | 582 -------------------+------------------+-----------------------+------------+------- 583 ELD + SBR | 16000 - 24999 | 32.00 - 44.10 | 32.00 | 1 584 ELD + SBR | 25000 - 31999 | 32.00 - 48.00 | 32.00 | 1 585 ELD + SBR | 32000 - 64000 | 32.00 - 48.00 | 48.00 | 1 586 -------------------+------------------+-----------------------+------------+------- 587 ELD + SBR | 32000 - 51999 | 32.00 - 48.00 | 44.10 | 2 588 ELD + SBR | 52000 - 128000 | 32.00 - 48.00 | 48.00 | 2 589 -------------------+------------------+-----------------------+------------+------- 590 ELD + SBR | 72000 - 192000 | 44.10 - 48.00 | 48.00 | 3 591 -------------------+------------------+-----------------------+------------+------- 592 ELD + SBR | 96000 - 256000 | 44.10 - 48.00 | 48.00 | 4 593 -------------------+------------------+-----------------------+------------+------- 594 ELD + SBR | 120000 - 320000 | 44.10 - 48.00 | 48.00 | 5 595 -------------------+------------------+-----------------------+------------+------- 596 LD, ELD | 16000 - 19999 | 16.00 - 24.00 | 16.00 | 1 597 LD, ELD | 20000 - 39999 | 16.00 - 32.00 | 24.00 | 1 598 LD, ELD | 40000 - 49999 | 22.05 - 32.00 | 32.00 | 1 599 LD, ELD | 50000 - 61999 | 24.00 - 44.10 | 32.00 | 1 600 LD, ELD | 62000 - 84999 | 32.00 - 48.00 | 44.10 | 1 601 LD, ELD | 85000 - 192000 | 44.10 - 48.00 | 48.00 | 1 602 -------------------+------------------+-----------------------+------------+------- 603 LD, ELD | 64000 - 75999 | 24.00 - 32.00 | 32.00 | 2 604 LD, ELD | 76000 - 97999 | 24.00 - 44.10 | 32.00 | 2 605 LD, ELD | 98000 - 135999 | 32.00 - 48.00 | 44.10 | 2 606 LD, ELD | 136000 - 384000 | 44.10 - 48.00 | 48.00 | 2 607 -------------------+------------------+-----------------------+------------+------- 608 LD, ELD | 96000 - 113999 | 24.00 - 32.00 | 32.00 | 3 609 LD, ELD | 114000 - 146999 | 24.00 - 44.10 | 32.00 | 3 610 LD, ELD | 147000 - 203999 | 32.00 - 48.00 | 44.10 | 3 611 LD, ELD | 204000 - 576000 | 44.10 - 48.00 | 48.00 | 3 612 -------------------+------------------+-----------------------+------------+------- 613 LD, ELD | 128000 - 151999 | 24.00 - 32.00 | 32.00 | 4 614 LD, ELD | 152000 - 195999 | 24.00 - 44.10 | 32.00 | 4 615 LD, ELD | 196000 - 271999 | 32.00 - 48.00 | 44.10 | 4 616 LD, ELD | 272000 - 768000 | 44.10 - 48.00 | 48.00 | 4 617 -------------------+------------------+-----------------------+------------+------- 618 LD, ELD | 160000 - 189999 | 24.00 - 32.00 | 32.00 | 5 619 LD, ELD | 190000 - 244999 | 24.00 - 44.10 | 32.00 | 5 620 LD, ELD | 245000 - 339999 | 32.00 - 48.00 | 44.10 | 5 621 LD, ELD | 340000 - 960000 | 44.10 - 48.00 | 48.00 | 5 622 ----------------------------------------------------------------------------------- 623 \endverbatim \n 624 625 \page ENCODERBEHAVIOUR Encoder Behaviour 626 627 \section BEHAVIOUR_BANDWIDTH Bandwidth 628 629 The FDK AAC encoder usually does not use the full frequency range of the input signal, but restricts the bandwidth 630 according to certain library-internal settings. They can be changed in the table "bandWidthTable" in the 631 file bandwidth.cpp (if available), or via command-line argument "-w" (see chapter \ref CommandLineUsage). 632 633 However it is not recommended to change these settings, because they are based on numerious listening 634 tests and careful tweaks to ensure the best overall encoding quality. 635 636 Theoretically a signal of for example 48 kHz can contain frequencies up to 24 kHz, but to use this full range 637 in an audio encoder usually does not make sense. Usually the encoder has a very limited amount of 638 bits to spend (typically 128 kbit/s for stereo 48 kHz content) and to allow full range bandwidth would 639 waste a lot of these bits for frequencies the human ear is hardly able to perceive anyway, if at all. Hence it 640 is wise to use the available bits for the really important frequency range and just skip the rest. 641 At lower bitrates (e. g. <= 80 kbit/s for stereo 48 kHz content) the encoder will choose an even smaller 642 bandwidth, because an encoded signal with smaller bandwidth and hence less artifacts sounds better than a signal 643 with higher bandwidth but then more coding artefacts across all frequencies. These artefacts would occur if 644 small bitrates and high bandwidths are chosen because the available bits are just not enough to encode all 645 frequencies well. 646 647 Unfortunately some people evaluate encoding quality based on possible bandwidth as well, but it is a two-sided 648 sword considering the trade-off described above. 649 650 Another aspect is workload consumption. The higher the allowed bandwidth, the more frequency lines have to be 651 processed, which in turn increases the workload. 652 653 \section FRAMESIZES_AND_BIT_RESERVOIR Frame Sizes & Bit Reservoir 654 655 For AAC there is a difference between constant bit rate and constant frame 656 length due to the so-called bit reservoir technique, which allows the encoder to use less 657 bits in an AAC frame for those audio signal sections which are easy to encode, 658 and then spend them at a later point in 659 time for more complex audio sections. The extent to which this "bit exchange" 660 is done is limited to allow for reliable and relatively low delay real time 661 streaming. 662 Over a longer period in time the bitrate will be constant in the AAC constant 663 bitrate mode, e.g. for ISDN transmission. This means that in AAC each bitstream 664 frame will in general have a different length in bytes but over time it 665 will reach the target bitrate. One could also make an MPEG compliant 666 AAC encoder which always produces constant length packages for each AAC frame, 667 but the audio quality would be considerably worse since the bit reservoir 668 technique would have to be switched off completely. A higher bit rate would have 669 to be used to get the same audio quality as with an enabled bit reservoir. 670 671 The maximum AAC frame length, regardless of the available bit reservoir, is defined 672 as 6144 bits per channel. 673 674 For mp3 by the way, the same bit reservoir technique exists, but there each bit 675 stream frame has a constant length for a given bit rate (ignoring the 676 padding byte). In mp3 there is a so-called "back pointer" which tells 677 the decoder which bits belong to the current mp3 frame - and in general some or 678 many bits have been transmitted in an earlier mp3 frame. Basically this leads to 679 the same "bit exchange between mp3 frames" as in AAC but with virtually constant 680 length frames. 681 682 This variable frame length at "constant bit rate" is not something special 683 in this Fraunhofer IIS AAC encoder. AAC has been designed in that way. 684 685 \subsection BEHAVIOUR_ESTIM_AVG_FRAMESIZES Estimating Average Frame Sizes 686 687 A HE-AAC v1 or v2 audio frame contains 2048 PCM samples per channel (there is 688 also one mode with 1920 samples per channel but this is only for special purposes 689 such as DAB+ digital radio). 690 691 The number of HE-AAC frames \f$N\_FRAMES\f$ per second at 44.1 kHz is: 692 693 \f[ 694 N\_FRAMES = 44100 / 2048 = 21.5332 695 \f] 696 697 At a bit rate of 8 kbps the average number of bits per frame \f$N\_BITS\_PER\_FRAME\f$ is: 698 699 \f[ 700 N\_BITS\_PER\_FRAME = 8000 / 21.5332 = 371.52 701 \f] 702 703 which is about 46.44 bytes per encoded frame. 704 705 At a bit rate of 32 kbps, which is quite high for single channel HE-AAC v1, it is: 706 707 \f[ 708 N\_BITS\_PER\_FRAME = 32000 / 21.5332 = 1486 709 \f] 710 711 which is about 185.76 bytes per encoded frame. 712 713 These bits/frame figures are average figures where each AAC frame generally has a different 714 size in bytes. To calculate the same for AAC-LC just use 1024 instead of 2048 PCM samples per 715 frame and channel. 716 For AAC-LD/ELD it is either 480 or 512 PCM samples per frame and channel. 717 718 719 \section BEHAVIOUR_TOOLS Encoder Tools 720 721 The AAC encoder supports TNS, PNS, MS, Intensity and activates these tools depending on the audio signal and 722 the encoder configuration (i.e. bitrate or AOT). It is not required to configure these tools manually. 723 724 PNS improves encoding quality only for certain bitrates. Therefore it makes sense to activate PNS only for 725 these bitrates and save the processing power required for PNS (about 10 % of the encoder) when using other 726 bitrates. This is done automatically inside the encoder library. PNS is disabled inside the encoder library if 727 an MPEG-2 AOT is choosen since PNS is an MPEG-4 AAC feature. 728 729 If SBR is activated, the encoder automatically deactivates PNS internally. If TNS is disabled but PNS is allowed, 730 the encoder deactivates PNS calculation internally. 731 732 733 */ 734 735 #ifndef _AAC_ENC_LIB_H_ 736 #define _AAC_ENC_LIB_H_ 737 738 #include "machine_type.h" 739 #include "FDK_audio.h" 740 741 742 /** 743 * AAC encoder error codes. 744 */ 745 typedef enum { 746 AACENC_OK = 0x0000, /*!< No error happened. All fine. */ 747 748 AACENC_INVALID_HANDLE = 0x0020, /*!< Handle passed to function call was invalid. */ 749 AACENC_MEMORY_ERROR = 0x0021, /*!< Memory allocation failed. */ 750 AACENC_UNSUPPORTED_PARAMETER = 0x0022, /*!< Parameter not available. */ 751 AACENC_INVALID_CONFIG = 0x0023, /*!< Configuration not provided. */ 752 753 AACENC_INIT_ERROR = 0x0040, /*!< General initialization error. */ 754 AACENC_INIT_AAC_ERROR = 0x0041, /*!< AAC library initialization error. */ 755 AACENC_INIT_SBR_ERROR = 0x0042, /*!< SBR library initialization error. */ 756 AACENC_INIT_TP_ERROR = 0x0043, /*!< Transport library initialization error. */ 757 AACENC_INIT_META_ERROR = 0x0044, /*!< Meta data library initialization error. */ 758 759 AACENC_ENCODE_ERROR = 0x0060, /*!< The encoding process was interrupted by an unexpected error. */ 760 761 AACENC_ENCODE_EOF = 0x0080 /*!< End of file reached. */ 762 763 } AACENC_ERROR; 764 765 766 /** 767 * AAC encoder buffer descriptors identifier. 768 * This identifier are used within buffer descriptors AACENC_BufDesc::bufferIdentifiers. 769 */ 770 typedef enum { 771 /* Input buffer identifier. */ 772 IN_AUDIO_DATA = 0, /*!< Audio input buffer, interleaved INT_PCM samples. */ 773 IN_ANCILLRY_DATA = 1, /*!< Ancillary data to be embedded into bitstream. */ 774 IN_METADATA_SETUP = 2, /*!< Setup structure for embedding meta data. */ 775 776 /* Output buffer identifier. */ 777 OUT_BITSTREAM_DATA = 3, /*!< Buffer holds bitstream output data. */ 778 OUT_AU_SIZES = 4 /*!< Buffer contains sizes of each access unit. This information 779 is necessary for superframing. */ 780 781 } AACENC_BufferIdentifier; 782 783 784 /** 785 * AAC encoder handle. 786 */ 787 typedef struct AACENCODER *HANDLE_AACENCODER; 788 789 790 /** 791 * Provides some info about the encoder configuration. 792 */ 793 typedef struct { 794 795 UINT maxOutBufBytes; /*!< Maximum number of encoder bitstream bytes within one frame. 796 Size depends on maximum number of supported channels in encoder instance. 797 For superframing (as used for example in DAB+), size has to be a multiple accordingly. */ 798 799 UINT maxAncBytes; /*!< Maximum number of ancillary data bytes which can be inserted into 800 bitstream within one frame. */ 801 802 UINT inBufFillLevel; /*!< Internal input buffer fill level in samples per channel. This parameter 803 will automatically be cleared if samplingrate or channel(Mode/Order) changes. */ 804 805 UINT inputChannels; /*!< Number of input channels expected in encoding process. */ 806 807 UINT frameLength; /*!< Amount of input audio samples consumed each frame per channel, depending 808 on audio object type configuration. */ 809 810 UINT encoderDelay; /*!< Codec delay in PCM samples/channel. Depends on framelength and AOT. Does not 811 include framing delay for filling up encoder PCM input buffer. */ 812 813 UCHAR confBuf[64]; /*!< Configuration buffer in binary format as an AudioSpecificConfig 814 or StreamMuxConfig according to the selected transport type. */ 815 816 UINT confSize; /*!< Number of valid bytes in confBuf. */ 817 818 } AACENC_InfoStruct; 819 820 821 /** 822 * Describes the input and output buffers for an aacEncEncode() call. 823 */ 824 typedef struct { 825 INT numBufs; /*!< Number of buffers. */ 826 void **bufs; /*!< Pointer to vector containing buffer addresses. */ 827 INT *bufferIdentifiers; /*!< Identifier of each buffer element. See ::AACENC_BufferIdentifier. */ 828 INT *bufSizes; /*!< Size of each buffer in 8-bit bytes. */ 829 INT *bufElSizes; /*!< Size of each buffer element in bytes. */ 830 831 } AACENC_BufDesc; 832 833 834 /** 835 * Defines the input arguments for an aacEncEncode() call. 836 */ 837 typedef struct { 838 INT numInSamples; /*!< Number of valid input audio samples (multiple of input channels). */ 839 INT numAncBytes; /*!< Number of ancillary data bytes to be encoded. */ 840 841 } AACENC_InArgs; 842 843 844 /** 845 * Defines the output arguments for an aacEncEncode() call. 846 */ 847 typedef struct { 848 INT numOutBytes; /*!< Number of valid bitstream bytes generated during aacEncEncode(). */ 849 INT numInSamples; /*!< Number of input audio samples consumed by the encoder. */ 850 INT numAncBytes; /*!< Number of ancillary data bytes consumed by the encoder. */ 851 852 } AACENC_OutArgs; 853 854 855 /** 856 * Meta Data Compression Profiles. 857 */ 858 typedef enum { 859 AACENC_METADATA_DRC_NONE = 0, /*!< None. */ 860 AACENC_METADATA_DRC_FILMSTANDARD = 1, /*!< Film standard. */ 861 AACENC_METADATA_DRC_FILMLIGHT = 2, /*!< Film light. */ 862 AACENC_METADATA_DRC_MUSICSTANDARD = 3, /*!< Music standard. */ 863 AACENC_METADATA_DRC_MUSICLIGHT = 4, /*!< Music light. */ 864 AACENC_METADATA_DRC_SPEECH = 5 /*!< Speech. */ 865 866 } AACENC_METADATA_DRC_PROFILE; 867 868 869 /** 870 * Meta Data setup structure. 871 */ 872 typedef struct { 873 874 AACENC_METADATA_DRC_PROFILE drc_profile; /*!< MPEG DRC compression profile. See ::AACENC_METADATA_DRC_PROFILE. */ 875 AACENC_METADATA_DRC_PROFILE comp_profile; /*!< ETSI heavy compression profile. See ::AACENC_METADATA_DRC_PROFILE. */ 876 877 INT drc_TargetRefLevel; /*!< Used to define expected level to: 878 Scaled with 16 bit. x*2^16. */ 879 INT comp_TargetRefLevel; /*!< Adjust limiter to avoid overload. 880 Scaled with 16 bit. x*2^16. */ 881 882 INT prog_ref_level_present; /*!< Flag, if prog_ref_level is present */ 883 INT prog_ref_level; /*!< Programme Reference Level = Dialogue Level: 884 -31.75dB .. 0 dB ; stepsize: 0.25dB 885 Scaled with 16 bit. x*2^16.*/ 886 887 UCHAR PCE_mixdown_idx_present; /*!< Flag, if dmx-idx should be written in programme config element */ 888 UCHAR ETSI_DmxLvl_present; /*!< Flag, if dmx-lvl should be written in ETSI-ancData */ 889 890 SCHAR centerMixLevel; /*!< Center downmix level (0...7, according to table) */ 891 SCHAR surroundMixLevel; /*!< Surround downmix level (0...7, according to table) */ 892 893 UCHAR dolbySurroundMode; /*!< Indication for Dolby Surround Encoding Mode. 894 - 0: Dolby Surround mode not indicated 895 - 1: 2-ch audio part is not Dolby surround encoded 896 - 2: 2-ch audio part is Dolby surround encoded */ 897 } AACENC_MetaData; 898 899 900 /** 901 * AAC encoder control flags. 902 * 903 * In interaction with the ::AACENC_CONTROL_STATE parameter it is possible to get information about the internal 904 * initialization process. It is also possible to overwrite the internal state from extern when necessary. 905 */ 906 typedef enum 907 { 908 AACENC_INIT_NONE = 0x0000, /*!< Do not trigger initialization. */ 909 AACENC_INIT_CONFIG = 0x0001, /*!< Initialize all encoder modules configuration. */ 910 AACENC_INIT_STATES = 0x0002, /*!< Reset all encoder modules history buffer. */ 911 AACENC_INIT_TRANSPORT = 0x1000, /*!< Initialize transport lib with new parameters. */ 912 AACENC_RESET_INBUFFER = 0x2000, /*!< Reset fill level of internal input buffer. */ 913 AACENC_INIT_ALL = 0xFFFF /*!< Initialize all. */ 914 } 915 AACENC_CTRLFLAGS; 916 917 918 /** 919 * \brief AAC encoder setting parameters. 920 * 921 * Use aacEncoder_SetParam() function to configure, or use aacEncoder_GetParam() function to read 922 * the internal status of the following parameters. 923 */ 924 typedef enum 925 { 926 AACENC_AOT = 0x0100, /*!< Audio object type. See ::AUDIO_OBJECT_TYPE in FDK_audio.h. 927 - 2: MPEG-4 AAC Low Complexity. 928 - 5: MPEG-4 AAC Low Complexity with Spectral Band Replication (HE-AAC). 929 - 29: MPEG-4 AAC Low Complexity with Spectral Band Replication and Parametric Stereo (HE-AAC v2). 930 This configuration can be used only with stereo input audio data. 931 - 23: MPEG-4 AAC Low-Delay. 932 - 39: MPEG-4 AAC Enhanced Low-Delay. Since there is no ::AUDIO_OBJECT_TYPE for ELD in 933 combination with SBR defined, enable SBR explicitely by ::AACENC_SBR_MODE parameter. 934 - 129: MPEG-2 AAC Low Complexity. 935 - 132: MPEG-2 AAC Low Complexity with Spectral Band Replication (HE-AAC). 936 - 156: MPEG-2 AAC Low Complexity with Spectral Band Replication and Parametric Stereo (HE-AAC v2). 937 This configuration can be used only with stereo input audio data. */ 938 939 AACENC_BITRATE = 0x0101, /*!< Total encoder bitrate. This parameter is mandatory and interacts with ::AACENC_BITRATEMODE. 940 - CBR: Bitrate in bits/second. 941 See \ref suppBitrates for details. */ 942 943 AACENC_BITRATEMODE = 0x0102, /*!< Bitrate mode. Configuration can be different kind of bitrate configurations: 944 - 0: Constant bitrate, use bitrate according to ::AACENC_BITRATE. (default) 945 Within none LD/ELD ::AUDIO_OBJECT_TYPE, the CBR mode makes use of full allowed bitreservoir. 946 In contrast, at Low-Delay ::AUDIO_OBJECT_TYPE the bitreservoir is kept very small. 947 - 8: LD/ELD full bitreservoir for packet based transmission. */ 948 949 AACENC_SAMPLERATE = 0x0103, /*!< Audio input data sampling rate. Encoder supports following sampling rates: 950 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000 */ 951 952 AACENC_SBR_MODE = 0x0104, /*!< Configure SBR independently of the chosen Audio Object Type ::AUDIO_OBJECT_TYPE:. 953 This parameter is only available for ELD. 954 - 0: Disable Spectral Band Replication. 955 - 1: Enable Spectral Band Replication. */ 956 957 AACENC_GRANULE_LENGTH = 0x0105, /*!< Core encoder (AAC) audio frame length in samples: 958 - 1024: Default configuration. 959 - 512: Optional length in LD/ELD configuration. 960 - 480: Default LD/ELD configuration. */ 961 962 AACENC_CHANNELMODE = 0x0106, /*!< Set explicit channel mode. Channel mode must match with number of input channels. 963 - 1-6: MPEG channel modes supported, see ::CHANNEL_MODE in FDK_audio.h. */ 964 965 AACENC_CHANNELORDER = 0x0107, /*!< Input audio data channel ordering scheme: 966 - 0: MPEG channel ordering (e. g. 5.1: C, L, R, SL, SR, LFE). (default) 967 - 1: WAVE file format channel ordering (e. g. 5.1: L, R, C, LFE, SL, SR). */ 968 969 AACENC_AFTERBURNER = 0x0200, /*!< This parameter controls the use of the afterburner feature. 970 The afterburner is a type of analysis by synthesis algorithm which increases the 971 audio quality but also the required processing power. It is recommended to always 972 activate this if additional memory consumption and processing power consumption 973 is not a problem. If increased MHz and memory consumption are an issue then the MHz 974 and memory cost of this optional module need to be evaluated against the improvement 975 in audio quality on a case by case basis. 976 - 0: Disable afterburner (default). 977 - 1: Enable afterburner. */ 978 979 AACENC_BANDWIDTH = 0x0203, /*!< Core encoder audio bandwidth: 980 - 0: Determine bandwidth internally (default, see chapter \ref BEHAVIOUR_BANDWIDTH). 981 - 1 to fs/2: Frequency bandwidth in Hertz. (Experts only, better do not 982 touch this value to avoid degraded audio quality) */ 983 984 AACENC_TRANSMUX = 0x0300, /*!< Transport type to be used. See ::TRANSPORT_TYPE in FDK_audio.h. Following 985 types can be configured in encoder library: 986 - 0: raw access units 987 - 1: ADIF bitstream format 988 - 2: ADTS bitstream format 989 - 6: Audio Mux Elements (LATM) with muxConfigPresent = 1 990 - 7: Audio Mux Elements (LATM) with muxConfigPresent = 0, out of band StreamMuxConfig 991 - 10: Audio Sync Stream (LOAS) */ 992 993 AACENC_HEADER_PERIOD = 0x0301, /*!< Frame count period for sending in-band configuration buffers within LATM/LOAS 994 transport layer. Additionally this parameter configures the PCE repetition period 995 in raw_data_block(). See \ref encPCE. 996 - 0xFF: auto-mode default 10 for TT_MP4_ADTS, TT_MP4_LOAS and TT_MP4_LATM_MCP1, otherwise 0. 997 - n: Frame count period. */ 998 999 AACENC_SIGNALING_MODE = 0x0302, /*!< Signaling mode of the extension AOT: 1000 - 0: Implicit backward compatible signaling. (default) 1001 - 1: Explicit SBR and implicit PS signaling. 1002 - 2: Explicit hierarchical signaling. 1003 1004 The use of backward-compatible implicit signaling is recommended if the user specically 1005 aims at preserving compatibility with decoders only capable of decoding AAC-LC. Otherwise 1006 use non-backward-compatible explicit signaling. 1007 Bitstream formats ADTS and ADIF can only do implicit signaling. */ 1008 1009 AACENC_TPSUBFRAMES = 0x0303, /*!< Number of sub frames in a transport frame for LOAS/LATM or ADTS (default 1). 1010 - ADTS: Maximum number of sub frames restricted to 4. 1011 - LOAS/LATM: Maximum number of sub frames restricted to 2.*/ 1012 1013 AACENC_PROTECTION = 0x0306, /*!< Configure protection in tranpsort layer: 1014 - 0: No protection. (default) 1015 - 1: CRC active for ADTS bitstream format. */ 1016 1017 AACENC_ANCILLARY_BITRATE = 0x0500, /*!< Constant ancillary data bitrate in bits/second. 1018 - 0: Either no ancillary data or insert exact number of bytes, denoted via 1019 input parameter, numAncBytes in AACENC_InArgs. 1020 - else: Insert ancillary data with specified bitrate. */ 1021 1022 AACENC_METADATA_MODE = 0x0600, /*!< Configure Meta Data. See ::AACENC_MetaData for further details: 1023 - 0: Do not embed any metadata. 1024 - 1: Embed MPEG defined metadata only. 1025 - 2: Embed all metadata. */ 1026 1027 AACENC_CONTROL_STATE = 0xFF00, /*!< There is an automatic process which internally reconfigures the encoder instance 1028 when a configuration parameter changed or an error occured. This paramerter allows 1029 overwriting or getting the control status of this process. See ::AACENC_CTRLFLAGS. */ 1030 1031 AACENC_NONE = 0xFFFF /*!< ------ */ 1032 1033 } AACENC_PARAM; 1034 1035 1036 #ifdef __cplusplus 1037 extern "C" { 1038 #endif 1039 1040 /** 1041 * \brief Open an instance of the encoder. 1042 * 1043 * Allocate memory for an encoder instance with a functional range denoted by the function parameters. 1044 * Preinitialize encoder instance with default configuration. 1045 * 1046 * \param phAacEncoder A pointer to an encoder handle. Initialized on return. 1047 * \param encModules Specify encoder modules to be supported in this encoder instance: 1048 * - 0x0: Allocate memory for all available encoder modules. 1049 * - else: Select memory allocation regarding encoder modules. Following flags are possible and can be combined. 1050 * - 0x01: AAC module. 1051 * - 0x02: SBR module. 1052 * - 0x04: PS module. 1053 * - 0x10: Metadata module. 1054 * - example: (0x01|0x02|0x04|0x10) allocates all modules and is equivalent to default configuration denotet by 0x0. 1055 * \param maxChannels Number of channels to be allocated. This parameter can be used in different ways: 1056 * - 0: Allocate maximum number of AAC and SBR channels as supported by the library. 1057 * - nChannels: Use same maximum number of channels for allocating memory in AAC and SBR module. 1058 * - nChannels | (nSbrCh<<8): Number of SBR channels can be different to AAC channels to save data memory. 1059 * 1060 * \return 1061 * - AACENC_OK, on succes. 1062 * - AACENC_INVALID_HANDLE, AACENC_MEMORY_ERROR, AACENC_INVALID_CONFIG, on failure. 1063 */ 1064 AACENC_ERROR aacEncOpen( 1065 HANDLE_AACENCODER *phAacEncoder, 1066 const UINT encModules, 1067 const UINT maxChannels 1068 ); 1069 1070 1071 /** 1072 * \brief Close the encoder instance. 1073 * 1074 * Deallocate encoder instance and free whole memory. 1075 * 1076 * \param phAacEncoder Pointer to the encoder handle to be deallocated. 1077 * 1078 * \return 1079 * - AACENC_OK, on success. 1080 * - AACENC_INVALID_HANDLE, on failure. 1081 */ 1082 AACENC_ERROR aacEncClose( 1083 HANDLE_AACENCODER *phAacEncoder 1084 ); 1085 1086 1087 /** 1088 * \brief Encode audio data. 1089 * 1090 * This function is mainly for encoding audio data. In addition the function can be used for an encoder (re)configuration 1091 * process. 1092 * - PCM input data will be retrieved from external input buffer until the fill level allows encoding a single frame. 1093 * This functionality allows an external buffer with reduced size in comparison to the AAC or HE-AAC audio frame length. 1094 * - If the value of the input samples argument is zero, just internal reinitialization will be applied if it is 1095 * requested. 1096 * - At the end of a file the flushing process can be triggerd via setting the value of the input samples argument to -1. 1097 * The encoder delay lines are fully flushed when the encoder returns no valid bitstream data AACENC_OutArgs::numOutBytes. 1098 * Furthermore the end of file is signaled by the return value AACENC_ENCODE_EOF. 1099 * - If an error occured in the previous frame or any of the encoder parameters changed, an internal reinitialization 1100 * process will be applied before encoding the incoming audio samples. 1101 * - The function can also be used for an independent reconfiguration process without encoding. The first parameter has to be a 1102 * valid encoder handle and all other parameters can be set to NULL. 1103 * - If the size of the external bitbuffer in outBufDesc is not sufficient for writing the whole bitstream, an internal 1104 * error will be the return value and a reconfiguration will be triggered. 1105 * 1106 * \param hAacEncoder A valid AAC encoder handle. 1107 * \param inBufDesc Input buffer descriptor, see AACENC_BufDesc: 1108 * - At least one input buffer with audio data is expected. 1109 * - Optionally a second input buffer with ancillary data can be fed. 1110 * \param outBufDesc Output buffer descriptor, see AACENC_BufDesc: 1111 * - Provide one output buffer for the encoded bitstream. 1112 * \param inargs Input arguments, see AACENC_InArgs. 1113 * \param outargs Output arguments, AACENC_OutArgs. 1114 * 1115 * \return 1116 * - AACENC_OK, on success. 1117 * - AACENC_INVALID_HANDLE, AACENC_ENCODE_ERROR, on failure in encoding process. 1118 * - AACENC_INVALID_CONFIG, AACENC_INIT_ERROR, AACENC_INIT_AAC_ERROR, AACENC_INIT_SBR_ERROR, AACENC_INIT_TP_ERROR, 1119 * AACENC_INIT_META_ERROR, on failure in encoder initialization. 1120 * - AACENC_ENCODE_EOF, when flushing fully concluded. 1121 */ 1122 AACENC_ERROR aacEncEncode( 1123 const HANDLE_AACENCODER hAacEncoder, 1124 const AACENC_BufDesc *inBufDesc, 1125 const AACENC_BufDesc *outBufDesc, 1126 const AACENC_InArgs *inargs, 1127 AACENC_OutArgs *outargs 1128 ); 1129 1130 1131 /** 1132 * \brief Acquire info about present encoder instance. 1133 * 1134 * This function retrieves information of the encoder configuration. In addition to informative internal states, 1135 * a configuration data block of the current encoder settings will be returned. The format is either Audio Specific Config 1136 * in case of Raw Packets transport format or StreamMuxConfig in case of LOAS/LATM transport format. The configuration 1137 * data block is binary coded as specified in ISO/IEC 14496-3 (MPEG-4 audio), to be used directly for MPEG-4 File Format 1138 * or RFC3016 or RFC3640 applications. 1139 * 1140 * \param hAacEncoder A valid AAC encoder handle. 1141 * \param pInfo Pointer to AACENC_InfoStruct. Filled on return. 1142 * 1143 * \return 1144 * - AACENC_OK, on succes. 1145 * - AACENC_INIT_ERROR, on failure. 1146 */ 1147 AACENC_ERROR aacEncInfo( 1148 const HANDLE_AACENCODER hAacEncoder, 1149 AACENC_InfoStruct *pInfo 1150 ); 1151 1152 1153 /** 1154 * \brief Set one single AAC encoder parameter. 1155 * 1156 * This function allows configuration of all encoder parameters specified in ::AACENC_PARAM. Each parameter must be 1157 * set with a separate function call. An internal validation of the configuration value range will be done and an 1158 * internal reconfiguration will be signaled. The actual configuration adoption is part of the subsequent aacEncEncode() call. 1159 * 1160 * \param hAacEncoder A valid AAC encoder handle. 1161 * \param param Parameter to be set. See ::AACENC_PARAM. 1162 * \param value Parameter value. See parameter description in ::AACENC_PARAM. 1163 * 1164 * \return 1165 * - AACENC_OK, on success. 1166 * - AACENC_INVALID_HANDLE, AACENC_UNSUPPORTED_PARAMETER, AACENC_INVALID_CONFIG, on failure. 1167 */ 1168 AACENC_ERROR aacEncoder_SetParam( 1169 const HANDLE_AACENCODER hAacEncoder, 1170 const AACENC_PARAM param, 1171 const UINT value 1172 ); 1173 1174 1175 /** 1176 * \brief Get one single AAC encoder parameter. 1177 * 1178 * This function is the complement to aacEncoder_SetParam(). After encoder reinitialization with user defined settings, 1179 * the internal status can be obtained of each parameter, specified with ::AACENC_PARAM. 1180 * 1181 * \param hAacEncoder A valid AAC encoder handle. 1182 * \param param Parameter to be returned. See ::AACENC_PARAM. 1183 * 1184 * \return Internal configuration value of specifed parameter ::AACENC_PARAM. 1185 */ 1186 UINT aacEncoder_GetParam( 1187 const HANDLE_AACENCODER hAacEncoder, 1188 const AACENC_PARAM param 1189 ); 1190 1191 1192 /** 1193 * \brief Get information about encoder library build. 1194 * 1195 * Fill a given LIB_INFO structure with library version information. 1196 * 1197 * \param info Pointer to an allocated LIB_INFO struct. 1198 * 1199 * \return 1200 * - AACENC_OK, on success. 1201 * - AACENC_INVALID_HANDLE, AACENC_INIT_ERROR, on failure. 1202 */ 1203 AACENC_ERROR aacEncGetLibInfo( 1204 LIB_INFO *info 1205 ); 1206 1207 1208 #ifdef __cplusplus 1209 } 1210 #endif 1211 1212 #endif /* _AAC_ENC_LIB_H_ */ 1213
