cwrs.c links to derf's article on pulse vector encoding.
[opus.git] / libcelt / modes.c
1 /* (C) 2007 Jean-Marc Valin, CSIRO
2 */
3 /*
4    Redistribution and use in source and binary forms, with or without
5    modification, are permitted provided that the following conditions
6    are met:
7    
8    - Redistributions of source code must retain the above copyright
9    notice, this list of conditions and the following disclaimer.
10    
11    - Redistributions in binary form must reproduce the above copyright
12    notice, this list of conditions and the following disclaimer in the
13    documentation and/or other materials provided with the distribution.
14    
15    - Neither the name of the Xiph.org Foundation nor the names of its
16    contributors may be used to endorse or promote products derived from
17    this software without specific prior written permission.
18    
19    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
23    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 */
31
32 #include "celt.h"
33 #include "modes.h"
34 #include "os_support.h"
35
36 int celt_mode_info(const CELTMode *mode, int request, celt_int32_t *value)
37 {
38    switch (request)
39    {
40       case CELT_GET_FRAME_SIZE:
41          *value = mode->mdctSize;
42          break;
43       case CELT_GET_LOOKAHEAD:
44          *value = mode->overlap;
45          break;
46       case CELT_GET_NB_CHANNELS:
47          *value = mode->nbChannels;
48          break;
49       default:
50          return CELT_BAD_ARG;
51    }
52    return CELT_OK;
53 }
54
55 #define PBANDS 8
56 #define MIN_BINS 4
57 /* Defining 25 critical bands for the full 0-20 kHz audio bandwidth
58    Taken from http://ccrma.stanford.edu/~jos/bbt/Bark_Frequency_Scale.html */
59 #define BARK_BANDS 25
60 const celt_int16_t bark_freq[BARK_BANDS+1] = {
61       0,   100,   200,   300,   400,
62     510,   630,   770,   920,  1080,
63    1270,  1480,  1720,  2000,  2320,
64    2700,  3150,  3700,  4400,  5300,
65    6400,  7700,  9500, 12000, 15500,
66   20000};
67
68 const celt_int16_t pitch_freq[PBANDS+1] ={0, 345, 689, 1034, 1378, 2067, 3273, 5340, 6374};
69
70 /* This allocation table is per critical band. When creating a mode, the bits get added together 
71    into the codec bands, which are sometimes larger than one critical band at low frequency */
72 #define BITALLOC_SIZE 10
73 int band_allocation[BARK_BANDS*BITALLOC_SIZE] = 
74    {  2,  2,  1,  1,  2,  2,  1,  1,  1,  1,  1,  1,  1,  1,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,
75       2,  2,  2,  1,  2,  2,  2,  2,  2,  1,  2,  2,  3,  3,  3,  3,  3,  3,  3,  0,  0,  0,  0,  0,  0,
76       2,  2,  2,  2,  3,  2,  2,  2,  2,  2,  3,  2,  4,  4,  4,  4,  4,  4,  4,  4,  0,  0,  0,  0,  0,
77       3,  2,  2,  2,  3,  3,  2,  3,  2,  2,  4,  3,  5,  5,  5,  5,  5,  5,  5,  5,  5,  5,  0,  0,  0,
78       3,  3,  2,  2,  3,  3,  3,  3,  3,  2,  4,  4,  7,  7,  5,  5,  5,  5,  5,  5,  5,  5,  5,  0,  0,
79       3,  3,  2,  2,  3,  3,  3,  3,  3,  3,  4,  4,  8,  8,  8,  8,  8,  8,  9, 10, 11, 10, 10,  5,  5,
80       4,  4,  4,  4,  5,  5,  5,  5,  5,  4,  7,  7, 14, 13, 13, 13, 13, 13, 15, 16, 17, 18, 20, 18, 11,
81       7,  7,  6,  6,  9,  8,  8,  8,  8,  8, 11, 11, 20, 18, 19, 19, 25, 22, 25, 30, 30, 35, 35, 35, 35,
82       8,  8,  8,  8, 10, 10, 10, 10,  9,  9, 19, 18, 25, 24, 23, 21, 29, 27, 35, 40, 42, 50, 59, 54, 51,
83      11, 11, 10, 10, 14, 13, 13, 13, 13, 12, 19, 18, 35, 34, 33, 31, 39, 37, 45, 50, 52, 60, 60, 60, 60,
84    };
85
86
87 static int *compute_ebands(int Fs, int frame_size, int *nbEBands)
88 {
89    int *eBands;
90    int i, res, min_width, lin, low, high;
91    res = (Fs+frame_size)/(2*frame_size);
92    min_width = MIN_BINS*res;
93    //printf ("min_width = %d\n", min_width);
94
95    /* Find where the linear part ends (i.e. where the spacing is more than min_width */
96    for (lin=0;lin<BARK_BANDS;lin++)
97       if (bark_freq[lin+1]-bark_freq[lin] >= min_width)
98          break;
99    
100    //printf ("lin = %d (%d Hz)\n", lin, bark_freq[lin]);
101    low = ((bark_freq[lin]/res)+(MIN_BINS-1))/MIN_BINS;
102    high = BARK_BANDS-lin;
103    *nbEBands = low+high;
104    eBands = celt_alloc(sizeof(int)*(*nbEBands+2));
105    
106    /* Linear spacing (min_width) */
107    for (i=0;i<low;i++)
108       eBands[i] = MIN_BINS*i;
109    /* Spacing follows critical bands */
110    for (i=0;i<high;i++)
111       eBands[i+low] = (bark_freq[lin+i]+res/2)/res;
112    /* Enforce the minimum spacing at the boundary */
113    for (i=0;i<*nbEBands;i++)
114       if (eBands[i] < MIN_BINS*i)
115          eBands[i] = MIN_BINS*i;
116    eBands[*nbEBands] = (bark_freq[BARK_BANDS]+res/2)/res;
117    eBands[*nbEBands+1] = frame_size;
118    if (eBands[*nbEBands] > eBands[*nbEBands+1])
119       eBands[*nbEBands] = eBands[*nbEBands+1];
120    
121    /* FIXME: Remove last band if too small */
122    /*for (i=0;i<*nbEBands+2;i++)
123       printf("%d ", eBands[i]);
124    printf ("\n");*/
125    return eBands;
126 }
127
128 static void compute_pbands(CELTMode *mode, int res)
129 {
130    int i;
131    int *pBands;
132    pBands=celt_alloc(sizeof(int)*(PBANDS+2));
133    mode->nbPBands = PBANDS;
134    for (i=0;i<PBANDS+1;i++)
135    {
136       pBands[i] = (pitch_freq[i]+res/2)/res;
137       if (pBands[i] < mode->eBands[i])
138          pBands[i] = mode->eBands[i];
139    }
140    pBands[PBANDS+1] = mode->eBands[mode->nbEBands+1];
141    for (i=1;i<mode->nbPBands+1;i++)
142    {
143       int j;
144       for (j=0;j<mode->nbEBands;j++)
145          if (mode->eBands[j] <= pBands[i] && mode->eBands[j+1] > pBands[i])
146             break;
147       //printf ("%d %d\n", i, j);
148       if (mode->eBands[j] != pBands[i])
149       {
150          if (pBands[i]-mode->eBands[j] < mode->eBands[j+1]-pBands[i] && 
151              mode->eBands[j] != pBands[i-1])
152             pBands[i] = mode->eBands[j];
153          else
154             pBands[i] = mode->eBands[j+1];
155       }
156    }
157    /*for (i=0;i<mode->nbPBands+2;i++)
158       printf("%d ", pBands[i]);
159    printf ("\n");*/
160    mode->pBands = pBands;
161    mode->pitchEnd = pBands[PBANDS];
162 }
163
164 static void compute_allocation_table(CELTMode *mode, int res)
165 {
166    int i, j, eband;
167    int *allocVectors;
168    
169    mode->nbAllocVectors = BITALLOC_SIZE;
170    allocVectors = celt_alloc(sizeof(int)*(BITALLOC_SIZE*mode->nbEBands));
171    for (i=0;i<BITALLOC_SIZE;i++)
172    {
173       eband = 0;
174       for (j=0;j<BARK_BANDS;j++)
175       {
176          int edge, low;
177          edge = mode->eBands[eband+1]*res;
178          if (edge < bark_freq[j+1])
179          {
180             int num, den;
181             num = band_allocation[i*BARK_BANDS+j] * (edge-bark_freq[j]);
182             den = bark_freq[j+1]-bark_freq[j];
183             //low = band_allocation[i*BARK_BANDS+j] * (edge-bark_freq[j])/(bark_freq[j+1]-bark_freq[j]);
184             low = (num+den/2)/den;
185             allocVectors[i*mode->nbEBands+eband] += low;
186             eband++;
187             allocVectors[i*mode->nbEBands+eband] += band_allocation[i*BARK_BANDS+j]-low;
188          } else {
189             allocVectors[i*mode->nbEBands+eband] += band_allocation[i*BARK_BANDS+j];
190          }
191       }
192    }
193    /*for (i=0;i<BITALLOC_SIZE;i++)
194    {
195       for (j=0;j<mode->nbEBands;j++)
196          printf ("%2d ", allocVectors[i*mode->nbEBands+j]);
197       printf ("\n");
198    }*/
199    mode->allocVectors = allocVectors;
200 }
201
202 CELTMode *celt_mode_create(int Fs, int channels, int frame_size, int lookahead, int *error)
203 {
204    int res;
205    CELTMode *mode;
206    
207    /* The good thing here is that permutation of the arguments will automatically be invalid */
208    
209    if (Fs < 32000 || Fs > 64000)
210    {
211       celt_warning("Sampling rate must be between 32 kHz and 64 kHz");
212       if (error)
213          *error = CELT_BAD_ARG;
214       return NULL;
215    }
216    if (channels < 0 || channels > 2)
217    {
218       celt_warning("Only mono and stereo supported");
219       if (error)
220          *error = CELT_BAD_ARG;
221       return NULL;
222    }
223    if (frame_size < 64 || frame_size > 256 || frame_size%2!=0)
224    {
225       celt_warning("Only even frame sizes between 64 and 256 are supported");
226       if (error)
227          *error = CELT_BAD_ARG;
228       return NULL;
229    }
230    if (lookahead < 32 || lookahead > frame_size)
231    {
232       celt_warning("The overlap must be between 32 and the frame size");
233       if (error)
234          *error = CELT_BAD_ARG;
235       return NULL;
236    }
237    res = (Fs+frame_size)/(2*frame_size);
238    
239    mode = celt_alloc(sizeof(CELTMode));
240    mode->overlap = lookahead;
241    mode->mdctSize = frame_size;
242    mode->nbMdctBlocks = 1;
243    mode->nbChannels = channels;
244    mode->eBands = compute_ebands(Fs, frame_size, &mode->nbEBands);
245    compute_pbands(mode, res);
246    mode->ePredCoef = .8;
247    
248    compute_allocation_table(mode, res);
249    
250    //printf ("%d bands\n", mode->nbEBands);
251    return mode;
252 }
253
254 void celt_mode_destroy(CELTMode *mode)
255 {
256    celt_free((int*)mode->eBands);
257    celt_free((int*)mode->pBands);
258    celt_free((int*)mode->allocVectors);
259    celt_free((CELTMode *)mode);
260 }