decoder excitation now in 16-bit precision (was 32), which saves quite a bit
[speexdsp.git] / libspeex / nb_celp.h
1 /* Copyright (C) 2002 Jean-Marc Valin */
2 /**
3     @file nb_celp.h
4     @brief Narrowband CELP encoder/decoder
5 */
6 /*
7    Redistribution and use in source and binary forms, with or without
8    modification, are permitted provided that the following conditions
9    are met:
10    
11    - Redistributions of source code must retain the above copyright
12    notice, this list of conditions and the following disclaimer.
13    
14    - Redistributions in binary form must reproduce the above copyright
15    notice, this list of conditions and the following disclaimer in the
16    documentation and/or other materials provided with the distribution.
17    
18    - Neither the name of the Xiph.org Foundation nor the names of its
19    contributors may be used to endorse or promote products derived from
20    this software without specific prior written permission.
21    
22    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
26    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
27    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
28    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
29    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
30    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
31    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
32    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33
34 */
35
36 #ifndef NB_CELP_H
37 #define NB_CELP_H
38
39 #include "modes.h"
40 #include <speex/speex_bits.h>
41 #include <speex/speex_callbacks.h>
42 #include "vbr.h"
43 #include "filters.h"
44
45 #ifdef VORBIS_PSYCHO
46 #include "vorbis_psy.h"
47 #endif
48
49 /**Structure representing the full state of the narrowband encoder*/
50 typedef struct EncState {
51    const SpeexMode *mode;       /**< Mode corresponding to the state */
52    int    first;          /**< Is this the first frame? */
53    int    frameSize;      /**< Size of frames */
54    int    subframeSize;   /**< Size of sub-frames */
55    int    nbSubframes;    /**< Number of sub-frames */
56    int    windowSize;     /**< Analysis (LPC) window length */
57    int    lpcSize;        /**< LPC order */
58    int    min_pitch;      /**< Minimum pitch value allowed */
59    int    max_pitch;      /**< Maximum pitch value allowed */
60
61    int    safe_pitch;     /**< Don't use too large values for pitch (in case we lose a packet) */
62    int    bounded_pitch;  /**< Next frame should not rely on previous frames for pitch */
63    int    ol_pitch;       /**< Open-loop pitch */
64    int    ol_voiced;      /**< Open-loop voiced/non-voiced decision */
65    int   *pitch;
66
67 #ifdef EPIC_48K
68    int    lbr_48k;
69 #endif
70
71 #ifdef VORBIS_PSYCHO
72    VorbisPsy *psy;
73    float *psy_window;
74    float *curve;
75    float *old_curve;
76 #endif
77
78    spx_word16_t  gamma1;         /**< Perceptual filter: A(z/gamma1) */
79    spx_word16_t  gamma2;         /**< Perceptual filter: A(z/gamma2) */
80    float  lag_factor;     /**< Lag windowing Gaussian width */
81    spx_word16_t  lpc_floor;      /**< Noise floor multiplier for A[0] in LPC analysis*/
82    char  *stack;          /**< Pseudo-stack allocation for temporary memory */
83    spx_word16_t *winBuf;          /**< Input buffer (original signal) */
84    spx_sig_t *excBuf;         /**< Excitation buffer */
85    spx_sig_t *exc;            /**< Start of excitation frame */
86    spx_word16_t *swBuf;          /**< Weighted signal buffer */
87    spx_word16_t *sw;             /**< Start of weighted signal frame */
88    const spx_word16_t *window;         /**< Temporary (Hanning) window */
89    spx_word16_t *autocorr;       /**< auto-correlation */
90    spx_word16_t *lagWindow;      /**< Window applied to auto-correlation */
91    spx_coef_t *lpc;            /**< LPCs for current frame */
92    spx_lsp_t *lsp;            /**< LSPs for current frame */
93    spx_lsp_t *qlsp;           /**< Quantized LSPs for current frame */
94    spx_lsp_t *old_lsp;        /**< LSPs for previous frame */
95    spx_lsp_t *old_qlsp;       /**< Quantized LSPs for previous frame */
96    spx_lsp_t *interp_lsp;     /**< Interpolated LSPs */
97    spx_lsp_t *interp_qlsp;    /**< Interpolated quantized LSPs */
98    spx_coef_t *interp_lpc;     /**< Interpolated LPCs */
99    spx_coef_t *interp_qlpc;    /**< Interpolated quantized LPCs */
100    spx_coef_t *bw_lpc1;        /**< LPCs after bandwidth expansion by gamma1 for perceptual weighting*/
101    spx_coef_t *bw_lpc2;        /**< LPCs after bandwidth expansion by gamma2 for perceptual weighting*/
102    spx_mem_t *mem_sp;         /**< Filter memory for signal synthesis */
103    spx_mem_t *mem_sw;         /**< Filter memory for perceptually-weighted signal */
104    spx_mem_t *mem_sw_whole;   /**< Filter memory for perceptually-weighted signal (whole frame)*/
105    spx_mem_t *mem_exc;        /**< Filter memory for excitation (whole frame) */
106    spx_mem_t *mem_exc2;        /**< Filter memory for excitation (whole frame) */
107    spx_word32_t *pi_gain;        /**< Gain of LPC filter at theta=pi (fe/2) */
108    spx_sig_t *innov_save;      /** If non-NULL, innovation is copied here */
109          
110    VBRState *vbr;         /**< State of the VBR data */
111    float  vbr_quality;    /**< Quality setting for VBR encoding */
112    float  relative_quality; /**< Relative quality that will be needed by VBR */
113    int    vbr_enabled;    /**< 1 for enabling VBR, 0 otherwise */
114    int    vad_enabled;    /**< 1 for enabling VAD, 0 otherwise */
115    int    dtx_enabled;    /**< 1 for enabling DTX, 0 otherwise */
116    int    dtx_count;      /**< Number of consecutive DTX frames */
117    int    abr_enabled;    /**< ABR setting (in bps), 0 if off */
118    float  abr_drift;
119    float  abr_drift2;
120    float  abr_count;
121    int    complexity;     /**< Complexity setting (0-10 from least complex to most complex) */
122    int    sampling_rate;
123    int    plc_tuning;
124    int    encode_submode;
125    const SpeexSubmode * const *submodes; /**< Sub-mode data */
126    int    submodeID;      /**< Activated sub-mode */
127    int    submodeSelect;  /**< Mode chosen by the user (may differ from submodeID if VAD is on) */
128 } EncState;
129
130 /**Structure representing the full state of the narrowband decoder*/
131 typedef struct DecState {
132    const SpeexMode *mode;       /**< Mode corresponding to the state */
133    int    first;          /**< Is this the first frame? */
134    int    count_lost;     /**< Was the last frame lost? */
135    int    frameSize;      /**< Size of frames */
136    int    subframeSize;   /**< Size of sub-frames */
137    int    nbSubframes;    /**< Number of sub-frames */
138    int    lpcSize;        /**< LPC order */
139    int    min_pitch;      /**< Minimum pitch value allowed */
140    int    max_pitch;      /**< Maximum pitch value allowed */
141    int    sampling_rate;
142
143 #ifdef EPIC_48K
144    int    lbr_48k;
145 #endif
146
147    spx_word16_t  last_ol_gain;   /**< Open-loop gain for previous frame */
148
149    char  *stack;          /**< Pseudo-stack allocation for temporary memory */
150    spx_word16_t *excBuf;         /**< Excitation buffer */
151    spx_word16_t *exc;            /**< Start of excitation frame */
152    spx_lsp_t *qlsp;           /**< Quantized LSPs for current frame */
153    spx_lsp_t *old_qlsp;       /**< Quantized LSPs for previous frame */
154    spx_coef_t *interp_qlpc;    /**< Interpolated quantized LPCs */
155    spx_mem_t *mem_sp;         /**< Filter memory for synthesis signal */
156    spx_word32_t *pi_gain;        /**< Gain of LPC filter at theta=pi (fe/2) */
157    spx_sig_t *innov_save;      /** If non-NULL, innovation is copied here */
158    
159    /* This is used in packet loss concealment */
160    int    last_pitch;     /**< Pitch of last correctly decoded frame */
161    spx_word16_t  last_pitch_gain; /**< Pitch gain of last correctly decoded frame */
162    spx_word16_t  pitch_gain_buf[3];  /**< Pitch gain of last decoded frames */
163    int    pitch_gain_buf_idx; /**< Tail of the buffer */
164    spx_int32_t seed;          /** Seed used for random number generation */
165    
166    int    encode_submode;
167    const SpeexSubmode * const *submodes; /**< Sub-mode data */
168    int    submodeID;      /**< Activated sub-mode */
169    int    lpc_enh_enabled; /**< 1 when LPC enhancer is on, 0 otherwise */
170 #ifdef OLD_ENHANCER
171    CombFilterMem *comb_mem;
172 #endif
173    SpeexCallback speex_callbacks[SPEEX_MAX_CALLBACKS];
174
175    SpeexCallback user_callback;
176
177    /*Vocoder data*/
178    spx_word16_t  voc_m1;
179    spx_word32_t  voc_m2;
180    float  voc_mean;
181    int    voc_offset;
182
183    int    dtx_enabled;
184 } DecState;
185
186 /** Initializes encoder state*/
187 void *nb_encoder_init(const SpeexMode *m);
188
189 /** De-allocates encoder state resources*/
190 void nb_encoder_destroy(void *state);
191
192 /** Encodes one frame*/
193 int nb_encode(void *state, void *in, SpeexBits *bits);
194
195
196 /** Initializes decoder state*/
197 void *nb_decoder_init(const SpeexMode *m);
198
199 /** De-allocates decoder state resources*/
200 void nb_decoder_destroy(void *state);
201
202 /** Decodes one frame*/
203 int nb_decode(void *state, SpeexBits *bits, void *out);
204
205 /** ioctl-like function for controlling a narrowband encoder */
206 int nb_encoder_ctl(void *state, int request, void *ptr);
207
208 /** ioctl-like function for controlling a narrowband decoder */
209 int nb_decoder_ctl(void *state, int request, void *ptr);
210
211
212 #endif