modes.h

00001 /* Copyright (C) 2002-2006 Jean-Marc Valin */
00002 /**
00003    @file modes.h
00004    @brief Describes the different modes of the codec
00005 */
00006 /*
00007    Redistribution and use in source and binary forms, with or without
00008    modification, are permitted provided that the following conditions
00009    are met:
00010    
00011    - Redistributions of source code must retain the above copyright
00012    notice, this list of conditions and the following disclaimer.
00013    
00014    - Redistributions in binary form must reproduce the above copyright
00015    notice, this list of conditions and the following disclaimer in the
00016    documentation and/or other materials provided with the distribution.
00017    
00018    - Neither the name of the Xiph.org Foundation nor the names of its
00019    contributors may be used to endorse or promote products derived from
00020    this software without specific prior written permission.
00021    
00022    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00023    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00024    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00025    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
00026    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00027    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00028    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00029    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00030    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00031    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00032    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00033 
00034 */
00035 
00036 #ifndef MODES_H
00037 #define MODES_H
00038 
00039 #include <speex/speex.h>
00040 #include <speex/speex_bits.h>
00041 #include "misc.h"
00042 
00043 #define NB_SUBMODES 16
00044 #define NB_SUBMODE_BITS 4
00045 
00046 #define SB_SUBMODES 8
00047 #define SB_SUBMODE_BITS 3
00048 
00049 /* Used internally, NOT TO BE USED in applications */
00050 /** Used internally*/
00051 #define SPEEX_GET_PI_GAIN 100
00052 /** Used internally*/
00053 #define SPEEX_GET_EXC     101
00054 /** Used internally*/
00055 #define SPEEX_GET_INNOV   102
00056 /** Used internally*/
00057 #define SPEEX_GET_DTX_STATUS   103
00058 /** Used internally*/
00059 #define SPEEX_SET_INNOVATION_SAVE   104
00060 /** Used internally*/
00061 #define SPEEX_SET_WIDEBAND   105
00062 
00063 /** Used internally*/
00064 #define SPEEX_GET_STACK   106
00065 
00066 
00067 /** Quantizes LSPs */
00068 typedef void (*lsp_quant_func)(spx_lsp_t *, spx_lsp_t *, int, SpeexBits *);
00069 
00070 /** Decodes quantized LSPs */
00071 typedef void (*lsp_unquant_func)(spx_lsp_t *, int, SpeexBits *);
00072 
00073 
00074 /** Long-term predictor quantization */
00075 typedef int (*ltp_quant_func)(spx_word16_t *, spx_word16_t *, spx_coef_t *, spx_coef_t *, 
00076                               spx_coef_t *, spx_sig_t *, const void *, int, int, spx_word16_t, 
00077                               int, int, SpeexBits*, char *, spx_word16_t *, spx_word16_t *, int, int, int, spx_word32_t *);
00078 
00079 /** Long-term un-quantize */
00080 typedef void (*ltp_unquant_func)(spx_word16_t *, spx_word32_t *, int, int, spx_word16_t, const void *, int, int *,
00081                                  spx_word16_t *, SpeexBits*, char*, int, int, spx_word16_t, int);
00082 
00083 
00084 /** Innovation quantization function */
00085 typedef void (*innovation_quant_func)(spx_word16_t *, spx_coef_t *, spx_coef_t *, spx_coef_t *, const void *, int, int, 
00086                                       spx_sig_t *, spx_word16_t *, SpeexBits *, char *, int, int);
00087 
00088 /** Innovation unquantization function */
00089 typedef void (*innovation_unquant_func)(spx_sig_t *, const void *, int, SpeexBits*, char *, spx_int32_t *);
00090 
00091 /** Description of a Speex sub-mode (wither narrowband or wideband */
00092 typedef struct SpeexSubmode {
00093    int     lbr_pitch;          /**< Set to -1 for "normal" modes, otherwise encode pitch using a global pitch and allowing a +- lbr_pitch variation (for low not-rates)*/
00094    int     forced_pitch_gain;  /**< Use the same (forced) pitch gain for all sub-frames */
00095    int     have_subframe_gain; /**< Number of bits to use as sub-frame innovation gain */
00096    int     double_codebook;    /**< Apply innovation quantization twice for higher quality (and higher bit-rate)*/
00097    /*LSP functions*/
00098    lsp_quant_func    lsp_quant; /**< LSP quantization function */
00099    lsp_unquant_func  lsp_unquant; /**< LSP unquantization function */
00100 
00101    /*Lont-term predictor functions*/
00102    ltp_quant_func    ltp_quant; /**< Long-term predictor (pitch) quantizer */
00103    ltp_unquant_func  ltp_unquant; /**< Long-term predictor (pitch) un-quantizer */
00104    const void       *ltp_params; /**< Pitch parameters (options) */
00105 
00106    /*Quantization of innovation*/
00107    innovation_quant_func innovation_quant; /**< Innovation quantization */
00108    innovation_unquant_func innovation_unquant; /**< Innovation un-quantization */
00109    const void             *innovation_params; /**< Innovation quantization parameters*/
00110 
00111    spx_word16_t      comb_gain;  /**< Gain of enhancer comb filter */
00112 
00113    int               bits_per_frame; /**< Number of bits per frame after encoding*/
00114 } SpeexSubmode;
00115 
00116 /** Struct defining the encoding/decoding mode*/
00117 typedef struct SpeexNBMode {
00118    int     frameSize;      /**< Size of frames used for encoding */
00119    int     subframeSize;   /**< Size of sub-frames used for encoding */
00120    int     lpcSize;        /**< Order of LPC filter */
00121    int     pitchStart;     /**< Smallest pitch value allowed */
00122    int     pitchEnd;       /**< Largest pitch value allowed */
00123 
00124    spx_word16_t gamma1;    /**< Perceptual filter parameter #1 */
00125    spx_word16_t gamma2;    /**< Perceptual filter parameter #2 */
00126    float   lag_factor;     /**< Lag-windowing parameter */
00127    spx_word16_t   lpc_floor;      /**< Noise floor for LPC analysis */
00128 
00129 #ifdef EPIC_48K
00130    int     lbr48k;         /**< 1 for the special 4.8 kbps mode */
00131 #endif
00132 
00133    const SpeexSubmode *submodes[NB_SUBMODES]; /**< Sub-mode data for the mode */
00134    int     defaultSubmode; /**< Default sub-mode to use when encoding */
00135    int     quality_map[11]; /**< Mode corresponding to each quality setting */
00136 } SpeexNBMode;
00137 
00138 
00139 /** Struct defining the encoding/decoding mode for SB-CELP (wideband) */
00140 typedef struct SpeexSBMode {
00141    const SpeexMode *nb_mode;    /**< Embedded narrowband mode */
00142    int     frameSize;     /**< Size of frames used for encoding */
00143    int     subframeSize;  /**< Size of sub-frames used for encoding */
00144    int     lpcSize;       /**< Order of LPC filter */
00145    int     bufSize;       /**< Signal buffer size in encoder */
00146    spx_word16_t gamma1;   /**< Perceptual filter parameter #1 */
00147    spx_word16_t gamma2;   /**< Perceptual filter parameter #1 */
00148    float   lag_factor;    /**< Lag-windowing parameter */
00149    spx_word16_t   lpc_floor;     /**< Noise floor for LPC analysis */
00150    spx_word16_t   folding_gain;
00151 
00152    const SpeexSubmode *submodes[SB_SUBMODES]; /**< Sub-mode data for the mode */
00153    int     defaultSubmode; /**< Default sub-mode to use when encoding */
00154    int     low_quality_map[11]; /**< Mode corresponding to each quality setting */
00155    int     quality_map[11]; /**< Mode corresponding to each quality setting */
00156    const float (*vbr_thresh)[11];
00157    int     nb_modes;
00158 } SpeexSBMode;
00159 
00160 int speex_encode_native(void *state, spx_word16_t *in, SpeexBits *bits);
00161 int speex_decode_native(void *state, SpeexBits *bits, spx_word16_t *out);
00162 
00163 int nb_mode_query(const void *mode, int request, void *ptr);
00164 int wb_mode_query(const void *mode, int request, void *ptr);
00165 
00166 #endif