libAACenc/src/aacenc.h

   1
   2 /* -----------------------------------------------------------------------------------------------------------
   3 Software License for The Fraunhofer FDK AAC Codec Library for Android
   4
   5 © Copyright  1995 - 2013 Fraunhofer-Gesellschaft zur Förderung 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@iis.fraunhofer.de
  82 ----------------------------------------------------------------------------------------------------------- */
  83
  84 /*************************  Fast MPEG AAC Audio Encoder  **********************
  85
  86    Initial author:       M. Schug / A. Groeschel
  87    contents/description: fast aac coder interface library functions
  88
  89 ******************************************************************************/
  90
  91 #ifndef _aacenc_h_
  92 #define _aacenc_h_
  93
  94 #include "common_fix.h"
  95 #include "FDK_audio.h"
  96
  97 #include "tpenc_lib.h"
  98
  99 #include "sbr_encoder.h"
 100
 101 #ifdef __cplusplus
 102 extern "C" {
 103 #endif
 104
 105 /*
 106  * AAC-LC error codes.
 107  */
 108 typedef enum {
 109   AAC_ENC_OK       = 0x0000,                          /*!< All fine. */
 110
 111   AAC_ENC_UNKNOWN  = 0x0002,                          /*!< Error condition is of unknown reason, or from another module.              */
 112
 113   /* initialization errors */
 114   aac_enc_init_error_start      = 0x2000,
 115   AAC_ENC_INVALID_HANDLE        = 0x2020,             /*!< The handle passed to the function call was invalid (probably NULL).        */
 116   AAC_ENC_INVALID_FRAME_LENGTH  = 0x2080,             /*!< Invalid frame length.                                                      */
 117   AAC_ENC_INVALID_N_CHANNELS    = 0x20e0,             /*!< Invalid amount of audio input channels.                                    */
 118   AAC_ENC_INVALID_SFB_TABLE     = 0x2140,             /*!< Internal encoder error.                                                    */
 119
 120   AAC_ENC_UNSUPPORTED_AOT            = 0x3000,        /*!< The Audio Object Type (AOT) is not supported.                              */
 121   AAC_ENC_UNSUPPORTED_BITRATE        = 0x3020,        /*!< The chosen bitrate is not supported.                                       */
 122   AAC_ENC_UNSUPPORTED_BITRATE_MODE   = 0x3028,        /*!< Unsupported bit rate mode (CBR or VBR).                                    */
 123   AAC_ENC_UNSUPPORTED_ANC_BITRATE    = 0x3040,        /*!< Unsupported ancillay bitrate.                                              */
 124   AAC_ENC_UNSUPPORTED_ANC_MODE       = 0x3060,
 125   AAC_ENC_UNSUPPORTED_TRANSPORT_TYPE = 0x3080,        /*!< The bitstream format is not supported.                                     */
 126   AAC_ENC_UNSUPPORTED_ER_FORMAT      = 0x30a0,        /*!< The error resilience tool format is not supported.                         */
 127   AAC_ENC_UNSUPPORTED_EPCONFIG       = 0x30c0,        /*!< The error protection format is not supported.                              */
 128   AAC_ENC_UNSUPPORTED_CHANNELCONFIG  = 0x30e0,        /*!< The channel configuration (either number or arrangement) is not supported. */
 129   AAC_ENC_UNSUPPORTED_SAMPLINGRATE   = 0x3100,        /*!< Sample rate of audio input is not supported.                               */
 130   AAC_ENC_NO_MEMORY                  = 0x3120,        /*!< Could not allocate memory. */
 131   AAC_ENC_PE_INIT_TABLE_NOT_FOUND    = 0x3140,        /*!< Internal encoder error.    */
 132
 133   aac_enc_init_error_end,
 134
 135   /* encode errors */
 136   aac_enc_error_start                       = 0x4000,
 137   AAC_ENC_QUANT_ERROR                       = 0x4020,       /*!< Too many bits used in quantization.             */
 138   AAC_ENC_WRITTEN_BITS_ERROR                = 0x4040,       /*!< Unexpected number of written bits, differs to
 139                                                                  calculated number of bits.                      */
 140   AAC_ENC_PNS_TABLE_ERROR                   = 0x4060,       /*!< PNS level out of range.                         */
 141   AAC_ENC_GLOBAL_GAIN_TOO_HIGH              = 0x4080,       /*!< Internal quantizer error.                       */
 142   AAC_ENC_BITRES_TOO_LOW                    = 0x40a0,       /*!< Too few  bits in bit reservoir.                 */
 143   AAC_ENC_BITRES_TOO_HIGH                   = 0x40a1,       /*!< Too many bits in bit reservoir.                 */
 144   AAC_ENC_INVALID_CHANNEL_BITRATE           = 0x4100,
 145   AAC_ENC_INVALID_ELEMENTINFO_TYPE          = 0x4120,       /*!< Internal encoder error.                         */
 146
 147   AAC_ENC_WRITE_SCAL_ERROR                  = 0x41e0,       /*!< Error writing scalefacData.                     */
 148   AAC_ENC_WRITE_SEC_ERROR                   = 0x4200,       /*!< Error writing sectionData.                      */
 149   AAC_ENC_WRITE_SPEC_ERROR                  = 0x4220,       /*!< Error writing spectralData.                     */
 150   aac_enc_error_end
 151
 152 } AAC_ENCODER_ERROR;
 153 /*-------------------------- defines --------------------------------------*/
 154
 155 #define ANC_DATA_BUFFERSIZE 1024      /* ancBuffer size */
 156
 157 #define MAX_TOTAL_EXT_PAYLOADS  (((8) * (1)) + (2+2))
 158
 159
 160 typedef enum {
 161   AACENC_BR_MODE_INVALID = -1,  /*!< Invalid bitrate mode.                            */
 162   AACENC_BR_MODE_CBR     =  0,  /*!< Constant bitrate mode.                           */
 163   AACENC_BR_MODE_VBR_1   =  1,  /*!< Variable bitrate mode, about 32 kbps/channel.    */
 164   AACENC_BR_MODE_VBR_2   =  2,  /*!< Variable bitrate mode, about 40 kbps/channel.    */
 165   AACENC_BR_MODE_VBR_3   =  3,  /*!< Variable bitrate mode, about 48-56 kbps/channel. */
 166   AACENC_BR_MODE_VBR_4   =  4,  /*!< Variable bitrate mode, about 64 kbps/channel.    */
 167   AACENC_BR_MODE_VBR_5   =  5,  /*!< Variable bitrate mode, about 80-96 kbps/channel. */
 168   AACENC_BR_MODE_FF      =  6,  /*!< Fixed frame mode.                                */
 169   AACENC_BR_MODE_SFR     =  7   /*!< Superframe mode.                                 */
 170
 171 } AACENC_BITRATE_MODE;
 172
 173 typedef enum {
 174
 175   CH_ORDER_MPEG = 0,  /*!< MPEG channel ordering (e. g. 5.1: C, L, R, SL, SR, LFE)           */
 176   CH_ORDER_WAV,       /*!< WAV fileformat channel ordering (e. g. 5.1: L, R, C, LFE, SL, SR) */
 177   CH_ORDER_WG4        /*!< WG4 fileformat channel ordering (e. g. 5.1: L, R, SL, SR, C, LFE) */
 178
 179 } CHANNEL_ORDER;
 180
 181 /*-------------------- structure definitions ------------------------------*/
 182
 183 struct AACENC_CONFIG {
 184   INT   sampleRate;             /* encoder sample rate */
 185   INT   bitRate;                /* encoder bit rate in bits/sec */
 186   INT   ancDataBitRate;         /* additional bits consumed by anc data or sbr have to be consiedered while configuration */
 187
 188   INT   nSubFrames;             /* number of frames in super frame (not ADTS/LATM subframes !) */
 189   AUDIO_OBJECT_TYPE audioObjectType;   /* Audio Object Type  */
 190
 191   INT   averageBits;            /* encoder bit rate in bits/superframe */
 192   INT   bitrateMode;            /* encoder bitrate mode (CBR/VBR) */
 193   INT   nChannels;              /* number of channels to process */
 194   CHANNEL_ORDER channelOrder;   /* Input Channel ordering scheme. */
 195   INT   bandWidth;              /* targeted audio bandwidth in Hz */
 196   CHANNEL_MODE  channelMode;    /* encoder channel mode configuration */
 197   INT   framelength;            /* used frame size */
 198
 199   UINT  syntaxFlags;            /* bitstreams syntax configuration */
 200   SCHAR epConfig;               /* error protection configuration */
 201
 202   INT   anc_Rate;               /* ancillary rate, 0 (disabled), -1 (default) else desired rate */
 203   UINT  maxAncBytesPerAU;
 204   INT   minBitsPerFrame;        /* minimum number of bits in AU */
 205   INT   maxBitsPerFrame;        /* maximum number of bits in AU */
 206   INT   bitreservoir;           /* size of bitreservoir */
 207
 208   UINT  sbrRatio;               /* sbr sampling rate ratio: dual- or single-rate */
 209
 210   UCHAR useTns;                 /* flag: use temporal noise shaping */
 211   UCHAR usePns;                 /* flag: use perceptual noise substitution */
 212   UCHAR useIS;                  /* flag: use intensity coding */
 213
 214   UCHAR useRequant;             /* flag: use afterburner */
 215 };
 216
 217 typedef struct {
 218   UCHAR            *pData;      /* pointer to extension payload data */
 219   UINT              dataSize;   /* extension payload data size in bits */
 220   EXT_PAYLOAD_TYPE  dataType;   /* extension payload data type */
 221   INT               associatedChElement;  /* number of the channel element the data is assigned to */
 222 } AACENC_EXT_PAYLOAD;
 223
 224 typedef struct AAC_ENC *HANDLE_AAC_ENC;
 225
 226 /**
 227  * \brief Limit given bit rate to a valid value
 228  * \param hTpEnc transport encoder handle
 229  * \param coreSamplingRate the sample rate to be used for the AAC encoder
 230  * \param frameLength the frameLength to be used for the AAC encoder
 231  * \param nChannels number of total channels
 232  * \param nChannelsEff number of effective channels
 233  * \param bitRate the initial bit rate value for which the closest valid bit rate value is searched for
 234  * \param averageBits average bits per frame for fixed framing. Set to -1 if not available.
 235  * \param optional pointer where the current bits per frame are stored into.
 236  * \param bitrateMode the current bit rate mode
 237  * \param nSubFrames number of sub frames for super framing (not transport frames).
 238  * \return a valid bit rate value as close as possible or identical to bitRate
 239  */
 240 INT FDKaacEnc_LimitBitrate(
 241         HANDLE_TRANSPORTENC hTpEnc,
 242         INT coreSamplingRate,
 243         INT frameLength,
 244         INT nChannels,
 245         INT nChannelsEff,
 246         INT bitRate,
 247         INT averageBits,
 248         INT *pAverageBitsPerFrame,
 249         INT bitrateMode,
 250         INT nSubFrames
 251         );
 252
 253  /*-----------------------------------------------------------------------------
 254
 255      functionname: FDKaacEnc_GetVBRBitrate
 256      description:  Get VBR bitrate from vbr quality
 257      input params: int vbrQuality (VBR0, VBR1, VBR2)
 258                    channelMode
 259      returns:      vbr bitrate
 260
 261  ------------------------------------------------------------------------------*/
 262  INT FDKaacEnc_GetVBRBitrate(INT bitrateMode, CHANNEL_MODE channelMode);
 263
 264
 265 /*-----------------------------------------------------------------------------
 266
 267      functionname: FDKaacEnc_AacInitDefaultConfig
 268      description:  gives reasonable default configuration
 269      returns:      ---
 270
 271  ------------------------------------------------------------------------------*/
 272 void FDKaacEnc_AacInitDefaultConfig(AACENC_CONFIG     *config);
 273
 274 /*---------------------------------------------------------------------------
 275
 276             functionname:FDKaacEnc_Open
 277     description: allocate and initialize a new encoder instance
 278     returns:     0 if success
 279
 280   ---------------------------------------------------------------------------*/
 281 AAC_ENCODER_ERROR FDKaacEnc_Open(HANDLE_AAC_ENC  *phAacEnc,              /* pointer to an encoder handle, initialized on return */
 282                                  const INT        nElements,             /* number of maximal elements in instance to support */
 283                                  const INT        nChannels,             /* number of maximal channels in instance to support */
 284                                  const INT        nSubFrames);           /* support superframing in instance */
 285
 286
 287 AAC_ENCODER_ERROR FDKaacEnc_Initialize(HANDLE_AAC_ENC     hAacEncoder,   /* pointer to an encoder handle, initialized on return */
 288                                        AACENC_CONFIG    *config,         /* pre-initialized config struct */
 289                                        HANDLE_TRANSPORTENC hTpEnc,
 290                                        ULONG               initFlags);
 291
 292
 293 /*---------------------------------------------------------------------------
 294
 295     functionname: FDKaacEnc_EncodeFrame
 296     description:  encode one frame
 297     returns:      0 if success
 298
 299   ---------------------------------------------------------------------------*/
 300
 301 AAC_ENCODER_ERROR FDKaacEnc_EncodeFrame( HANDLE_AAC_ENC       hAacEnc,         /* encoder handle */
 302                                          HANDLE_TRANSPORTENC  hTpEnc,
 303                                          INT_PCM*             inputBuffer,
 304                                          INT*                 numOutBytes,
 305                                          AACENC_EXT_PAYLOAD   extPayload[MAX_TOTAL_EXT_PAYLOADS]
 306                                        );
 307
 308 /*---------------------------------------------------------------------------
 309
 310     functionname:FDKaacEnc_Close
 311     description: delete encoder instance
 312     returns:
 313
 314   ---------------------------------------------------------------------------*/
 315
 316 void FDKaacEnc_Close( HANDLE_AAC_ENC*  phAacEnc);   /* encoder handle */
 317
 318 #ifdef __cplusplus
 319 }
 320 #endif
 321
 322 #endif /* _aacenc_h_ */
 323