fenix/fdk-aac
1
0
Fork 0
mirror of https://github.com/mstorsjo/fdk-aac.git synced 2024-12-12 08:26:11 +01:00
Code Issues Projects Releases Wiki Activity
8d150d51be
fdk-aac/libSACdec/include/sac_dec_lib.h
Fraunhofer IIS FDK 5eb9ed1b1f Check number of core channels and SAC decoder input channels to avoid a channel mismatch. 
Bug: 176246647
Test: atest android.media.cts.DecoderTestAacFormat android.media.cts.DecoderTestXheAac android.media.cts.DecoderTestAacDrc
Change-Id: Ib8b6973e9c29e13b8ef33d7736be2b977928face
2020-12-28 09:21:16 -08:00

483 lines
21 KiB
C
Raw Blame History

/* -----------------------------------------------------------------------------
Software License for The Fraunhofer FDK AAC Codec Library for Android
© Copyright 1995 - 2020 Fraunhofer-Gesellschaft zur Förderung der angewandten
Forschung e.V. All rights reserved.
1. INTRODUCTION
The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software
that implements the MPEG Advanced Audio Coding ("AAC") encoding and decoding
scheme for digital audio. This FDK AAC Codec software is intended to be used on
a wide variety of Android devices.
AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient
general perceptual audio codecs. AAC-ELD is considered the best-performing
full-bandwidth communications codec by independent studies and is widely
deployed. AAC has been standardized by ISO and IEC as part of the MPEG
specifications.
Patent licenses for necessary patent claims for the FDK AAC Codec (including
those of Fraunhofer) may be obtained through Via Licensing
(www.vialicensing.com) or through the respective patent owners individually for
the purpose of encoding or decoding bit streams in products that are compliant
with the ISO/IEC MPEG audio standards. Please note that most manufacturers of
Android devices already license these patent claims through Via Licensing or
directly from the patent owners, and therefore FDK AAC Codec software may
already be covered under those patent licenses when it is used for those
licensed purposes only.
Commercially-licensed AAC software libraries, including floating-point versions
with enhanced sound quality, are also available from Fraunhofer. Users are
encouraged to check the Fraunhofer website for additional applications
information and documentation.
2. COPYRIGHT LICENSE
Redistribution and use in source and binary forms, with or without modification,
are permitted without payment of copyright license fees provided that you
satisfy the following conditions:
You must retain the complete text of this software license in redistributions of
the FDK AAC Codec or your modifications thereto in source code form.
You must retain the complete text of this software license in the documentation
and/or other materials provided with redistributions of the FDK AAC Codec or
your modifications thereto in binary form. You must make available free of
charge copies of the complete source code of the FDK AAC Codec and your
modifications thereto to recipients of copies in binary form.
The name of Fraunhofer may not be used to endorse or promote products derived
from this library without prior written permission.
You may not charge copyright license fees for anyone to use, copy or distribute
the FDK AAC Codec software or your modifications thereto.
Your modified versions of the FDK AAC Codec must carry prominent notices stating
that you changed the software and the date of any change. For modified versions
of the FDK AAC Codec, the term "Fraunhofer FDK AAC Codec Library for Android"
must be replaced by the term "Third-Party Modified Version of the Fraunhofer FDK
AAC Codec Library for Android."
3. NO PATENT LICENSE
NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without
limitation the patents of Fraunhofer, ARE GRANTED BY THIS SOFTWARE LICENSE.
Fraunhofer provides no warranty of patent non-infringement with respect to this
software.
You may use this FDK AAC Codec software or modifications thereto only for
purposes that are authorized by appropriate patent licenses.
4. DISCLAIMER
This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright
holders and contributors "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
including but not limited to the implied warranties of merchantability and
fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary,
or consequential damages, including but not limited to procurement of substitute
goods or services; loss of use, data, or profits, or business interruption,
however caused and on any theory of liability, whether in contract, strict
liability, or tort (including negligence), arising in any way out of the use of
this software, even if advised of the possibility of such damage.
5. CONTACT INFORMATION
Fraunhofer Institute for Integrated Circuits IIS
Attention: Audio and Multimedia Departments - FDK AAC LL
Am Wolfsmantel 33
91058 Erlangen, Germany
www.iis.fraunhofer.de/amm
amm-info@iis.fraunhofer.de
----------------------------------------------------------------------------- */
/*********************** MPEG surround decoder library *************************
Author(s):
Description: Space Decoder
*******************************************************************************/
#ifndef SAC_DEC_LIB_H
#define SAC_DEC_LIB_H
#include "common_fix.h"
#include "FDK_audio.h"
#include "sac_dec_errorcodes.h"
#include "FDK_bitstream.h"
#include "FDK_qmf_domain.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
* \brief MPEG Surround input data interface mode.
**/
typedef enum {
SAC_INTERFACE_QMF =
0, /*!< Use QMF domain interface for the input downmix audio. */
SAC_INTERFACE_TIME, /*!< Use time domain interface for the input downmix
audio. */
SAC_INTERFACE_AUTO /*!< */
} SAC_INPUT_CONFIG;
/**
* \brief MPEG Surround output mode.
**/
typedef enum {
SACDEC_OUT_MODE_NORMAL =
0, /*!< Normal multi channel processing without output restrictions. */
SACDEC_OUT_MODE_BINAURAL, /*!< Two channel output with binaural processsing.
*/
SACDEC_OUT_MODE_STEREO, /*!< Always two channel output mode. */
SACDEC_OUT_MODE_6CHANNEL /*!< Always process with 5.1 channel output. */
} SAC_DEC_OUTPUT_MODE;
/**
* \brief MPEG Surround binaural HRTF model.
* HRTF will be applied only in combination with upmixtype
*SAC_UPMIX_TYPE_BINAURAL.
**/
typedef enum {
SAC_BINAURAL_HRTF_KEMAR = 0,
SAC_BINAURAL_HRTF_VAST,
SAC_BINAURAL_HRTF_MPSVT,
SAC_BINAURAL_SINGLE_HRTFS
} SAC_BINAURAL_HRTF_MODEL;
/**
* \brief MPEG Surround decoder instance available.
**/
typedef enum {
SAC_INSTANCE_NOT_FULL_AVAILABLE =
0, /*!< MPEG Surround decoder instance not full available. */
SAC_INSTANCE_FULL_AVAILABLE /*!< MPEG Surround decoder instance full
available. */
} SAC_INSTANCE_AVAIL;
/**
* \brief MPEG Surround decoder dynamic parameters.
*
* Use mpegSurroundDecoder_SetParam() function to configure internal status of
* following parameters.
*/
typedef enum {
SACDEC_OUTPUT_MODE = 0x0001, /*!< Set MPEG Surround decoder output mode. See
SAC_DEC_OUTPUT_MODE. */
SACDEC_BLIND_ENABLE =
0x0002, /*!< Multi channel output without MPEG Surround side info. */
SACDEC_PARTIALLY_COMPLEX =
0x0003, /*!< Set partially complex flag for MPEG Surround.
0: Use complex valued QMF data.
1: Use real valued QMF data (low power mode) */
SACDEC_INTERFACE =
0x0004, /*!< Select signal input interface for MPEG Surround.
Switch time interface off: 0
Switch time interface on: 1 */
SACDEC_BS_DELAY = 0x0005, /*!< Select bit stream delay for MPEG Surround.
Switch bit stream delay off: 0
Switch bit stream delay on: 1 */
SACDEC_BINAURAL_QUALITY =
0x0102, /*!< Set binaural quality for MPEG Surround binaural mode.
0: Low Complexity,
1: High Quality */
SACDEC_BINAURAL_DISTANCE = 0x0103, /*!< Set perceived distance for binaural
playback (binaural mode only). The valid
values range from 0 to 100. Where 100
corresponds to the farthest perceived
distance. */
SACDEC_BINAURAL_DIALOG_CLARITY =
0x0104, /*!< Set dialog clarity (for binaural playback).
The valid values range from 0 to 100. */
SACDEC_BINAURAL_FRONT_ANGLE = 0x0105, /*!< Set angle between the virtual front
speaker pair (binaural mode only).
The valid range is from 0 to 180
angular degrees. */
SACDEC_BINAURAL_BACK_ANGLE = 0x0106, /*!< Set angle between the virtual back
speaker pair (binaural mode only). The
valid range is from 0 to 180 angular
degrees. */
SACDEC_BINAURAL_PRESET = 0x0107, /*!< Set a virtual speaker setup preset for
binaural playback (binaural mode only).
This meta-parameter implicitly modifies
the following parameters:
SACDEC_BINAURAL_DISTANCE,
SACDEC_BINAURAL_DIALOG_CLARITY,
SACDEC_BINAURAL_FRONT_ANGLE and
SACDEC_BINAURAL_BACK_ANGLE.
The following presets are available:
1: Dry room
2: Living room (default)
3: Cinema */
SACDEC_BS_INTERRUPTION =
0x0200, /*!< If the given value is unequal to 0 hint the MPEG Surround
decoder that the next input data is discontinuous, because of
frame loss, seeking, etc. Announce the decoder that the
bitstream data was interrupted (fSync = 0). This will cause the
surround decoder not to parse any new bitstream data until a
new header with a valid Spatial Specific Config and a
independently decodable frame is found. Specially important
when the MPEG Surround data is split accross several frames
(for example in the case of AAC-LC downmix with 1024
framelength and 2048 surround frame length) and a discontinuity
in the bitstream data occurs. If fSync is 1, assume that MPEG
Surround data is in sync (out of band config for example). */
SACDEC_CLEAR_HISTORY = 0x0201, /*!< If the given value is unequal to 0 clear
all internal states (delay lines, QMF
states, ...) of the MPEG Surround decoder.
This will cause a discontinuity in the audio
output signal. */
SACDEC_CONCEAL_NUM_KEEP_FRAMES =
0x0301, /*!< Error concealment: The Number of frames the module keeps the
last spatial image before fading to the particular spatial
scenario starts. The default is 10 frames. */
SACDEC_CONCEAL_FADE_OUT_SLOPE_LENGTH =
0x0302, /*!< Error concealment: Length of the slope (in frames) the module
creates to fade from the last spatial scenario to the
particular default scenario (downmix) in case of consecutive
errors. Default is 5. */
SACDEC_CONCEAL_FADE_IN_SLOPE_LENGTH =
0x0303, /*!< Error concealment: Length of the slope (in frames) the module
creates to fade from the default spatial scenario (downmix) to
the current scenario after fade-out. Default parameter value
is 5. */
SACDEC_CONCEAL_NUM_RELEASE_FRAMES =
0x0304 /*!< Error concealment: The number of error free frames before the
module starts fading from default to the current spatial
scenario. Default parameter value is 3 frames. */
} SACDEC_PARAM;
#define PCM_MPS LONG
/**
* \brief MPEG Surround decoder handle.
*/
typedef struct MpegSurroundDecoder CMpegSurroundDecoder;
/**
* \brief Check if the full MPEG Surround decoder instance is allocated.
*
* Check if the full MPEG Surround decoder instance is allocated.
*
* \param pMpegSurroundDecoder A pointer to a decoder stucture.
*
* \return SACDEC_ERROR error code
*/
SAC_INSTANCE_AVAIL
mpegSurroundDecoder_IsFullMpegSurroundDecoderInstanceAvailable(
CMpegSurroundDecoder *pMpegSurroundDecoder);
/**
* \brief Open one instance of the MPEG Surround decoder.
*
* Allocate one instance of decoder and input buffers.
* - Allocate decoder structure
* - Allocate input buffers (QMF/time/MPS data)
*
* \param pMpegSurroundDecoder A pointer to a decoder handle; filled on
* return.
* \param splitMemoryAllocation Allocate only outer layer of MPS decoder. Core
* part is reallocated later if needed.
* \param stereoConfigIndex USAC: Save memory by opening the MPS decoder
* for a specific stereoConfigIndex. (Needs optimization macros enabled.)
* \param pQmfDomain Pointer to QMF domain data structure.
*
* \return SACDEC_ERROR error code
*/
SACDEC_ERROR mpegSurroundDecoder_Open(
CMpegSurroundDecoder **pMpegSurroundDecoder, int stereoConfigIndex,
HANDLE_FDK_QMF_DOMAIN pQmfDomain);
/**
* \brief Init one instance of the MPEG Surround decoder.
*
* Init one instance of the MPEG Surround decoder
*
* \param pMpegSurroundDecoder A pointer to a decoder handle;
*
* \return SACDEC_ERROR error code
*/
SACDEC_ERROR mpegSurroundDecoder_Init(
CMpegSurroundDecoder *pMpegSurroundDecoder);
/**
* \brief Read and parse SpatialSpecificConfig.
*
* \param pMpegSurroundDecoder A pointer to a decoder handle.
* \param hBs bitstream handle config parsing data source.
*
* \return SACDEC_ERROR error code
*/
SACDEC_ERROR mpegSurroundDecoder_Config(
CMpegSurroundDecoder *pMpegSurroundDecoder, HANDLE_FDK_BITSTREAM hBs,
AUDIO_OBJECT_TYPE coreCodec, INT samplingRate, INT frameSize,
INT numChannels, INT stereoConfigIndex, INT coreSbrFrameLengthIndex,
INT configBytes, const UCHAR configMode, UCHAR *configChanged);
SACDEC_ERROR
mpegSurroundDecoder_ConfigureQmfDomain(
CMpegSurroundDecoder *pMpegSurroundDecoder,
SAC_INPUT_CONFIG sac_dec_interface, UINT coreSamplingRate,
AUDIO_OBJECT_TYPE coreCodec);
/**
* \brief Parse MPEG Surround data without header
*
* \param pMpegSurroundDecoder A MPEG Surrround decoder handle.
* \param hBs Bit stream handle data input source
* \param pMpsDataBits Pointer to number of valid bits in extension
* payload. Function updates mpsDataBits while parsing bitstream.
* \param fGlobalIndependencyFlag Global independency flag of current frame.
*
* \return Error code.
*/
int mpegSurroundDecoder_ParseNoHeader(
CMpegSurroundDecoder *pMpegSurroundDecoder, HANDLE_FDK_BITSTREAM hBs,
int *pMpsDataBits, int fGlobalIndependencyFlag);
/* #ifdef SACDEC_MPS_ENABLE */
/**
* \brief Parse MPEG Surround data with header. Header is ancType, ancStart,
ancStop (4 bits total). Body is ancDataSegmentByte[i].
*
* \param pMpegSurroundDecoder A MPEG Surrround decoder handle.
* \param hBs Bit stream handle data input source
* \param pMpsDataBits Pointer to number of valid bits in extension
payload. Function updates mpsDataBits while parsing bitstream. Needs to be a
multiple of 8 + 4 (4 bits header).
* \param coreCodec The audio object type of the core codec handling
the downmix input signal.
* \param sampleRate Samplerate of input downmix data.
* \param nChannels Amount of input channels.
* \param frameSize Amount of input samples.
* \param fGlobalIndependencyFlag Global independency flag of current frame.
*
* \return Error code.
*/
int mpegSurroundDecoder_Parse(CMpegSurroundDecoder *pMpegSurroundDecoder,
HANDLE_FDK_BITSTREAM hBs, int *pMpsDataBits,
AUDIO_OBJECT_TYPE coreCodec, int sampleRate,
int frameSize, int fGlobalIndependencyFlag);
/* #endif */
/**
* \brief Apply MPEG Surround upmix.
*
* Process one downmix audio frame and decode one surround frame if it applies.
* Downmix framing can be different from surround framing, so depending on the
* frame size of the downmix audio data and the framing being used by the MPEG
* Surround decoder, it could be that only every second call, for example, of
* this function actually surround data was decoded. The returned value of
* frameSize will be zero, if no surround data was decoded.
*
* Decoding one MPEG Surround frame. Depending on interface configuration
* mpegSurroundDecoder_SetParam(self, SACDEC_INTERFACE, value), the QMF or time
* interface will be applied. External access to QMF buffer interface can be
* achieved by mpegSurroundDecoder_GetQmfBuffer() call before decode frame.
* While using time interface, pTimeData buffer will be shared as input and
* output buffer.
*
* \param pMpegSurroundDecoder A MPEG Surrround decoder handle.
* \param pTimeData Pointer to time buffer. Depending on interface
* configuration, the content of pTimeData is ignored, and the internal QMF
* buffer will be used as input data source.
* Otherwise, the MPEG Surround processing is applied to the timesignal
* pTimeData. For both variants, the resulting MPEG
* Surround signal is written into pTimeData.
* \param timeDataSize Size of pTimeData (available buffer size).
* \param timeDataFrameSize Frame size of input timedata
* \param nChannels Pointer where the amount of input channels is
* given and amount of output channels is returned.
* \param frameSize Pointer where the amount of output samples is
* returned into.
* \param channelType Array were the corresponding channel type for
* each output audio channel is stored into.
* \param channelIndices Array were the corresponding channel type index
* for each output audio channel is stored into.
* \param mapDescr Channep map descriptor for output channel mapping
* to be used (From MPEG PCE ordering to whatever is required).
* \param inDataHeadroom Headroom of SAC input time signal to prevent
* clipping.
* \param outDataHeadroom Pointer to headroom of SAC output time signal to
* prevent clipping.
*
* \return Error code.
*/
int mpegSurroundDecoder_Apply(CMpegSurroundDecoder *pMpegSurroundDecoder,
PCM_MPS *input, PCM_MPS *pTimeData,
const int timeDataSize, int timeDataFrameSize,
int *nChannels, int *frameSize, int sampleRate,
AUDIO_OBJECT_TYPE coreCodec,
AUDIO_CHANNEL_TYPE channelType[],
UCHAR channelIndices[],
const FDK_channelMapDescr *const mapDescr,
const INT inDataHeadroom, INT *outDataHeadroom);
/**
* \brief Deallocate a MPEG Surround decoder instance.
* \param pMpegSurroundDecoder A decoder handle.
* \return No return value.
*/
void mpegSurroundDecoder_Close(CMpegSurroundDecoder *pMpegSurroundDecoder);
/**
* \brief Free config dependent MPEG Surround memory.
* \param pMpegSurroundDecoder A decoder handle.
* \return error.
*/
SACDEC_ERROR mpegSurroundDecoder_FreeMem(
CMpegSurroundDecoder *pMpegSurroundDecoder);
/**
* \brief Set one single MPEG Surround decoder parameter.
*
* \param pMpegSurroundDecoder A MPEG Surrround decoder handle. Must not be
* NULL pointer.
* \param param Parameter to be set. See SACDEC_PARAM.
* \param value Parameter value. See SACDEC_PARAM.
*
* \return 0 on sucess, and non-zero on failure.
*/
SACDEC_ERROR mpegSurroundDecoder_SetParam(
CMpegSurroundDecoder *pMpegSurroundDecoder, const SACDEC_PARAM param,
const INT value);
/**
* \brief Retrieve MPEG Surround decoder library info and fill info list with all depending library infos.
* \param libInfo Pointer to library info list to be filled.
* \return 0 on sucess, and non-zero on failure.
**/
int mpegSurroundDecoder_GetLibInfo(LIB_INFO *libInfo);
/**
* \brief Set one single MPEG Surround decoder parameter.
*
* \param pMpegSurroundDecoder A valid MPEG Surrround decoder handle.
*
* \return The additional signal delay caused by the module.
*/
UINT mpegSurroundDecoder_GetDelay(const CMpegSurroundDecoder *self);
/**
* \brief Get info on whether the USAC pseudo LR feature is active.
*
* \param pMpegSurroundDecoder A valid MPEG Surrround decoder handle.
* \param bsPseudoLr Pointer to return wether pseudo LR USAC feature
* is used.
*
* \return 0 on sucess, and non-zero on failure.
*/
SACDEC_ERROR mpegSurroundDecoder_IsPseudoLR(
CMpegSurroundDecoder *pMpegSurroundDecoder, int *bsPseudoLr);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* #ifndef SAC_DEC_LIB_H */
Reference in New Issue View Git Blame Copy Permalink