opencore/codecs_v2/audio/gsm_amr/amr_nb/enc/include/gsmamr_encoder_wrapper.h

   1 /* ------------------------------------------------------------------
   2  * Copyright (C) 1998-2009 PacketVideo
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
  13  * express or implied.
  14  * See the License for the specific language governing permissions
  15  * and limitations under the License.
  16  * -------------------------------------------------------------------
  17  */
  18 /****************************************************************************************
  19 Portions of this file are derived from the following 3GPP standard:
  20
  21     3GPP TS 26.073
  22     ANSI-C code for the Adaptive Multi-Rate (AMR) speech codec
  23     Available from http://www.3gpp.org
  24
  25 (C) 2004, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TTA, TTC)
  26 Permission to distribute, modify and use this file under the standard license
  27 terms listed above has been obtained from the copyright holder.
  28 ****************************************************************************************/
  29 #ifndef __GSMAMR_ENCODER_WRAPPER_H__
  30 #define __GSMAMR_ENCODER_WRAPPER_H__
  31
  32 //----------------------------------------------------------------------------
  33 // INCLUDES
  34 //----------------------------------------------------------------------------
  35 #include "oscl_base.h"
  36
  37 class TInputAudioStream
  38 {
  39     public:
  40         // Pointer to buffer containing the audio samples.
  41         // The application is required to allocate this buffer.
  42         uint8* iSampleBuffer;
  43
  44         // Number of samples in bytes contained in iSampleBuffer
  45         int32 iSampleLength;
  46
  47         // Mode of operation (the same as bit rate)
  48         // For example, "GSM_AMR_4_75" (for 4.75 kbps) for GSM-AMR
  49         int32 iMode;
  50
  51         // Start time when samples were taken
  52         uint64 iStartTime;
  53
  54         // End time when samples were taken
  55         uint64 iStopTime;
  56 };
  57
  58
  59 class TOutputAudioStream
  60 {
  61     public:
  62         // Pointer to buffer containing encoded audio samples
  63         uint8* iBitStreamBuffer;
  64
  65         // Number of sample frames encoded and are contained in the buffer
  66         int32 iNumSampleFrames;
  67
  68         // Size in bytes of each encoded sample frame;
  69         // This variable may point to an array if the sample frame sizes are
  70         // variable. For example:
  71         //    iSampleFrameSize[0] = 23   (frame size of frame #1)
  72         //    iSampleFrameSize[1] = 12   (frame size of frame #2)
  73         //    . . .
  74         //    iSampleFrameSize[iNumSampleFrames] = 10 (frame size of last frame)
  75         int32* iSampleFrameSize;
  76
  77         // Start time of the encoded samples contained in the bit stream buffer
  78         uint32 iStartTime;
  79
  80         // Stop time of encoded samples contained in the bit stream buffer
  81         uint32 iStopTime;
  82 };
  83
  84 class TEncodeProperties
  85 {
  86     public:
  87         // /////////////////////////////////////////////
  88         // Input stream properties (uncompressed audio)
  89         // /////////////////////////////////////////////
  90
  91         enum EInterleaveMode
  92         {
  93             EINTERLEAVE_LR,        // interleaved left-right
  94             EGROUPED_LR,           // non-interleaved left-right
  95             ENUM_INTERLEAVE_MODES  // number of modes supported
  96         };
  97
  98         // DESCRIPTION: Number of bits per sample. For example, set it to "16"
  99         //              bits for PCM.
 100         // USAGE:       The authoring application is required to fill this in.
 101         //              The CAEI uses the value for encoding.
 102         int32 iInBitsPerSample;
 103
 104         // DESCRIPTION: Sampling rate of the input samples in Hz.
 105         //              For example, set it to "22050" Hz.
 106         // USAGE:       The authoring application is required to fill this in.
 107         //              If sampling rate is not known until CAEI is initialized,
 108         //              use '0'. The CAEI uses the value for encoding.
 109         uint32 iInSamplingRate;
 110
 111         // DESCRIPTION: Clock rate or time scale to be used for the input timestamps
 112         //              (ticks per secs). For example, "22050" ticks/sec.
 113         // USAGE:       The authoring application is required to fill this in.
 114         //              If sampling rate is not known until CAEI is initialized,
 115         //              use '0'. The CAEI uses the value for encoding.
 116         uint32 iInClockRate;
 117
 118         // DESCRIPTION: Number of input channels:1=Mono,2=Stereo.(Mono uses 1 channel;
 119         //              Stereo uses 2 channels).
 120         // USAGE:       The authoring application is required to fill this in.
 121         //              The CAEI uses the value for encoding.
 122         uint8 iInNumChannels;
 123
 124         // DESCRIPTION: Whether to interleave or not the multi-channel input samples:
 125         //              EINTERLEAVE_LR  = LRLRLRLRLR    (interleaved left-right)
 126         //              EGROUPED_LR = LLLLLL...RRRRRR   (non-interleaved left-right)
 127         // USAGE:       The authoring application is required to fill this in.
 128         //              The CAEI uses the value for encoding.
 129         EInterleaveMode iInInterleaveMode;
 130
 131         // DESCRIPTION: Desired Sampling rate for a given bitrate combination:
 132         //              For example, set it to "16000" Hz if the encoding 16kbps
 133         //              mono/stereo or 24 kbps stereo
 134         // USAGE:       The authoring application is required to fill this in.
 135         //              The CAEI uses the value for encoding.
 136         uint32 iDesiredSamplingRate;
 137
 138     public:
 139         // ////////////////////////////////////////////
 140         // Output stream properties (compressed audio)
 141         // ////////////////////////////////////////////
 142
 143         // DESCRIPTION: Mode of operation (the same as bit rate). For example,
 144         //              "GSM_AMR_4_75" (for 4.75 kbps).
 145         // USAGE:       The authoring application is required to fill this in.
 146         //              The CAEI uses the value to configure the codec library.
 147         int32 iMode;
 148
 149         // DESCRIPTION: Bit order format:
 150         //              TRUE  = MSB..................LSB
 151         //                       d7 d6 d5 d4 d3 d2 d1 d0
 152         //              FALSE = MSB..................LSB
 153         //                      d0 d1 d2 d3 d4 d5 d6 d7
 154         // USAGE:       The authoring application is required to fill this in.
 155         //              The CAEI will use the value to setup the codec library.
 156         int32 iBitStreamFormat;
 157
 158         // DESCRIPTION: Audio object type for the output bitstream; only applies
 159         //              to AAC codec
 160         // USAGE:       The application is required to fill this in.
 161         //              The CADI will use the value to setup the codec library.
 162         int32 iAudioObjectType;
 163
 164         // DESCRIPTION: Final sampling frequency used when encoding in Hz.
 165         //              For example, "44100" Hz.
 166         // USAGE:       If the input sampling rate is not appropriate (e.g.,
 167         //              the codec requires a different sampling frequency),
 168         //              the CAEI will fill this in with the final sampling
 169         //              rate. The CAEI will perform resampling if the
 170         //              input sampling frequency is not the same as the output
 171         //              sampling frequency.
 172         uint32 iOutSamplingRate;
 173
 174         // DESCRIPTION: Number of output channels:1=Mono,2=Stereo. (Mono uses 1
 175         //              channel; Stereo uses 2 channels).
 176         // USAGE:       The CAEI will fill this in if it needs to convert
 177         //              the input samples to what is required by the codec.
 178         uint8 iOutNumChannels;
 179
 180         // DESCRIPTION: Clock rate or time scale used for the timestamps (ticks per secs)
 181         //              For example, "8000" ticks/sec.
 182         // USAGE:       The CAEI will fill this in if the input data will be
 183         //              resampled.
 184         uint32 iOutClockRate;
 185 };
 186
 187
 188
 189 /**
 190 **   This class encodes audio samples using the GSM-AMR algorithm.
 191 **   This codec operates on a 20-msec frame duration corresponding to 160
 192 **   samples at the sampling frequency of 8000 samples/sec. The size of a frame
 193 **   is 320 bytes. For each 20-ms frame, a bit-rate of 4.75, 5.15, 5.90, 6.70,
 194 **   7.40, 7.95, 10.2, or 12.2 kbits/sec can be produced.
 195 **
 196 **   Sample usage:
 197 **   ------------
 198 **       // create a GSM-AMR encoder object
 199 **       CGsmAmrEncoder* myAppEncoder = OSCL_NEW(CGsmAmrEncoder, ());
 200 **       // set input parameters
 201 **       TEncodeProperties myProps;
 202 **       myProps.iInSamplingRate = 8000;
 203 **       myProps.iInBitsPerSample = 16;
 204 **       myProps.iOutBitRate = CGsmAmrEncoder::GSM_AMR_12_2;
 205 **       myAppEncoder->InitializeEncoder(myProps, 2000);
 206 **
 207 **       // encode a sample block
 208 **       myAppEncoder->Encode(myInput, myOutput);
 209 **
 210 //       // done encoding so cleanup
 211 **       myAppEncoder->CleanupEncoder();
 212 **       OSCL_DELETE(myAppEncoder);
 213 **
 214 */
 215
 216 class CPvGsmAmrEncoder
 217 {
 218     public:
 219         //! Constructor -- creates a GSM-AMR encoder object
 220         OSCL_IMPORT_REF CPvGsmAmrEncoder();
 221
 222         //! Destructor -- destroys the GSM-AMR encoder object
 223         OSCL_IMPORT_REF ~CPvGsmAmrEncoder();
 224
 225         /**
 226         *  This function initializes the GSM-AMR encoder.
 227         * @param "aMaxOutputBufferSize" "the maximum buffer size for the output buffer when Encode() gets called"
 228         * @param "aProps" "TEncodeProperties based pointer for the input encoding setting. if aProps=NULL, then
 229         *        default settings will be set"
 230         * @return 0 for the correct operation, and -1 for the wrong operation
 231         */
 232         OSCL_IMPORT_REF int32 InitializeEncoder(int32 aMaxOutputBufferSize,
 233                                                 TEncodeProperties* aProps = NULL);
 234
 235         /**
 236         *  This function initializes the GSM-AMR encoder.
 237         * @param "aInStream" "TInputAudioStream based reference object that contains the input buffer and buffer size and timestamp info"
 238         * @param "aOutStream" "TOutputAudioStream based reference object that contains the output buffer for compressed data
 239         * @return 0 for the correct operation, and -1 for the wrong operation
 240         */
 241         OSCL_IMPORT_REF int32 Encode(TInputAudioStream& aInStream,
 242                                      TOutputAudioStream& aOutStream);
 243
 244         /**
 245         *  This function cleans up the encoder workspace when done encoding.
 246         */
 247         OSCL_IMPORT_REF int32 CleanupEncoder();
 248
 249         /**
 250         *  This function reset the encoder workspace.
 251         */
 252         OSCL_IMPORT_REF int32 Reset();
 253
 254
 255     public:
 256         // GSM AMR modes
 257         // ** values should be the same as the Mode enum specified by AMR library
 258         enum GSM_AMR_MODES
 259         {
 260             GSM_AMR_4_75,
 261             GSM_AMR_5_15,
 262             GSM_AMR_5_90,
 263             GSM_AMR_6_70,
 264             GSM_AMR_7_40,
 265             GSM_AMR_7_95,
 266             GSM_AMR_10_2,
 267             GSM_AMR_12_2,
 268             GSM_AMR_DTX,
 269             GSM_AMR_N_MODES      /* number of (SPC) modes */
 270         };
 271
 272     private:
 273
 274         /**
 275         *  This inline function checks whether the specified mode is valid or not.
 276         * @param "aMode" "input the current mode to be used in encoding"
 277         * @return true for the valid mode, and false for the wrong mode
 278         */
 279         inline bool IsModeValid(int32 aMode)
 280         {
 281             return((aMode < GSM_AMR_N_MODES) && (aMode >= 0));
 282         }
 283
 284     private:
 285
 286         // GSM AMR encoder state variables
 287         void* iEncState;
 288         void* iSidState;
 289
 290         // contains the current mode of GSM AMR
 291         GSM_AMR_MODES iGsmAmrMode;
 292
 293         // last mode used
 294         int32 iLastModeUsed;
 295
 296         // number of samples per frame (granulity)
 297         int32 iNumSamplesPerFrame;
 298         // number of bytes per sample
 299         int32 iBytesPerSample;
 300
 301         // maximum size allowed for output buffer
 302         int32 iMaxOutputBufferSize;
 303
 304         // bit stream format
 305         int32 iBitStreamFormat;
 306
 307 };
 308
 309 typedef enum
 310 {
 311     GSMAMR_ENC_NO_ERROR                 = 0,
 312     GSMAMR_ENC_NO_MEMORY_ERROR          = -1,
 313     GSMAMR_ENC_CODEC_INIT_FAILURE       = -2,
 314     GSMAMR_ENC_CODEC_NOT_INITIALIZED    = -3,
 315     GSMAMR_ENC_INVALID_PARAM            = -4,
 316     GSMAMR_ENC_INVALID_MODE             = -5,
 317     GSMAMR_ENC_CODEC_ENCODE_FAILURE     = -6,
 318     GSMAMR_ENC_MEMORY_OVERFLOW          = -7
 319 } GSMAMR_ENC_STATUS;
 320
 321 #endif  // __GSMAMR_ENCODER_WRAPPER_H__
 322
 323