libSBRdec/src/env_extr.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 /*!
  85   \file
  86   \brief  Envelope extraction prototypes
  87 */
  88
  89 #ifndef __ENVELOPE_EXTRACTION_H
  90 #define __ENVELOPE_EXTRACTION_H
  91
  92 #include "sbrdecoder.h"
  93
  94 #include "FDK_bitstream.h"
  95 #include "lpp_tran.h"
  96
  97 #include "psdec.h"
  98
  99 #define ENV_EXP_FRACT 0
 100 /*!< Shift raw envelope data to support fractional numbers.
 101   Can be set to 8 instead of 0 to enhance accuracy during concealment.
 102   This is not required for conformance and #requantizeEnvelopeData() will
 103   become more expensive.
 104 */
 105
 106 #define EXP_BITS 6
 107 /*!< Size of exponent-part of a pseudo float envelope value (should be at least 6).
 108   The remaining bits in each word are used for the mantissa (should be at least 10).
 109   This format is used in the arrays iEnvelope[] and sbrNoiseFloorLevel[]
 110   in the FRAME_DATA struct which must fit in a certain part of the output buffer
 111   (See buffer management in sbr_dec.cpp).
 112   Exponents and mantissas could also be stored in separate arrays.
 113   Accessing the exponent or the mantissa would be simplified and the masks #MASK_E
 114   resp. #MASK_M would   no longer be required.
 115 */
 116
 117 #define MASK_M (((1 << (FRACT_BITS - EXP_BITS)) - 1) << EXP_BITS)  /*!< Mask for extracting the mantissa of a pseudo float envelope value */
 118 #define MASK_E ((1 << EXP_BITS) - 1)           /*!< Mask for extracting the exponent of a pseudo float envelope value */
 119
 120 #define SIGN_EXT ( ((SCHAR)-1) ^ MASK_E)        /*!< a CHAR-constant with all bits above our sign-bit set */
 121 #define ROUNDING ( (FIXP_SGL)(1<<(EXP_BITS-1)) ) /*!< 0.5-offset for rounding the mantissa of a pseudo-float envelope value */
 122 #define NRG_EXP_OFFSET  16                     /*!< Will be added to the reference energy's exponent to prevent negative numbers */
 123 #define NOISE_EXP_OFFSET  38                   /*!< Will be added to the noise level exponent to prevent negative numbers */
 124
 125 typedef enum
 126 {
 127   HEADER_NOT_PRESENT,
 128   HEADER_OK,
 129   HEADER_RESET
 130 }
 131 SBR_HEADER_STATUS;
 132
 133 typedef enum
 134 {
 135   SBR_NOT_INITIALIZED,
 136   UPSAMPLING,
 137   SBR_HEADER,
 138   SBR_ACTIVE
 139 }
 140 SBR_SYNC_STATE;
 141
 142
 143 typedef enum
 144 {
 145   COUPLING_OFF = 0,
 146   COUPLING_LEVEL,
 147   COUPLING_BAL
 148 }
 149 COUPLING_MODE;
 150
 151 typedef struct
 152 {
 153   UCHAR nSfb[2];           /*!< Number of SBR-bands for low and high freq-resolution */
 154   UCHAR nNfb;              /*!< Actual number of noise bands to read from the bitstream*/
 155   UCHAR numMaster;         /*!< Number of SBR-bands in v_k_master */
 156   UCHAR lowSubband;        /*!< QMF-band where SBR frequency range starts */
 157   UCHAR highSubband;       /*!< QMF-band where SBR frequency range ends */
 158   UCHAR limiterBandTable[MAX_NUM_LIMITERS+1]; /*!< Limiter band table. */
 159   UCHAR noLimiterBands;    /*!< Number of limiter bands. */
 160   UCHAR nInvfBands;        /*!< Number of bands for inverse filtering */
 161   UCHAR *freqBandTable[2]; /*!< Pointers to freqBandTableLo and freqBandTableHi */
 162   UCHAR freqBandTableLo[MAX_FREQ_COEFFS/2+1];
 163                                    /*!< Mapping of SBR bands to QMF bands for low frequency resolution */
 164   UCHAR freqBandTableHi[MAX_FREQ_COEFFS+1];
 165                                    /*!< Mapping of SBR bands to QMF bands for high frequency resolution */
 166   UCHAR freqBandTableNoise[MAX_NOISE_COEFFS+1];
 167                                    /*!< Mapping of SBR noise bands to QMF bands */
 168   UCHAR v_k_master[MAX_FREQ_COEFFS+1];
 169                                    /*!< Master BandTable which freqBandTable is derived from */
 170 }
 171 FREQ_BAND_DATA;
 172
 173 typedef FREQ_BAND_DATA *HANDLE_FREQ_BAND_DATA;
 174
 175 #define SBRDEC_ELD_GRID        1
 176 #define SBRDEC_SYNTAX_SCAL     2
 177 #define SBRDEC_SYNTAX_USAC     4
 178 #define SBRDEC_SYNTAX_RSVD50   8
 179 #define SBRDEC_LOW_POWER      16  /* Flag indicating that Low Power QMF mode shall be used. */
 180 #define SBRDEC_PS_DECODED     32  /* Flag indicating that PS was decoded and rendered. */
 181 #define SBRDEC_LD_MPS_QMF    512  /* Flag indicating that the LD-MPS QMF shall be used. */
 182
 183 #define SBRDEC_HDR_STAT_RESET  1
 184 #define SBRDEC_HDR_STAT_UPDATE 2
 185
 186 typedef struct {
 187   UCHAR ampResolution;       /*!< Amplitude resolution of envelope values (0: 1.5dB, 1: 3dB) */
 188   UCHAR xover_band;          /*!< Start index in #v_k_master[] used for dynamic crossover frequency */
 189   UCHAR sbr_preprocessing;   /*!< SBR prewhitening flag. */
 190 } SBR_HEADER_DATA_BS_INFO;
 191
 192 typedef struct {
 193   /* Changes in these variables causes a reset of the decoder */
 194   UCHAR startFreq;           /*!< Index for SBR start frequency */
 195   UCHAR stopFreq;            /*!< Index for SBR highest frequency */
 196   UCHAR freqScale;           /*!< 0: linear scale,  1-3 logarithmic scales */
 197   UCHAR alterScale;          /*!< Flag for coarser frequency resolution */
 198   UCHAR noise_bands;         /*!< Noise bands per octave, read from bitstream*/
 199
 200   /* don't require reset */
 201   UCHAR limiterBands;        /*!< Index for number of limiter bands per octave */
 202   UCHAR limiterGains;        /*!< Index to select gain limit */
 203   UCHAR interpolFreq;        /*!< Select gain calculation method (1: per QMF channel, 0: per SBR band) */
 204   UCHAR smoothingLength;     /*!< Smoothing of gains over time (0: on  1: off) */
 205
 206 } SBR_HEADER_DATA_BS;
 207
 208 typedef struct
 209 {
 210   SBR_SYNC_STATE syncState;    /*!< The current initialization status of the header */
 211
 212   UCHAR status;                /*!< Flags field used for signaling a reset right before the processing starts and an update from config (e.g. ASC). */
 213   UCHAR frameErrorFlag;        /*!< Frame data valid flag. CAUTION: This variable will be overwritten by the flag stored in the element structure.
 214                                     This is necessary because of the frame delay. There it might happen that different slots use the same header. */
 215   UCHAR numberTimeSlots;       /*!< AAC: 16,15 */
 216   UCHAR numberOfAnalysisBands; /*!< Number of QMF analysis bands */
 217   UCHAR timeStep;              /*!< Time resolution of SBR in QMF-slots */
 218   UINT  sbrProcSmplRate;       /*!< SBR processing sampling frequency (!= OutputSamplingRate)
 219                                      (always: CoreSamplingRate * UpSamplingFactor; even in single rate mode) */
 220
 221   SBR_HEADER_DATA_BS      bs_data;  /*!< current SBR header. */
 222   SBR_HEADER_DATA_BS_INFO bs_info;  /*!< SBR info. */
 223
 224   FREQ_BAND_DATA freqBandData;  /*!< Pointer to struct #FREQ_BAND_DATA */
 225 }
 226 SBR_HEADER_DATA;
 227
 228 typedef SBR_HEADER_DATA *HANDLE_SBR_HEADER_DATA;
 229
 230
 231 typedef struct
 232 {
 233   UCHAR frameClass;               /*!< Select grid type */
 234   UCHAR nEnvelopes;               /*!< Number of envelopes */
 235   UCHAR borders[MAX_ENVELOPES+1]; /*!< Envelope borders (in SBR-timeslots, e.g. mp3PRO: 0..11) */
 236   UCHAR freqRes[MAX_ENVELOPES];   /*!< Frequency resolution for each envelope (0=low, 1=high) */
 237   SCHAR  tranEnv;                 /*!< Transient envelope, -1 if none */
 238   UCHAR nNoiseEnvelopes;          /*!< Number of noise envelopes */
 239   UCHAR bordersNoise[MAX_NOISE_ENVELOPES+1];/*!< borders of noise envelopes */
 240 }
 241 FRAME_INFO;
 242
 243
 244 typedef struct
 245 {
 246   FIXP_SGL sfb_nrg_prev[MAX_FREQ_COEFFS];    /*!< Previous envelope (required for differential-coded values) */
 247   FIXP_SGL prevNoiseLevel[MAX_NOISE_COEFFS]; /*!< Previous noise envelope (required for differential-coded values) */
 248   COUPLING_MODE coupling;                    /*!< Stereo-mode of previous frame */
 249   INVF_MODE sbr_invf_mode[MAX_INVF_BANDS];   /*!< Previous strength of filtering in transposer */
 250   UCHAR ampRes;                              /*!< Previous amplitude resolution (0: 1.5dB, 1: 3dB) */
 251   UCHAR stopPos;                             /*!< Position in time where last envelope ended */
 252   UCHAR frameErrorFlag;                      /*!< Previous frame status */
 253 }
 254 SBR_PREV_FRAME_DATA;
 255
 256 typedef SBR_PREV_FRAME_DATA *HANDLE_SBR_PREV_FRAME_DATA;
 257
 258
 259 typedef struct
 260 {
 261   int nScaleFactors;                    /*!< total number of scalefactors in frame */
 262
 263   FRAME_INFO frameInfo;                 /*!< time grid for current frame */
 264   UCHAR domain_vec[MAX_ENVELOPES];      /*!< Bitfield containing direction of delta-coding for each envelope (0:frequency, 1:time) */
 265   UCHAR domain_vec_noise[MAX_NOISE_ENVELOPES]; /*!< Same as above, but for noise envelopes */
 266
 267   INVF_MODE sbr_invf_mode[MAX_INVF_BANDS]; /*!< Strength of filtering in transposer */
 268   COUPLING_MODE coupling;                  /*!< Stereo-mode */
 269   int ampResolutionCurrentFrame;           /*!< Amplitude resolution of envelope values (0: 1.5dB, 1: 3dB) */
 270
 271   UCHAR addHarmonics[MAX_FREQ_COEFFS];     /*!< Flags for synthetic sine addition */
 272
 273   FIXP_SGL iEnvelope[MAX_NUM_ENVELOPE_VALUES];       /*!< Envelope data */
 274   FIXP_SGL sbrNoiseFloorLevel[MAX_NUM_NOISE_VALUES]; /*!< Noise envelope data */
 275 }
 276 SBR_FRAME_DATA;
 277
 278 typedef SBR_FRAME_DATA *HANDLE_SBR_FRAME_DATA;
 279
 280 void initSbrPrevFrameData (HANDLE_SBR_PREV_FRAME_DATA h_prev_data,
 281                            int timeSlots);
 282
 283
 284 int sbrGetSingleChannelElement (HANDLE_SBR_HEADER_DATA hHeaderData,
 285                                 HANDLE_SBR_FRAME_DATA  hFrameData,
 286                                 HANDLE_FDK_BITSTREAM   hBitBuf,
 287                                 HANDLE_PS_DEC hParametricStereoDec,
 288                                 const UINT             flags,
 289                                 const int              overlap
 290                                );
 291
 292 int sbrGetChannelPairElement (HANDLE_SBR_HEADER_DATA hHeaderData,
 293                               HANDLE_SBR_FRAME_DATA  hFrameDataLeft,
 294                               HANDLE_SBR_FRAME_DATA  hFrameDataRight,
 295                               HANDLE_FDK_BITSTREAM   hBitBuf,
 296                               const UINT             flags,
 297                               const int              overlap);
 298
 299 SBR_HEADER_STATUS
 300 sbrGetHeaderData (HANDLE_SBR_HEADER_DATA headerData,
 301                   HANDLE_FDK_BITSTREAM   hBitBuf,
 302                   const UINT             flags,
 303                   const int              fIsSbrData);
 304
 305 /*!
 306   \brief     Initialize SBR header data
 307
 308   Copy default values to the header data struct and patch some entries
 309   depending on the core codec.
 310 */
 311 SBR_ERROR
 312 initHeaderData (
 313         HANDLE_SBR_HEADER_DATA  hHeaderData,
 314         const int               sampleRateIn,
 315         const int               sampleRateOut,
 316         const int               samplesPerFrame,
 317         const UINT              flags
 318         );
 319 #endif