Fixed a bunch of typos pointed to by: larry@doolittle.boa.org
[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_bits.h"
41 #include "speex_callbacks.h"
42 #include "vbr.h"
43 #include "filters.h"
44
45 /**Structure representing the full state of the narrowband encoder*/
46 typedef struct EncState {
47    SpeexMode *mode;       /**< Mode corresponding to the state */
48    int    first;          /**< Is this the first frame? */
49    int    frameSize;      /**< Size of frames */
50    int    subframeSize;   /**< Size of sub-frames */
51    int    nbSubframes;    /**< Number of sub-frames */
52    int    windowSize;     /**< Analysis (LPC) window length */
53    int    lpcSize;        /**< LPC order */
54    int    bufSize;        /**< Buffer size */
55    int    min_pitch;      /**< Minimum pitch value allowed */
56    int    max_pitch;      /**< Maximum pitch value allowed */
57
58    int    safe_pitch;     /**< Don't use too large values for pitch (in case we lose a packet) */
59    int    bounded_pitch;  /**< Next frame should not rely on previous frames for pitch */
60    int    ol_pitch;       /**< Open-loop pitch */
61    int    ol_voiced;      /**< Open-loop voiced/non-voiced decision */
62    int   *pitch;
63    float  gamma1;         /**< Perceptual filter: A(z/gamma1) */
64    float  gamma2;         /**< Perceptual filter: A(z/gamma2) */
65    float  lag_factor;     /**< Lag windowing Gaussian width */
66    float  lpc_floor;      /**< Noise floor multiplier for A[0] in LPC analysis*/
67    float  preemph;        /**< Pre-emphasis: P(z) = 1 - a*z^-1*/
68    float  pre_mem;        /**< 1-element memory for pre-emphasis */
69    float  pre_mem2;       /**< 1-element memory for pre-emphasis */
70    char  *stack;          /**< Pseudo-stack allocation for temporary memory */
71    float *inBuf;          /**< Input buffer (original signal) */
72    float *frame;          /**< Start of original frame */
73    float *excBuf;         /**< Excitation buffer */
74    float *exc;            /**< Start of excitation frame */
75    float *exc2Buf;        /**< "Pitch enhanced" excitation */
76    float *exc2;           /**< "Pitch enhanced" excitation */
77    float *swBuf;          /**< Weighted signal buffer */
78    float *sw;             /**< Start of weighted signal frame */
79    float *innov;          /**< Innovation for the frame */
80    float *window;         /**< Temporary (Hanning) window */
81    float *buf2;           /**< 2nd temporary buffer */
82    float *autocorr;       /**< auto-correlation */
83    float *lagWindow;      /**< Window applied to auto-correlation */
84    float *lpc;            /**< LPCs for current frame */
85    float *lsp;            /**< LSPs for current frame */
86    float *qlsp;           /**< Quantized LSPs for current frame */
87    float *old_lsp;        /**< LSPs for previous frame */
88    float *old_qlsp;       /**< Quantized LSPs for previous frame */
89    float *interp_lsp;     /**< Interpolated LSPs */
90    float *interp_qlsp;    /**< Interpolated quantized LSPs */
91    float *interp_lpc;     /**< Interpolated LPCs */
92    float *interp_qlpc;    /**< Interpolated quantized LPCs */
93    float *bw_lpc1;        /**< LPCs after bandwidth expansion by gamma1 for perceptual weighting*/
94    float *bw_lpc2;        /**< LPCs after bandwidth expansion by gamma2 for perceptual weighting*/
95    float *rc;             /**< Reflection coefficients */
96    float *mem_sp;         /**< Filter memory for signal synthesis */
97    float *mem_sw;         /**< Filter memory for perceptually-weighted signal */
98    float *mem_sw_whole;   /**< Filter memory for perceptually-weighted signal (whole frame)*/
99    float *mem_exc;        /**< Filter memory for excitation (whole frame) */
100    float *pi_gain;        /**< Gain of LPC filter at theta=pi (fe/2) */
101
102    VBRState *vbr;         /**< State of the VBR data */
103    float  vbr_quality;    /**< Quality setting for VBR encoding */
104    float  relative_quality; /**< Relative quality that will be needed by VBR */
105    int    vbr_enabled;    /**< 1 for enabling VBR, 0 otherwise */
106    int    vad_enabled;    /**< 1 for enabling VAD, 0 otherwise */
107    int    dtx_enabled;    /**< 1 for enabling DTX, 0 otherwise */
108    int    dtx_count;      /**< Number of consecutive DTX frames */
109    int    abr_enabled;    /**< ABR setting (in bps), 0 if off */
110    float  abr_drift;
111    float  abr_drift2;
112    float  abr_count;
113    int    complexity;     /**< Complexity setting (0-10 from least complex to most complex) */
114    int    sampling_rate;
115
116    SpeexSubmode **submodes; /**< Sub-mode data */
117    int    submodeID;      /**< Activated sub-mode */
118    int    submodeSelect;  /**< Mode chosen by the user (may differ from submodeID if VAD is on) */
119 } EncState;
120
121 /**Structure representing the full state of the narrowband decoder*/
122 typedef struct DecState {
123    SpeexMode *mode;       /**< Mode corresponding to the state */
124    int    first;          /**< Is this the first frame? */
125    int    count_lost;     /**< Was the last frame lost? */
126    int    frameSize;      /**< Size of frames */
127    int    subframeSize;   /**< Size of sub-frames */
128    int    nbSubframes;    /**< Number of sub-frames */
129    int    windowSize;     /**< Analysis (LPC) window length */
130    int    lpcSize;        /**< LPC order */
131    int    bufSize;        /**< Buffer size */
132    int    min_pitch;      /**< Minimum pitch value allowed */
133    int    max_pitch;      /**< Maximum pitch value allowed */
134    int    sampling_rate;
135    float  last_ol_gain;   /**< Open-loop gain for previous frame */
136
137
138    float  gamma1;         /**< Perceptual filter: A(z/gamma1) */
139    float  gamma2;         /**< Perceptual filter: A(z/gamma2) */
140    float  preemph;        /**< Pre-emphasis: P(z) = 1 - a*z^-1*/
141    float  pre_mem;        /**< 1-element memory for pre-emphasis */
142    char  *stack;          /**< Pseudo-stack allocation for temporary memory */
143    float *inBuf;          /**< Input buffer (original signal) */
144    float *frame;          /**< Start of original frame */
145    float *excBuf;         /**< Excitation buffer */
146    float *exc;            /**< Start of excitation frame */
147    float *innov;          /**< Innovation for the frame */
148    float *qlsp;           /**< Quantized LSPs for current frame */
149    float *old_qlsp;       /**< Quantized LSPs for previous frame */
150    float *interp_qlsp;    /**< Interpolated quantized LSPs */
151    float *interp_qlpc;    /**< Interpolated quantized LPCs */
152    float *mem_sp;         /**< Filter memory for synthesis signal */
153    float *pi_gain;        /**< Gain of LPC filter at theta=pi (fe/2) */
154    int    last_pitch;     /**< Pitch of last correctly decoded frame */
155    float  last_pitch_gain; /**< Pitch gain of last correctly decoded frame */
156    float  pitch_gain_buf[3];  /**< Pitch gain of last decoded frames */
157    int    pitch_gain_buf_idx; /**< Tail of the buffer */
158
159    SpeexSubmode **submodes; /**< Sub-mode data */
160    int    submodeID;      /**< Activated sub-mode */
161    int    lpc_enh_enabled; /**< 1 when LPC enhancer is on, 0 otherwise */
162    CombFilterMem *comb_mem;
163    SpeexCallback speex_callbacks[SPEEX_MAX_CALLBACKS];
164
165    SpeexCallback user_callback;
166
167    /*Vocoder data*/
168    float  voc_m1;
169    float  voc_m2;
170    float  voc_mean;
171    int    voc_offset;
172
173    int    dtx_enabled;
174 } DecState;
175
176 /** Initializes encoder state*/
177 void *nb_encoder_init(SpeexMode *m);
178
179 /** De-allocates encoder state resources*/
180 void nb_encoder_destroy(void *state);
181
182 /** Encodes one frame*/
183 int nb_encode(void *state, float *in, SpeexBits *bits);
184
185
186 /** Initializes decoder state*/
187 void *nb_decoder_init(SpeexMode *m);
188
189 /** De-allocates decoder state resources*/
190 void nb_decoder_destroy(void *state);
191
192 /** Decodes one frame*/
193 int nb_decode(void *state, SpeexBits *bits, float *out);
194
195 /** ioctl-like function for controlling a narrowband encoder */
196 int nb_encoder_ctl(void *state, int request, void *ptr);
197
198 /** ioctl-like function for controlling a narrowband decoder */
199 int nb_decoder_ctl(void *state, int request, void *ptr);
200
201
202 #endif