More work on the CELT encoder description, fixed Opus figures
[opus.git] / doc / draft-ietf-codec-opus.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>
3 <?rfc toc="yes" symrefs="yes" ?>
4
5 <rfc ipr="trust200902" category="std" docName="draft-ietf-codec-opus-08">
6
7 <front>
8 <title abbrev="Interactive Audio Codec">Definition of the Opus Audio Codec</title>
9
10
11 <author initials="JM" surname="Valin" fullname="Jean-Marc Valin">
12 <organization>Octasic Inc.</organization>
13 <address>
14 <postal>
15 <street>4101, Molson Street</street>
16 <city>Montreal</city>
17 <region>Quebec</region>
18 <code></code>
19 <country>Canada</country>
20 </postal>
21 <phone>+1 514 282-8858</phone>
22 <email>jmvalin@jmvalin.ca</email>
23 </address>
24 </author>
25
26 <author initials="K." surname="Vos" fullname="Koen Vos">
27 <organization>Skype Technologies S.A.</organization>
28 <address>
29 <postal>
30 <street>Stadsgarden 6</street>
31 <city>Stockholm</city>
32 <region></region>
33 <code>11645</code>
34 <country>SE</country>
35 </postal>
36 <phone>+46 855 921 989</phone>
37 <email>koen.vos@skype.net</email>
38 </address>
39 </author>
40
41 <author initials="T." surname="Terriberry" fullname="Timothy Terriberry">
42 <organization>Mozilla Corporation</organization>
43 <address>
44 <postal>
45 <street>650 Castro Street</street>
46 <city>Mountain View</city>
47 <region>CA</region>
48 <code>94041</code>
49 <country>USA</country>
50 </postal>
51 <phone>+1 650 903-0800</phone>
52 <email>tterriberry@mozilla.com</email>
53 </address>
54 </author>
55
56 <date day="16" month="August" year="2011" />
57
58 <area>General</area>
59
60 <workgroup></workgroup>
61
62 <abstract>
63 <t>
64 This document defines the Opus codec, designed for interactive speech and audio
65  transmission over the Internet.
66 </t>
67 </abstract>
68 </front>
69
70 <middle>
71
72 <section anchor="introduction" title="Introduction">
73 <t>
74 The Opus codec is a real-time interactive audio codec composed of a linear
75  prediction (LP)-based layer and a Modified Discrete Cosine Transform
76  (MDCT)-based layer.
77 The main idea behind using two layers is that in speech, linear prediction
78  techniques (such as CELP) code low frequencies more efficiently than transform
79  (e.g., MDCT) domain techniques, while the situation is reversed for music and
80  higher speech frequencies.
81 Thus a codec with both layers available can operate over a wider range than
82  either one alone and, by combining them, achieve better quality than either
83  one individually.
84 </t>
85
86 <t>
87 The primary normative part of this specification is provided by the source code
88  in <xref target="ref-implementation"></xref>.
89 In general, only the decoder portion of this software is normative, though a
90  significant amount of code is shared by both the encoder and decoder.
91 <!--TODO: Forward reference conformance test-->
92 The decoder contains significant amounts of integer and fixed-point arithmetic
93  which must be performed exactly, including all rounding considerations, so any
94  useful specification must make extensive use of domain-specific symbolic
95  language to adequately define these operations.
96 Additionally, any
97 conflict between the symbolic representation and the included reference
98 implementation must be resolved. For the practical reasons of compatibility and
99 testability it would be advantageous to give the reference implementation
100 priority in any disagreement. The C language is also one of the most
101 widely understood human-readable symbolic representations for machine
102 behavior.
103 For these reasons this RFC uses the reference implementation as the sole
104  symbolic representation of the codec.
105 </t>
106
107 <!--TODO: C is not unambiguous; many parts are implementation-defined-->
108 <t>While the symbolic representation is unambiguous and complete it is not
109 always the easiest way to understand the codec's operation. For this reason
110 this document also describes significant parts of the codec in English and
111 takes the opportunity to explain the rationale behind many of the more
112 surprising elements of the design. These descriptions are intended to be
113 accurate and informative, but the limitations of common English sometimes
114 result in ambiguity, so it is expected that the reader will always read
115 them alongside the symbolic representation. Numerous references to the
116 implementation are provided for this purpose. The descriptions sometimes
117 differ from the reference in ordering or through mathematical simplification
118 wherever such deviation makes an explanation easier to understand.
119 For example, the right shift and left shift operations in the reference
120 implementation are often described using division and multiplication in the text.
121 In general, the text is focused on the "what" and "why" while the symbolic
122 representation most clearly provides the "how".
123 </t>
124
125 <section anchor="notation" title="Notation and Conventions">
126 <t>
127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
128  "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
129  interpreted as described in RFC 2119.
130 </t>
131 <t>
132 Even when using floating-point, various operations in the codec require
133  bit-exact fixed-point behavior.
134 The notation "Q&lt;n&gt;", where n is an integer, denotes the number of binary
135  digits to the right of the decimal point in a fixed-point number.
136 For example, a signed Q14 value in a 16-bit word can represent values from
137  -2.0 to 1.99993896484375, inclusive.
138 This notation is for informational purposes only.
139 Arithmetic, when described, always operates on the underlying integer.
140 E.g., the text will explicitly indicate any shifts required after a
141  multiplication.
142 </t>
143 <t>
144 Expressions, where included in the text, follow C operator rules and
145  precedence, with the exception that syntax like "2**n" is used to indicate 2
146  raised to the power n.
147 The text also makes use of the following functions:
148 </t>
149
150 <section anchor="min" title="min(x,y)">
151 <t>
152 The smallest of two values x and y.
153 </t>
154 </section>
155
156 <section anchor="max" title="max(x,y)">
157 <t>
158 The largest of two values x and y.
159 </t>
160 </section>
161
162 <section anchor="clamp" title="clamp(lo,x,hi)">
163 <figure align="center">
164 <artwork align="center"><![CDATA[
165 clamp(lo,x,hi) = max(lo,min(x,hi))
166 ]]></artwork>
167 </figure>
168 <t>
169 With this definition, if lo&gt;hi, the lower bound is the one that is enforced.
170 </t>
171 </section>
172
173 <section anchor="sign" title="sign(x)">
174 <t>
175 The sign of x, i.e.,
176 <figure align="center">
177 <artwork align="center"><![CDATA[
178           ( -1,  x < 0 ,
179 sign(x) = <  0,  x == 0 ,
180           (  1,  x > 0 .
181 ]]></artwork>
182 </figure>
183 </t>
184 </section>
185
186 <section anchor="log2" title="log2(f)">
187 <t>
188 The base-two logarithm of f.
189 </t>
190 </section>
191
192 <section anchor="ilog" title="ilog(n)">
193 <t>
194 The minimum number of bits required to store a positive integer n in two's
195  complement notation, or 0 for a non-positive integer n.
196 <figure align="center">
197 <artwork align="center"><![CDATA[
198           ( 0,                 n <= 0,
199 ilog(n) = <
200           ( floor(log2(n))+1,  n > 0
201 ]]></artwork>
202 </figure>
203 Examples:
204 <list style="symbols">
205 <t>ilog(-1) = 0</t>
206 <t>ilog(0) = 0</t>
207 <t>ilog(1) = 1</t>
208 <t>ilog(2) = 2</t>
209 <t>ilog(3) = 2</t>
210 <t>ilog(4) = 3</t>
211 <t>ilog(7) = 3</t>
212 </list>
213 </t>
214 </section>
215
216 </section>
217
218 </section>
219
220 <section anchor="overview" title="Opus Codec Overview">
221
222 <t>
223 The Opus codec scales from 6&nbsp;kb/s narrowband mono speech to 510&nbsp;kb/s
224  fullband stereo music, with algorithmic delays ranging from 5&nbsp;ms to
225  65.2&nbsp;ms.
226 At any given time, either the LP layer, the MDCT layer, or both, may be active.
227 It can seamlessly switch between all of its various operating modes, giving it
228  a great deal of flexibility to adapt to varying content and network
229  conditions without renegotiating the current session.
230 Internally, the codec always operates at a 48&nbsp;kHz sampling rate, though it
231  allows input and output of various bandwidths, defined as follows:
232 </t>
233 <texttable>
234 <ttcol>Abbreviation</ttcol>
235 <ttcol align="right">Audio Bandwidth</ttcol>
236 <ttcol align="right">Sampling Rate (Effective)</ttcol>
237 <c>NB (narrowband)</c>       <c>4&nbsp;kHz</c>  <c>8&nbsp;kHz</c>
238 <c>MB (medium-band)</c>      <c>6&nbsp;kHz</c> <c>12&nbsp;kHz</c>
239 <c>WB (wideband)</c>         <c>8&nbsp;kHz</c> <c>16&nbsp;kHz</c>
240 <c>SWB (super-wideband)</c> <c>12&nbsp;kHz</c> <c>24&nbsp;kHz</c>
241 <c>FB (fullband)</c>        <c>20&nbsp;kHz</c> <c>48&nbsp;kHz</c>
242 </texttable>
243 <t>
244 These can be chosen independently on the encoder and decoder side, e.g., a
245  fullband signal can be decoded as wideband, or vice versa.
246 This approach ensures a sender and receiver can always interoperate, regardless
247  of the capabilities of their actual audio hardware.
248 </t>
249
250 <t>
251 Opus defines super-wideband (SWB) mode to have an effective sampling rate of
252  24&nbsp;kHz, unlike some other audio coding standards that use 32&nbsp;kHz.
253 This was chosen for a number of reasons.
254 The band layout in the MDCT layer naturally allows skipping coefficients for
255  frequencies over 12&nbsp;kHz, but does not allow cleanly dropping frequencies
256  over 16&nbsp;kHz.
257 The choice of 24&nbsp;kHz also makes resampling in the MDCT layer easier, as 24
258  evenly divides 48, and when 24&nbsp;kHz is sufficient, it can save computation
259  in other processing, such as Acoustic Echo Cancellation (AEC).
260 Experimental changes to the band layout to allow a 16&nbsp;kHz cutoff showed
261  potential quality degredations, and at typical bitrates the number of bits
262  saved by using such a cutoff instead of coding in fullband (FB) mode is very
263  small.
264 Therefore, if an application wishes to process a signal sampled at 32&nbsp;kHz,
265  it should just use FB mode.
266 </t>
267
268 <t>
269 The LP layer is based on the
270  <eref target='http://developer.skype.com/silk'>SILK</eref> codec
271  <xref target="SILK"></xref>.
272 It supports NB, MB, or WB audio and frame sizes from 10&nbsp;ms to 60&nbsp;ms,
273  and requires an additional 5.2&nbsp;ms look-ahead for noise shaping estimation
274  (5&nbsp;ms) and internal resampling (0.2&nbsp;ms).
275 Like Vorbis and many other modern codecs, SILK is inherently designed for
276  variable-bitrate (VBR) coding, though an encoder can with sufficient effort
277  produce constant-bitrate (CBR) or near-CBR streams.
278 </t>
279
280 <t>
281 The MDCT layer is based on the
282  <eref target='http://www.celt-codec.org/'>CELT</eref>  codec
283  <xref target="CELT"></xref>.
284 It supports sampling NB, WB, SWB, or FB audio and frame sizes from 2.5&nbsp;ms
285  to 20&nbsp;ms, and requires an additional 2.5&nbsp;ms look-ahead due to the
286  overlapping MDCT windows.
287 The CELT codec is inherently designed for CBR coding, but unlike many CBR
288  codecs it is not limited to a set of predetermined rates.
289 It internally allocates bits to exactly fill any given target budget, and an
290  encoder can produce a VBR stream by varying the target on a per-frame basis.
291 The MDCT layer is not used for speech when the audio bandwidth is WB or less,
292  as it is not useful there.
293 On the other hand, non-speech signals are not always adequately coded using
294  linear prediction, so for music only the MDCT layer should be used.
295 </t>
296
297 <t>
298 A hybrid mode allows the use of both layers simultaneously with a frame size of
299  10 or 20&nbsp;ms and a SWB or FB audio bandwidth.
300 Each frame is split into a low frequency signal and a high frequency signal,
301  with a cutoff of 8&nbsp;kHz.
302 The LP layer then codes the low frequency signal, followed by the MDCT layer
303  coding the high frequency signal.
304 In the MDCT layer, all bands below 8&nbsp;kHz are discarded, so there is no
305  coding redundancy between the two layers.
306 </t>
307
308 <t>
309 At the decoder, the two decoder outputs are simply added together.
310 To compensate for the different look-aheads required by each layer, the CELT
311  encoder input is delayed by an additional 2.7&nbsp;ms.
312 This ensures that low frequencies and high frequencies arrive at the same time.
313 This extra delay MAY be reduced by an encoder by using less look-ahead for noise
314  shaping or using a simpler resampler in the LP layer, but this will reduce
315  quality.
316 However, the base 2.5&nbsp;ms look-ahead in the CELT layer cannot be reduced in
317  the encoder because it is needed for the MDCT overlap, whose size is fixed by
318  the decoder.
319 </t>
320
321 <t>
322 Both layers use the same entropy coder, avoiding any waste from "padding bits"
323  between them.
324 The hybrid approach makes it easy to support both CBR and VBR coding.
325 Although the LP layer is VBR, the bit allocation of the MDCT layer can produce
326  a final stream that is CBR by using all the bits left unused by the LP layer.
327 </t>
328
329 </section>
330
331 <section anchor="modes" title="Codec Modes">
332 <t>
333 As described, the two layers can be combined in three possible operating modes:
334 <list style="numbers">
335 <t>A LP-only mode for use in low bitrate connections with an audio bandwidth of
336  WB or less,</t>
337 <t>A hybrid (LP+MDCT) mode for SWB or FB speech at medium bitrates, and</t>
338 <t>An MDCT-only mode for very low delay speech transmission as well as music
339  transmission.</t>
340 </list>
341 </t>
342 <t>
343 A single packet may contain multiple audio frames.
344 However, they must share a common set of parameters, including the operating
345  mode, audio bandwidth, frame size, and channel count.
346 This section describes the possible combinations of these parameters and the
347  internal framing used to pack multiple frames into a single packet.
348 This framing is not self-delimiting.
349 Instead, it assumes that a higher layer (such as UDP or RTP or Ogg or Matroska)
350  will communicate the length, in bytes, of the packet, and it uses this
351  information to reduce the framing overhead in the packet itself.
352 A decoder implementation MUST support the framing described in this section.
353 An alternative, self-delimiting variant of the framing is described in
354  <xref target="self-delimiting-framing"/>.
355 Support for that variant is OPTIONAL.
356 </t>
357
358 <section anchor="toc_byte" title="The TOC Byte">
359 <t>
360 An Opus packet begins with a single-byte table-of-contents (TOC) header that
361  signals which of the various modes and configurations a given packet uses.
362 It is composed of a frame count code, "c", a stereo flag, "s", and a
363  configuration number, "config", arranged as illustrated in
364  <xref target="toc_byte_fig"/>.
365 A description of each of these fields follows.
366 </t>
367
368 <figure anchor="toc_byte_fig" title="The TOC byte">
369 <artwork align="center"><![CDATA[
370  0
371  0 1 2 3 4 5 6 7
372 +-+-+-+-+-+-+-+-+
373 | c |s| config  |
374 +-+-+-+-+-+-+-+-+
375 ]]></artwork>
376 </figure>
377
378 <t>
379 The top five bits of the TOC byte, labeled "config", encode one of 32 possible
380  configurations of operating mode, audio bandwidth, and frame size.
381 <xref target="config_bits"/> lists the parameters for each configuration.
382 </t>
383 <texttable anchor="config_bits" title="TOC Byte Configuration Parameters">
384 <ttcol>Configuration Number(s)</ttcol>
385 <ttcol>Mode</ttcol>
386 <ttcol>Bandwidth</ttcol>
387 <ttcol>Frame Size(s)</ttcol>
388 <c>0...3</c>   <c>LP-only</c>   <c>NB</c>  <c>10, 20, 40, 60&nbsp;ms</c>
389 <c>4...7</c>   <c>LP-only</c>   <c>MB</c>  <c>10, 20, 40, 60&nbsp;ms</c>
390 <c>8...11</c>  <c>LP-only</c>   <c>WB</c>  <c>10, 20, 40, 60&nbsp;ms</c>
391 <c>12...13</c> <c>Hybrid</c>    <c>SWB</c> <c>10, 20&nbsp;ms</c>
392 <c>14...15</c> <c>Hybrid</c>    <c>FB</c>  <c>10, 20&nbsp;ms</c>
393 <c>16...19</c> <c>MDCT-only</c> <c>NB</c>  <c>2.5, 5, 10, 20&nbsp;ms</c>
394 <c>20...23</c> <c>MDCT-only</c> <c>WB</c>  <c>2.5, 5, 10, 20&nbsp;ms</c>
395 <c>24...27</c> <c>MDCT-only</c> <c>SWB</c> <c>2.5, 5, 10, 20&nbsp;ms</c>
396 <c>28...31</c> <c>MDCT-only</c> <c>FB</c>  <c>2.5, 5, 10, 20&nbsp;ms</c>
397 </texttable>
398
399 <t>
400 One additional bit, labeled "s", is used to signal mono vs. stereo, with 0
401  indicating mono and 1 indicating stereo.
402 </t>
403
404 <t>
405 The remaining two bits of the TOC byte, labeled "c", code the number of frames
406  per packet (codes 0 to 3) as follows:
407 <list style="symbols">
408 <t>0:    1 frame in the packet</t>
409 <t>1:    2 frames in the packet, each with equal compressed size</t>
410 <t>2:    2 frames in the packet, with different compressed sizes</t>
411 <t>3:    an arbitrary number of frames in the packet</t>
412 </list>
413 This draft refers to a packet as a code 0 packet, code 1 packet, etc., based on
414  the value of "c".
415 </t>
416
417 <t>
418 A well-formed Opus packet MUST contain at least one byte with the TOC
419  information, though the frame(s) within a packet MAY be zero bytes long.
420 </t>
421 </section>
422
423 <section title="Frame Packing">
424
425 <t>
426 This section describes how frames are packed according to each possible value
427  of "c" in the TOC byte.
428 </t>
429
430 <section anchor="frame-length-coding" title="Frame Length Coding">
431 <t>
432 When a packet contains multiple VBR frames, the compressed length of one or
433  more of these frames is indicated with a one or two byte sequence, with the
434  meaning of the first byte as follows:
435 <list style="symbols">
436 <t>0:          No frame (discontinuous transmission (DTX) or lost packet)</t>
437 <!--TODO: Would be nice to be clearer about the distinction between "frame
438  size" (in samples or ms) and "the compressed size of the frame" (in bytes).
439 "the compressed length of the frame" is maybe a little better, but not when we
440  jump back and forth to talking about sizes.-->
441 <t>1...251:    Size of the frame in bytes</t>
442 <t>252...255:  A second byte is needed. The total size is (size[1]*4)+size[0]</t>
443 </list>
444 </t>
445
446 <t>
447 The maximum representable size is 255*4+255=1275&nbsp;bytes. This limit MUST NOT
448 be exceeded, even when no length field is used.
449 For 20&nbsp;ms frames, this represents a bitrate of 510&nbsp;kb/s, which is
450  approximately the highest useful rate for lossily compressed fullband stereo
451  music.
452 Beyond this point, lossless codecs are more appropriate.
453 It is also roughly the maximum useful rate of the MDCT layer, as shortly
454  thereafter quality no longer improves with additional bits due to limitations
455  on the codebook sizes.
456 </t>
457
458 <t>
459 No length is transmitted for the last frame in a VBR packet, or for any of the
460  frames in a CBR packet, as it can be inferred from the total size of the
461  packet and the size of all other data in the packet.
462 However, the length of any individual frame MUST NOT exceed 1275&nbsp;bytes, to
463  allow for repacketization by gateways, conference bridges, or other software.
464 </t>
465 </section>
466
467 <section title="One Frame in the Packet (Code&nbsp;0)">
468
469 <t>
470 For code&nbsp;0 packets, the TOC byte is immediately followed by N-1&nbsp;bytes
471  of compressed data for a single frame (where N is the size of the packet),
472  as illustrated in <xref target="code0_packet"/>.
473 </t>
474 <figure anchor="code0_packet" title="A Code 0 Packet" align="center">
475 <artwork align="center"><![CDATA[
476  0                   1                   2                   3
477  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
478 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
479 |0|0|s| config  |                                               |
480 +-+-+-+-+-+-+-+-+                                               |
481 |                    Compressed frame 1 (N-1 bytes)...          :
482 :                                                               |
483 |                                                               |
484 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
485 ]]></artwork>
486 </figure>
487 </section>
488
489 <section title="Two Frames in the Packet, Each with Equal Compressed Size (Code&nbsp;1)">
490 <t>
491 For code 1 packets, the TOC byte is immediately followed by the
492  (N-1)/2&nbsp;bytes of compressed data for the first frame, followed by
493  (N-1)/2&nbsp;bytes of compressed data for the second frame, as illustrated in
494  <xref target="code1_packet"/>.
495 The number of payload bytes available for compressed data, N-1, MUST be even
496  for all code 1 packets.
497 </t>
498 <figure anchor="code1_packet" title="A Code 1 Packet" align="center">
499 <artwork align="center"><![CDATA[
500  0                   1                   2                   3
501  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
502 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
503 |1|0|s| config  |                                               |
504 +-+-+-+-+-+-+-+-+                                               :
505 |             Compressed frame 1 ((N-1)/2 bytes)...             |
506 :                               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
507 |                               |                               |
508 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               :
509 |             Compressed frame 2 ((N-1)/2 bytes)...             |
510 :                                               +-+-+-+-+-+-+-+-+
511 |                                               |
512 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
513 ]]></artwork>
514 </figure>
515 </section>
516
517 <section title="Two Frames in the Packet, with Different Compressed Sizes (Code&nbsp;2)">
518 <t>
519 For code 2 packets, the TOC byte is followed by a one or two byte sequence
520  indicating the length of the first frame (marked N1 in the figure below),
521  followed by N1 bytes of compressed data for the first frame.
522 The remaining N-N1-2 or N-N1-3&nbsp;bytes are the compressed data for the
523  second frame.
524 This is illustrated in <xref target="code2_packet"/>.
525 The length of the first frame, N1, MUST be no larger than the size of the
526  payload remaining after decoding that length for all code 2 packets.
527 </t>
528 <figure anchor="code2_packet" title="A Code 2 Packet" align="center">
529 <artwork align="center"><![CDATA[
530  0                   1                   2                   3
531  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
532 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
533 |0|1|s| config  | N1 (1-2 bytes):                               |
534 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               :
535 |               Compressed frame 1 (N1 bytes)...                |
536 :                               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
537 |                               |                               |
538 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               |
539 |                     Compressed frame 2...                     :
540 :                                                               |
541 |                                                               |
542 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
543 ]]></artwork>
544 </figure>
545 </section>
546
547 <section title="An Arbitrary Number of Frames in the Packet (Code&nbsp;3)">
548 <t>
549 Code 3 packets may encode an arbitrary number of frames, as well as additional
550  padding, called "Opus padding" to indicate that this padding is added at the
551  Opus layer, rather than at the transport layer.
552 For code 3 packets, the TOC byte is followed by a byte encoding the number of
553  frames in the packet in bits 0 to 5 (marked "M" in the figure below), with bit
554  6 indicating whether or not Opus padding is inserted (marked "p" in the figure
555  below), and bit 7 indicating VBR (marked "v" in the figure below).
556 M MUST NOT be zero, and the audio duration contained within a packet MUST NOT
557  exceed 120&nbsp;ms.
558 This limits the maximum frame count for any frame size to 48 (for 2.5&nbsp;ms
559  frames), with lower limits for longer frame sizes.
560 <xref target="frame_count_byte"/> illustrates the layout of the frame count
561  byte.
562 </t>
563 <figure anchor="frame_count_byte" title="The frame count byte">
564 <artwork align="center"><![CDATA[
565  0
566  0 1 2 3 4 5 6 7
567 +-+-+-+-+-+-+-+-+
568 |     M     |p|v|
569 +-+-+-+-+-+-+-+-+
570 ]]></artwork>
571 </figure>
572 <t>
573 When Opus padding is used, the number of bytes of padding is encoded in the
574  bytes following the frame count byte.
575 Values from 0...254 indicate that 0...254&nbsp;bytes of padding are included,
576  in addition to the byte(s) used to indicate the size of the padding.
577 If the value is 255, then the size of the additional padding is 254&nbsp;bytes,
578  plus the padding value encoded in the next byte.
579 The additional padding bytes appear at the end of the packet, and SHOULD be set
580  to zero by the encoder.
581 The decoder MUST accept any value for the padding bytes, however.
582 By using code 255 multiple times, it is possible to create a packet of any
583  specific, desired size.
584 Let P be the total amount of padding, including both the trailing padding bytes
585  themselves and the header bytes used to indicate how many there are.
586 Then P MUST be no more than N-2 for CBR packets, or N-M-1 for VBR packets.
587 </t>
588 <t>
589 In the CBR case, the compressed length of each frame in bytes is equal to the
590  number of remaining bytes in the packet after subtracting the (optional)
591  padding, (N-2-P), divided by M.
592 This number MUST be an integer multiple of M.
593 The compressed data for all M frames then follows, each of size
594  (N-2-P)/M&nbsp;bytes, as illustrated in <xref target="code3cbr_packet"/>.
595 </t>
596
597 <figure anchor="code3cbr_packet" title="A CBR Code 3 Packet" align="center">
598 <artwork align="center"><![CDATA[
599  0                   1                   2                   3
600  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
601 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
602 |1|1|s| config  |     M     |p|0|  Padding length (Optional)    :
603 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
604 |                                                               |
605 :            Compressed frame 1 ((N-2-P)/M bytes)...            :
606 |                                                               |
607 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
608 |                                                               |
609 :            Compressed frame 2 ((N-2-P)/M bytes)...            :
610 |                                                               |
611 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
612 |                                                               |
613 :                              ...                              :
614 |                                                               |
615 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
616 |                                                               |
617 :            Compressed frame M ((N-2-P)/M bytes)...            :
618 |                                                               |
619 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
620 :                  Opus Padding (Optional)...                   |
621 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
622 ]]></artwork>
623 </figure>
624
625 <t>
626 In the VBR case, the (optional) padding length is followed by M-1 frame
627  lengths (indicated by "N1" to "N[M-1]" in the figure below), each encoded in a
628  one or two byte sequence as described above.
629 The packet MUST contain enough data for the M-1 lengths after the (optional)
630  padding, and the sum of these lengths MUST be no larger than the number of
631  bytes remaining in the packet after decoding them.
632 The compressed data for all M frames follows, each frame consisting of the
633  indicated number of bytes, with the final frame consuming any remaining bytes
634  before the final padding, as illustrated in <xref target="code3cbr_packet"/>.
635 The number of header bytes (TOC byte, frame count byte, padding length bytes,
636  and frame length bytes), plus the length of the first M-1 frames themselves,
637  plus the length of the padding MUST be no larger than N, the total size of the
638  packet.
639 </t>
640
641 <figure anchor="code3vbr_packet" title="A VBR Code 3 Packet" align="center">
642 <artwork align="center"><![CDATA[
643  0                   1                   2                   3
644  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
645 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
646 |1|1|s| config  |     M     |p|1| Padding length (Optional)     :
647 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
648 : N1 (1-2 bytes): N2 (1-2 bytes):     ...       :     N[M-1]    |
649 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
650 |                                                               |
651 :               Compressed frame 1 (N1 bytes)...                :
652 |                                                               |
653 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
654 |                                                               |
655 :               Compressed frame 2 (N2 bytes)...                :
656 |                                                               |
657 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
658 |                                                               |
659 :                              ...                              :
660 |                                                               |
661 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
662 |                                                               |
663 :                     Compressed frame M...                     :
664 |                                                               |
665 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
666 :                  Opus Padding (Optional)...                   |
667 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
668 ]]></artwork>
669 </figure>
670 </section>
671 </section>
672
673 <section anchor="examples" title="Examples">
674 <t>
675 Simplest case, one NB mono 20&nbsp;ms SILK frame:
676 </t>
677
678 <figure>
679 <artwork><![CDATA[
680  0                   1                   2                   3
681  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
682 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
683 |0|0|0|    1    |               compressed data...              :
684 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
685 ]]></artwork>
686 </figure>
687
688 <t>
689 Two FB mono 5&nbsp;ms CELT frames of the same compressed size:
690 </t>
691
692 <figure>
693 <artwork><![CDATA[
694  0                   1                   2                   3
695  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
696 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
697 |1|0|0|   29    |               compressed data...              :
698 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
699 ]]></artwork>
700 </figure>
701
702 <t>
703 Two FB mono 20&nbsp;ms hybrid frames of different compressed size:
704 </t>
705
706 <figure>
707 <artwork><![CDATA[
708  0                   1                   2                   3
709  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
710 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
711 |1|1|0|   15    |     2     |0|1|      N1       |               |
712 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               |
713 |                       compressed data...                      :
714 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
715 ]]></artwork>
716 </figure>
717
718 <t>
719 Four FB stereo 20&nbsp;ms CELT frames of the same compressed size:
720 </t>
721
722 <figure>
723 <artwork><![CDATA[
724  0                   1                   2                   3
725  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
726 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
727 |1|1|1|   31    |     4     |0|0|      compressed data...       :
728 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
729 ]]></artwork>
730 </figure>
731 </section>
732
733 <section title="Extending Opus">
734 <t>
735 A receiver MUST NOT process packets which violate the rules above as normal
736  Opus packets.
737 They are reserved for future applications, such as in-band headers (containing
738  metadata, etc.) or multichannel support.
739 </t>
740 </section>
741
742 </section>
743
744 <section title="Opus Decoder">
745 <t>
746 The Opus decoder consists of two main blocks: the SILK decoder and the CELT decoder.
747 The output of the Opus decode is the sum of the outputs from the SILK and CELT decoders
748 with proper sample rate conversion and delay compensation as illustrated in the
749 block diagram below. At any given time, one or both of the SILK and CELT decoders
750 may be active.
751 </t>
752 <figure>
753 <artwork>
754 <![CDATA[
755                        +-------+    +----------+
756                        | SILK  |    |  sample  |
757                     +->|decoder|--->|   rate   |----+
758 bit-    +-------+   |  |       |    |conversion|    v
759 stream  | Range |---+  +-------+    +----------+  /---\  audio
760 ------->|decoder|                                 | + |------>
761         |       |---+  +-------+                  \---/
762         +-------+   |  | CELT  |                    ^
763                     +->|decoder|--------------------+
764                        |       |
765                        +-------+
766 ]]>
767 </artwork>
768 </figure>
769
770 <section anchor="range-decoder" title="Range Decoder">
771 <t>
772 Opus uses an entropy coder based on <xref target="range-coding"></xref>,
773 which is itself a rediscovery of the FIFO arithmetic code introduced by <xref target="coding-thesis"></xref>.
774 It is very similar to arithmetic encoding, except that encoding is done with
775 digits in any base instead of with bits,
776 so it is faster when using larger bases (i.e., an octet). All of the
777 calculations in the range coder must use bit-exact integer arithmetic.
778 </t>
779 <t>
780 Symbols may also be coded as "raw bits" packed directly into the bitstream,
781  bypassing the range coder.
782 These are packed backwards starting at the end of the frame, as illustrated in
783  <xref target="rawbits-example"/>.
784 This reduces complexity and makes the stream more resilient to bit errors, as
785  corruption in the raw bits will not desynchronize the decoding process, unlike
786  corruption in the input to the range decoder.
787 Raw bits are only used in the CELT layer.
788 </t>
789
790 <figure anchor="rawbits-example" title="Illustrative example of packing range
791  coder and raw bits data">
792 <artwork align="center"><![CDATA[
793  0               1               2               3
794  7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
795 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
796 | Range coder data (packed MSb to LSb) ->                       :
797 +                                                               +
798 :                                                               :
799 +     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
800 :     | <- Boundary occurs at an arbitrary bit position         :
801 +-+-+-+                                                         +
802 :                          <- Raw bits data (packed LSb to MSb) |
803 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
804 ]]></artwork>
805 </figure>
806
807 <t>
808 Each symbol coded by the range coder is drawn from a finite alphabet and coded
809  in a separate "context", which describes the size of the alphabet and the
810  relative frequency of each symbol in that alphabet.
811 Opus only uses static contexts.
812 They are not adapted to the statistics of the data as it is coded.
813 </t>
814 <t>
815 Suppose there is a context with n symbols, identified with an index that ranges
816  from 0 to n-1.
817 The parameters needed to encode or decode a symbol in this context are
818  represented by a three-tuple (fl[k],&nbsp;fh[k],&nbsp;ft), with
819  0&nbsp;&lt;=&nbsp;fl[k]&nbsp;&lt;&nbsp;fh[k]&nbsp;&lt;=&nbsp;ft&nbsp;&lt;=&nbsp;65535.
820 The values of this tuple are derived from the probability model for the
821  symbol, represented by traditional "frequency counts" (although, since Opus
822  uses static contexts, these are not updated as symbols are decoded).
823 Let f[i] be the frequency of symbol i.
824 Then the three-tuple corresponding to symbol k is given by
825 </t>
826 <figure align="center">
827 <artwork align="center"><![CDATA[
828         k-1                                      n-1
829         __                                       __
830 fl[k] = \  f[i],  fh[k] = fl[k] + f[k],  ft[k] = \  f[i]
831         /_                                       /_
832         i=0                                      i=0
833 ]]></artwork>
834 </figure>
835 <t>
836 The range decoder extracts the symbols and integers encoded using the range
837  encoder in <xref target="range-encoder"/>.
838 The range decoder maintains an internal state vector composed of the two-tuple
839  (val,rng), representing the difference between the high end of the current
840  range and the actual coded value, minus one, and the size of the current
841  range, respectively.
842 Both val and rng are 32-bit unsigned integer values.
843 The decoder initializes rng to 128 and initializes val to 127 minus the top 7
844  bits of the first input octet.
845 The remaining bit is saved for use in the renormalization procedure described
846  in <xref target="range-decoder-renorm"/>, which the decoder invokes
847  immediately after initialization to read additional bits and establish the
848  invariant that rng&nbsp;&gt;&nbsp;2**23.
849 </t>
850
851 <section anchor="decoding-symbols" title="Decoding Symbols">
852 <t>
853 Decoding a symbol is a two-step process.
854 The first step determines a 16-bit unsigned value fs, which lies within the
855  range of some symbol in the current context.
856 The second step updates the range decoder state with the three-tuple
857  (fl[k],&nbsp;fh[k],&nbsp;ft) corresponding to that symbol.
858 </t>
859 <t>
860 The first step is implemented by ec_decode() (entdec.c), which computes
861 <figure align="center">
862 <artwork align="center"><![CDATA[
863 fs = ft - min(val/(rng/ft)+1, ft) .
864 ]]></artwork>
865 </figure>
866 The divisions here are exact integer division.
867 </t>
868 <t>
869 The decoder then identifies the symbol in the current context corresponding to
870  fs; i.e., the value of k whose three-tuple (fl[k],&nbsp;fh[k],&nbsp;ft)
871  satisfies fl[k]&nbsp;&lt;=&nbsp;fs&nbsp;&lt;&nbsp;fh[k].
872 It uses this tuple to update val according to
873 <figure align="center">
874 <artwork align="center"><![CDATA[
875 val = val - (rng/ft)*(ft-fh[k]) .
876 ]]></artwork>
877 </figure>
878 If fl[k] is greater than zero, then the decoder updates rng using
879 <figure align="center">
880 <artwork align="center"><![CDATA[
881 rng = (rng/ft)*(fh[k]-fl[k]) .
882 ]]></artwork>
883 </figure>
884 Otherwise, it updates rng using
885 <figure align="center">
886 <artwork align="center"><![CDATA[
887 rng = rng - (rng/ft)*(ft-fh[k]).
888 ]]></artwork>
889 </figure>
890 </t>
891 <t>
892 Using a special case for the first symbol (rather than the last symbol, as is
893  commonly done in other arithmetic coders) ensures that all the truncation
894  error from the finite precision arithmetic accumulates in symbol 0.
895 This makes the cost of coding a 0 slightly smaller, on average, than its
896  estimated probability indicates and makes the cost of coding any other symbol
897  slightly larger.
898 When contexts are designed so that 0 is the most probable symbol, which is
899  often the case, this strategy minimizes the inefficiency introduced by the
900  finite precision.
901 It also makes some of the special-case decoding routines in
902  <xref target="decoding-alternate"/> particularly simple.
903 </t>
904 <t>
905 After the updates, implemented by ec_dec_update() (entdec.c), the decoder
906  normalizes the range using the procedure in the next section, and returns the
907  index k.
908 </t>
909
910 <section anchor="range-decoder-renorm" title="Renormalization">
911 <t>
912 To normalize the range, the decoder repeats the following process, implemented
913  by ec_dec_normalize() (entdec.c), until rng&nbsp;&gt;&nbsp;2**23.
914 If rng is already greater than 2**23, the entire process is skipped.
915 First, it sets rng to (rng&lt;&lt;8).
916 Then it reads the next octet of the payload and combines it with the left-over
917  bit buffered from the previous octet to form the 8-bit value sym.
918 It takes the left-over bit as the high bit (bit 7) of sym, and the top 7 bits
919  of the octet it just read as the other 7 bits of sym.
920 The remaining bit in the octet just read is buffered for use in the next
921  iteration.
922 If no more input octets remain, it uses zero bits instead.
923 Then, it sets
924 <figure align="center">
925 <artwork align="center"><![CDATA[
926 val = ((val<<8) + (255-sym)) & 0x7FFFFFFF .
927 ]]></artwork>
928 </figure>
929 </t>
930 <t>
931 It is normal and expected that the range decoder will read several bytes
932  into the raw bits data (if any) at the end of the packet by the time the frame
933  is completely decoded, as illustrated in <xref target="finalize-example"/>.
934 This same data MUST also be returned as raw bits when requested.
935 The encoder is expected to terminate the stream in such a way that the decoder
936  will decode the intended values regardless of the data contained in the raw
937  bits.
938 <xref target="encoder-finalizing"/> describes a procedure for doing this.
939 If the range decoder consumes all of the bytes belonging to the current frame,
940  it MUST continue to use zero when any further input bytes are required, even
941  if there is additional data in the current packet from padding or other
942  frames.
943 </t>
944
945 <figure anchor="finalize-example" title="Illustrative example of raw bits
946  overlapping range coder data">
947 <artwork align="center"><![CDATA[
948  n               n+1             n+2             n+3
949  7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
950 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
951 :     | <----------- Overlap region ------------> |             :
952 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
953       ^                                           ^
954       |   End of data buffered by the range coder |
955 ...-----------------------------------------------+
956       |
957       | End of data consumed by raw bits
958       +-------------------------------------------------------...
959 ]]></artwork>
960 </figure>
961 </section>
962 </section>
963
964 <section anchor="decoding-alternate" title="Alternate Decoding Methods">
965 <t>
966 The reference implementation uses three additional decoding methods that are
967  exactly equivalent to the above, but make assumptions and simplifications that
968  allow for a more efficient implementation.
969 </t>
970 <section title="ec_decode_bin()">
971 <t>
972 The first is ec_decode_bin() (entdec.c), defined using the parameter ftb
973  instead of ft.
974 It is mathematically equivalent to calling ec_decode() with
975  ft = (1&lt;&lt;ftb), but avoids one of the divisions.
976 </t>
977 </section>
978 <section title="ec_dec_bit_logp()">
979 <t>
980 The next is ec_dec_bit_logp() (entdec.c), which decodes a single binary symbol,
981  replacing both the ec_decode() and ec_dec_update() steps.
982 The context is described by a single parameter, logp, which is the absolute
983  value of the base-2 logarithm of the probability of a "1".
984 It is mathematically equivalent to calling ec_decode() with
985  ft&nbsp;=&nbsp;(1&lt;&lt;logp), followed by ec_dec_update() with
986  the 3-tuple (fl[k]&nbsp;=&nbsp;0, fh[k]&nbsp;=&nbsp;(1&lt;&lt;logp)-1,
987  ft&nbsp;=&nbsp;(1&lt;&lt;logp)) if the returned value
988  of fs is less than (1&lt;&lt;logp)-1 (a "0" was decoded), and with
989  (fl[k]&nbsp;=&nbsp;(1&lt;&lt;logp)-1,
990  fh[k]&nbsp;=&nbsp;ft&nbsp;=&nbsp;(1&lt;&lt;logp)) otherwise (a "1" was
991  decoded).
992 The implementation requires no multiplications or divisions.
993 </t>
994 </section>
995 <section title="ec_dec_icdf()">
996 <t>
997 The last is ec_dec_icdf() (entdec.c), which decodes a single symbol with a
998  table-based context of up to 8 bits, also replacing both the ec_decode() and
999  ec_dec_update() steps, as well as the search for the decoded symbol in between.
1000 The context is described by two parameters, an icdf
1001  ("inverse" cumulative distribution function) table and ftb.
1002 As with ec_decode_bin(), (1&lt;&lt;ftb) is equivalent to ft.
1003 idcf[k], on the other hand, stores (1&lt;&lt;ftb)-fh[k], which is equal to
1004  (1&lt;&lt;ftb)-fl[k+1].
1005 fl[0] is assumed to be 0, and the table is terminated by a value of 0 (where
1006  fh[k]&nbsp;==&nbsp;ft).
1007 </t>
1008 <t>
1009 The function is mathematically equivalent to calling ec_decode() with
1010  ft&nbsp;=&nbsp;(1&lt;&lt;ftb), using the returned value fs to search the table
1011  for the first entry where fs&nbsp;&lt;&nbsp;(1&lt;&lt;ftb)-icdf[k], and
1012  calling ec_dec_update() with fl[k]&nbsp;=&nbsp;(1&lt;&lt;ftb)-icdf[k-1] (or 0
1013  if k&nbsp;==&nbsp;0), fh[k]&nbsp;=&nbsp;(1&lt;&lt;ftb)-idcf[k], and
1014  ft&nbsp;=&nbsp;(1&lt;&lt;ftb).
1015 Combining the search with the update allows the division to be replaced by a
1016  series of multiplications (which are usually much cheaper), and using an
1017  inverse CDF allows the use of an ftb as large as 8 in an 8-bit table without
1018  any special cases.
1019 This is the primary interface with the range decoder in the SILK layer, though
1020  it is used in a few places in the CELT layer as well.
1021 </t>
1022 <t>
1023 Although icdf[k] is more convenient for the code, the frequency counts, f[k],
1024  are a more natural representation of the probability distribution function
1025  (PDF) for a given symbol.
1026 Therefore this draft lists the latter, not the former, when describing the
1027  context in which a symbol is coded as a list, e.g., {4, 4, 4, 4}/16 for a
1028  uniform context with four possible values and ft=16.
1029 The value of ft after the slash is always the sum of the entries in the PDF,
1030  but is included for convenience.
1031 Contexts with identical probabilities, f[k]/ft, but different values of ft
1032  (or equivalently, ftb) are not the same, and cannot, in general, be used in
1033  place of one another.
1034 An icdf table is also not capable of representing a PDF where the first symbol
1035  has 0 probability.
1036 In such contexts, ec_dec_icdf() can decode the symbol by using a table that
1037  drops the entries for any initial zero-probability values and adding the
1038  constant offset of the first value with a non-zero probability to its return
1039  value.
1040 </t>
1041 </section>
1042 </section>
1043
1044 <section anchor="decoding-bits" title="Decoding Raw Bits">
1045 <t>
1046 The raw bits used by the CELT layer are packed at the end of the packet, with
1047  the least significant bit of the first value packed in the least significant
1048  bit of the last byte, filling up to the most significant bit in the last byte,
1049  continuing on to the least significant bit of the penultimate byte, and so on.
1050 The reference implementation reads them using ec_dec_bits() (entdec.c).
1051 Because the range decoder must read several bytes ahead in the stream, as
1052  described in <xref target="range-decoder-renorm"/>, the input consumed by the
1053  raw bits MAY overlap with the input consumed by the range coder, and a decoder
1054  MUST allow this.
1055 The format should render it impossible to attempt to read more raw bits than
1056  there are actual bits in the frame, though a decoder MAY wish to check for
1057  this and report an error.
1058 </t>
1059 </section>
1060
1061 <section anchor="decoding-ints" title="Decoding Uniformly Distributed Integers">
1062 <t>
1063 The ec_dec_uint() (entdec.c) function decodes one of ft equiprobable values in
1064  the range 0 to ft-1, inclusive, each with a frequency of 1, where ft may be as
1065  large as 2**32-1.
1066 Because ec_decode() is limited to a total frequency of 2**16-1, this is split
1067  up into a range coded symbol representing up to 8 of the high bits of the
1068  value, and, if necessary, raw bits representing the remaining bits.
1069 The limit of 8 bits in the range coded symbol is a trade-off between
1070  implementation complexity, modeling error (since the symbols no longer truly
1071  have equal coding cost), and rounding error introduced by the range coder
1072  itself (which gets larger as more bits are included).
1073 Using raw bits reduces the maximum number of divisions required in the worst
1074  case, but means that it may be possible to decode a value outside the range
1075  0 to ft-1, inclusive.
1076 </t>
1077
1078 <t>
1079 ec_dec_uint() takes a single, positive parameter, ft, which is not necessarily
1080  a power of two, and returns an integer, t, whose value lies between 0 and
1081  ft-1, inclusive.
1082 Let ftb = ilog(ft-1), i.e., the number of bits required to store ft-1 in two's
1083  complement notation.
1084 If ftb is 8 or less, then t is decoded with t = ec_decode(ft), and the range
1085  coder state is updated using the three-tuple (t,t+1,ft).
1086 </t>
1087 <t>
1088 If ftb is greater than 8, then the top 8 bits of t are decoded using
1089  t = ec_decode((ft-1&gt;&gt;ftb-8)+1),
1090  the decoder state is updated using the three-tuple
1091  (t,t+1,(ft-1&gt;&gt;ftb-8)+1), and the remaining bits are decoded as raw bits,
1092  setting t = t&lt;&lt;ftb-8|ec_dec_bits(ftb-8).
1093 If, at this point, t >= ft, then the current frame is corrupt.
1094 In that case, the decoder should assume there has been an error in the coding,
1095  decoding, or transmission and SHOULD take measures to conceal the
1096  error and/or report to the application that a problem has occurred.
1097 </t>
1098
1099 </section>
1100
1101 <section anchor="decoder-tell" title="Current Bit Usage">
1102 <t>
1103 The bit allocation routines in the CELT decoder need a conservative upper bound
1104  on the number of bits that have been used from the current frame thus far,
1105  including both range coder bits and raw bits.
1106 This drives allocation decisions that must match those made in the encoder.
1107 The upper bound is computed in the reference implementation to whole-bit
1108  precision by the function ec_tell() (entcode.h) and to fractional 1/8th bit
1109  precision by the function ec_tell_frac() (entcode.c).
1110 Like all operations in the range coder, it must be implemented in a bit-exact
1111  manner, and must produce exactly the same value returned by the same functions
1112  in the encoder after encoding the same symbols.
1113 </t>
1114 <t>
1115 ec_tell() is guaranteed to return ceil(ec_tell_frac()/8.0).
1116 In various places the codec will check to ensure there is enough room to
1117  contain a symbol before attempting to decode it.
1118 In practice, although the number of bits used so far is an upper bound,
1119  decoding a symbol whose probability model suggests it has a worst-case cost of
1120  p 1/8th bits may actually advance the return value of ec_tell_frac() by
1121  p-1, p, or p+1 1/8th bits, due to approximation error in that upper bound,
1122  truncation error in the range coder, and for large values of ft, modeling
1123  error in ec_dec_uint().
1124 </t>
1125 <t>
1126 However, this error is bounded, and periodic calls to ec_tell() or
1127  ec_tell_frac() at precisely defined points in the decoding process prevent it
1128  from accumulating.
1129 For a range coder symbol that requires a whole number of bits (i.e.,
1130  ft/(fh[k]-fl[k]) is a power of two), where there are at least p 1/8th bits
1131  available, decoding the symbol will never advance the decoder past the end of
1132  the frame ("bust the budget").
1133 In this case the return value of ec_tell_frac() will only advance by more than
1134  p 1/8th bits if there was an additional, fractional number of bits remaining,
1135  and it will never advance beyond the next whole-bit boundary, which is safe,
1136  since frames always contain a whole number of bits.
1137 However, when p is not a whole number of bits, an extra 1/8th bit is required
1138  to ensure that decoding the symbol will not bust the budget.
1139 </t>
1140 <t>
1141 The reference implementation keeps track of the total number of whole bits that
1142  have been processed by the decoder so far in the variable nbits_total,
1143  including the (possibly fractional) number of bits that are currently
1144  buffered, but not consumed, inside the range coder.
1145 nbits_total is initialized to 33 just after the initial range renormalization
1146  process completes (or equivalently, it can be initialized to 9 before the
1147  first renormalization).
1148 The extra two bits over the actual amount buffered by the range coder
1149  guarantees that it is an upper bound and that there is enough room for the
1150  encoder to terminate the stream.
1151 Each iteration through the range coder's renormalization loop increases
1152  nbits_total by 8.
1153 Reading raw bits increases nbits_total by the number of raw bits read.
1154 </t>
1155
1156 <section anchor="ec_tell" title="ec_tell()">
1157 <t>
1158 The whole number of bits buffered in rng may be estimated via l = ilog(rng).
1159 ec_tell() then becomes a simple matter of removing these bits from the total.
1160 It returns (nbits_total - l).
1161 </t>
1162 <t>
1163 In a newly initialized decoder, before any symbols have been read, this reports
1164  that 1 bit has been used.
1165 This is the bit reserved for termination of the encoder.
1166 </t>
1167 </section>
1168
1169 <section anchor="ec_tell_frac" title="ec_tell_frac()">
1170 <t>
1171 ec_tell_frac() estimates the number of bits buffered in rng to fractional
1172  precision.
1173 Since rng must be greater than 2**23 after renormalization, l must be at least
1174  24.
1175 Let r = rng&gt;&gt;(l-16), so that 32768 &lt;= r &lt; 65536, an unsigned Q15
1176  value representing the fractional part of rng.
1177 Then the following procedure can be used to add one bit of precision to l.
1178 First, update r = r*r&gt;&gt;15.
1179 Then add the 16th bit of r to l via l = 2*l + (r&gt;&gt;16).
1180 Finally, if this bit was a 1, reduce r by a factor of two via r = r&gt;&gt;1,
1181  so that it once again lies in the range 32768 &lt;= r &lt; 65536.
1182 </t>
1183 <t>
1184 This procedure is repeated three times to extend l to 1/8th bit precision.
1185 ec_tell_frac() then returns (nbits_total*8 - l).
1186 </t>
1187 </section>
1188
1189 </section>
1190
1191 </section>
1192
1193 <section anchor='outline_decoder' title='SILK Decoder'>
1194 <t>
1195 The decoder's LP layer uses a modified version of the SILK codec (herein simply
1196  called "SILK"), which runs a decoded excitation signal through adaptive
1197  long-term and short-term prediction synthesis filters.
1198 It runs in NB, MB, and WB modes internally.
1199 When used in a hybrid frame in SWB or FB mode, the LP layer itself still only
1200  runs in WB mode.
1201 </t>
1202 <t>
1203 Internally, the LP layer of a single Opus frame is composed of either a single
1204  10&nbsp;ms regular SILK frame or between one and three 20&nbsp;ms regular SILK
1205  frames.
1206 A stereo Opus frame may double the number of regular SILK frames (up to a total
1207  of six), since it includes separate frames for a mid channel and, optionally,
1208  a side channel.
1209 Optional Low Bit-Rate Redundancy (LBRR) frames, which are reduced-bitrate
1210  encodings of previous SILK frames, may be included to aid in recovery from
1211  packet loss.
1212 If present, these appear before the regular SILK frames.
1213 They are in most respects identical to regular, active SILK frames, except that
1214  they are usually encoded with a lower bitrate.
1215 This draft uses "SILK frame" to refer to either one and "regular SILK frame" if
1216  it needs to draw a distinction between the two.
1217 </t>
1218 <t>
1219 Each SILK frame is in turn composed of either two or four 5&nbsp;ms subframes.
1220 Various parameters, such as the quantization gain of the excitation and the
1221  pitch lag and filter coefficients can vary on a subframe-by-subframe basis.
1222 </t>
1223 <t>
1224 All of these frames and subframes are decoded from the same range coder, with
1225  no padding between them.
1226 Thus packing multiple SILK frames in a single Opus frame saves, on average,
1227  half a byte per SILK frame.
1228 It also allows some parameters to be predicted from prior SILK frames in the
1229  same Opus frame, since this does not degrade packet loss robustness (beyond
1230  any penalty for merely using fewer, larger packets to store multiple frames).
1231 </t>
1232
1233 <t>
1234 Stereo support in SILK uses a variant of mid-side coding, allowing a mono
1235  decoder to simply decode the mid channel.
1236 However, the data for the two channels is interleaved, so a mono decoder must
1237  still unpack the data for the side channel.
1238 It would be required to do so anyway for hybrid Opus frames, or to support
1239  decoding individual 20&nbsp;ms frames.
1240 </t>
1241
1242 <texttable anchor="silk_symbols">
1243 <ttcol align="center">Symbol(s)</ttcol>
1244 <ttcol align="center">PDF(s)</ttcol>
1245 <ttcol align="center">Condition</ttcol>
1246
1247 <c>VAD flags</c>
1248 <c>{1, 1}/2</c>
1249 <c/>
1250
1251 <c>LBRR flag</c>
1252 <c>{1, 1}/2</c>
1253 <c/>
1254
1255 <c>Per-frame LBRR flags</c>
1256 <c><xref target="silk_lbrr_flag_pdfs"/></c>
1257 <c><xref target="silk_lbrr_flags"/></c>
1258
1259 <c>LBRR Frame(s)</c>
1260 <c><xref target="silk_frame"/></c>
1261 <c><xref target="silk_lbrr_flags"/></c>
1262
1263 <c>Regular SILK Frame(s)</c>
1264 <c><xref target="silk_frame"/></c>
1265 <c/>
1266
1267 <postamble>
1268 Organization of the SILK layer of an Opus frame.
1269 </postamble>
1270 </texttable>
1271
1272 <section title="Decoder Modules">
1273 <t>
1274 An overview of the decoder is given in <xref target="decoder_figure"/>.
1275 </t>
1276 <figure align="center" anchor="decoder_figure">
1277 <artwork align="center">
1278 <![CDATA[
1279
1280    +---------+    +------------+
1281 -->| Range   |--->| Decode     |---------------------------+
1282  1 | Decoder | 2  | Parameters |----------+       5        |
1283    +---------+    +------------+     4    |                |
1284                        3 |                |                |
1285                         \/               \/               \/
1286                   +------------+   +------------+   +------------+
1287                   | Generate   |-->| LTP        |-->| LPC        |-->
1288                   | Excitation |   | Synthesis  |   | Synthesis  | 6
1289                   +------------+   +------------+   +------------+
1290
1291 1: Range encoded bitstream
1292 2: Coded parameters
1293 3: Pulses and gains
1294 4: Pitch lags and LTP coefficients
1295 5: LPC coefficients
1296 6: Decoded signal
1297 ]]>
1298 </artwork>
1299 <postamble>Decoder block diagram.</postamble>
1300 </figure>
1301
1302           <section title='Range Decoder'>
1303             <t>
1304               The range decoder decodes the encoded parameters from the received bitstream. Output from this function includes the pulses and gains for generating the excitation signal, as well as LTP and LSF codebook indices, which are needed for decoding LTP and LPC coefficients needed for LTP and LPC synthesis filtering the excitation signal, respectively.
1305             </t>
1306           </section>
1307
1308           <section title='Decode Parameters'>
1309             <t>
1310               Pulses and gains are decoded from the parameters that were decoded by the range decoder.
1311             </t>
1312
1313             <t>
1314               When a voiced frame is decoded and LTP codebook selection and indices are received, LTP coefficients are decoded using the selected codebook by choosing the vector that corresponds to the given codebook index in that codebook. This is done for each of the four subframes.
1315               The LPC coefficients are decoded from the LSF codebook by first adding the chosen LSF vector and the decoded LSF residual signal. The resulting LSF vector is stabilized using the same method that was used in the encoder; see
1316               <xref target='lsf_stabilizer_overview_section' />. The LSF coefficients are then converted to LPC coefficients, and passed on to the LPC synthesis filter.
1317             </t>
1318           </section>
1319
1320           <section title='Generate Excitation'>
1321             <t>
1322               The pulses signal is multiplied with the quantization gain to create the excitation signal.
1323             </t>
1324           </section>
1325
1326           <section title='LTP Synthesis'>
1327             <t>
1328               For voiced speech, the excitation signal e(n) is input to an LTP synthesis filter that recreates the long-term correlation removed in the LTP analysis filter and generates an LPC excitation signal e_LPC(n), according to
1329               <figure align="center">
1330                 <artwork align="center">
1331                   <![CDATA[
1332                    d
1333                   __
1334 e_LPC(n) = e(n) + \  e_LPC(n - L - i) * b_i,
1335                   /_
1336                  i=-d
1337 ]]>
1338                 </artwork>
1339               </figure>
1340               using the pitch lag L, and the decoded LTP coefficients b_i.
1341               The number of LTP coefficients is 5, and thus d&nbsp;=&nbsp;2.
1342
1343               For unvoiced speech, the output signal is simply a copy of the excitation signal, i.e., e_LPC(n) = e(n).
1344             </t>
1345           </section>
1346
1347           <section title='LPC Synthesis'>
1348             <t>
1349               In a similar manner, the short-term correlation that was removed in the LPC analysis filter is recreated in the LPC synthesis filter. The LPC excitation signal e_LPC(n) is filtered using the LTP coefficients a_i, according to
1350               <figure align="center">
1351                 <artwork align="center">
1352                   <![CDATA[
1353                  d_LPC
1354                   __
1355 y(n) = e_LPC(n) + \  y(n - i) * a_i,
1356                   /_
1357                   i=1
1358 ]]>
1359                 </artwork>
1360               </figure>
1361               where d_LPC is the LPC synthesis filter order, and y(n) is the decoded output signal.
1362             </t>
1363           </section>
1364         </section>
1365
1366 <!--TODO: Document mandated decoder resets-->
1367
1368 <section title="Header Bits">
1369 <t>
1370 The LP layer begins with two to eight header bits, decoded in silk_Decode()
1371  (silk_dec_API.c).
1372 These consist of one Voice Activity Detection (VAD) bit per frame (up to 3),
1373  followed by a single flag indicating the presence of LBRR frames.
1374 For a stereo packet, these flags correspond to the mid channel, and a second
1375  set of flags is included for the side channel.
1376 </t>
1377 <t>
1378 Because these are the first symbols decoded by the range coder, they can be
1379  extracted directly from the upper bits of the first byte of compressed data.
1380 Thus, a receiver can determine if an Opus frame contains any active SILK frames
1381  without the overhead of using the range decoder.
1382 </t>
1383 </section>
1384
1385 <section anchor="silk_lbrr_flags" title="LBRR Flags">
1386 <t>
1387 For Opus frames longer than 20&nbsp;ms, a set of per-frame LBRR flags is
1388  decoded for each channel that has its LBRR flag set.
1389 For 40&nbsp;ms Opus frames the 2-frame LBRR flag PDF from
1390  <xref target="silk_lbrr_flag_pdfs"/> is used, and for 60&nbsp;ms Opus frames
1391  the 3-frame LBRR flag PDF is used.
1392 For each channel, the resulting 2- or 3-bit integer contains the corresponding
1393  LBRR flag for each frame, packed in order from the LSb to the MSb.
1394 </t>
1395
1396 <texttable anchor="silk_lbrr_flag_pdfs" title="LBRR Flag PDFs">
1397 <ttcol>Frame Size</ttcol>
1398 <ttcol>PDF</ttcol>
1399 <c>40&nbsp;ms</c> <c>{0, 53, 53, 150}/256</c>
1400 <c>60&nbsp;ms</c> <c>{0, 41, 20, 29, 41, 15, 28, 82}/256</c>
1401 </texttable>
1402
1403 </section>
1404
1405 <section anchor="silk_lbrr_frames" title="LBRR Frames">
1406 <t>
1407 The LBRR frames, if present, immediately follow, one per set LBRR flag, and
1408  prior to any regular SILK frames.
1409 <xref target="silk_frame"/> describes their exact contents.
1410 LBRR frames do not include their own separate VAD flags.
1411 LBRR frames are only meant to be transmitted for active speech, thus all LBRR
1412  frames are treated as active.
1413 </t>
1414
1415 <t>
1416 In a stereo Opus frame longer than 20&nbsp;ms, although all the per-frame LBRR
1417  flags for the mid channel are coded before the per-frame LBRR flags for the
1418  side channel, the LBRR frames themselves are interleaved.
1419 The LBRR frame for the mid channel of a given 20&nbsp;ms interval (if present)
1420  is immediately followed by the corresponding LBRR frame for the side channel
1421  (if present).
1422 </t>
1423 </section>
1424
1425 <section anchor="silk_regular_frames" title="Regular SILK Frames">
1426 <t>
1427 The regular SILK frame(s) follow the LBRR frames (if any).
1428 <xref target="silk_frame"/> describes their contents, as well.
1429 Unlike the LBRR frames, a regular SILK frame is always coded for each time
1430  interval in an Opus frame, even if the corresponding VAD flag is unset.
1431 Like the LBRR frames, in stereo Opus frames longer than 20&nbsp;ms, the mid and
1432  side frames are interleaved for each 20&nbsp;ms interval.
1433 The side frame may be skipped by coding an appropriate flag, as detailed in
1434  <xref target="silk_mid_only_flag"/>.
1435 </t>
1436 </section>
1437
1438 <section anchor="silk_frame" title="SILK Frame Contents">
1439 <t>
1440 Each SILK frame includes a set of side information that encodes the frame type,
1441  quantization type and gains, short-term prediction filter coefficients, an LSF
1442  interpolation weight, long-term prediction filter lags and gains, and a
1443  linear congruential generator (LCG) seed.
1444 The quantized excitation signal follows these at the end of the frame.
1445 <xref target="silk_frame_symbols"/> details the overall organization of a
1446  SILK frame.
1447 </t>
1448
1449 <texttable anchor="silk_frame_symbols">
1450 <ttcol align="center">Symbol(s)</ttcol>
1451 <ttcol align="center">PDF(s)</ttcol>
1452 <ttcol align="center">Condition</ttcol>
1453
1454 <c>Stereo Prediction Weights</c>
1455 <c><xref target="silk_stereo_pred_pdfs"/></c>
1456 <c><xref target="silk_stereo_pred"/></c>
1457
1458 <c>Mid-Only Flag</c>
1459 <c><xref target="silk_mid_only_pdf"/></c>
1460 <c><xref target="silk_mid_only_flag"/></c>
1461
1462 <c>Frame Type</c>
1463 <c><xref target="silk_frame_type"/></c>
1464 <c/>
1465
1466 <c>Subframe Gains</c>
1467 <c><xref target="silk_gains"/></c>
1468 <c/>
1469
1470 <c>Normalized LSF Stage 1 Index</c>
1471 <c><xref target="silk_nlsf_stage1_pdfs"/></c>
1472 <c/>
1473
1474 <c>Normalized LSF Stage 2 Residual</c>
1475 <c><xref target="silk_nlsf_stage2"/></c>
1476 <c/>
1477
1478 <c>Normalized LSF Interpolation Weight</c>
1479 <c><xref target="silk_nlsf_interp_pdf"/></c>
1480 <c><xref target="silk_nlsf_interpolation"/></c>
1481
1482 <c>Primary Pitch Lag</c>
1483 <c><xref target="silk_ltp_lags"/></c>
1484 <c>Voiced frame</c>
1485
1486 <c>Subframe Pitch Contour</c>
1487 <c><xref target="silk_pitch_contour_pdfs"/></c>
1488 <c>Voiced frame</c>
1489
1490 <c>Periodicity Index</c>
1491 <c><xref target="silk_perindex_pdf"/></c>
1492 <c>Voiced frame</c>
1493
1494 <c>LTP Filter</c>
1495 <c><xref target="silk_ltp_filter_pdfs"/></c>
1496 <c>Voiced frame</c>
1497
1498 <c>LTP Scaling</c>
1499 <c><xref target="silk_ltp_scaling_pdf"/></c>
1500 <c><xref target="silk_ltp_scaling"/></c>
1501
1502 <c>LCG Seed</c>
1503 <c><xref target="silk_seed_pdf"/></c>
1504 <c/>
1505
1506 <c>Excitation Rate Level</c>
1507 <c><xref target="silk_rate_level_pdfs"/></c>
1508 <c/>
1509
1510 <c>Excitation Pulse Counts</c>
1511 <c><xref target="silk_pulse_count_pdfs"/></c>
1512 <c/>
1513
1514 <c>Excitation Pulse Locations</c>
1515 <c><xref target="silk_pulse_locations"/></c>
1516 <c>Non-zero pulse count</c>
1517
1518 <c>Excitation LSb's</c>
1519 <c><xref target="silk_shell_lsb_pdf"/></c>
1520 <c><xref target="silk_pulse_counts"/></c>
1521
1522 <c>Excitation Signs</c>
1523 <c><xref target="silk_sign_pdfs"/></c>
1524 <c><xref target="silk_signs"/></c>
1525
1526 <postamble>
1527 Order of the symbols in an individual SILK frame.
1528 </postamble>
1529 </texttable>
1530
1531 <section anchor="silk_stereo_pred" title="Stereo Prediction Weights">
1532 <t>
1533 A SILK frame corresponding to the mid channel of a stereo Opus frame begins
1534  with a pair of side channel prediction weights, designed such that zeros
1535  indicate normal mid-side coupling.
1536 Since these weights can change on every frame, the first portion of each frame
1537  linearly interpolates between the previous weights and the current ones, using
1538  zeros for the previous weights if none are available.
1539 These prediction weights are never included in a mono Opus frame, and the
1540  previous weights are reset to zeros on any transition from a mono to stereo.
1541 They are also not included in an LBRR frame for the side channel, even if the
1542  LBRR flags indicate the corresponding mid channel was not coded.
1543 In that case, the previous weights are used, again substituting in zeros if no
1544  previous weights are available since the last decoder reset.
1545 </t>
1546
1547 <t>
1548 The prediction weights are coded in three separate pieces, which are decoded
1549  by silk_stereo_decode_pred() (silk_decode_stereo_pred.c).
1550 The first piece jointly codes the high-order part of a table index for both
1551  weights.
1552 The second piece codes the low-order part of each table index.
1553 The third piece codes an offset used to linearly interpolate between table
1554  indices.
1555 The details are as follows.
1556 </t>
1557
1558 <t>
1559 Let n be an index decoded with the 25-element stage-1 PDF in
1560  <xref target="silk_stereo_pred_pdfs"/>.
1561 Then let i0 and i1 be indices decoded with the stage-2 and stage-3 PDFs in
1562  <xref target="silk_stereo_pred_pdfs"/>, respectively, and let i2 and i3
1563  be two more indices decoded with the stage-2 and stage-3 PDFs, all in that
1564  order.
1565 </t>
1566
1567 <texttable anchor="silk_stereo_pred_pdfs" title="Stereo Weight PDFs">
1568 <ttcol align="left">Stage</ttcol>
1569 <ttcol align="left">PDF</ttcol>
1570 <c>Stage 1</c>
1571 <c>{7,  2,  1,  1,  1,
1572    10, 24,  8,  1,  1,
1573     3, 23, 92, 23,  3,
1574     1,  1,  8, 24, 10,
1575     1,  1,  1,  2,  7}/256</c>
1576
1577 <c>Stage 2</c>
1578 <c>{85, 86, 85}/256</c>
1579
1580 <c>Stage 3</c>
1581 <c>{51, 51, 52, 51, 51}/256</c>
1582 </texttable>
1583
1584 <t>
1585 Then use n, i0, and i2 to form two table indices, wi0 and wi1, according to
1586 <figure align="center">
1587 <artwork align="center"><![CDATA[
1588 wi0 = i0 + 3*(n/5)
1589 wi1 = i2 + 3*(n%5)
1590 ]]></artwork>
1591 </figure>
1592  where the division is exact integer division.
1593 The range of these indices is 0 to 14, inclusive.
1594 Let w[i] be the i'th weight from <xref target="silk_stereo_weights_table"/>.
1595 Then the two prediction weights, w0_Q13 and w1_Q13, are
1596 <figure align="center">
1597 <artwork align="center"><![CDATA[
1598 w1_Q13 = w_Q13[wi1]
1599          + ((w_Q13[wi1+1] - w_Q13[wi1])*6554) >> 16)*(2*i3 + 1)
1600
1601 w0_Q13 = w_Q13[wi0]
1602          + ((w_Q13[wi0+1] - w_Q13[wi0])*6554) >> 16)*(2*i1 + 1)
1603          - w1_Q13
1604 ]]></artwork>
1605 </figure>
1606 </t>
1607
1608 <texttable anchor="silk_stereo_weights_table"
1609  title="Stereo Weight Table">
1610 <ttcol align="left">Index</ttcol>
1611 <ttcol align="right">Weight (Q13)</ttcol>
1612  <c>0</c> <c>-13732</c>
1613  <c>1</c> <c>-10050</c>
1614  <c>2</c>  <c>-8266</c>
1615  <c>3</c>  <c>-7526</c>
1616  <c>4</c>  <c>-6500</c>
1617  <c>5</c>  <c>-5000</c>
1618  <c>6</c>  <c>-2950</c>
1619  <c>7</c>   <c>-820</c>
1620  <c>8</c>    <c>820</c>
1621  <c>9</c>   <c>2950</c>
1622 <c>10</c>   <c>5000</c>
1623 <c>11</c>   <c>6500</c>
1624 <c>12</c>   <c>7526</c>
1625 <c>13</c>   <c>8266</c>
1626 <c>14</c>  <c>10050</c>
1627 <c>15</c>  <c>13732</c>
1628 </texttable>
1629
1630 </section>
1631
1632 <section anchor="silk_mid_only_flag" title="Mid-Only Flag">
1633 <t>
1634 A flag appears after the stereo prediction weights that indicates if only the
1635  mid channel is coded for this time interval.
1636 It is omitted when there are no stereo weights, i.e., unless the SILK frame
1637  corresponds to the mid channel of a stereo Opus frame, and it is also omitted
1638  for an LBRR frame when the corresponding LBRR flags indicate the side channel
1639  is present.
1640 When present, the decoder reads a single value using the PDF in
1641  <xref target="silk_mid_only_pdf"/>, as implemented in
1642  silk_stereo_decode_mid_only() (silk_decode_stereo_pred.c).
1643 If the flag is set, then there is no corresponding SILK frame for the side
1644  channel, the entire decoding process for the side channel is skipped, and
1645  zeros are used during the stereo unmixing process<!--TODO: ref-->.
1646 As stated above, LBRR frames still include this flag when the LBRR flag
1647  indicates that the side channel is not coded.
1648 In that case, if this flag is zero (indicating that there should be a side
1649  channel), then Packet Loss Concealment (PLC, see
1650  <xref target="Packet Loss Concealment"/>) SHOULD be invoked to recover a
1651  side channel signal.
1652 </t>
1653
1654 <texttable anchor="silk_mid_only_pdf" title="Mid-Only Flag PDF">
1655 <ttcol align="left">PDF</ttcol>
1656 <c>{192, 64}/256</c>
1657 </texttable>
1658
1659 </section>
1660
1661 <section anchor="silk_frame_type" title="Frame Type">
1662 <t>
1663 Each SILK frame contains a single "frame type" symbol that jointly codes the
1664  signal type and quantization offset type of the corresponding frame.
1665 If the current frame is a regular SILK frame whose VAD bit was not set (an
1666  "inactive" frame), then the frame type symbol takes on a value of either 0 or
1667  1 and is decoded using the first PDF in <xref target="silk_frame_type_pdfs"/>.
1668 If the frame is an LBRR frame or a regular SILK frame whose VAD flag was set
1669  (an "active" frame), then the value of the symbol may range from 2 to 5,
1670  inclusive, and is decoded using the second PDF in
1671  <xref target="silk_frame_type_pdfs"/>.
1672 <xref target="silk_frame_type_table"/> translates between the value of the
1673  frame type symbol and the corresponding signal type and quantization offset
1674  type.
1675 </t>
1676
1677 <texttable anchor="silk_frame_type_pdfs" title="Frame Type PDFs">
1678 <ttcol>VAD Flag</ttcol>
1679 <ttcol>PDF</ttcol>
1680 <c>Inactive</c> <c>{26, 230, 0, 0, 0, 0}/256</c>
1681 <c>Active</c>   <c>{0, 0, 24, 74, 148, 10}/256</c>
1682 </texttable>
1683
1684 <texttable anchor="silk_frame_type_table"
1685  title="Signal Type and Quantization Offset Type from Frame Type">
1686 <ttcol>Frame Type</ttcol>
1687 <ttcol>Signal Type</ttcol>
1688 <ttcol align="right">Quantization Offset Type</ttcol>
1689 <c>0</c> <c>Inactive</c> <c>Low</c>
1690 <c>1</c> <c>Inactive</c> <c>High</c>
1691 <c>2</c> <c>Unvoiced</c> <c>Low</c>
1692 <c>3</c> <c>Unvoiced</c> <c>High</c>
1693 <c>4</c> <c>Voiced</c>   <c>Low</c>
1694 <c>5</c> <c>Voiced</c>   <c>High</c>
1695 </texttable>
1696
1697 </section>
1698
1699 <section anchor="silk_gains" title="Subframe Gains">
1700 <t>
1701 A separate quantization gain is coded for each 5&nbsp;ms subframe.
1702 These gains control the step size between quantization levels of the excitation
1703  signal and, therefore, the quality of the reconstruction.
1704 They are independent of the pitch gains coded for voiced frames.
1705 The quantization gains are themselves uniformly quantized to 6&nbsp;bits on a
1706  log scale, giving them a resolution of approximately 1.369&nbsp;dB and a range
1707  of approximately 1.94&nbsp;dB to 88.21&nbsp;dB.
1708 </t>
1709 <t>
1710 For the first LBRR frame, an LBRR frame where the previous LBRR frame in the
1711  same channel is not coded, or the first regular SILK frame in the current
1712  channel of an Opus frame, the first subframe uses an independent coding
1713  method.
1714 In a stereo Opus frame, the mid-only flag (from
1715  <xref target="silk_mid_only_flag"/>) may cause the first regular SILK frame in
1716  the side channel to occur in a later time interval than the first regular SILK
1717  frame in the mid channel.
1718 The 3 most significant bits of the quantization gain are decoded using a PDF
1719  selected from <xref target="silk_independent_gain_msb_pdfs"/> based on the
1720  decoded signal type.
1721 </t>
1722
1723 <texttable anchor="silk_independent_gain_msb_pdfs"
1724  title="PDFs for Independent Quantization Gain MSb Coding">
1725 <ttcol align="left">Signal Type</ttcol>
1726 <ttcol align="left">PDF</ttcol>
1727 <c>Inactive</c> <c>{32, 112, 68, 29, 12,  1,  1, 1}/256</c>
1728 <c>Unvoiced</c>  <c>{2,  17, 45, 60, 62, 47, 19, 4}/256</c>
1729 <c>Voiced</c>    <c>{1,   3, 26, 71, 94, 50,  9, 2}/256</c>
1730 </texttable>
1731
1732 <t>
1733 The 3 least significant bits are decoded using a uniform PDF:
1734 </t>
1735 <texttable anchor="silk_independent_gain_lsb_pdf"
1736  title="PDF for Independent Quantization Gain LSb Coding">
1737 <ttcol align="left">PDF</ttcol>
1738 <c>{32, 32, 32, 32, 32, 32, 32, 32}/256</c>
1739 </texttable>
1740
1741 <t>
1742 For all other subframes (including the first subframe of frames not listed as
1743  using independent coding above), the quantization gain is coded relative to
1744  the gain from the previous subframe (in the same channel).
1745 In particular, unlike an LBRR frame where the previous frame is not coded, in a
1746  60&nbsp;ms stereo Opus frame, if the first and third regular SILK frames
1747  in the side channel are coded, but the second is not, the first subframe of
1748  the third frame is still coded relative to the last subframe in the first
1749  frame.
1750 The PDF in <xref target="silk_delta_gain_pdf"/> yields a delta gain index
1751  between 0 and 40, inclusive.
1752 </t>
1753 <texttable anchor="silk_delta_gain_pdf"
1754  title="PDF for Delta Quantization Gain Coding">
1755 <ttcol align="left">PDF</ttcol>
1756 <c>{6,   5,  11,  31, 132,  21,   8,   4,
1757     3,   2,   2,   2,   1,   1,   1,   1,
1758     1,   1,   1,   1,   1,   1,   1,   1,
1759     1,   1,   1,   1,   1,   1,   1,   1,
1760     1,   1,   1,   1,   1,   1,   1,   1,   1}/256</c>
1761 </texttable>
1762 <t>
1763 The following formula translates this index into a quantization gain for the
1764  current subframe using the gain from the previous subframe:
1765 </t>
1766 <figure align="center">
1767 <artwork align="center"><![CDATA[
1768 log_gain = min(max(2*gain_index - 16,
1769                    previous_log_gain + gain_index - 4), 63)
1770 ]]></artwork>
1771 </figure>
1772 <t>
1773 silk_gains_dequant() (silk_gain_quant.c) dequantizes the gain for the
1774  k'th subframe and converts it into a linear Q16 scale factor via
1775 <figure align="center">
1776 <artwork align="center"><![CDATA[
1777 gain_Q16[k] = silk_log2lin((0x1D1C71*log_gain>>16) + 2090)
1778 ]]></artwork>
1779 </figure>
1780 </t>
1781 <t>
1782 The function silk_log2lin() (silk_log2lin.c) computes an approximation of
1783  of 2**(inLog_Q7/128.0), where inLog_Q7 is its Q7 input.
1784 Let i = inLog_Q7&gt;&gt;7 be the integer part of inLogQ7 and
1785  f = inLog_Q7&amp;127 be the fractional part.
1786 Then, if i &lt; 16, then
1787 <figure align="center">
1788 <artwork align="center"><![CDATA[
1789 (1<<i) + (((-174*f*(128-f)>>16)+f)>>7)*(1<<i)
1790 ]]></artwork>
1791 </figure>
1792  yields the approximate exponential.
1793 Otherwise, silk_log2lin uses
1794 <figure align="center">
1795 <artwork align="center"><![CDATA[
1796 (1<<i) + ((-174*f*(128-f)>>16)+f)*((1<<i)>>7) .
1797 ]]></artwork>
1798 </figure>
1799 </t>
1800 </section>
1801
1802 <section anchor="silk_nlsfs" title="Normalized Line Spectral Frequency (LSF)
1803  and Linear Predictive Coding (LPC) Coefficients">
1804 <t>
1805 Normalized Line Spectral Frequency (LSF) coefficients follow the quantization
1806  gains in the bitstream, and represent the Linear Predictive Coding (LPC)
1807  coefficients for the current SILK frame.
1808 Once decoded, the normalized LSFs form an increasing list of Q15 values between
1809  0 and 1.
1810 These represent the interleaved zeros on the unit circle between 0 and pi
1811  (hence "normalized") in the standard decomposition of the LPC filter into a
1812  symmetric part and an anti-symmetric part (P and Q in
1813  <xref target="silk_nlsf2lpc"/>).
1814 Because of non-linear effects in the decoding process, an implementation SHOULD
1815  match the fixed-point arithmetic described in this section exactly.
1816 An encoder SHOULD also use the same process.
1817 </t>
1818 <t>
1819 The normalized LSFs are coded using a two-stage vector quantizer (VQ)
1820  (<xref target="silk_nlsf_stage1"/> and <xref target="silk_nlsf_stage2"/>).
1821 NB and MB frames use an order-10 predictor, while WB frames use an order-16
1822  predictor, and thus have different sets of tables.
1823 After reconstructing the normalized LSFs
1824  (<xref target="silk_nlsf_reconstruction"/>), the decoder runs them through a
1825  stabilization process (<xref target="silk_nlsf_stabilization"/>), interpolates
1826  them between frames (<xref target="silk_nlsf_interpolation"/>), converts them
1827  back into LPC coefficients (<xref target="silk_nlsf2lpc"/>), and then runs
1828  them through further processes to limit the range of the coefficients
1829  (<xref target="silk_lpc_range_limit"/>) and the gain of the filter
1830  (<xref target="silk_lpc_gain_limit"/>).
1831 All of this is necessary to ensure the reconstruction process is stable.
1832 </t>
1833
1834 <section anchor="silk_nlsf_stage1" title="Stage 1 Normalized LSF Decoding">
1835 <t>
1836 The first VQ stage uses a 32-element codebook, coded with one of the PDFs in
1837  <xref target="silk_nlsf_stage1_pdfs"/>, depending on the audio bandwidth and
1838  the signal type of the current SILK frame.
1839 This yields a single index, I1, for the entire frame.
1840 This indexes an element in a coarse codebook, selects the PDFs for the
1841  second stage of the VQ, and selects the prediction weights used to remove
1842  intra-frame redundancy from the second stage.
1843 The actual codebook elements are listed in
1844  <xref target="silk_nlsf_nbmb_codebook"/> and
1845  <xref target="silk_nlsf_wb_codebook"/>, but they are not needed until the last
1846  stages of reconstructing the LSF coefficients.
1847 </t>
1848
1849 <texttable anchor="silk_nlsf_stage1_pdfs"
1850  title="PDFs for Normalized LSF Index Stage-1 Decoding">
1851 <ttcol align="left">Audio Bandwidth</ttcol>
1852 <ttcol align="left">Signal Type</ttcol>
1853 <ttcol align="left">PDF</ttcol>
1854 <c>NB or MB</c> <c>Inactive or unvoiced</c>
1855 <c>
1856 {44, 34, 30, 19, 21, 12, 11,  3,
1857   3,  2, 16,  2,  2,  1,  5,  2,
1858   1,  3,  3,  1,  1,  2,  2,  2,
1859   3,  1,  9,  9,  2,  7,  2,  1}/256
1860 </c>
1861 <c>NB or MB</c> <c>Voiced</c>
1862 <c>
1863 {1, 10,  1,  8,  3,  8,  8, 14,
1864 13, 14,  1, 14, 12, 13, 11, 11,
1865 12, 11, 10, 10, 11,  8,  9,  8,
1866  7,  8,  1,  1,  6,  1,  6,  5}/256
1867 </c>
1868 <c>WB</c> <c>Inactive or unvoiced</c>
1869 <c>
1870 {31, 21,  3, 17,  1,  8, 17,  4,
1871   1, 18, 16,  4,  2,  3,  1, 10,
1872   1,  3, 16, 11, 16,  2,  2,  3,
1873   2, 11,  1,  4,  9,  8,  7,  3}/256
1874 </c>
1875 <c>WB</c> <c>Voiced</c>
1876 <c>
1877 {1,  4, 16,  5, 18, 11,  5, 14,
1878 15,  1,  3, 12, 13, 14, 14,  6,
1879 14, 12,  2,  6,  1, 12, 12, 11,
1880 10,  3, 10,  5,  1,  1,  1,  3}/256
1881 </c>
1882 </texttable>
1883
1884 </section>
1885
1886 <section anchor="silk_nlsf_stage2" title="Stage 2 Normalized LSF Decoding">
1887 <t>
1888 A total of 16 PDFs are available for the LSF residual in the second stage: the
1889  8 (a...h) for NB and MB frames given in
1890  <xref target="silk_nlsf_stage2_nbmb_pdfs"/>, and the 8 (i...p) for WB frames
1891  given in <xref target="silk_nlsf_stage2_wb_pdfs"/>.
1892 Which PDF is used for which coefficient is driven by the index, I1,
1893  decoded in the first stage.
1894 <xref target="silk_nlsf_nbmb_stage2_cb_sel"/> lists the letter of the
1895  corresponding PDF for each normalized LSF coefficient for NB and MB, and
1896  <xref target="silk_nlsf_wb_stage2_cb_sel"/> lists the same information for WB.
1897 </t>
1898
1899 <texttable anchor="silk_nlsf_stage2_nbmb_pdfs"
1900  title="PDFs for NB/MB Normalized LSF Index Stage-2 Decoding">
1901 <ttcol align="left">Codebook</ttcol>
1902 <ttcol align="left">PDF</ttcol>
1903 <c>a</c> <c>{1,   1,   1,  15, 224,  11,   1,   1,   1}/256</c>
1904 <c>b</c> <c>{1,   1,   2,  34, 183,  32,   1,   1,   1}/256</c>
1905 <c>c</c> <c>{1,   1,   4,  42, 149,  55,   2,   1,   1}/256</c>
1906 <c>d</c> <c>{1,   1,   8,  52, 123,  61,   8,   1,   1}/256</c>
1907 <c>e</c> <c>{1,   3,  16,  53, 101,  74,   6,   1,   1}/256</c>
1908 <c>f</c> <c>{1,   3,  17,  55,  90,  73,  15,   1,   1}/256</c>
1909 <c>g</c> <c>{1,   7,  24,  53,  74,  67,  26,   3,   1}/256</c>
1910 <c>h</c> <c>{1,   1,  18,  63,  78,  58,  30,   6,   1}/256</c>
1911 </texttable>
1912
1913 <texttable anchor="silk_nlsf_stage2_wb_pdfs"
1914  title="PDFs for WB Normalized LSF Index Stage-2 Decoding">
1915 <ttcol align="left">Codebook</ttcol>
1916 <ttcol align="left">PDF</ttcol>
1917 <c>i</c> <c>{1,   1,   1,   9, 232,   9,   1,   1,   1}/256</c>
1918 <c>j</c> <c>{1,   1,   2,  28, 186,  35,   1,   1,   1}/256</c>
1919 <c>k</c> <c>{1,   1,   3,  42, 152,  53,   2,   1,   1}/256</c>
1920 <c>l</c> <c>{1,   1,  10,  49, 126,  65,   2,   1,   1}/256</c>
1921 <c>m</c> <c>{1,   4,  19,  48, 100,  77,   5,   1,   1}/256</c>
1922 <c>n</c> <c>{1,   1,  14,  54, 100,  72,  12,   1,   1}/256</c>
1923 <c>o</c> <c>{1,   1,  15,  61,  87,  61,  25,   4,   1}/256</c>
1924 <c>p</c> <c>{1,   7,  21,  50,  77,  81,  17,   1,   1}/256</c>
1925 </texttable>
1926
1927 <texttable anchor="silk_nlsf_nbmb_stage2_cb_sel"
1928  title="Codebook Selection for NB/MB Normalized LSF Index Stage 2 Decoding">
1929 <ttcol>I1</ttcol>
1930 <ttcol>Coefficient</ttcol>
1931 <c/>
1932 <c><spanx style="vbare">0&nbsp;1&nbsp;2&nbsp;3&nbsp;4&nbsp;5&nbsp;6&nbsp;7&nbsp;8&nbsp;9</spanx></c>
1933 <c> 0</c>
1934 <c><spanx style="vbare">a&nbsp;a&nbsp;a&nbsp;a&nbsp;a&nbsp;a&nbsp;a&nbsp;a&nbsp;a&nbsp;a</spanx></c>
1935 <c> 1</c>
1936 <c><spanx style="vbare">b&nbsp;d&nbsp;b&nbsp;c&nbsp;c&nbsp;b&nbsp;c&nbsp;b&nbsp;b&nbsp;b</spanx></c>
1937 <c> 2</c>
1938 <c><spanx style="vbare">c&nbsp;b&nbsp;b&nbsp;b&nbsp;b&nbsp;b&nbsp;b&nbsp;b&nbsp;b&nbsp;b</spanx></c>
1939 <c> 3</c>
1940 <c><spanx style="vbare">b&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;b&nbsp;c&nbsp;b&nbsp;b&nbsp;b</spanx></c>
1941 <c> 4</c>
1942 <c><spanx style="vbare">c&nbsp;d&nbsp;d&nbsp;d&nbsp;d&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;c</spanx></c>
1943 <c> 5</c>
1944 <c><spanx style="vbare">a&nbsp;f&nbsp;d&nbsp;d&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;b&nbsp;b</spanx></c>
1945 <c> g</c>
1946 <c><spanx style="vbare">a&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;b</spanx></c>
1947 <c> 7</c>
1948 <c><spanx style="vbare">c&nbsp;d&nbsp;g&nbsp;e&nbsp;e&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;f</spanx></c>
1949 <c> 8</c>
1950 <c><spanx style="vbare">c&nbsp;e&nbsp;f&nbsp;f&nbsp;e&nbsp;f&nbsp;e&nbsp;g&nbsp;e&nbsp;e</spanx></c>
1951 <c> 9</c>
1952 <c><spanx style="vbare">c&nbsp;e&nbsp;e&nbsp;h&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;f&nbsp;e</spanx></c>
1953 <c>10</c>
1954 <c><spanx style="vbare">e&nbsp;d&nbsp;d&nbsp;d&nbsp;c&nbsp;d&nbsp;c&nbsp;c&nbsp;c&nbsp;c</spanx></c>
1955 <c>11</c>
1956 <c><spanx style="vbare">b&nbsp;f&nbsp;f&nbsp;g&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;f&nbsp;f</spanx></c>
1957 <c>12</c>
1958 <c><spanx style="vbare">c&nbsp;h&nbsp;e&nbsp;g&nbsp;f&nbsp;f&nbsp;f&nbsp;f&nbsp;f&nbsp;f</spanx></c>
1959 <c>13</c>
1960 <c><spanx style="vbare">c&nbsp;h&nbsp;f&nbsp;f&nbsp;f&nbsp;f&nbsp;f&nbsp;g&nbsp;f&nbsp;e</spanx></c>
1961 <c>14</c>
1962 <c><spanx style="vbare">d&nbsp;d&nbsp;f&nbsp;e&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;e&nbsp;e</spanx></c>
1963 <c>15</c>
1964 <c><spanx style="vbare">c&nbsp;d&nbsp;d&nbsp;f&nbsp;f&nbsp;e&nbsp;e&nbsp;e&nbsp;e&nbsp;e</spanx></c>
1965 <c>16</c>
1966 <c><spanx style="vbare">c&nbsp;e&nbsp;e&nbsp;g&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;f&nbsp;f</spanx></c>
1967 <c>17</c>
1968 <c><spanx style="vbare">c&nbsp;f&nbsp;e&nbsp;g&nbsp;f&nbsp;f&nbsp;f&nbsp;e&nbsp;f&nbsp;e</spanx></c>
1969 <c>18</c>
1970 <c><spanx style="vbare">c&nbsp;h&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;f&nbsp;f</spanx></c>
1971 <c>19</c>
1972 <c><spanx style="vbare">c&nbsp;f&nbsp;e&nbsp;g&nbsp;h&nbsp;g&nbsp;f&nbsp;g&nbsp;f&nbsp;e</spanx></c>
1973 <c>20</c>
1974 <c><spanx style="vbare">d&nbsp;g&nbsp;h&nbsp;e&nbsp;g&nbsp;f&nbsp;f&nbsp;g&nbsp;e&nbsp;f</spanx></c>
1975 <c>21</c>
1976 <c><spanx style="vbare">c&nbsp;h&nbsp;g&nbsp;e&nbsp;e&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;f</spanx></c>
1977 <c>22</c>
1978 <c><spanx style="vbare">e&nbsp;f&nbsp;f&nbsp;e&nbsp;g&nbsp;g&nbsp;f&nbsp;g&nbsp;f&nbsp;e</spanx></c>
1979 <c>23</c>
1980 <c><spanx style="vbare">c&nbsp;f&nbsp;f&nbsp;g&nbsp;f&nbsp;g&nbsp;e&nbsp;g&nbsp;e&nbsp;e</spanx></c>
1981 <c>24</c>
1982 <c><spanx style="vbare">e&nbsp;f&nbsp;f&nbsp;f&nbsp;d&nbsp;h&nbsp;e&nbsp;f&nbsp;f&nbsp;e</spanx></c>
1983 <c>25</c>
1984 <c><spanx style="vbare">c&nbsp;d&nbsp;e&nbsp;f&nbsp;f&nbsp;g&nbsp;e&nbsp;f&nbsp;f&nbsp;e</spanx></c>
1985 <c>26</c>
1986 <c><spanx style="vbare">c&nbsp;d&nbsp;c&nbsp;d&nbsp;d&nbsp;e&nbsp;c&nbsp;d&nbsp;d&nbsp;d</spanx></c>
1987 <c>27</c>
1988 <c><spanx style="vbare">b&nbsp;b&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;c&nbsp;d&nbsp;c&nbsp;c</spanx></c>
1989 <c>28</c>
1990 <c><spanx style="vbare">e&nbsp;f&nbsp;f&nbsp;g&nbsp;g&nbsp;g&nbsp;f&nbsp;g&nbsp;e&nbsp;f</spanx></c>
1991 <c>29</c>
1992 <c><spanx style="vbare">d&nbsp;f&nbsp;f&nbsp;e&nbsp;e&nbsp;e&nbsp;e&nbsp;d&nbsp;d&nbsp;c</spanx></c>
1993 <c>30</c>
1994 <c><spanx style="vbare">c&nbsp;f&nbsp;d&nbsp;h&nbsp;f&nbsp;f&nbsp;e&nbsp;e&nbsp;f&nbsp;e</spanx></c>
1995 <c>31</c>
1996 <c><spanx style="vbare">e&nbsp;e&nbsp;f&nbsp;e&nbsp;f&nbsp;g&nbsp;f&nbsp;g&nbsp;f&nbsp;e</spanx></c>
1997 </texttable>
1998
1999 <texttable anchor="silk_nlsf_wb_stage2_cb_sel"
2000  title="Codebook Selection for WB Normalized LSF Index Stage 2 Decoding">
2001 <ttcol>I1</ttcol>
2002 <ttcol>Coefficient</ttcol>
2003 <c/>
2004 <c><spanx style="vbare">0&nbsp;&nbsp;1&nbsp;&nbsp;2&nbsp;&nbsp;3&nbsp;&nbsp;4&nbsp;&nbsp;5&nbsp;&nbsp;6&nbsp;&nbsp;7&nbsp;&nbsp;8&nbsp;&nbsp;9&nbsp;10&nbsp;11&nbsp;12&nbsp;13&nbsp;14&nbsp;15</spanx></c>
2005 <c> 0</c>
2006 <c><spanx style="vbare">i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i</spanx></c>
2007 <c> 1</c>
2008 <c><spanx style="vbare">k&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;l</spanx></c>
2009 <c> 2</c>
2010 <c><spanx style="vbare">k&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;p&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;k&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l</spanx></c>
2011 <c> 3</c>
2012 <c><spanx style="vbare">i&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;j</spanx></c>
2013 <c> 4</c>
2014 <c><spanx style="vbare">i&nbsp;&nbsp;o&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;o&nbsp;&nbsp;m&nbsp;&nbsp;p&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;l</spanx></c>
2015 <c> 5</c>
2016 <c><spanx style="vbare">i&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;m</spanx></c>
2017 <c> 6</c>
2018 <c><spanx style="vbare">i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i</spanx></c>
2019 <c> 7</c>
2020 <c><spanx style="vbare">i&nbsp;&nbsp;k&nbsp;&nbsp;o&nbsp;&nbsp;l&nbsp;&nbsp;p&nbsp;&nbsp;k&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;l</spanx></c>
2021 <c> 8</c>
2022 <c><spanx style="vbare">i&nbsp;&nbsp;o&nbsp;&nbsp;k&nbsp;&nbsp;o&nbsp;&nbsp;o&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;o&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l</spanx></c>
2023 <c> 9</c>
2024 <c><spanx style="vbare">k&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i</spanx></c>
2025 <c>j0</c>
2026 <c><spanx style="vbare">i&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;j</spanx></c>
2027 <c>11</c>
2028 <c><spanx style="vbare">k&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;l</spanx></c>
2029 <c>12</c>
2030 <c><spanx style="vbare">k&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;l</spanx></c>
2031 <c>13</c>
2032 <c><spanx style="vbare">l&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;o&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;m</spanx></c>
2033 <c>14</c>
2034 <c><spanx style="vbare">i&nbsp;&nbsp;o&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;p&nbsp;&nbsp;n&nbsp;&nbsp;k&nbsp;&nbsp;o&nbsp;&nbsp;n&nbsp;&nbsp;p&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;l</spanx></c>
2035 <c>15</c>
2036 <c><spanx style="vbare">i&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;j&nbsp;&nbsp;i</spanx></c>
2037 <c>16</c>
2038 <c><spanx style="vbare">j&nbsp;&nbsp;o&nbsp;&nbsp;n&nbsp;&nbsp;p&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;m</spanx></c>
2039 <c>17</c>
2040 <c><spanx style="vbare">j&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;m</spanx></c>
2041 <c>18</c>
2042 <c><spanx style="vbare">k&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;m</spanx></c>
2043 <c>19</c>
2044 <c><spanx style="vbare">i&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i</spanx></c>
2045 <c>20</c>
2046 <c><spanx style="vbare">l&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;m</spanx></c>
2047 <c>21</c>
2048 <c><spanx style="vbare">k&nbsp;&nbsp;o&nbsp;&nbsp;l&nbsp;&nbsp;p&nbsp;&nbsp;p&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;l</spanx></c>
2049 <c>22</c>
2050 <c><spanx style="vbare">k&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;o&nbsp;&nbsp;o&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;m</spanx></c>
2051 <c>23</c>
2052 <c><spanx style="vbare">j&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;j</spanx></c>
2053 <c>24</c>
2054 <c><spanx style="vbare">k&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;o&nbsp;&nbsp;o&nbsp;&nbsp;m&nbsp;&nbsp;p&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l</spanx></c>
2055 <c>25</c>
2056 <c><spanx style="vbare">i&nbsp;&nbsp;o&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i</spanx></c>
2057 <c>26</c>
2058 <c><spanx style="vbare">i&nbsp;&nbsp;o&nbsp;&nbsp;o&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;k&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;p&nbsp;&nbsp;p&nbsp;&nbsp;m&nbsp;&nbsp;m&nbsp;&nbsp;m</spanx></c>
2059 <c>27</c>
2060 <c><spanx style="vbare">l&nbsp;&nbsp;l&nbsp;&nbsp;p&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;l</spanx></c>
2061 <c>28</c>
2062 <c><spanx style="vbare">i&nbsp;&nbsp;i&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;j&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;j</spanx></c>
2063 <c>29</c>
2064 <c><spanx style="vbare">i&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;j</spanx></c>
2065 <c>30</c>
2066 <c><spanx style="vbare">l&nbsp;&nbsp;n&nbsp;&nbsp;n&nbsp;&nbsp;m&nbsp;&nbsp;p&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;i&nbsp;&nbsp;j&nbsp;&nbsp;i</spanx></c>
2067 <c>31</c>
2068 <c><spanx style="vbare">k&nbsp;&nbsp;l&nbsp;&nbsp;n&nbsp;&nbsp;l&nbsp;&nbsp;m&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;l&nbsp;&nbsp;k&nbsp;&nbsp;j&nbsp;&nbsp;k&nbsp;&nbsp;o&nbsp;&nbsp;m&nbsp;&nbsp;i&nbsp;&nbsp;i&nbsp;&nbsp;i</spanx></c>
2069 </texttable>
2070
2071 <t>
2072 Decoding the second stage residual proceeds as follows.
2073 For each coefficient, the decoder reads a symbol using the PDF corresponding to
2074  I1 from either <xref target="silk_nlsf_nbmb_stage2_cb_sel"/> or
2075  <xref target="silk_nlsf_wb_stage2_cb_sel"/>, and subtracts 4 from the result
2076  to give an index in the range -4 to 4, inclusive.
2077 If the index is either -4 or 4, it reads a second symbol using the PDF in
2078  <xref target="silk_nlsf_ext_pdf"/>, and adds the value of this second symbol
2079  to the index, using the same sign.
2080 This gives the index, I2[k], a total range of -10 to 10, inclusive.
2081 </t>
2082
2083 <texttable anchor="silk_nlsf_ext_pdf"
2084  title="PDF for Normalized LSF Index Extension Decoding">
2085 <ttcol align="left">PDF</ttcol>
2086 <c>{156, 60, 24,  9,  4,  2,  1}/256</c>
2087 </texttable>
2088
2089 <t>
2090 The decoded indices from both stages are translated back into normalized LSF
2091  coefficients in silk_NLSF_decode() (silk_NLSF_decode.c).
2092 The stage-2 indices represent residuals after both the first stage of the VQ
2093  and a separate backwards-prediction step.
2094 The backwards prediction process in the encoder subtracts a prediction from
2095  each residual formed by a multiple of the coefficient that follows it.
2096 The decoder must undo this process.
2097 <xref target="silk_nlsf_pred_weights"/> contains lists of prediction weights
2098  for each coefficient.
2099 There are two lists for NB and MB, and another two lists for WB, giving two
2100  possible prediction weights for each coefficient.
2101 </t>
2102
2103 <texttable anchor="silk_nlsf_pred_weights"
2104  title="Prediction Weights for Normalized LSF Decoding">
2105 <ttcol align="left">Coefficient</ttcol>
2106 <ttcol align="right">A</ttcol>
2107 <ttcol align="right">B</ttcol>
2108 <ttcol align="right">C</ttcol>
2109 <ttcol align="right">D</ttcol>
2110  <c>0</c> <c>179</c> <c>116</c> <c>175</c>  <c>68</c>
2111  <c>1</c> <c>138</c>  <c>67</c> <c>148</c>  <c>62</c>
2112  <c>2</c> <c>140</c>  <c>82</c> <c>160</c>  <c>66</c>
2113  <c>3</c> <c>148</c>  <c>59</c> <c>176</c>  <c>60</c>
2114  <c>4</c> <c>151</c>  <c>92</c> <c>178</c>  <c>72</c>
2115  <c>5</c> <c>149</c>  <c>72</c> <c>173</c> <c>117</c>
2116  <c>6</c> <c>153</c> <c>100</c> <c>174</c>  <c>85</c>
2117  <c>7</c> <c>151</c>  <c>89</c> <c>164</c>  <c>90</c>
2118  <c>8</c> <c>163</c>  <c>92</c> <c>177</c> <c>118</c>
2119  <c>9</c> <c/>        <c/>      <c>174</c> <c>136</c>
2120 <c>10</c> <c/>        <c/>      <c>196</c> <c>151</c>
2121 <c>11</c> <c/>        <c/>      <c>182</c> <c>142</c>
2122 <c>12</c> <c/>        <c/>      <c>198</c> <c>160</c>
2123 <c>13</c> <c/>        <c/>      <c>192</c> <c>142</c>
2124 <c>14</c> <c/>        <c/>      <c>182</c> <c>155</c>
2125 </texttable>
2126
2127 <t>
2128 The prediction is undone using the procedure implemented in
2129  silk_NLSF_residual_dequant() (silk_NLSF_decode.c), which is as follows.
2130 Each coefficient selects its prediction weight from one of the two lists based
2131  on the stage-1 index, I1.
2132 <xref target="silk_nlsf_nbmb_weight_sel"/> gives the selections for each
2133  coefficient for NB and MB, and <xref target="silk_nlsf_wb_weight_sel"/> gives
2134  the selections for WB.
2135 Let d_LPC be the order of the codebook, i.e., 10 for NB and MB, and 16 for WB,
2136  and let pred_Q8[k] be the weight for the k'th coefficient selected by this
2137  process for 0&nbsp;&lt;=&nbsp;k&nbsp;&lt;&nbsp;d_LPC-1.
2138 Then, the stage-2 residual for each coefficient is computed via
2139 <figure align="center">
2140 <artwork align="center"><![CDATA[
2141 res_Q10[k] = (k+1 < d_LPC ? (res_Q10[k+1]*pred_Q8[k])>>8 : 0)
2142              + ((((I2[k]<<10) + sign(I2[k])*102)*qstep)>>16) ,
2143 ]]></artwork>
2144 </figure>
2145  where qstep is the Q16 quantization step size, which is 11796 for NB and MB
2146  and 9830 for WB (representing step sizes of approximately 0.18 and 0.15,
2147  respectively).
2148 </t>
2149
2150 <texttable anchor="silk_nlsf_nbmb_weight_sel"
2151  title="Prediction Weight Selection for NB/MB Normalized LSF Decoding">
2152 <ttcol>I1</ttcol>
2153 <ttcol>Coefficient</ttcol>
2154 <c/>
2155 <c><spanx style="vbare">0&nbsp;1&nbsp;2&nbsp;3&nbsp;4&nbsp;5&nbsp;6&nbsp;7&nbsp;8</spanx></c>
2156 <c> 0</c>
2157 <c><spanx style="vbare">A&nbsp;B&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2158 <c> 1</c>
2159 <c><spanx style="vbare">B&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2160 <c> 2</c>
2161 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2162 <c> 3</c>
2163 <c><spanx style="vbare">B&nbsp;B&nbsp;B&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;B&nbsp;A</spanx></c>
2164 <c> 4</c>
2165 <c><spanx style="vbare">A&nbsp;B&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2166 <c> 5</c>
2167 <c><spanx style="vbare">A&nbsp;B&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2168 <c> 6</c>
2169 <c><spanx style="vbare">B&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;A&nbsp;A&nbsp;B&nbsp;A</spanx></c>
2170 <c> 7</c>
2171 <c><spanx style="vbare">A&nbsp;B&nbsp;B&nbsp;A&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;A</spanx></c>
2172 <c> 8</c>
2173 <c><spanx style="vbare">A&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;A&nbsp;B&nbsp;B</spanx></c>
2174 <c> 9</c>
2175 <c><spanx style="vbare">A&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;A&nbsp;B&nbsp;B&nbsp;B</spanx></c>
2176 <c>10</c>
2177 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2178 <c>11</c>
2179 <c><spanx style="vbare">A&nbsp;B&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;A</spanx></c>
2180 <c>12</c>
2181 <c><spanx style="vbare">A&nbsp;B&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;A</spanx></c>
2182 <c>13</c>
2183 <c><spanx style="vbare">A&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;A</spanx></c>
2184 <c>14</c>
2185 <c><spanx style="vbare">B&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;B</spanx></c>
2186 <c>15</c>
2187 <c><spanx style="vbare">A&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;A</spanx></c>
2188 <c>16</c>
2189 <c><spanx style="vbare">A&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;A&nbsp;B&nbsp;A</spanx></c>
2190 <c>17</c>
2191 <c><spanx style="vbare">A&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;B&nbsp;B</spanx></c>
2192 <c>18</c>
2193 <c><spanx style="vbare">A&nbsp;B&nbsp;B&nbsp;A&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;A</spanx></c>
2194 <c>19</c>
2195 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;A</spanx></c>
2196 <c>20</c>
2197 <c><spanx style="vbare">A&nbsp;B&nbsp;B&nbsp;A&nbsp;A&nbsp;B&nbsp;A&nbsp;B&nbsp;A</spanx></c>
2198 <c>21</c>
2199 <c><spanx style="vbare">A&nbsp;B&nbsp;B&nbsp;A&nbsp;A&nbsp;A&nbsp;B&nbsp;B&nbsp;A</spanx></c>
2200 <c>22</c>
2201 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;B</spanx></c>
2202 <c>23</c>
2203 <c><spanx style="vbare">A&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;A&nbsp;A&nbsp;B&nbsp;B</spanx></c>
2204 <c>24</c>
2205 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;B&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;B</spanx></c>
2206 <c>25</c>
2207 <c><spanx style="vbare">A&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;B&nbsp;A</spanx></c>
2208 <c>26</c>
2209 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2210 <c>27</c>
2211 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2212 <c>28</c>
2213 <c><spanx style="vbare">A&nbsp;A&nbsp;B&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;A</spanx></c>
2214 <c>29</c>
2215 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;B&nbsp;A&nbsp;A&nbsp;A&nbsp;A&nbsp;A</spanx></c>
2216 <c>30</c>
2217 <c><spanx style="vbare">A&nbsp;A&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;A&nbsp;B</spanx></c>
2218 <c>31</c>
2219 <c><spanx style="vbare">B&nbsp;A&nbsp;B&nbsp;B&nbsp;A&nbsp;B&nbsp;B&nbsp;B&nbsp;B</spanx></c>
2220 </texttable>
2221
2222 <texttable anchor="silk_nlsf_wb_weight_sel"
2223  title="Prediction Weight Selection for WB Normalized LSF Decoding">
2224 <ttcol>I1</ttcol>
2225 <ttcol>Coefficient</ttcol>
2226 <c/>
2227 <c><spanx style="vbare">0&nbsp;&nbsp;1&nbsp;&nbsp;2&nbsp;&nbsp;3&nbsp;&nbsp;4&nbsp;&nbsp;5&nbsp;&nbsp;6&nbsp;&nbsp;7&nbsp;&nbsp;8&nbsp;&nbsp;9&nbsp;10&nbsp;11&nbsp;12&nbsp;13&nbsp;14</spanx></c>
2228 <c> 0</c>
2229 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D</spanx></c>
2230 <c> 1</c>
2231 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2232 <c> 2</c>
2233 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2234 <c> 3</c>
2235 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2236 <c> 4</c>
2237 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C</spanx></c>
2238 <c> 5</c>
2239 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2240 <c> 6</c>
2241 <c><spanx style="vbare">D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C</spanx></c>
2242 <c> 7</c>
2243 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D</spanx></c>
2244 <c> 8</c>
2245 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D</spanx></c>
2246 <c> 9</c>
2247 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D</spanx></c>
2248 <c>10</c>
2249 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2250 <c>11</c>
2251 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2252 <c>12</c>
2253 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2254 <c>13</c>
2255 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2256 <c>14</c>
2257 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D</spanx></c>
2258 <c>15</c>
2259 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C</spanx></c>
2260 <c>16</c>
2261 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2262 <c>17</c>
2263 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2264 <c>18</c>
2265 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D</spanx></c>
2266 <c>19</c>
2267 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2268 <c>20</c>
2269 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2270 <c>21</c>
2271 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C</spanx></c>
2272 <c>22</c>
2273 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2274 <c>23</c>
2275 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C</spanx></c>
2276 <c>24</c>
2277 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D</spanx></c>
2278 <c>25</c>
2279 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D</spanx></c>
2280 <c>26</c>
2281 <c><spanx style="vbare">C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D</spanx></c>
2282 <c>27</c>
2283 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D</spanx></c>
2284 <c>28</c>
2285 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D</spanx></c>
2286 <c>29</c>
2287 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D</spanx></c>
2288 <c>30</c>
2289 <c><spanx style="vbare">D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;C</spanx></c>
2290 <c>31</c>
2291 <c><spanx style="vbare">C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C&nbsp;&nbsp;C&nbsp;&nbsp;D&nbsp;&nbsp;C</spanx></c>
2292 </texttable>
2293
2294 </section>
2295
2296 <section anchor="silk_nlsf_reconstruction"
2297  title="Reconstructing the Normalized LSF Coefficients">
2298 <t>
2299 Once the stage-1 index I1 and the stage-2 residual res_Q10[] have been decoded,
2300  the final normalized LSF coefficients can be reconstructed.
2301 </t>
2302 <t>
2303 The spectral distortion introduced by the quantization of each LSF coefficient
2304  varies, so the stage-2 residual is weighted accordingly, using the
2305  low-complexity Inverse Harmonic Mean Weighting (IHMW) function proposed in
2306  <xref target="laroia-icassp"/>.
2307 The weights are derived directly from the stage-1 codebook vector.
2308 Let cb1_Q8[k] be the k'th entry of the stage-1 codebook vector from
2309  <xref target="silk_nlsf_nbmb_codebook"/> or
2310  <xref target="silk_nlsf_wb_codebook"/>.
2311 Then for 0&nbsp;&lt;=&nbsp;k&nbsp;&lt;&nbsp;d_LPC the following expression
2312  computes the square of the weight as a Q18 value:
2313 <figure align="center">
2314 <artwork align="center">
2315 <![CDATA[
2316 w2_Q18[k] = (1024/(cb1_Q8[k] - cb1_Q8[k-1])
2317              + 1024/(cb1_Q8[k+1] - cb1_Q8[k])) << 16 ,
2318 ]]>
2319 </artwork>
2320 </figure>
2321  where cb1_Q8[-1]&nbsp;=&nbsp;0 and cb1_Q8[d_LPC]&nbsp;=&nbsp;256, and the
2322  division is exact integer division.
2323 This is reduced to an unsquared, Q9 value using the following square-root
2324  approximation:
2325 <figure align="center">
2326 <artwork align="center"><![CDATA[
2327 i = ilog(w2_Q18[k])
2328 f = (w2_Q18[k]>>(i-8)) & 127
2329 y = ((i&1) ? 32768 : 46214) >> ((32-i)>>1)
2330 w_Q9[k] = y + ((213*f*y)>>16)
2331 ]]></artwork>
2332 </figure>
2333 The cb1_Q8[] vector completely determines these weights, and they may be
2334  tabulated and stored as 13-bit unsigned values (with a range of 1819 to 5227,
2335  inclusive) to avoid computing them when decoding.
2336 The reference implementation already requires code to compute these weights on
2337  unquantized coefficients in the encoder, in silk_NLSF_VQ_weights_laroia()
2338  (silk_NLSF_VQ_weights_laroia.c) and its callers, so it reuses that code in the
2339  decoder instead of using a pre-computed table to reduce the amount of ROM
2340  required.
2341 </t>
2342
2343 <texttable anchor="silk_nlsf_nbmb_codebook"
2344            title="Codebook Vectors for NB/MB Normalized LSF Stage 1 Decoding">
2345 <ttcol>I1</ttcol>
2346 <ttcol>Codebook (Q8)</ttcol>
2347 <c/>
2348 <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;&nbsp;4&nbsp;&nbsp;&nbsp;5&nbsp;&nbsp;&nbsp;6&nbsp;&nbsp;&nbsp;7&nbsp;&nbsp;&nbsp;8&nbsp;&nbsp;&nbsp;9</spanx></c>
2349 <c>0</c>
2350 <c><spanx style="vbare">12&nbsp;&nbsp;35&nbsp;&nbsp;60&nbsp;&nbsp;83&nbsp;108&nbsp;132&nbsp;157&nbsp;180&nbsp;206&nbsp;228</spanx></c>
2351 <c>1</c>
2352 <c><spanx style="vbare">15&nbsp;&nbsp;32&nbsp;&nbsp;55&nbsp;&nbsp;77&nbsp;101&nbsp;125&nbsp;151&nbsp;175&nbsp;201&nbsp;225</spanx></c>
2353 <c>2</c>
2354 <c><spanx style="vbare">19&nbsp;&nbsp;42&nbsp;&nbsp;66&nbsp;&nbsp;89&nbsp;114&nbsp;137&nbsp;162&nbsp;184&nbsp;209&nbsp;230</spanx></c>
2355 <c>3</c>
2356 <c><spanx style="vbare">12&nbsp;&nbsp;25&nbsp;&nbsp;50&nbsp;&nbsp;72&nbsp;&nbsp;97&nbsp;120&nbsp;147&nbsp;172&nbsp;200&nbsp;223</spanx></c>
2357 <c>4</c>
2358 <c><spanx style="vbare">26&nbsp;&nbsp;44&nbsp;&nbsp;69&nbsp;&nbsp;90&nbsp;114&nbsp;135&nbsp;159&nbsp;180&nbsp;205&nbsp;225</spanx></c>
2359 <c>5</c>
2360 <c><spanx style="vbare">13&nbsp;&nbsp;22&nbsp;&nbsp;53&nbsp;&nbsp;80&nbsp;106&nbsp;130&nbsp;156&nbsp;180&nbsp;205&nbsp;228</spanx></c>
2361 <c>6</c>
2362 <c><spanx style="vbare">15&nbsp;&nbsp;25&nbsp;&nbsp;44&nbsp;&nbsp;64&nbsp;&nbsp;90&nbsp;115&nbsp;142&nbsp;168&nbsp;196&nbsp;222</spanx></c>
2363 <c>7</c>
2364 <c><spanx style="vbare">19&nbsp;&nbsp;24&nbsp;&nbsp;62&nbsp;&nbsp;82&nbsp;100&nbsp;120&nbsp;145&nbsp;168&nbsp;190&nbsp;214</spanx></c>
2365 <c>8</c>
2366 <c><spanx style="vbare">22&nbsp;&nbsp;31&nbsp;&nbsp;50&nbsp;&nbsp;79&nbsp;103&nbsp;120&nbsp;151&nbsp;170&nbsp;203&nbsp;227</spanx></c>
2367 <c>9</c>
2368 <c><spanx style="vbare">21&nbsp;&nbsp;29&nbsp;&nbsp;45&nbsp;&nbsp;65&nbsp;106&nbsp;124&nbsp;150&nbsp;171&nbsp;196&nbsp;224</spanx></c>
2369 <c>10</c>
2370 <c><spanx style="vbare">30&nbsp;&nbsp;49&nbsp;&nbsp;75&nbsp;&nbsp;97&nbsp;121&nbsp;142&nbsp;165&nbsp;186&nbsp;209&nbsp;229</spanx></c>
2371 <c>11</c>
2372 <c><spanx style="vbare">19&nbsp;&nbsp;25&nbsp;&nbsp;52&nbsp;&nbsp;70&nbsp;&nbsp;93&nbsp;116&nbsp;143&nbsp;166&nbsp;192&nbsp;219</spanx></c>
2373 <c>12</c>
2374 <c><spanx style="vbare">26&nbsp;&nbsp;34&nbsp;&nbsp;62&nbsp;&nbsp;75&nbsp;&nbsp;97&nbsp;118&nbsp;145&nbsp;167&nbsp;194&nbsp;217</spanx></c>
2375 <c>13</c>
2376 <c><spanx style="vbare">25&nbsp;&nbsp;33&nbsp;&nbsp;56&nbsp;&nbsp;70&nbsp;&nbsp;91&nbsp;113&nbsp;143&nbsp;165&nbsp;196&nbsp;223</spanx></c>
2377 <c>14</c>
2378 <c><spanx style="vbare">21&nbsp;&nbsp;34&nbsp;&nbsp;51&nbsp;&nbsp;72&nbsp;&nbsp;97&nbsp;117&nbsp;145&nbsp;171&nbsp;196&nbsp;222</spanx></c>
2379 <c>15</c>
2380 <c><spanx style="vbare">20&nbsp;&nbsp;29&nbsp;&nbsp;50&nbsp;&nbsp;67&nbsp;&nbsp;90&nbsp;117&nbsp;144&nbsp;168&nbsp;197&nbsp;221</spanx></c>
2381 <c>16</c>
2382 <c><spanx style="vbare">22&nbsp;&nbsp;31&nbsp;&nbsp;48&nbsp;&nbsp;66&nbsp;&nbsp;95&nbsp;117&nbsp;146&nbsp;168&nbsp;196&nbsp;222</spanx></c>
2383 <c>17</c>
2384 <c><spanx style="vbare">24&nbsp;&nbsp;33&nbsp;&nbsp;51&nbsp;&nbsp;77&nbsp;116&nbsp;134&nbsp;158&nbsp;180&nbsp;200&nbsp;224</spanx></c>
2385 <c>18</c>
2386 <c><spanx style="vbare">21&nbsp;&nbsp;28&nbsp;&nbsp;70&nbsp;&nbsp;87&nbsp;106&nbsp;124&nbsp;149&nbsp;170&nbsp;194&nbsp;217</spanx></c>
2387 <c>19</c>
2388 <c><spanx style="vbare">26&nbsp;&nbsp;33&nbsp;&nbsp;53&nbsp;&nbsp;64&nbsp;&nbsp;83&nbsp;117&nbsp;152&nbsp;173&nbsp;204&nbsp;225</spanx></c>
2389 <c>20</c>
2390 <c><spanx style="vbare">27&nbsp;&nbsp;34&nbsp;&nbsp;65&nbsp;&nbsp;95&nbsp;108&nbsp;129&nbsp;155&nbsp;174&nbsp;210&nbsp;225</spanx></c>
2391 <c>21</c>
2392 <c><spanx style="vbare">20&nbsp;&nbsp;26&nbsp;&nbsp;72&nbsp;&nbsp;99&nbsp;113&nbsp;131&nbsp;154&nbsp;176&nbsp;200&nbsp;219</spanx></c>
2393 <c>22</c>
2394 <c><spanx style="vbare">34&nbsp;&nbsp;43&nbsp;&nbsp;61&nbsp;&nbsp;78&nbsp;&nbsp;93&nbsp;114&nbsp;155&nbsp;177&nbsp;205&nbsp;229</spanx></c>
2395 <c>23</c>
2396 <c><spanx style="vbare">23&nbsp;&nbsp;29&nbsp;&nbsp;54&nbsp;&nbsp;97&nbsp;124&nbsp;138&nbsp;163&nbsp;179&nbsp;209&nbsp;229</spanx></c>
2397 <c>24</c>
2398 <c><spanx style="vbare">30&nbsp;&nbsp;38&nbsp;&nbsp;56&nbsp;&nbsp;89&nbsp;118&nbsp;129&nbsp;158&nbsp;178&nbsp;200&nbsp;231</spanx></c>
2399 <c>25</c>
2400 <c><spanx style="vbare">21&nbsp;&nbsp;29&nbsp;&nbsp;49&nbsp;&nbsp;63&nbsp;&nbsp;85&nbsp;111&nbsp;142&nbsp;163&nbsp;193&nbsp;222</spanx></c>
2401 <c>26</c>
2402 <c><spanx style="vbare">27&nbsp;&nbsp;48&nbsp;&nbsp;77&nbsp;103&nbsp;133&nbsp;158&nbsp;179&nbsp;196&nbsp;215&nbsp;232</spanx></c>
2403 <c>27</c>
2404 <c><spanx style="vbare">29&nbsp;&nbsp;47&nbsp;&nbsp;74&nbsp;&nbsp;99&nbsp;124&nbsp;151&nbsp;176&nbsp;198&nbsp;220&nbsp;237</spanx></c>
2405 <c>28</c>
2406 <c><spanx style="vbare">33&nbsp;&nbsp;42&nbsp;&nbsp;61&nbsp;&nbsp;76&nbsp;&nbsp;93&nbsp;121&nbsp;155&nbsp;174&nbsp;207&nbsp;225</spanx></c>
2407 <c>29</c>
2408 <c><spanx style="vbare">29&nbsp;&nbsp;53&nbsp;&nbsp;87&nbsp;112&nbsp;136&nbsp;154&nbsp;170&nbsp;188&nbsp;208&nbsp;227</spanx></c>
2409 <c>30</c>
2410 <c><spanx style="vbare">24&nbsp;&nbsp;30&nbsp;&nbsp;52&nbsp;&nbsp;84&nbsp;131&nbsp;150&nbsp;166&nbsp;186&nbsp;203&nbsp;229</spanx></c>
2411 <c>31</c>
2412 <c><spanx style="vbare">37&nbsp;&nbsp;48&nbsp;&nbsp;64&nbsp;&nbsp;84&nbsp;104&nbsp;118&nbsp;156&nbsp;177&nbsp;201&nbsp;230</spanx></c>
2413 </texttable>
2414
2415 <texttable anchor="silk_nlsf_wb_codebook"
2416            title="Codebook Vectors for WB Normalized LSF Stage 1 Decoding">
2417 <ttcol>I1</ttcol>
2418 <ttcol>Codebook (Q8)</ttcol>
2419 <c/>
2420 <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;1&nbsp;&nbsp;2&nbsp;&nbsp;3&nbsp;&nbsp;4&nbsp;&nbsp;&nbsp;5&nbsp;&nbsp;&nbsp;6&nbsp;&nbsp;&nbsp;7&nbsp;&nbsp;&nbsp;8&nbsp;&nbsp;&nbsp;9&nbsp;&nbsp;10&nbsp;&nbsp;11&nbsp;&nbsp;12&nbsp;&nbsp;13&nbsp;&nbsp;14&nbsp;&nbsp;15</spanx></c>
2421 <c>0</c>
2422 <c><spanx style="vbare">&nbsp;7&nbsp;23&nbsp;38&nbsp;54&nbsp;69&nbsp;&nbsp;85&nbsp;100&nbsp;116&nbsp;131&nbsp;147&nbsp;162&nbsp;178&nbsp;193&nbsp;208&nbsp;223&nbsp;239</spanx></c>
2423 <c>1</c>
2424 <c><spanx style="vbare">13&nbsp;25&nbsp;41&nbsp;55&nbsp;69&nbsp;&nbsp;83&nbsp;&nbsp;98&nbsp;112&nbsp;127&nbsp;142&nbsp;157&nbsp;171&nbsp;187&nbsp;203&nbsp;220&nbsp;236</spanx></c>
2425 <c>2</c>
2426 <c><spanx style="vbare">15&nbsp;21&nbsp;34&nbsp;51&nbsp;61&nbsp;&nbsp;78&nbsp;&nbsp;92&nbsp;106&nbsp;126&nbsp;136&nbsp;152&nbsp;167&nbsp;185&nbsp;205&nbsp;225&nbsp;240</spanx></c>
2427 <c>3</c>
2428 <c><spanx style="vbare">10&nbsp;21&nbsp;36&nbsp;50&nbsp;63&nbsp;&nbsp;79&nbsp;&nbsp;95&nbsp;110&nbsp;126&nbsp;141&nbsp;157&nbsp;173&nbsp;189&nbsp;205&nbsp;221&nbsp;237</spanx></c>
2429 <c>4</c>
2430 <c><spanx style="vbare">17&nbsp;20&nbsp;37&nbsp;51&nbsp;59&nbsp;&nbsp;78&nbsp;&nbsp;89&nbsp;107&nbsp;123&nbsp;134&nbsp;150&nbsp;164&nbsp;184&nbsp;205&nbsp;224&nbsp;240</spanx></c>
2431 <c>5</c>
2432 <c><spanx style="vbare">10&nbsp;15&nbsp;32&nbsp;51&nbsp;67&nbsp;&nbsp;81&nbsp;&nbsp;96&nbsp;112&nbsp;129&nbsp;142&nbsp;158&nbsp;173&nbsp;189&nbsp;204&nbsp;220&nbsp;236</spanx></c>
2433 <c>6</c>
2434 <c><spanx style="vbare">&nbsp;8&nbsp;21&nbsp;37&nbsp;51&nbsp;65&nbsp;&nbsp;79&nbsp;&nbsp;98&nbsp;113&nbsp;126&nbsp;138&nbsp;155&nbsp;168&nbsp;179&nbsp;192&nbsp;209&nbsp;218</spanx></c>
2435 <c>7</c>
2436 <c><spanx style="vbare">12&nbsp;15&nbsp;34&nbsp;55&nbsp;63&nbsp;&nbsp;78&nbsp;&nbsp;87&nbsp;108&nbsp;118&nbsp;131&nbsp;148&nbsp;167&nbsp;185&nbsp;203&nbsp;219&nbsp;236</spanx></c>
2437 <c>8</c>
2438 <c><spanx style="vbare">16&nbsp;19&nbsp;32&nbsp;36&nbsp;56&nbsp;&nbsp;79&nbsp;&nbsp;91&nbsp;108&nbsp;118&nbsp;136&nbsp;154&nbsp;171&nbsp;186&nbsp;204&nbsp;220&nbsp;237</spanx></c>
2439 <c>9</c>
2440 <c><spanx style="vbare">11&nbsp;28&nbsp;43&nbsp;58&nbsp;74&nbsp;&nbsp;89&nbsp;105&nbsp;120&nbsp;135&nbsp;150&nbsp;165&nbsp;180&nbsp;196&nbsp;211&nbsp;226&nbsp;241</spanx></c>
2441 <c>10</c>
2442 <c><spanx style="vbare">&nbsp;6&nbsp;16&nbsp;33&nbsp;46&nbsp;60&nbsp;&nbsp;75&nbsp;&nbsp;92&nbsp;107&nbsp;123&nbsp;137&nbsp;156&nbsp;169&nbsp;185&nbsp;199&nbsp;214&nbsp;225</spanx></c>
2443 <c>11</c>
2444 <c><spanx style="vbare">11&nbsp;19&nbsp;30&nbsp;44&nbsp;57&nbsp;&nbsp;74&nbsp;&nbsp;89&nbsp;105&nbsp;121&nbsp;135&nbsp;152&nbsp;169&nbsp;186&nbsp;202&nbsp;218&nbsp;234</spanx></c>
2445 <c>12</c>
2446 <c><spanx style="vbare">12&nbsp;19&nbsp;29&nbsp;46&nbsp;57&nbsp;&nbsp;71&nbsp;&nbsp;88&nbsp;100&nbsp;120&nbsp;132&nbsp;148&nbsp;165&nbsp;182&nbsp;199&nbsp;216&nbsp;233</spanx></c>
2447 <c>13</c>
2448 <c><spanx style="vbare">17&nbsp;23&nbsp;35&nbsp;46&nbsp;56&nbsp;&nbsp;77&nbsp;&nbsp;92&nbsp;106&nbsp;123&nbsp;134&nbsp;152&nbsp;167&nbsp;185&nbsp;204&nbsp;222&nbsp;237</spanx></c>
2449 <c>14</c>
2450 <c><spanx style="vbare">14&nbsp;17&nbsp;45&nbsp;53&nbsp;63&nbsp;&nbsp;75&nbsp;&nbsp;89&nbsp;107&nbsp;115&nbsp;132&nbsp;151&nbsp;171&nbsp;188&nbsp;206&nbsp;221&nbsp;240</spanx></c>
2451 <c>15</c>
2452 <c><spanx style="vbare">&nbsp;9&nbsp;16&nbsp;29&nbsp;40&nbsp;56&nbsp;&nbsp;71&nbsp;&nbsp;88&nbsp;103&nbsp;119&nbsp;137&nbsp;154&nbsp;171&nbsp;189&nbsp;205&nbsp;222&nbsp;237</spanx></c>
2453 <c>16</c>
2454 <c><spanx style="vbare">16&nbsp;19&nbsp;36&nbsp;48&nbsp;57&nbsp;&nbsp;76&nbsp;&nbsp;87&nbsp;105&nbsp;118&nbsp;132&nbsp;150&nbsp;167&nbsp;185&nbsp;202&nbsp;218&nbsp;236</spanx></c>
2455 <c>17</c>
2456 <c><spanx style="vbare">12&nbsp;17&nbsp;29&nbsp;54&nbsp;71&nbsp;&nbsp;81&nbsp;&nbsp;94&nbsp;104&nbsp;126&nbsp;136&nbsp;149&nbsp;164&nbsp;182&nbsp;201&nbsp;221&nbsp;237</spanx></c>
2457 <c>18</c>
2458 <c><spanx style="vbare">15&nbsp;28&nbsp;47&nbsp;62&nbsp;79&nbsp;&nbsp;97&nbsp;115&nbsp;129&nbsp;142&nbsp;155&nbsp;168&nbsp;180&nbsp;194&nbsp;208&nbsp;223&nbsp;238</spanx></c>
2459 <c>19</c>
2460 <c><spanx style="vbare">&nbsp;8&nbsp;14&nbsp;30&nbsp;45&nbsp;62&nbsp;&nbsp;78&nbsp;&nbsp;94&nbsp;111&nbsp;127&nbsp;143&nbsp;159&nbsp;175&nbsp;192&nbsp;207&nbsp;223&nbsp;239</spanx></c>
2461 <c>20</c>
2462 <c><spanx style="vbare">17&nbsp;30&nbsp;49&nbsp;62&nbsp;79&nbsp;&nbsp;92&nbsp;107&nbsp;119&nbsp;132&nbsp;145&nbsp;160&nbsp;174&nbsp;190&nbsp;204&nbsp;220&nbsp;235</spanx></c>
2463 <c>21</c>
2464 <c><spanx style="vbare">14&nbsp;19&nbsp;36&nbsp;45&nbsp;61&nbsp;&nbsp;76&nbsp;&nbsp;91&nbsp;108&nbsp;121&nbsp;138&nbsp;154&nbsp;172&nbsp;189&nbsp;205&nbsp;222&nbsp;238</spanx></c>
2465 <c>22</c>
2466 <c><spanx style="vbare">12&nbsp;18&nbsp;31&nbsp;45&nbsp;60&nbsp;&nbsp;76&nbsp;&nbsp;91&nbsp;107&nbsp;123&nbsp;138&nbsp;154&nbsp;171&nbsp;187&nbsp;204&nbsp;221&nbsp;236</spanx></c>
2467 <c>23</c>
2468 <c><spanx style="vbare">13&nbsp;17&nbsp;31&nbsp;43&nbsp;53&nbsp;&nbsp;70&nbsp;&nbsp;83&nbsp;103&nbsp;114&nbsp;131&nbsp;149&nbsp;167&nbsp;185&nbsp;203&nbsp;220&nbsp;237</spanx></c>
2469 <c>24</c>
2470 <c><spanx style="vbare">17&nbsp;22&nbsp;35&nbsp;42&nbsp;58&nbsp;&nbsp;78&nbsp;&nbsp;93&nbsp;110&nbsp;125&nbsp;139&nbsp;155&nbsp;170&nbsp;188&nbsp;206&nbsp;224&nbsp;240</spanx></c>
2471 <c>25</c>
2472 <c><spanx style="vbare">&nbsp;8&nbsp;15&nbsp;34&nbsp;50&nbsp;67&nbsp;&nbsp;83&nbsp;&nbsp;99&nbsp;115&nbsp;131&nbsp;146&nbsp;162&nbsp;178&nbsp;193&nbsp;209&nbsp;224&nbsp;239</spanx></c>
2473 <c>26</c>
2474 <c><spanx style="vbare">13&nbsp;16&nbsp;41&nbsp;66&nbsp;73&nbsp;&nbsp;86&nbsp;&nbsp;95&nbsp;111&nbsp;128&nbsp;137&nbsp;150&nbsp;163&nbsp;183&nbsp;206&nbsp;225&nbsp;241</spanx></c>
2475 <c>27</c>
2476 <c><spanx style="vbare">17&nbsp;25&nbsp;37&nbsp;52&nbsp;63&nbsp;&nbsp;75&nbsp;&nbsp;92&nbsp;102&nbsp;119&nbsp;132&nbsp;144&nbsp;160&nbsp;175&nbsp;191&nbsp;212&nbsp;231</spanx></c>
2477 <c>28</c>
2478 <c><spanx style="vbare">19&nbsp;31&nbsp;49&nbsp;65&nbsp;83&nbsp;100&nbsp;117&nbsp;133&nbsp;147&nbsp;161&nbsp;174&nbsp;187&nbsp;200&nbsp;213&nbsp;227&nbsp;242</spanx></c>
2479 <c>29</c>
2480 <c><spanx style="vbare">18&nbsp;31&nbsp;52&nbsp;68&nbsp;88&nbsp;103&nbsp;117&nbsp;126&nbsp;138&nbsp;149&nbsp;163&nbsp;177&nbsp;192&nbsp;207&nbsp;223&nbsp;239</spanx></c>
2481 <c>30</c>
2482 <c><spanx style="vbare">16&nbsp;29&nbsp;47&nbsp;61&nbsp;76&nbsp;&nbsp;90&nbsp;106&nbsp;119&nbsp;133&nbsp;147&nbsp;161&nbsp;176&nbsp;193&nbsp;209&nbsp;224&nbsp;240</spanx></c>
2483 <c>31</c>
2484 <c><spanx style="vbare">15&nbsp;21&nbsp;35&nbsp;50&nbsp;61&nbsp;&nbsp;73&nbsp;&nbsp;86&nbsp;&nbsp;97&nbsp;110&nbsp;119&nbsp;129&nbsp;141&nbsp;175&nbsp;198&nbsp;218&nbsp;237</spanx></c>
2485 </texttable>
2486
2487 <t>
2488 Given the stage-1 codebook entry cb1_Q8[], the stage-2 residual res_Q10[], and
2489  their corresponding weights, w_Q9[], the reconstructed normalized LSF
2490  coefficients are
2491 <figure align="center">
2492 <artwork align="center"><![CDATA[
2493 NLSF_Q15[k] = (cb1_Q8[k]<<7) + (res_Q10[k]<<14)/w_Q9[k] ,
2494 ]]></artwork>
2495 </figure>
2496  where the division is exact integer division.
2497 However, nothing in either the reconstruction process or the
2498  quantization process in the encoder thus far guarantees that the coefficients
2499  are monotonically increasing and separated well enough to ensure a stable
2500  filter.
2501 When using the reference encoder, roughly 2% of frames violate this constraint.
2502 The next section describes a stabilization procedure used to make these
2503  guarantees.
2504 </t>
2505
2506 </section>
2507
2508 <section anchor="silk_nlsf_stabilization" title="Normalized LSF Stabilization">
2509 <t>
2510 The normalized LSF stabilization procedure is implemented in
2511  silk_NLSF_stabilize() (silk_NLSF_stabilize.c).
2512 This process ensures that consecutive values of the normalized LSF
2513  coefficients, NLSF_Q15[], are spaced some minimum distance apart
2514  (predetermined to be the 0.01 percentile of a large training set).
2515 <xref target="silk_nlsf_min_spacing"/> gives the minimum spacings for NB and MB
2516  and those for WB, where row k is the minimum allowed value of
2517  NLSF_Q[k]-NLSF_Q[k-1].
2518 For the purposes of computing this spacing for the first and last coefficient,
2519  NLSF_Q15[-1] is taken to be 0, and NLSF_Q15[d_LPC] is taken to be 32768.
2520 </t>
2521
2522 <texttable anchor="silk_nlsf_min_spacing"
2523            title="Minimum Spacing for Normalized LSF Coefficients">
2524 <ttcol>Coefficient</ttcol>
2525 <ttcol align="right">NB and MB</ttcol>
2526 <ttcol align="right">WB</ttcol>
2527  <c>0</c> <c>250</c> <c>100</c>
2528  <c>1</c>   <c>3</c>   <c>3</c>
2529  <c>2</c>   <c>6</c>  <c>40</c>
2530  <c>3</c>   <c>3</c>   <c>3</c>
2531  <c>4</c>   <c>3</c>   <c>3</c>
2532  <c>5</c>   <c>3</c>   <c>3</c>
2533  <c>6</c>   <c>4</c>   <c>5</c>
2534  <c>7</c>   <c>3</c>  <c>14</c>
2535  <c>8</c>   <c>3</c>  <c>14</c>
2536  <c>9</c>   <c>3</c>  <c>10</c>
2537 <c>10</c> <c>461</c>  <c>11</c>
2538 <c>11</c>       <c/>   <c>3</c>
2539 <c>12</c>       <c/>   <c>8</c>
2540 <c>13</c>       <c/>   <c>9</c>
2541 <c>14</c>       <c/>   <c>7</c>
2542 <c>15</c>       <c/>   <c>3</c>
2543 <c>16</c>       <c/> <c>347</c>
2544 </texttable>
2545
2546 <t>
2547 The procedure starts off by trying to make small adjustments which attempt to
2548  minimize the amount of distortion introduced.
2549 After 20 such adjustments, it falls back to a more direct method which
2550  guarantees the constraints are enforced but may require large adjustments.
2551 </t>
2552 <t>
2553 Let NDeltaMin_Q15[k] be the minimum required spacing for the current audio
2554  bandwidth from <xref target="silk_nlsf_min_spacing"/>.
2555 First, the procedure finds the index i where
2556  NLSF_Q15[i]&nbsp;-&nbsp;NLSF_Q15[i-1]&nbsp;-&nbsp;NDeltaMin_Q15[i] is the
2557  smallest, breaking ties by using the lower value of i.
2558 If this value is non-negative, then the stabilization stops; the coefficients
2559  satisfy all the constraints.
2560 Otherwise, if i&nbsp;==&nbsp;0, it sets NLSF_Q15[0] to NDeltaMin_Q15[0], and if
2561  i&nbsp;==&nbsp;d_LPC, it sets NLSF_Q15[d_LPC-1] to
2562  (32768&nbsp;-&nbsp;NDeltaMin_Q15[d_LPC]).
2563 For all other values of i, both NLSF_Q15[i-1] and NLSF_Q15[i] are updated as
2564  follows:
2565 <figure align="center">
2566 <artwork align="center"><![CDATA[
2567                                       i-1
2568                                       __
2569  min_center_Q15 = (NDeltaMin[i]>>1) + \  NDeltaMin[k]
2570                                       /_
2571                                       k=0
2572                                              d_LPC
2573                                               __
2574  max_center_Q15 = 32768 - (NDeltaMin[i]>>1) - \  NDeltaMin[k]
2575                                               /_
2576                                              k=i+1
2577 center_freq_Q15 = clamp(min_center_Q15[i],
2578                         (NLSF_Q15[i-1] + NLSF_Q15[i] + 1)>>1,
2579                         max_center_Q15[i])
2580
2581  NLSF_Q15[i-1] = center_freq_Q15 - (NDeltaMin_Q15[i]>>1)
2582
2583    NLSF_Q15[i] = NLSF_Q15[i-1] + NDeltaMin_Q15[i] .
2584 ]]></artwork>
2585 </figure>
2586 Then the procedure repeats again, until it has either executed 20 times or
2587  has stopped because the coefficients satisfy all the constraints.
2588 </t>
2589 <t>
2590 After the 20th repetition of the above procedure, the following fallback
2591  procedure executes once.
2592 First, the values of NLSF_Q15[k] for 0&nbsp;&lt;=&nbsp;k&nbsp;&lt;&nbsp;d_LPC
2593  are sorted in ascending order.
2594 Then for each value of k from 0 to d_LPC-1, NLSF_Q15[k] is set to
2595 <figure align="center">
2596 <artwork align="center"><![CDATA[
2597 max(NLSF_Q15[k], NLSF_Q15[k-1] + NDeltaMin_Q15[k]) .
2598 ]]></artwork>
2599 </figure>
2600 Next, for each value of k from d_LPC-1 down to 0, NLSF_Q15[k] is set to
2601 <figure align="center">
2602 <artwork align="center"><![CDATA[
2603 min(NLSF_Q15[k], NLSF_Q15[k+1] - NDeltaMin_Q15[k+1]) .
2604 ]]></artwork>
2605 </figure>
2606 </t>
2607
2608 </section>
2609
2610 <section anchor="silk_nlsf_interpolation" title="Normalized LSF Interpolation">
2611 <t>
2612 For 20&nbsp;ms SILK frames, the first half of the frame (i.e., the first two
2613  subframes) may use normalized LSF coefficients that are interpolated between
2614  the decoded LSFs for the most recent coded frame (in the same channel) and the
2615  current frame.
2616 A Q2 interpolation factor follows the LSF coefficient indices in the bitstream,
2617  which is decoded using the PDF in <xref target="silk_nlsf_interp_pdf"/>.
2618 This happens in silk_decode_indices() (silk_decode_indices.c).
2619 For the first frame after a decoder reset, when no prior LSF coefficients are
2620  available, the decoder still decodes this factor, but ignores its value and
2621  always uses 4 instead.
2622 For 10&nbsp;ms SILK frames, this factor is not stored at all.
2623 </t>
2624
2625 <texttable anchor="silk_nlsf_interp_pdf"
2626            title="PDF for Normalized LSF Interpolation Index">
2627 <ttcol>PDF</ttcol>
2628 <c>{13, 22, 29, 11, 181}/256</c>
2629 </texttable>
2630
2631 <t>
2632 Let n2_Q15[k] be the normalized LSF coefficients decoded by the procedure in
2633  <xref target="silk_nlsfs"/>, n0_Q15[k] be the LSF coefficients
2634  decoded for the prior frame, and w_Q2 be the interpolation factor.
2635 Then the normalized LSF coefficients used for the first half of a 20&nbsp;ms
2636  frame, n1_Q15[k], are
2637 <figure align="center">
2638 <artwork align="center"><![CDATA[
2639 n1_Q15[k] = n0_Q15[k] + (w_Q2*(n2_Q15[k] - n0_Q15[k]) >> 2) .
2640 ]]></artwork>
2641 </figure>
2642 This interpolation is performed in silk_decode_parameters()
2643  (silk_decode_parameters.c).
2644 </t>
2645 </section>
2646
2647 <section anchor="silk_nlsf2lpc"
2648  title="Converting Normalized LSFs to LPC Coefficients">
2649 <t>
2650 Any LPC filter A(z) can be split into a symmetric part P(z) and an
2651  anti-symmetric part Q(z) such that
2652 <figure align="center">
2653 <artwork align="center"><![CDATA[
2654           d_LPC
2655            __         -k   1
2656 A(z) = 1 - \  a[k] * z   = - * (P(z) + Q(z))
2657            /_              2
2658            k=1
2659 ]]></artwork>
2660 </figure>
2661 with
2662 <figure align="center">
2663 <artwork align="center"><![CDATA[
2664                -d_LPC-1      -1
2665 P(z) = A(z) + z         * A(z  )
2666
2667                -d_LPC-1      -1
2668 Q(z) = A(z) - z         * A(z  ) .
2669 ]]></artwork>
2670 </figure>
2671 The even normalized LSF coefficients correspond to a pair of conjugate roots of
2672  P(z), while the odd coefficients correspond to a pair of conjugate roots of
2673  Q(z), all of which lie on the unit circle.
2674 In addition, P(z) has a root at pi and Q(z) has a root at 0.
2675 Thus, they may be reconstructed mathematically from a set of normalized LSF
2676  coefficients, n[k], as
2677 <figure align="center">
2678 <artwork align="center"><![CDATA[
2679                  d_LPC/2-1
2680              -1     ___                        -1    -2
2681 P(z) = (1 + z  ) *  | |  (1 - 2*cos(pi*n[2*k])*z  + z  )
2682                     k=0
2683
2684                  d_LPC/2-1
2685              -1     ___                          -1    -2
2686 Q(z) = (1 - z  ) *  | |  (1 - 2*cos(pi*n[2*k+1])*z  + z  )
2687                     k=0
2688 ]]></artwork>
2689 </figure>
2690 </t>
2691 <t>
2692 However, SILK performs this reconstruction using a fixed-point approximation so
2693  that all decoders can reproduce it in a bit-exact manner to avoid prediction
2694  drift.
2695 The function silk_NLSF2A() (silk_NLSF2A.c) implements this procedure.
2696 </t>
2697 <t>
2698 To start, it approximates cos(pi*n[k]) using a table lookup with linear
2699  interpolation.
2700 The encoder SHOULD use the inverse of this piecewise linear approximation,
2701  rather than the true inverse of the cosine function, when deriving the
2702  normalized LSF coefficients.
2703 </t>
2704 <t>
2705 The top 7 bits of each normalized LSF coefficient index a value in the table,
2706  and the next 8 bits interpolate between it and the next value.
2707 Let i&nbsp;=&nbsp;n[k]&gt;&gt;8 be the integer index and
2708  f&nbsp;=&nbsp;n[k]&amp;255 be the fractional part of a given coefficient.
2709 Then the approximated cosine, c_Q17[k], is
2710 <figure align="center">
2711 <artwork align="center"><![CDATA[
2712 c_Q17[k] = (cos_Q13[i]*256 + (cos_Q13[i+1]-cos_Q13[i])*f + 8) >> 4 ,
2713 ]]></artwork>
2714 </figure>
2715  where cos_Q13[i] is the corresponding entry of
2716  <xref target="silk_cos_table"/>.
2717 </t>
2718
2719 <texttable anchor="silk_cos_table"
2720            title="Q13 Cosine Table for LSF Conversion">
2721 <ttcol align="right"></ttcol>
2722 <ttcol align="right">0</ttcol>
2723 <ttcol align="right">1</ttcol>
2724 <ttcol align="right">2</ttcol>
2725 <ttcol align="right">3</ttcol>
2726 <c>0</c>
2727  <c>8192</c> <c>8190</c> <c>8182</c> <c>8170</c>
2728 <c>4</c>
2729  <c>8152</c> <c>8130</c> <c>8104</c> <c>8072</c>
2730 <c>8</c>
2731  <c>8034</c> <c>7994</c> <c>7946</c> <c>7896</c>
2732 <c>12</c>
2733  <c>7840</c> <c>7778</c> <c>7714</c> <c>7644</c>
2734 <c>16</c>
2735  <c>7568</c> <c>7490</c> <c>7406</c> <c>7318</c>
2736 <c>20</c>
2737  <c>7226</c> <c>7128</c> <c>7026</c> <c>6922</c>
2738 <c>24</c>
2739  <c>6812</c> <c>6698</c> <c>6580</c> <c>6458</c>
2740 <c>28</c>
2741  <c>6332</c> <c>6204</c> <c>6070</c> <c>5934</c>
2742 <c>32</c>
2743  <c>5792</c> <c>5648</c> <c>5502</c> <c>5352</c>
2744 <c>36</c>
2745  <c>5198</c> <c>5040</c> <c>4880</c> <c>4718</c>
2746 <c>40</c>
2747  <c>4552</c> <c>4382</c> <c>4212</c> <c>4038</c>
2748 <c>44</c>
2749  <c>3862</c> <c>3684</c> <c>3502</c> <c>3320</c>
2750 <c>48</c>
2751  <c>3136</c> <c>2948</c> <c>2760</c> <c>2570</c>
2752 <c>52</c>
2753  <c>2378</c> <c>2186</c> <c>1990</c> <c>1794</c>
2754 <c>56</c>
2755  <c>1598</c> <c>1400</c> <c>1202</c> <c>1002</c>
2756 <c>60</c>
2757   <c>802</c>  <c>602</c>  <c>402</c>  <c>202</c>
2758 <c>64</c>
2759     <c>0</c> <c>-202</c> <c>-402</c> <c>-602</c>
2760 <c>68</c>
2761  <c>-802</c><c>-1002</c><c>-1202</c><c>-1400</c>
2762 <c>72</c>
2763 <c>-1598</c><c>-1794</c><c>-1990</c><c>-2186</c>
2764 <c>76</c>
2765 <c>-2378</c><c>-2570</c><c>-2760</c><c>-2948</c>
2766 <c>80</c>
2767 <c>-3136</c><c>-3320</c><c>-3502</c><c>-3684</c>
2768 <c>84</c>
2769 <c>-3862</c><c>-4038</c><c>-4212</c><c>-4382</c>
2770 <c>88</c>
2771 <c>-4552</c><c>-4718</c><c>-4880</c><c>-5040</c>
2772 <c>92</c>
2773 <c>-5198</c><c>-5352</c><c>-5502</c><c>-5648</c>
2774 <c>96</c>
2775 <c>-5792</c><c>-5934</c><c>-6070</c><c>-6204</c>
2776 <c>100</c>
2777 <c>-6332</c><c>-6458</c><c>-6580</c><c>-6698</c>
2778 <c>104</c>
2779 <c>-6812</c><c>-6922</c><c>-7026</c><c>-7128</c>
2780 <c>108</c>
2781 <c>-7226</c><c>-7318</c><c>-7406</c><c>-7490</c>
2782 <c>112</c>
2783 <c>-7568</c><c>-7644</c><c>-7714</c><c>-7778</c>
2784 <c>116</c>
2785 <c>-7840</c><c>-7896</c><c>-7946</c><c>-7994</c>
2786 <c>120</c>
2787 <c>-8034</c><c>-8072</c><c>-8104</c><c>-8130</c>
2788 <c>124</c>
2789 <c>-8152</c><c>-8170</c><c>-8182</c><c>-8190</c>
2790 <c>128</c>
2791 <c>-8192</c>        <c/>        <c/>        <c/>
2792 </texttable>
2793
2794 <t>
2795 Given the list of cosine values, silk_NLSF2A_find_poly() (silk_NLSF2A.c)
2796  computes the coefficients of P and Q, described here via a simple recurrence.
2797 Let p_Q16[k][j] and q_Q16[k][j] be the coefficients of the products of the
2798  first (k+1) root pairs for P and Q, with j indexing the coefficient number.
2799 Only the first (k+2) coefficients are needed, as the products are symmetric.
2800 Let p_Q16[0][0]&nbsp;=&nbsp;q_Q16[0][0]&nbsp;=&nbsp;1&lt;&lt;16,
2801  p_Q16[0][1]&nbsp;=&nbsp;-c_Q17[0], q_Q16[0][1]&nbsp;=&nbsp;-c_Q17[1], and
2802  d2&nbsp;=&nbsp;d_LPC/2.
2803 As boundary conditions, assume
2804  p_Q16[k][j]&nbsp;=&nbsp;q_Q16[k][j]&nbsp;=&nbsp;0 for all
2805  j&nbsp;&lt;&nbsp;0.
2806 Also, assume p_Q16[k][k+2]&nbsp;=&nbsp;p_Q16[k][k] and
2807  q_Q16[k][k+2]&nbsp;=&nbsp;q_Q16[k][k] (because of the symmetry).
2808 Then, for 0&nbsp;&lt;k&nbsp;&lt;&nbsp;d2 and 0&nbsp;&lt;=&nbsp;j&nbsp;&lt;=&nbsp;k+1,
2809 <figure align="center">
2810 <artwork align="center"><![CDATA[
2811 p_Q16[k][j] = p_Q16[k-1][j] + p_Q16[k-1][j-2]
2812               - ((c_Q17[2*k]*p_Q16[k-1][j-1] + 32768)>>16) ,
2813
2814 q_Q16[k][j] = q_Q16[k-1][j] + q_Q16[k-1][j-2]
2815               - ((c_Q17[2*k+1]*q_Q16[k-1][j-1] + 32768)>>16) .
2816 ]]></artwork>
2817 </figure>
2818 The use of Q17 values for the cosine terms in an otherwise Q16 expression
2819  implicitly scales them by a factor of 2.
2820 The multiplications in this recurrence may require up to 48 bits of precision
2821  in the result to avoid overflow.
2822 In practice, each row of the recurrence only depends on the previous row, so an
2823  implementation does not need to store all of them.
2824 </t>
2825 <t>
2826 silk_NLSF2A() uses the values from the last row of this recurrence to
2827  reconstruct a 32-bit version of the LPC filter (without the leading 1.0
2828  coefficient), a32_Q17[k], 0&nbsp;&lt;=&nbsp;k&nbsp;&lt;&nbsp;d2:
2829 <figure align="center">
2830 <artwork align="center"><![CDATA[
2831 a32_Q17[k]         = -(q_Q16[d2-1][k+1] - q_Q16[d2-1][k])
2832                      - (p_Q16[d2-1][k+1] + p_Q16[d2-1][k])) ,
2833
2834 a32_Q17[d_LPC-k-1] =  (q_Q16[d2-1][k+1] - q_Q16[d2-1][k])
2835                      - (p_Q16[d2-1][k+1] + p_Q16[d2-1][k])) .
2836 ]]></artwork>
2837 </figure>
2838 The sum and difference of two terms from each of the p_Q16 and q_Q16
2839  coefficient lists reflect the (1&nbsp;+&nbsp;z**-1) and
2840  (1&nbsp;-&nbsp;z**-1) factors of P and Q, respectively.
2841 The promotion of the expression from Q16 to Q17 implicitly scales the result
2842  by 1/2.
2843 </t>
2844 </section>
2845
2846 <section anchor="silk_lpc_range_limit"
2847  title="Limiting the Range of the LPC Coefficients">
2848 <t>
2849 The a32_Q17[] coefficients are too large to fit in a 16-bit value, which
2850  significantly increases the cost of applying this filter in fixed-point
2851  decoders.
2852 Reducing them to Q12 precision doesn't incur any significant quality loss,
2853  but still does not guarantee they will fit.
2854 silk_NLSF2A() applies up to 10 rounds of bandwidth expansion to limit
2855  the dynamic range of these coefficients.
2856 Even floating-point decoders SHOULD perform these steps, to avoid mismatch.
2857 </t>
2858 <t>
2859 For each round, the process first finds the index k such that abs(a32_Q17[k])
2860  is largest, breaking ties by choosing the lowest value of k.
2861 Then, it computes the corresponding Q12 precision value, maxabs_Q12, subject to
2862  an upper bound to avoid overflow in subsequent computations:
2863 <figure align="center">
2864 <artwork align="center"><![CDATA[
2865 maxabs_Q12 = min((maxabs_Q17 + 16) >> 5, 163838) .
2866 ]]></artwork>
2867 </figure>
2868 If this is larger than 32767, the procedure derives the chirp factor,
2869  sc_Q16[0], to use in the bandwidth expansion as
2870 <figure align="center">
2871 <artwork align="center"><![CDATA[
2872                     (maxabs_Q12 - 32767) << 14
2873 sc_Q16[0] = 65470 - -------------------------- ,
2874                     (maxabs_Q12 * (k+1)) >> 2
2875 ]]></artwork>
2876 </figure>
2877  where the division here is exact integer division.
2878 This is an approximation of the chirp factor needed to reduce the target
2879  coefficient to 32767, though it is both less than 0.999 and, for
2880  k&nbsp;&gt;&nbsp;0 when maxabs_Q12 is much greater than 32767, still slightly
2881  too large.
2882 </t>
2883 <t>
2884 silk_bwexpander_32() (silk_bwexpander_32.c) performs the bandwidth expansion
2885  (again, only when maxabs_Q12 is greater than 32767) using the following
2886  recurrence:
2887 <figure align="center">
2888 <artwork align="center"><![CDATA[
2889  a32_Q17[k] = (a32_Q17[k]*sc_Q16[k]) >> 16
2890
2891 sc_Q16[k+1] = (sc_Q16[0]*sc_Q16[k] + 32768) >> 16
2892 ]]></artwork>
2893 </figure>
2894 The first multiply may require up to 48 bits of precision in the result to
2895  avoid overflow.
2896 The second multiply must be unsigned to avoid overflow with only 32 bits of
2897  precision.
2898 The reference implementation uses a slightly more complex formulation that
2899  avoids the 32-bit overflow using signed multiplication, but is otherwise
2900  equivalent.
2901 </t>
2902 <t>
2903 After 10 rounds of bandwidth expansion are performed, they are simply saturated
2904  to 16 bits:
2905 <figure align="center">
2906 <artwork align="center"><![CDATA[
2907 a32_Q17[k] = clamp(-32768, (a32_Q17[k]+16) >> 5, 32767) << 5 .
2908 ]]></artwork>
2909 </figure>
2910 Because this performs the actual saturation in the Q12 domain, but converts the
2911  coefficients back to the Q17 domain for the purposes of prediction gain
2912  limiting, this step must be performed after the 10th round of bandwidth
2913  expansion, regardless of whether or not the Q12 version of any coefficient
2914  still overflows a 16-bit integer.
2915 This saturation is not performed if maxabs_Q12 drops to 32767 or less prior to
2916  the 10th round.
2917 </t>
2918 </section>
2919
2920 <section anchor="silk_lpc_gain_limit"
2921  title="Limiting the Prediction Gain of the LPC Filter">
2922 <t>
2923 Even if the Q12 coefficients would fit, the resulting filter may still have a
2924  significant gain (especially for voiced sounds), making the filter unstable.
2925 silk_NLSF2A() applies up to 18 additional rounds of bandwidth expansion to
2926  limit the prediction gain.
2927 Instead of controlling the amount of bandwidth expansion using the prediction
2928  gain itself (which may diverge to infinity for an unstable filter),
2929  silk_NLSF2A() uses LPC_inverse_pred_gain_QA() (silk_LPC_inv_pred_gain.c)
2930  to compute the reflection coefficients associated with the filter.
2931 The filter is stable if and only if the magnitude of these coefficients is
2932  sufficiently less than one.
2933 The reflection coefficients, rc[k], can be computed using a simple Levinson
2934  recurrence, initialized with the LPC coefficients
2935  a[d_LPC-1][n]&nbsp;=&nbsp;a[n], and then updated via
2936 <figure align="center">
2937 <artwork align="center"><![CDATA[
2938     rc[k] = -a[k][k] ,
2939
2940             a[k][n] - a[k][k-n-1]*rc[k]
2941 a[k-1][n] = --------------------------- .
2942                              2
2943                     1 - rc[k]
2944 ]]></artwork>
2945 </figure>
2946 </t>
2947 <t>
2948 However, LPC_inverse_pred_gain_QA() approximates this using fixed-point
2949  arithmetic to guarantee reproducible results across platforms and
2950  implementations.
2951 It is important to run on the real Q12 coefficients that will be used during
2952  reconstruction, because small changes in the coefficients can make a stable
2953  filter unstable, but increasing the precision back to Q16 allows more accurate
2954  computation of the reflection coefficients.
2955 Thus, let
2956 <figure align="center">
2957 <artwork align="center"><![CDATA[
2958 a32_Q16[d_LPC-1][n] = ((a32_Q17[n] + 16) >> 5) << 4
2959 ]]></artwork>
2960 </figure>
2961  be the Q16 representation of the Q12 version of the LPC coefficients that will
2962  eventually be used.
2963 Then for each k from d_LPC-1 down to 0, if
2964  abs(a32_Q16[k][k])&nbsp;&gt;&nbsp;65520, the filter is unstable and the
2965  recurrence stops.
2966 Otherwise, the row k-1 of a32_Q16 is computed from row k as
2967 <figure align="center">
2968 <artwork align="center"><![CDATA[
2969       rc_Q31[k] = -a32_Q16[k][k] << 15 ,
2970
2971      div_Q30[k] = (1<<30) - 1 - (rc_Q31[k]*rc_Q31[k] >> 32) ,
2972
2973           b1[k] = ilog(div_Q30[k]) - 16 ,
2974
2975                         (1<<29) - 1
2976      inv_Qb1[k] = ----------------------- ,
2977                   div_Q30[k] >> (b1[k]+1)
2978
2979      err_Q29[k] = (1<<29)
2980                   - ((div_Q30[k]<<(15-b1[k]))*inv_Qb1[k] >> 16) ,
2981
2982      mul_Q16[k] = ((inv_Qb1[k] << 16)
2983                    + (err_Q29[k]*inv_Qb1[k] >> 13)) >> b1[k] ,
2984
2985           b2[k] = ilog(mul_Q16[k]) - 15 ,
2986
2987   t_Q16[k-1][n] = a32_Q16[k][n]
2988                   - ((a32_Q16[k][k-n-1]*rc_Q31[k] >> 32) << 1) ,
2989
2990 a32_Q16[k-1][n] = ((t_Q16[k-1][n] *
2991                     (mul_Q16[k] << (16-b2[k]))) >> 32) << b2[k] .
2992 ]]></artwork>
2993 </figure>
2994 Here, rc_Q30[k] are the reflection coefficients.
2995 div_Q30[k] is the denominator for each iteration, and mul_Q16[k] is its
2996  multiplicative inverse.
2997 inv_Qb1[k], which ranges from 16384 to 32767, is a low-precision version of
2998  that inverse (with b1[k] fractional bits, where b1[k] ranges from 3 to 14).
2999 err_Q29[k] is the residual error, ranging from -32392 to 32763, which is used
3000  to improve the accuracy.
3001 t_Q16[k-1][n], 0&nbsp;&lt;=&nbsp;n&nbsp;&lt;&nbsp;k, are the numerators for the
3002  next row of coefficients in the recursion, and a32_Q16[k-1][n] is the final
3003  version of that row.
3004 Every multiply in this procedure except the one used to compute mul_Q16[k]
3005  requires more than 32 bits of precision, but otherwise all intermediate
3006  results fit in 32 bits or less.
3007 In practice, because each row only depends on the next one, an implementation
3008  does not need to store them all.
3009 If abs(a32_Q16[k][k])&nbsp;&lt;=&nbsp;65520 for
3010  0&nbsp;&lt;=&nbsp;k&nbsp;&lt;&nbsp;d_LPC, then the filter is considered stable.
3011 </t>
3012 <t>
3013 On round i, 1&nbsp;&lt;=&nbsp;i&nbsp;&lt;=&nbsp;18, if the filter passes this
3014  stability check, then this procedure stops, and the final LPC coefficients to
3015  use for reconstruction<!--TODO: In section...--> are
3016 <figure align="center">
3017 <artwork align="center"><![CDATA[
3018 a_Q12[k] = (a32_Q17[k] + 16) >> 5 .
3019 ]]></artwork>
3020 </figure>
3021 Otherwise, a round of bandwidth expansion is applied using the same procedure
3022  as in <xref target="silk_lpc_range_limit"/>, with
3023 <figure align="center">
3024 <artwork align="center"><![CDATA[
3025 sc_Q16[0] = 65536 - i*(i+9) .
3026 ]]></artwork>
3027 </figure>
3028 If, after the 18th round, the filter still fails the stability check, then
3029  a_Q12[k] is set to 0 for all k.
3030 </t>
3031 </section>
3032
3033 </section>
3034
3035 <section anchor="silk_ltp_params"
3036  title="Long-Term Prediction (LTP) Parameters">
3037 <t>
3038 After the normalized LSF indices and, for 20&nbsp;ms frames, the LSF
3039  interpolation index, voiced frames (see <xref target="silk_frame_type"/>)
3040  include additional Long-Term Prediction (LTP) parameters.
3041 There is one primary lag index for each SILK frame, but this is refined to
3042  produce a separate lag index per subframe using a vector quantizer.
3043 Each subframe also gets its own prediction gain coefficient.
3044 </t>
3045
3046 <section anchor="silk_ltp_lags" title="Pitch Lags">
3047 <t>
3048 The primary lag index is coded either relative to the primary lag of the prior
3049  frame or as an absolute index.
3050 Like the quantization gains, the first LBRR frame, an LBRR frame where the
3051  previous LBRR frame was not coded, and the first regular SILK frame in each
3052  channel of an Opus frame all code the pitch lag as an absolute index.
3053 When the most recent coded frame in the current channel was not voiced, this
3054  also forces absolute coding.
3055 In particular, unlike an LBRR frame where the previous frame is not coded, in a
3056  60&nbsp;ms stereo Opus frame, if the first and third regular SILK frames
3057  in the side channel are coded, voiced frames, but the second is not coded, the
3058  third still uses relative coding.
3059 </t>
3060 <t>
3061 With absolute coding, the primary pitch lag may range from 2&nbsp;ms
3062  (inclusive) up to 18&nbsp;ms (exclusive), corresponding to pitches from
3063  500&nbsp;Hz down to 55.6&nbsp;Hz, respectively.
3064 It is comprised of a high part and a low part, where the decoder reads the high
3065  part using the 32-entry codebook in <xref target="silk_abs_pitch_high_pdf"/>
3066  and the low part using the codebook corresponding to the current audio
3067  bandwidth from <xref target="silk_abs_pitch_low_pdf"/>.
3068 The final primary pitch lag is then
3069 <figure align="center">
3070 <artwork align="center"><![CDATA[
3071 lag = lag_high*lag_scale + lag_low + lag_min
3072 ]]></artwork>
3073 </figure>
3074  where lag_high is the high part, lag_low is the low part, and lag_scale
3075  and lag_min are the values from the "Scale" and "Minimum Lag" columns of
3076  <xref target="silk_abs_pitch_low_pdf"/>, respectively.
3077 </t>
3078
3079 <texttable anchor="silk_abs_pitch_high_pdf"
3080  title="PDF for High Part of Primary Pitch Lag">
3081 <ttcol align="left">PDF</ttcol>
3082 <c>{3,   3,   6,  11,  21,  30,  32,  19,
3083    11,  10,  12,  13,  13,  12,  11,   9,
3084     8,   7,   6,   4,   2,   2,   2,   1,
3085     1,   1,   1,   1,   1,   1,   1,   1}/256</c>
3086 </texttable>
3087
3088 <texttable anchor="silk_abs_pitch_low_pdf"
3089  title="PDF for Low Part of Primary Pitch Lag">
3090 <ttcol>Audio Bandwidth</ttcol>
3091 <ttcol>PDF</ttcol>
3092 <ttcol>Scale</ttcol>
3093 <ttcol>Minimum Lag</ttcol>
3094 <ttcol>Maximum Lag</ttcol>
3095 <c>NB</c> <c>{64, 64, 64, 64}/256</c>                 <c>4</c> <c>16</c> <c>144</c>
3096 <c>MB</c> <c>{43, 42, 43, 43, 42, 43}/256</c>         <c>6</c> <c>24</c> <c>216</c>
3097 <c>WB</c> <c>{32, 32, 32, 32, 32, 32, 32, 32}/256</c> <c>8</c> <c>32</c> <c>288</c>
3098 </texttable>
3099
3100 <t>
3101 All frames that do not use absolute coding for the primary lag index use
3102  relative coding instead.
3103 The decoder reads a single delta value using the 21-entry PDF in
3104  <xref target="silk_rel_pitch_pdf"/>.
3105 If the resulting value is zero, it falls back to the absolute coding procedure
3106  from the prior paragraph.
3107 Otherwise, the final primary pitch lag is then
3108 <figure align="center">
3109 <artwork align="center"><![CDATA[
3110 lag = lag_prev + (delta_lag_index - 9)
3111 ]]></artwork>
3112 </figure>
3113  where lag_prev is the primary pitch lag from the most recent frame in the same
3114  channel and delta_lag_index is the value just decoded.
3115 This allows a per-frame change in the pitch lag of -8 to +11 samples.
3116 The decoder does no clamping at this point, so this value can fall outside the
3117  range of 2&nbsp;ms to 18&nbsp;ms, and the decoder must use this unclamped
3118  value when using relative coding in the next SILK frame (if any).
3119 However, because an Opus frame can use relative coding for at most two
3120  consecutive SILK frames, integer overflow should not be an issue.
3121 </t>
3122
3123 <texttable anchor="silk_rel_pitch_pdf"
3124  title="PDF for Primary Pitch Lag Change">
3125 <ttcol align="left">PDF</ttcol>
3126 <c>{46,  2,  2,  3,  4,  6, 10, 15,
3127     26, 38, 30, 22, 15, 10,  7,  6,
3128      4,  4,  2,  2,  2}/256</c>
3129 </texttable>
3130
3131 <t>
3132 After the primary pitch lag, a "pitch contour", stored as a single entry from
3133  one of four small VQ codebooks, gives lag offsets for each subframe in the
3134  current SILK frame.
3135 The codebook index is decoded using one of the PDFs in
3136  <xref target="silk_pitch_contour_pdfs"/> depending on the current frame size
3137  and audio bandwidth.
3138 <xref target="silk_pitch_contour_cb_nb10ms"/> through
3139  <xref target="silk_pitch_contour_cb_mbwb20ms"/> give the corresponding offsets
3140  to apply to the primary pitch lag for each subframe given the decoded codebook
3141  index.
3142 </t>
3143
3144 <texttable anchor="silk_pitch_contour_pdfs"
3145  title="PDFs for Subframe Pitch Contour">
3146 <ttcol>Audio Bandwidth</ttcol>
3147 <ttcol>SILK Frame Size</ttcol>
3148 <ttcol align="right">Codebook Size</ttcol>
3149 <ttcol>PDF</ttcol>
3150 <c>NB</c>       <c>10&nbsp;ms</c>  <c>3</c>
3151 <c>{143, 50, 63}/256</c>
3152 <c>NB</c>       <c>20&nbsp;ms</c> <c>11</c>
3153 <c>{68, 12, 21, 17, 19, 22, 30, 24,
3154     17, 16, 10}/256</c>
3155 <c>MB or WB</c> <c>10&nbsp;ms</c> <c>12</c>
3156 <c>{91, 46, 39, 19, 14, 12,  8,  7,
3157      6,  5,  5,  4}/256</c>
3158 <c>MB or WB</c> <c>20&nbsp;ms</c> <c>34</c>
3159 <c>{33, 22, 18, 16, 15, 14, 14, 13,
3160     13, 10,  9,  9,  8,  6,  6,  6,
3161      5,  4,  4,  4,  3,  3,  3,  2,
3162      2,  2,  2,  2,  2,  2,  1,  1,
3163      1,  1}/256</c>
3164 </texttable>
3165
3166 <texttable anchor="silk_pitch_contour_cb_nb10ms"
3167  title="Codebook Vectors for Subframe Pitch Contour: NB, 10&nbsp;ms Frames">
3168 <ttcol>Index</ttcol>
3169 <ttcol align="right">Subframe Offsets</ttcol>
3170 <c>0</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0</spanx></c>
3171 <c>1</c> <c><spanx style="vbare">&nbsp;1&nbsp;&nbsp;0</spanx></c>
3172 <c>2</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;1</spanx></c>
3173 </texttable>
3174
3175 <texttable anchor="silk_pitch_contour_cb_nb20ms"
3176  title="Codebook Vectors for Subframe Pitch Contour: NB, 20&nbsp;ms Frames">
3177 <ttcol>Index</ttcol>
3178 <ttcol align="right">Subframe Offsets</ttcol>
3179  <c>0</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0</spanx></c>
3180  <c>1</c> <c><spanx style="vbare">&nbsp;2&nbsp;&nbsp;1&nbsp;&nbsp;0&nbsp;-1</spanx></c>
3181  <c>2</c> <c><spanx style="vbare">-1&nbsp;&nbsp;0&nbsp;&nbsp;1&nbsp;&nbsp;2</spanx></c>
3182  <c>3</c> <c><spanx style="vbare">-1&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;1</spanx></c>
3183  <c>4</c> <c><spanx style="vbare">-1&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0</spanx></c>
3184  <c>5</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;1</spanx></c>
3185  <c>6</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;1&nbsp;&nbsp;1</spanx></c>
3186  <c>7</c> <c><spanx style="vbare">&nbsp;1&nbsp;&nbsp;1&nbsp;&nbsp;0&nbsp;&nbsp;0</spanx></c>
3187  <c>8</c> <c><spanx style="vbare">&nbsp;1&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0</spanx></c>
3188  <c>9</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;-1</spanx></c>
3189 <c>10</c> <c><spanx style="vbare">&nbsp;1&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;-1</spanx></c>
3190 </texttable>
3191
3192 <texttable anchor="silk_pitch_contour_cb_mbwb10ms"
3193  title="Codebook Vectors for Subframe Pitch Contour: MB or WB, 10&nbsp;ms Frames">
3194 <ttcol>Index</ttcol>
3195 <ttcol align="right">Subframe Offsets</ttcol>
3196  <c>0</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0</spanx></c>
3197  <c>1</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;1</spanx></c>
3198  <c>2</c> <c><spanx style="vbare">&nbsp;1&nbsp;&nbsp;0</spanx></c>
3199  <c>3</c> <c><spanx style="vbare">-1&nbsp;&nbsp;1</spanx></c>
3200  <c>4</c> <c><spanx style="vbare">&nbsp;1&nbsp;-1</spanx></c>
3201  <c>5</c> <c><spanx style="vbare">-1&nbsp;&nbsp;2</spanx></c>
3202  <c>6</c> <c><spanx style="vbare">&nbsp;2&nbsp;-1</spanx></c>
3203  <c>7</c> <c><spanx style="vbare">-2&nbsp;&nbsp;2</spanx></c>
3204  <c>8</c> <c><spanx style="vbare">&nbsp;2&nbsp;-2</spanx></c>
3205  <c>9</c> <c><spanx style="vbare">-2&nbsp;&nbsp;3</spanx></c>
3206 <c>10</c> <c><spanx style="vbare">&nbsp;3&nbsp;-2</spanx></c>
3207 <c>11</c> <c><spanx style="vbare">-3&nbsp;&nbsp;3</spanx></c>
3208 </texttable>
3209
3210 <texttable anchor="silk_pitch_contour_cb_mbwb20ms"
3211  title="Codebook Vectors for Subframe Pitch Contour: MB or WB, 20&nbsp;ms Frames">
3212 <ttcol>Index</ttcol>
3213 <ttcol align="right">Subframe Offsets</ttcol>
3214  <c>0</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0</spanx></c>
3215  <c>1</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;1&nbsp;&nbsp;1</spanx></c>
3216  <c>2</c> <c><spanx style="vbare">&nbsp;1&nbsp;&nbsp;1&nbsp;&nbsp;0&nbsp;&nbsp;0</spanx></c>
3217  <c>3</c> <c><spanx style="vbare">-1&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0</spanx></c>
3218  <c>4</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;1</spanx></c>
3219  <c>5</c> <c><spanx style="vbare">&nbsp;1&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0</spanx></c>
3220  <c>6</c> <c><spanx style="vbare">-1&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;1</spanx></c>
3221  <c>7</c> <c><spanx style="vbare">&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;-1</spanx></c>
3222  <c>8</c> <c><spanx style="vbare">-1&nbsp;&nbsp;0&nbsp;&nbsp;1&nbsp;&nbsp;2</spanx></c>
3223  <c>9</c> <c><spanx style="vbare">&nbsp;1&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;-1</spanx></c>
3224 <c>10</c> <c><spanx style="vbare">-2&nbsp;-1&nbsp;&nbsp;1&nbsp;&nbsp;2</spanx></c>
3225 <c>11</c> <c><spanx style="vbare">&nbsp;2&nbsp;&nbsp;1&nbsp;&nbsp;0&nbsp;-1</spanx></c>
3226 <c>12</c> <c><spanx style="vbare">-2&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;&nbsp;2</spanx></c>
3227 <c>13</c> <c><spanx style="vbare">-2&nbsp;&nbsp;0&nbsp;&nbsp;1&nbsp;&nbsp;3</spanx></c>
3228 <c>14</c> <c><spanx style="vbare">&nbsp;2&nbsp;&nbsp;1&nbsp;-1&nbsp;-2</spanx></c>
3229 <c>15</c> <c><spanx style="vbare">-3&nbsp;-1&nbsp;&nbsp;1&nbsp;&nbsp;3</spanx></c>
3230 <c>16</c> <c><spanx style="vbare">&nbsp;2&nbsp;&nbsp;0&nbsp;&nbsp;0&nbsp;-2</spanx></c>
3231 <c>17</c> <c><spanx style="vbare">&nbsp;3&nbsp;&nbsp;1&nbsp;&nbsp;0&nbsp;-2</spanx></c>
3232 <c>18</c> <c><spanx style="vbare">-3&nbsp;-1&nbsp;&nbsp;2&nbsp;&nbsp;4</spanx></c>
3233 <c>19</c> <c><spanx style="vbare">-4&nbsp;-1&nbsp;&nbsp;1&nbsp;&nbsp;4</spanx></c>
3234 <c>20</c> <c><spanx style="vbare">&nbsp;3&nbsp;&nbsp;1&nbsp;-1&nbsp;-3</spanx></c>
3235 <c>21</c> <c><spanx style="vbare">-4&nbsp;-1&nbsp;&nbsp;2&nbsp;&nbsp;5</spanx></c>
3236 <c>22</c> <c><spanx style="vbare">&nbsp;4&nbsp;&nbsp;2&nbsp;-1&nbsp;-3</spanx></c>
3237 <c>23</c> <c><spanx style="vbare">&nbsp;4&nbsp;&nbsp;1&nbsp;-1&nbsp;-4</spanx></c>
3238 <c>24</c> <c><spanx style="vbare">-5&nbsp;-1&nbsp;&nbsp;2&nbsp;&nbsp;6</spanx></c>
3239 <c>25</c> <c><spanx style="vbare">&nbsp;5&nbsp;&nbsp;2&nbsp;-1&nbsp;-4</spanx></c>
3240 <c>26</c> <c><spanx style="vbare">-6&nbsp;-2&nbsp;&nbsp;2&nbsp;&nbsp;6</spanx></c>
3241 <c>27</c> <c><spanx style="vbare">-5&nbsp;-2&nbsp;&nbsp;2&nbsp;&nbsp;5</spanx></c>
3242 <c>28</c> <c><spanx style="vbare">&nbsp;6&nbsp;&nbsp;2&nbsp;-1&nbsp;-5</spanx></c>
3243 <c>29</c> <c><spanx style="vbare">-7&nbsp;-2&nbsp;&nbsp;3&nbsp;&nbsp;8</spanx></c>
3244 <c>30</c> <c><spanx style="vbare">&nbsp;6&nbsp;&nbsp;2&nbsp;-2&nbsp;-6</spanx></c>
3245 <c>31</c> <c><spanx style="vbare">&nbsp;5&nbsp;&nbsp;2&nbsp;-2&nbsp;-5</spanx></c>
3246 <c>32</c> <c><spanx style="vbare">&nbsp;8&nbsp;&nbsp;3&nbsp;-2&nbsp;-7</spanx></c>
3247 <c>33</c> <c><spanx style="vbare">-9&nbsp;-3&nbsp;&nbsp;3&nbsp;&nbsp;9</spanx></c>
3248 </texttable>
3249
3250 <t>
3251 The final pitch lag for each subframe is assembled in silk_decode_pitch()
3252  (silk_decode_pitch.c).
3253 Let lag be the primary pitch lag for the current SILK frame, contour_index be
3254  index of the VQ codebook, and lag_cb[contour_index][k] be the corresponding
3255  entry of the codebook from the appropriate table given above for the k'th
3256  subframe.
3257 Then the final pitch lag for that subframe is
3258 <figure align="center">
3259 <artwork align="center"><![CDATA[
3260 pitch_lags[k] = clamp(lag_min, lag + lag_cb[contour_index][k],
3261                       lag_max)
3262 ]]></artwork>
3263 </figure>
3264  where lag_min and lag_max are the values from the "Minimum Lag" and
3265  "Maximum Lag" columns of <xref target="silk_abs_pitch_low_pdf"/>,
3266  respectively.
3267 </t>
3268
3269 </section>
3270
3271 <section anchor="silk_ltp_coeffs" title="LTP Filter Coefficients">
3272 <t>
3273 SILK can use a separate 5-tap pitch filter for each subframe.
3274 It selects the filter to use from one of three codebooks.
3275 The three codebooks each represent different rate-distortion trade-offs, with
3276  average rates of 1.61&nbsp;bits/subframe, 3.68&nbsp;bits/subframe, and
3277  4.85&nbsp;bits/subframe, respectively.
3278 </t>
3279
3280 <t>
3281 The importance of the filter coefficients generally depends on two factors: the
3282  periodicity of the signal and relative energy between the current subframe and
3283  the signal from one period earlier.
3284 Greater periodicity and decaying energy both lead to more important filter
3285  coefficients, and thus should be coded with lower distortion and higher rate.
3286 These properties are relatively stable over the duration of a single SILK
3287  frame, hence all of the subframes in a SILK frame must choose their filter
3288  from the same codebook.
3289 This is signaled with an explicitly-coded "periodicity index".
3290 This immediately follows the subframe pitch lags, and is coded using the
3291  3-entry PDF from <xref target="silk_perindex_pdf"/>.
3292 </t>
3293
3294 <texttable anchor="silk_perindex_pdf" title="Periodicity Index PDF">
3295 <ttcol>PDF</ttcol>
3296 <c>{77, 80, 99}/256</c>
3297 </texttable>
3298
3299 <t>
3300 The index of the filter to use for each subframe follows.
3301 They are all coded using the PDF from <xref target="silk_ltp_filter_pdfs"/>
3302  corresponding to the periodicity index.
3303 <xref target="silk_ltp_filter_coeffs0"/> through
3304  <xref target="silk_ltp_filter_coeffs2"/> contain the corresponding filter taps
3305  as signed Q7 integers.
3306 </t>
3307
3308 <texttable anchor="silk_ltp_filter_pdfs" title="LTP Filter PDFs">
3309 <ttcol>Periodicity Index</ttcol>
3310 <ttcol align="right">Codebook Size</ttcol>
3311 <ttcol>PDF</ttcol>
3312 <c>0</c>  <c>8</c> <c>{185, 15, 13, 13, 9, 9, 6, 6}/256</c>
3313 <c>1</c> <c>16</c> <c>{57, 34, 21, 20, 15, 13, 12, 13,
3314                        10, 10,  9, 10,  9,  8,  7,  8}/256</c>
3315 <c>2</c> <c>32</c> <c>{15, 16, 14, 12, 12, 12, 11, 11,
3316                        11, 10,  9,  9,  9,  9,  8,  8,
3317                         8,  8,  7,  7,  6,  6,  5,  4,
3318                         5,  4,  4,  4,  3,  4,  3,  2}/256</c>
3319 </texttable>
3320
3321 <texttable anchor="silk_ltp_filter_coeffs0"
3322  title="Codebook Vectors for LTP Filter, Periodicity Index 0">
3323 <ttcol>Index</ttcol>
3324 <ttcol align="right">Filter Taps (Q7)</ttcol>
3325  <c>0</c>
3326 <c><spanx style="vbare">&nbsp;&nbsp;4&nbsp;&nbsp;&nbsp;6&nbsp;&nbsp;24&nbsp;&nbsp;&nbsp;7&nbsp;&nbsp;&nbsp;5</spanx></c>
3327  <c>1</c>
3328 <c><spanx style="vbare">&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;0</spanx></c>
3329  <c>2</c>
3330 <c><spanx style="vbare">&nbsp;12&nbsp;&nbsp;28&nbsp;&nbsp;41&nbsp;&nbsp;13&nbsp;&nbsp;-4</spanx></c>
3331  <c>3</c>
3332 <c><spanx style="vbare">&nbsp;-9&nbsp;&nbsp;15&nbsp;&nbsp;42&nbsp;&nbsp;25&nbsp;&nbsp;14</spanx></c>
3333  <c>4</c>
3334 <c><spanx style="vbare">&nbsp;&nbsp;1&nbsp;&nbsp;-2&nbsp;&nbsp;62&nbsp;&nbsp;41&nbsp;&nbsp;-9</spanx></c>
3335  <c>5</c>
3336 <c><spanx style="vbare">-10&nbsp;&nbsp;37&nbsp;&nbsp;65&nbsp;&nbsp;-4&nbsp;&nbsp;&nbsp;3</spanx></c>
3337  <c>6</c>
3338 <c><spanx style="vbare">&nbsp;-6&nbsp;&nbsp;&nbsp;4&nbsp;&nbsp;66&nbsp;&nbsp;&nbsp;7&nbsp;&nbsp;-8</spanx></c>
3339  <c>7</c>
3340 <c><spanx style="vbare">&nbsp;16&nbsp;&nbsp;14&nbsp;&nbsp;38&nbsp;&nbsp;-3&nbsp;&nbsp;33</spanx></c>
3341 </texttable>
3342
3343 <texttable anchor="silk_ltp_filter_coeffs1"
3344  title="Codebook Vectors for LTP Filter, Periodicity Index 1">
3345 <ttcol>Index</ttcol>
3346 <ttcol align="right">Filter Taps (Q7)</ttcol>
3347
3348  <c>0</c>
3349 <c><spanx style="vbare">&nbsp;13&nbsp;&nbsp;22&nbsp;&nbsp;39&nbsp;&nbsp;23&nbsp;&nbsp;12</spanx></c>
3350  <c>1</c>
3351 <c><spanx style="vbare">&nbsp;-1&nbsp;&nbsp;36&nbsp;&nbsp;64&nbsp;&nbsp;27&nbsp;&nbsp;-6</spanx></c>
3352  <c>2</c>
3353 <c><spanx style="vbare">&nbsp;-7&nbsp;&nbsp;10&nbsp;&nbsp;55&nbsp;&nbsp;43&nbsp;&nbsp;17</spanx></c>
3354  <c>3</c>
3355 <c><spanx style="vbare">&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;8&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;1</spanx></c>
3356  <c>4</c>
3357 <c><spanx style="vbare">&nbsp;&nbsp;6&nbsp;-11&nbsp;&nbsp;74&nbsp;&nbsp;53&nbsp;&nbsp;-9</spanx></c>
3358  <c>5</c>
3359 <c><spanx style="vbare">-12&nbsp;&nbsp;55&nbsp;&nbsp;76&nbsp;-12&nbsp;&nbsp;&nbsp;8</spanx></c>
3360  <c>6</c>
3361 <c><spanx style="vbare">&nbsp;-3&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;93&nbsp;&nbsp;27&nbsp;&nbsp;-4</spanx></c>
3362  <c>7</c>
3363 <c><spanx style="vbare">&nbsp;26&nbsp;&nbsp;39&nbsp;&nbsp;59&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;-8</spanx></c>
3364  <c>8</c>
3365 <c><spanx style="vbare">&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;77&nbsp;&nbsp;11&nbsp;&nbsp;&nbsp;9</spanx></c>
3366  <c>9</c>
3367 <c><spanx style="vbare">&nbsp;-8&nbsp;&nbsp;22&nbsp;&nbsp;44&nbsp;&nbsp;-6&nbsp;&nbsp;&nbsp;7</spanx></c>
3368 <c>10</c>
3369 <c><spanx style="vbare">&nbsp;40&nbsp;&nbsp;&nbsp;9&nbsp;&nbsp;26&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;&nbsp;9</spanx></c>
3370 <c>11</c>
3371 <c><spanx style="vbare">&nbsp;-7&nbsp;&nbsp;20&nbsp;101&nbsp;&nbsp;-7&nbsp;&nbsp;&nbsp;4</spanx></c>
3372 <c>12</c>
3373 <c><spanx style="vbare">&nbsp;&nbsp;3&nbsp;&nbsp;-8&nbsp;&nbsp;42&nbsp;&nbsp;26&nbsp;&nbsp;&nbsp;0</spanx></c>
3374 <c>13</c>
3375 <c><spanx style="vbare">-15&nbsp;&nbsp;33&nbsp;&nbsp;68&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;23</spanx></c>
3376 <c>14</c>
3377 <c><spanx style="vbare">&nbsp;-2&nbsp;&nbsp;55&nbsp;&nbsp;46&nbsp;&nbsp;-2&nbsp;&nbsp;15</spanx></c>
3378 <c>15</c>
3379 <c><spanx style="vbare">&nbsp;&nbsp;3&nbsp;&nbsp;-1&nbsp;&nbsp;21&nbsp;&nbsp;16&nbsp;&nbsp;41</spanx></c>
3380 </texttable>
3381
3382 <texttable anchor="silk_ltp_filter_coeffs2"
3383  title="Codebook Vectors for LTP Filter, Periodicity Index 2">
3384 <ttcol>Index</ttcol>
3385 <ttcol align="right">Filter Taps (Q7)</ttcol>
3386  <c>0</c>
3387 <c><spanx style="vbare">&nbsp;-6&nbsp;&nbsp;27&nbsp;&nbsp;61&nbsp;&nbsp;39&nbsp;&nbsp;&nbsp;5</spanx></c>
3388  <c>1</c>
3389 <c><spanx style="vbare">-11&nbsp;&nbsp;42&nbsp;&nbsp;88&nbsp;&nbsp;&nbsp;4&nbsp;&nbsp;&nbsp;1</spanx></c>
3390  <c>2</c>
3391 <c><spanx style="vbare">&nbsp;-2&nbsp;&nbsp;60&nbsp;&nbsp;65&nbsp;&nbsp;&nbsp;6&nbsp;&nbsp;-4</spanx></c>
3392  <c>3</c>
3393 <c><spanx style="vbare">&nbsp;-1&nbsp;&nbsp;-5&nbsp;&nbsp;73&nbsp;&nbsp;56&nbsp;&nbsp;&nbsp;1</spanx></c>
3394  <c>4</c>
3395 <c><spanx style="vbare">&nbsp;-9&nbsp;&nbsp;19&nbsp;&nbsp;94&nbsp;&nbsp;29&nbsp;&nbsp;-9</spanx></c>
3396  <c>5</c>
3397 <c><spanx style="vbare">&nbsp;&nbsp;0&nbsp;&nbsp;12&nbsp;&nbsp;99&nbsp;&nbsp;&nbsp;6&nbsp;&nbsp;&nbsp;4</spanx></c>
3398  <c>6</c>
3399 <c><spanx style="vbare">&nbsp;&nbsp;8&nbsp;-19&nbsp;102&nbsp;&nbsp;46&nbsp;-13</spanx></c>
3400  <c>7</c>
3401 <c><spanx style="vbare">&nbsp;&nbsp;3&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;13&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;&nbsp;2</spanx></c>
3402  <c>8</c>
3403 <c><spanx style="vbare">&nbsp;&nbsp;9&nbsp;-21&nbsp;&nbsp;84&nbsp;&nbsp;72&nbsp;-18</spanx></c>
3404  <c>9</c>
3405 <c><spanx style="vbare">-11&nbsp;&nbsp;46&nbsp;104&nbsp;-22&nbsp;&nbsp;&nbsp;8</spanx></c>
3406 <c>10</c>
3407 <c><spanx style="vbare">&nbsp;18&nbsp;&nbsp;38&nbsp;&nbsp;48&nbsp;&nbsp;23&nbsp;&nbsp;&nbsp;0</spanx></c>
3408 <c>11</c>
3409 <c><spanx style="vbare">-16&nbsp;&nbsp;70&nbsp;&nbsp;83&nbsp;-21&nbsp;&nbsp;11</spanx></c>
3410 <c>12</c>
3411 <c><spanx style="vbare">&nbsp;&nbsp;5&nbsp;-11&nbsp;117&nbsp;&nbsp;22&nbsp;&nbsp;-8</spanx></c>
3412 <c>13</c>
3413 <c><spanx style="vbare">&nbsp;-6&nbsp;&nbsp;23&nbsp;117&nbsp;-12&nbsp;&nbsp;&nbsp;3</spanx></c>
3414 <c>14</c>
3415 <c><spanx style="vbare">&nbsp;&nbsp;3&nbsp;&nbsp;-8&nbsp;&nbsp;95&nbsp;&nbsp;28&nbsp;&nbsp;&nbsp;4</spanx></c>
3416 <c>15</c>
3417 <c><spanx style="vbare">-10&nbsp;&nbsp;15&nbsp;&nbsp;77&nbsp;&nbsp;60&nbsp;-15</spanx></c>
3418 <c>16</c>
3419 <c><spanx style="vbare">&nbsp;-1&nbsp;&nbsp;&nbsp;4&nbsp;124&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;-4</spanx></c>
3420 <c>17</c>
3421 <c><spanx style="vbare">&nbsp;&nbsp;3&nbsp;&nbsp;38&nbsp;&nbsp;84&nbsp;&nbsp;24&nbsp;-25</spanx></c>
3422 <c>18</c>
3423 <c><spanx style="vbare">&nbsp;&nbsp;2&nbsp;&nbsp;13&nbsp;&nbsp;42&nbsp;&nbsp;13&nbsp;&nbsp;31</spanx></c>
3424 <c>19</c>
3425 <c><spanx style="vbare">&nbsp;21&nbsp;&nbsp;-4&nbsp;&nbsp;56&nbsp;&nbsp;46&nbsp;&nbsp;-1</spanx></c>
3426 <c>20</c>
3427 <c><spanx style="vbare">&nbsp;-1&nbsp;&nbsp;35&nbsp;&nbsp;79&nbsp;-13&nbsp;&nbsp;19</spanx></c>
3428 <c>21</c>
3429 <c><spanx style="vbare">&nbsp;-7&nbsp;&nbsp;65&nbsp;&nbsp;88&nbsp;&nbsp;-9&nbsp;-14</spanx></c>
3430 <c>22</c>
3431 <c><spanx style="vbare">&nbsp;20&nbsp;&nbsp;&nbsp;4&nbsp;&nbsp;81&nbsp;&nbsp;49&nbsp;-29</spanx></c>
3432 <c>23</c>
3433 <c><spanx style="vbare">&nbsp;20&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;75&nbsp;&nbsp;&nbsp;3&nbsp;-17</spanx></c>
3434 <c>24</c>
3435 <c><spanx style="vbare">&nbsp;&nbsp;5&nbsp;&nbsp;-9&nbsp;&nbsp;44&nbsp;&nbsp;92&nbsp;&nbsp;-8</spanx></c>
3436 <c>25</c>
3437 <c><spanx style="vbare">&nbsp;&nbsp;1&nbsp;&nbsp;-3&nbsp;&nbsp;22&nbsp;&nbsp;69&nbsp;&nbsp;31</spanx></c>
3438 <c>26</c>
3439 <c><spanx style="vbare">&nbsp;-6&nbsp;&nbsp;95&nbsp;&nbsp;41&nbsp;-12&nbsp;&nbsp;&nbsp;5</spanx></c>
3440 <c>27</c>
3441 <c><spanx style="vbare">&nbsp;39&nbsp;&nbsp;67&nbsp;&nbsp;16&nbsp;&nbsp;-4&nbsp;&nbsp;&nbsp;1</spanx></c>
3442 <c>28</c>
3443 <c><spanx style="vbare">&nbsp;&nbsp;0&nbsp;&nbsp;-6&nbsp;120&nbsp;&nbsp;55&nbsp;-36</spanx></c>
3444 <c>29</c>
3445 <c><spanx style="vbare">-13&nbsp;&nbsp;44&nbsp;122&nbsp;&nbsp;&nbsp;4&nbsp;-24</spanx></c>
3446 <c>30</c>
3447 <c><spanx style="vbare">&nbsp;81&nbsp;&nbsp;&nbsp;5&nbsp;&nbsp;11&nbsp;&nbsp;&nbsp;3&nbsp;&nbsp;&nbsp;7</spanx></c>
3448 <c>31</c>
3449 <c><spanx style="vbare">&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;9&nbsp;&nbsp;10&nbsp;&nbsp;88</spanx></c>
3450 </texttable>
3451
3452 </section>
3453
3454 <section anchor="silk_ltp_scaling" title="LTP Scaling Parameter">
3455 <t>
3456 In some circumstances an LTP scaling parameter appears after the LTP filter
3457  coefficients.
3458 This allows the encoder to trade off the prediction gain between
3459  packets against the recovery time after packet loss.
3460 Like the quantization gains, only the first LBRR frame in an Opus frame,
3461  an LBRR frame where the prior LBRR frame was not coded, and the first regular
3462  SILK frame in each channel of an Opus frame include this field, and, like all
3463  of the other LTP parameters, only for frames that are also voiced.
3464 Unlike absolute-coding for pitch lags, a regular SILK frame other than the
3465  first one in a channel will not include this field even if the prior frame was
3466  not voiced.
3467 </t>
3468 <t>
3469 If present, the value is coded using the 3-entry PDF in
3470  <xref target="silk_ltp_scaling_pdf"/>.
3471 The three possible values represent Q14 scale factors of 15565, 12288, and
3472  8192, respectively (corresponding to approximately 0.95, 0.75, and 0.5).
3473 Frames that do not code the scaling parameter use the default factor of 15565
3474  (approximately 0.95).
3475 </t>
3476
3477 <texttable anchor="silk_ltp_scaling_pdf"
3478  title="PDF for LTP Scaling Parameter">
3479 <ttcol align="left">PDF</ttcol>
3480 <c>{128, 64, 64}/256</c>
3481 </texttable>
3482
3483 </section>
3484
3485 </section>
3486
3487 <section anchor="silk_seed" title="Linear Congruential Generator (LCG) Seed">
3488 <t>
3489 SILK uses a linear congruential generator (LCG) to inject pseudorandom noise
3490  into the quantized excitation.
3491 To ensure synchronization of this process between the encoder and decoder, each
3492  SILK frame stores a 2-bit seed after the LTP parameters (if any).
3493 The encoder may consider the choice of this seed during quantization, meaning
3494  the flexibility to choose the LCG seed can reduce distortion.
3495 The seed is decoded with the uniform 4-entry PDF in
3496  <xref target="silk_seed_pdf"/>, yielding a value between 0 and 3, inclusive.
3497 </t>
3498
3499 <texttable anchor="silk_seed_pdf"
3500  title="PDF for LCG Seed">
3501 <ttcol align="left">PDF</ttcol>
3502 <c>{64, 64, 64, 64}/256</c>
3503 </texttable>
3504
3505 </section>
3506
3507 <section anchor="silk_excitation" title="Excitation">
3508 <t>
3509 SILK codes the excitation using a modified version of the Pyramid Vector
3510  Quantization (PVQ) codebook <xref target="PVQ"/>.
3511 The PVQ codebook is designed for Laplace-distributed values and consists of all
3512  sums of K signed, unit pulses in a vector of dimension N, where two pulses at
3513  the same position are required to have the same sign.
3514 Thus the codebook includes all integer codevectors y of dimension N that
3515  satisfy
3516 <figure align="center">
3517 <artwork align="center"><![CDATA[
3518 N-1
3519 __
3520 \  abs(y[j]) = K .
3521 /_
3522 j=0
3523 ]]></artwork>
3524 </figure>
3525 Unlike regular PVQ, SILK uses a variable-length, rather than fixed-length,
3526  encoding.
3527 This encoding is better suited to the more Gaussian-like distribution of the
3528  coefficient magnitudes and the non-uniform distribution of their signs (caused
3529  by the quantization offset described below).
3530 SILK also handles large codebooks by coding the least significant bits (LSb's)
3531  of each coefficient directly.
3532 This adds a small coding efficiency loss, but greatly reduces the computation
3533  time and ROM size required for decoding, as implemented in
3534  silk_decode_pulses() (silk_decode_pulses.c).
3535 </t>
3536
3537 <t>
3538 SILK fixes the dimension of the codebook to N&nbsp;=&nbsp;16.
3539 The excitation is made up of a number of "shell blocks", each 16 samples in
3540  size.
3541 <xref target="silk_shell_block_table"/> lists the number of shell blocks
3542  required for a SILK frame for each possible audio bandwidth and frame size.
3543 10&nbsp;ms MB frames nominally contain 120&nbsp;samples (10&nbsp;ms at
3544  12&nbsp;kHz), which is not a multiple of 16.
3545 This is handled by coding 8 shell blocks (128 samples) and discarding the final
3546  8 samples of the last block.
3547 The decoder contains no special case that prevents an encoder from placing
3548  pulses in these samples, and they must be correctly parsed from the bitstream
3549  if present, but they are otherwise ignored.
3550 </t>
3551
3552 <texttable anchor="silk_shell_block_table"
3553  title="Number of Shell Blocks Per SILK Frame">
3554 <ttcol>Audio Bandwidth</ttcol>
3555 <ttcol>Frame Size</ttcol>
3556 <ttcol align="right">Number of Shell Blocks</ttcol>
3557 <c>NB</c> <c>10&nbsp;ms</c>  <c>5</c>
3558 <c>MB</c> <c>10&nbsp;ms</c>  <c>8</c>
3559 <c>WB</c> <c>10&nbsp;ms</c> <c>10</c>
3560 <c>NB</c> <c>20&nbsp;ms</c> <c>10</c>
3561 <c>MB</c> <c>20&nbsp;ms</c> <c>15</c>
3562 <c>WB</c> <c>20&nbsp;ms</c> <c>20</c>
3563 </texttable>
3564
3565 <section anchor="silk_rate_level" title="Rate Level">
3566 <t>
3567 The first symbol in the excitation is a "rate level", which is an index from 0
3568  to 8, inclusive, coded using the PDF in <xref target="silk_rate_level_pdfs"/>
3569  corresponding to the signal type of the current frame (from
3570  <xref target="silk_frame_type"/>).
3571 The rate level selects the PDF used to decode the number of pulses in
3572  the individual shell blocks.
3573 It does not directly convey any information about the bitrate or the number of
3574  pulses itself, but merely changes the probability of the symbols in
3575  <xref target="silk_pulse_counts"/>.
3576 Level&nbsp;0 provides a more efficient encoding at low rates generally, and
3577  level&nbsp;8 provides a more efficient encoding at high rates generally,
3578  though the most efficient level for a particular SILK frame may depend on the
3579  exact distribution of the coded symbols.
3580 An encoder should, but is not required to, use the most efficient rate level.
3581 </t>
3582
3583 <texttable anchor="silk_rate_level_pdfs"
3584  title="PDFs for the Rate Level">
3585 <ttcol>Signal Type</ttcol>
3586 <ttcol>PDF</ttcol>
3587 <c>Inactive or Unvoiced</c>
3588 <c>{15, 51, 12, 46, 45, 13, 33, 27, 14}/256</c>
3589 <c>Voiced</c>
3590 <c>{33, 30, 36, 17, 34, 49, 18, 21, 18}/256</c>
3591 </texttable>
3592
3593 </section>
3594
3595 <section anchor="silk_pulse_counts" title="Pulses Per Shell Block">
3596 <t>
3597 The total number of pulses in each of the shell blocks follows the rate level.
3598 The pulse counts for all of the shell blocks are coded consecutively, before
3599  the content of any of the blocks.
3600 Each block may have anywhere from 0 to 16 pulses, inclusive, coded using the
3601  18-entry PDF in <xref target="silk_pulse_count_pdfs"/> corresponding to the
3602  rate level from <xref target="silk_rate_level"/>.
3603 The special value 17 indicates that this block has one or more additional
3604  LSb's to decode for each coefficient.
3605 If the decoder encounters this value, it decodes another value for the actual
3606  pulse count of the block, but uses the PDF corresponding to the special rate
3607  level&nbsp;9 instead of the normal rate level.
3608 This process repeats until the decoder reads a value less than 17, and it then
3609  sets the number of extra LSb's used to the number of 17's decoded for that
3610  block.
3611 If it reads the value 17 ten times, then the next iteration uses the special
3612  rate level&nbsp;10 instead of 9.
3613 The probability of decoding a 17 when using the PDF for rate level&nbsp;10 is
3614  zero, ensuring that the number of LSb's for a block will not exceed 10.
3615 The cumulative distribution for rate level&nbsp;10 is just a shifted version of
3616  that for 9 and thus does not require any additional storage.
3617 </t>
3618
3619 <texttable anchor="silk_pulse_count_pdfs"
3620  title="PDFs for the Pulse Count">
3621 <ttcol>Rate Level</ttcol>
3622 <ttcol>PDF</ttcol>
3623 <c>0</c>
3624 <c>{131, 74, 25, 8, 3, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}/256</c>
3625 <c>1</c>
3626 <c>{58, 93, 60, 23, 7, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}/256</c>
3627 <c>2</c>
3628 <c>{43, 51, 46, 33, 24, 16, 11, 8, 6, 3, 3, 3, 2, 1, 1, 2, 1, 2}/256</c>
3629 <c>3</c>
3630 <c>{17, 52, 71, 57, 31, 12, 5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}/256</c>
3631 <c>4</c>
3632 <c>{6, 21, 41, 53, 49, 35, 21, 11, 6, 3, 2, 2, 1, 1, 1, 1, 1, 1}/256</c>
3633 <c>5</c>
3634 <c>{7, 14, 22, 28, 29, 28, 25, 20, 17, 13, 11, 9, 7, 5, 4, 4, 3, 10}/256</c>
3635 <c>6</c>
3636 <c>{2, 5, 14, 29, 42, 46, 41, 31, 19, 11, 6, 3, 2, 1, 1, 1, 1, 1}/256</c>
3637 <c>7</c>
3638 <c>{1, 2, 4, 10, 19, 29, 35, 37, 34, 28, 20, 14, 8, 5, 4, 2, 2, 2}/256</c>
3639 <c>8</c>
3640 <c>{1, 2, 2, 5, 9, 14, 20, 24, 27, 28, 26, 23, 20, 15, 11, 8, 6, 15}/256</c>
3641 <c>9</c>
3642 <c>{1, 1, 1, 6, 27, 58, 56, 39, 25, 14, 10, 6, 3, 3, 2, 1, 1, 2}/256</c>
3643 <c>10</c>
3644 <c>{2, 1, 6, 27, 58, 56, 39, 25, 14, 10, 6, 3, 3, 2, 1, 1, 2, 0}/256</c>
3645 </texttable>
3646
3647 </section>
3648
3649 <section anchor="silk_pulse_locations" title="Pulse Location Decoding">
3650 <t>
3651 The locations of the pulses in each shell block follows the pulse counts,
3652  as decoded by silk_shell_decoder() (silk_shell_coder.c).
3653 As with the pulse counts, these locations are coded for all the shell blocks
3654  before any of the remaining information for each block.
3655 Unlike many other codecs, SILK places no restriction on the distribution of
3656  pulses within a shell block.
3657 All of the pulses may be placed in a single location, or each one in a unique
3658  location, or anything in between.
3659 </t>
3660
3661 <t>
3662 The location of pulses is coded by recursively partitioning each block into
3663  halves, and coding how many pulses fall on the left side of the split.
3664 All remaining pulses must fall on the right side of the split.
3665 The process then recurses into the left half, and after that returns, the
3666  right half (preorder traversal).
3667 The PDF to use is chosen by the size of the current partition (16, 8, 4, or 2)
3668  and the number of pulses in the partition (1 to 16, inclusive).
3669 <xref target="silk_shell_code3_pdfs"/> through
3670  <xref target="silk_shell_code0_pdfs"/> list the PDFs used for each partition
3671  size and pulse count.
3672 This process skips partitions without any pulses, i.e., where the initial pulse
3673  count from <xref target="silk_pulse_counts"/> was zero, or where the split in
3674  the prior level indicated that all of the pulses fell on the other side.
3675 These partitions have nothing to code, so they require no PDF.
3676 </t>
3677
3678 <texttable anchor="silk_shell_code3_pdfs"
3679  title="PDFs for Pulse Count Split, 16 Sample Partitions">
3680 <ttcol>Pulse Count</ttcol>
3681 <ttcol>PDF</ttcol>
3682  <c>1</c> <c>{126, 130}/256</c>
3683  <c>2</c> <c>{56, 142, 58}/256</c>
3684  <c>3</c> <c>{25, 101, 104, 26}/256</c>
3685  <c>4</c> <c>{12, 60, 108, 64, 12}/256</c>
3686  <c>5</c> <c>{7, 35, 84, 87, 37, 6}/256</c>
3687  <c>6</c> <c>{4, 20, 59, 86, 63, 21, 3}/256</c>
3688  <c>7</c> <c>{3, 12, 38, 72, 75, 42, 12, 2}/256</c>
3689  <c>8</c> <c>{2, 8, 25, 54, 73, 59, 27, 7, 1}/256</c>
3690  <c>9</c> <c>{2, 5, 17, 39, 63, 65, 42, 18, 4, 1}/256</c>
3691 <c>10</c> <c>{1, 4, 12, 28, 49, 63, 54, 30, 11, 3, 1}/256</c>
3692 <c>11</c> <c>{1, 4, 8, 20, 37, 55, 57, 41, 22, 8, 2, 1}/256</c>
3693 <c>12</c> <c>{1, 3, 7, 15, 28, 44, 53, 48, 33, 16, 6, 1, 1}/256</c>
3694 <c>13</c> <c>{1, 2, 6, 12, 21, 35, 47, 48, 40, 25, 12, 5, 1, 1}/256</c>
3695 <c>14</c> <c>{1, 1, 4, 10, 17, 27, 37, 47, 43, 33, 21, 9, 4, 1, 1}/256</c>
3696 <c>15</c> <c>{1, 1, 1, 8, 14, 22, 33, 40, 43, 38, 28, 16, 8, 1, 1, 1}/256</c>
3697 <c>16</c> <c>{1, 1, 1, 1, 13, 18, 27, 36, 41, 41, 34, 24, 14, 1, 1, 1, 1}/256</c>
3698 </texttable>
3699
3700 <texttable anchor="silk_shell_code2_pdfs"
3701  title="PDFs for Pulse Count Split, 8 Sample Partitions">
3702 <ttcol>Pulse Count</ttcol>
3703 <ttcol>PDF</ttcol>
3704  <c>1</c> <c>{127, 129}/256</c>
3705  <c>2</c> <c>{53, 149, 54}/256</c>
3706  <c>3</c> <c>{22, 105, 106, 23}/256</c>
3707  <c>4</c> <c>{11, 61, 111, 63, 10}/256</c>
3708  <c>5</c> <c>{6, 35, 86, 88, 36, 5}/256</c>
3709  <c>6</c> <c>{4, 20, 59, 87, 62, 21, 3}/256</c>
3710  <c>7</c> <c>{3, 13, 40, 71, 73, 41, 13, 2}/256</c>
3711  <c>8</c> <c>{3, 9, 27, 53, 70, 56, 28, 9, 1}/256</c>
3712  <c>9</c> <c>{3, 8, 19, 37, 57, 61, 44, 20, 6, 1}/256</c>
3713 <c>10</c> <c>{3, 7, 15, 28, 44, 54, 49, 33, 17, 5, 1}/256</c>
3714 <c>11</c> <c>{1, 7, 13, 22, 34, 46, 48, 38, 28, 14, 4, 1}/256</c>
3715 <c>12</c> <c>{1, 1, 11, 22, 27, 35, 42, 47, 33, 25, 10, 1, 1}/256</c>
3716 <c>13</c> <c>{1, 1, 6, 14, 26, 37, 43, 43, 37, 26, 14, 6, 1, 1}/256</c>
3717 <c>14</c> <c>{1, 1, 4, 10, 20, 31, 40, 42, 40, 31, 20, 10, 4, 1, 1}/256</c>
3718 <c>15</c> <c>{1, 1, 3, 8, 16, 26, 35, 38, 38, 35, 26, 16, 8, 3, 1, 1}/256</c>
3719 <c>16</c> <c>{1, 1, 2, 6, 12, 21, 30, 36, 38, 36, 30, 21, 12, 6, 2, 1, 1}/256</c>
3720 </texttable>
3721
3722 <texttable anchor="silk_shell_code1_pdfs"
3723  title="PDFs for Pulse Count Split, 4 Sample Partitions">
3724 <ttcol>Pulse Count</ttcol>
3725 <ttcol>PDF</ttcol>
3726  <c>1</c> <c>{127, 129}/256</c>
3727  <c>2</c> <c>{49, 157, 50}/256</c>
3728  <c>3</c> <c>{20, 107, 109, 20}/256</c>
3729  <c>4</c> <c>{11, 60, 113, 62, 10}/256</c>
3730  <c>5</c> <c>{7, 36, 84, 87, 36, 6}/256</c>
3731  <c>6</c> <c>{6, 24, 57, 82, 60, 23, 4}/256</c>
3732  <c>7</c> <c>{5, 18, 39, 64, 68, 42, 16, 4}/256</c>
3733  <c>8</c> <c>{6, 14, 29, 47, 61, 52, 30, 14, 3}/256</c>
3734  <c>9</c> <c>{1, 15, 23, 35, 51, 50, 40, 30, 10, 1}/256</c>
3735 <c>10</c> <c>{1, 1, 21, 32, 42, 52, 46, 41, 18, 1, 1}/256</c>
3736 <c>11</c> <c>{1, 6, 16, 27, 36, 42, 42, 36, 27, 16, 6, 1}/256</c>
3737 <c>12</c> <c>{1, 5, 12, 21, 31, 38, 40, 38, 31, 21, 12, 5, 1}/256</c>
3738 <c>13</c> <c>{1, 3, 9, 17, 26, 34, 38, 38, 34, 26, 17, 9, 3, 1}/256</c>
3739 <c>14</c> <c>{1, 3, 7, 14, 22, 29, 34, 36, 34, 29, 22, 14, 7, 3, 1}/256</c>
3740 <c>15</c> <c>{1, 2, 5, 11, 18, 25, 31, 35, 35, 31, 25, 18, 11, 5, 2, 1}/256</c>
3741 <c>16</c> <c>{1, 1, 4, 9, 15, 21, 28, 32, 34, 32, 28, 21, 15, 9, 4, 1, 1}/256</c>
3742 </texttable>
3743
3744 <texttable anchor="silk_shell_code0_pdfs"
3745  title="PDFs for Pulse Count Split, 2 Sample Partitions">
3746 <ttcol>Pulse Count</ttcol>
3747 <ttcol>PDF</ttcol>
3748  <c>1</c> <c>{128, 128}/256</c>
3749  <c>2</c> <c>{42, 172, 42}/256</c>
3750  <c>3</c> <c>{21, 107, 107, 21}/256</c>
3751  <c>4</c> <c>{12, 60, 112, 61, 11}/256</c>
3752  <c>5</c> <c>{8, 34, 86, 86, 35, 7}/256</c>
3753  <c>6</c> <c>{8, 23, 55, 90, 55, 20, 5}/256</c>
3754  <c>7</c> <c>{5, 15, 38, 72, 72, 36, 15, 3}/256</c>
3755  <c>8</c> <c>{6, 12, 27, 52, 77, 47, 20, 10, 5}/256</c>
3756  <c>9</c> <c>{6, 19, 28, 35, 40, 40, 35, 28, 19, 6}/256</c>
3757 <c>10</c> <c>{4, 14, 22, 31, 37, 40, 37, 31, 22, 14, 4}/256</c>
3758 <c>11</c> <c>{3, 10, 18, 26, 33, 38, 38, 33, 26, 18, 10, 3}/256</c>
3759 <c>12</c> <c>{2, 8, 13, 21, 29, 36, 38, 36, 29, 21, 13, 8, 2}/256</c>
3760 <c>13</c> <c>{1, 5, 10, 17, 25, 32, 38, 38, 32, 25, 17, 10, 5, 1}/256</c>
3761 <c>14</c> <c>{1, 4, 7, 13, 21, 29, 35, 36, 35, 29, 21, 13, 7, 4, 1}/256</c>
3762 <c>15</c> <c>{1, 2, 5, 10, 17, 25, 32, 36, 36, 32, 25, 17, 10, 5, 2, 1}/256</c>
3763 <c>16</c> <c>{1, 2, 4, 7, 13, 21, 28, 34, 36, 34, 28, 21, 13, 7, 4, 2, 1}/256</c>
3764 </texttable>
3765
3766 </section>
3767
3768 <section anchor="silk_shell_lsb" title="LSb Decoding">
3769 <t>
3770 After the decoder reads the pulse locations for all blocks, it reads the LSb's
3771  (if any) for each block in turn.
3772 Inside each block, it reads all the LSb's for each coefficient in turn, even
3773  those where no pulses were allocated, before proceeding to the next one.
3774 They are coded from most significant to least significant, and they all use the
3775  PDF in <xref target="silk_shell_lsb_pdf"/>.
3776 </t>
3777
3778 <texttable anchor="silk_shell_lsb_pdf" title="PDF for Excitation LSb's">
3779 <ttcol>PDF</ttcol>
3780 <c>{136, 120}/256</c>
3781 </texttable>
3782
3783 <t>
3784 The number of LSb's read for each coefficient in a block is determined in
3785  <xref target="silk_pulse_counts"/>.
3786 The magnitude of the coefficient is initially equal to the number of pulses
3787  placed at that location in <xref target="silk_pulse_locations"/>.
3788 As each LSb is decoded, the magnitude is doubled, and then the value of the LSb
3789  added to it, to obtain an updated magnitude.
3790 </t>
3791 </section>
3792
3793 <section anchor="silk_signs" title="Sign Decoding">
3794 <t>
3795 After decoding the pulse locations and the LSb's, the decoder knows the
3796  magnitude of each coefficient in the excitation.
3797 It then decodes a sign for all coefficients with a non-zero magnitude, using
3798  one of the PDFs from <xref target="silk_sign_pdfs"/>.
3799 If the value decoded is 0, then the coefficient magnitude is negated.
3800 Otherwise, it remains positive.
3801 </t>
3802
3803 <t>
3804 The decoder chooses the PDF for the sign based on the signal type and
3805  quantization offset type (from <xref target="silk_frame_type"/>) and the
3806  number of pulses in the block (from <xref target="silk_pulse_counts"/>).
3807 The number of pulses in the block does not take into account any LSb's.
3808 If a block has no pulses, even if it has some LSb's (and thus may have some
3809  non-zero coefficients), then no signs are decoded.
3810 In that case, any non-zero coefficients use a positive sign.
3811 </t>
3812
3813 <texttable anchor="silk_sign_pdfs"
3814  title="PDFs for Excitation Signs">
3815 <ttcol>Signal Type</ttcol>
3816 <ttcol>Quantization Offset Type</ttcol>
3817 <ttcol>Pulse Count</ttcol>
3818 <ttcol>PDF</ttcol>
3819 <c>Inactive</c> <c>Low</c>  <c>1</c>         <c>{207, 49}/256</c>
3820 <c>Inactive</c> <c>Low</c>  <c>2</c>         <c>{189, 67}/256</c>
3821 <c>Inactive</c> <c>Low</c>  <c>3</c>         <c>{179, 77}/256</c>
3822 <c>Inactive</c> <c>Low</c>  <c>4</c>         <c>{174, 82}/256</c>
3823 <c>Inactive</c> <c>Low</c>  <c>5</c>         <c>{163, 93}/256</c>
3824 <c>Inactive</c> <c>Low</c>  <c>6 or more</c> <c>{157, 99}/256</c>
3825 <c>Inactive</c> <c>High</c> <c>1</c>         <c>{245, 11}/256</c>
3826 <c>Inactive</c> <c>High</c> <c>2</c>         <c>{238, 18}/256</c>
3827 <c>Inactive</c> <c>High</c> <c>3</c>         <c>{232, 24}/256</c>
3828 <c>Inactive</c> <c>High</c> <c>4</c>         <c>{225, 31}/256</c>
3829 <c>Inactive</c> <c>High</c> <c>5</c>         <c>{220, 36}/256</c>
3830 <c>Inactive</c> <c>High</c> <c>6 or more</c> <c>{211, 45}/256</c>
3831 <c>Unvoiced</c> <c>Low</c>  <c>1</c>         <c>{210, 46}/256</c>
3832 <c>Unvoiced</c> <c>Low</c>  <c>2</c>         <c>{190, 66}/256</c>
3833 <c>Unvoiced</c> <c>Low</c>  <c>3</c>         <c>{178, 78}/256</c>
3834 <c>Unvoiced</c> <c>Low</c>  <c>4</c>         <c>{169, 87}/256</c>
3835 <c>Unvoiced</c> <c>Low</c>  <c>5</c>         <c>{162, 94}/256</c>
3836 <c>Unvoiced</c> <c>Low</c>  <c>6 or more</c> <c>{152, 104}/256</c>
3837 <c>Unvoiced</c> <c>High</c> <c>1</c>         <c>{242, 14}/256</c>
3838 <c>Unvoiced</c> <c>High</c> <c>2</c>         <c>{235, 21}/256</c>
3839 <c>Unvoiced</c> <c>High</c> <c>3</c>         <c>{224, 32}/256</c>
3840 <c>Unvoiced</c> <c>High</c> <c>4</c>         <c>{214, 42}/256</c>
3841 <c>Unvoiced</c> <c>High</c> <c>5</c>         <c>{205, 51}/256</c>
3842 <c>Unvoiced</c> <c>High</c> <c>6 or more</c> <c>{190, 66}/256</c>
3843 <c>Voiced</c>   <c>Low</c>  <c>1</c>         <c>{162, 94}/256</c>
3844 <c>Voiced</c>   <c>Low</c>  <c>2</c>         <c>{152, 104}/256</c>
3845 <c>Voiced</c>   <c>Low</c>  <c>3</c>         <c>{147, 109}/256</c>
3846 <c>Voiced</c>   <c>Low</c>  <c>4</c>         <c>{144, 112}/256</c>
3847 <c>Voiced</c>   <c>Low</c>  <c>5</c>         <c>{141, 115}/256</c>
3848 <c>Voiced</c>   <c>Low</c>  <c>6 or more</c> <c>{138, 118}/256</c>
3849 <c>Voiced</c>   <c>High</c> <c>1</c>         <c>{203, 53}/256</c>
3850 <c>Voiced</c>   <c>High</c> <c>2</c>         <c>{187, 69}/256</c>
3851 <c>Voiced</c>   <c>High</c> <c>3</c>         <c>{176, 80}/256</c>
3852 <c>Voiced</c>   <c>High</c> <c>4</c>         <c>{168, 88}/256</c>
3853 <c>Voiced</c>   <c>High</c> <c>5</c>         <c>{161, 95}/256</c>
3854 <c>Voiced</c>   <c>High</c> <c>6 or more</c> <c>{154, 102}/256</c>
3855 </texttable>
3856
3857 </section>
3858
3859 </section>
3860
3861 </section>
3862
3863 </section>
3864
3865
3866 <section title="CELT Decoder">
3867
3868 <t>
3869 The CELT layer is decoded based on the following symbols and sets of symbols:
3870 </t>
3871
3872 <texttable anchor='table_example'>
3873 <ttcol align='center'>Symbol(s)</ttcol>
3874 <ttcol align='center'>PDF</ttcol>
3875 <ttcol align='center'>Condition</ttcol>
3876 <c>silence</c>      <c>{32767, 1}/32768</c> <c></c>
3877 <c>post-filter</c>  <c>{1, 1}/2</c> <c></c>
3878 <c>octave</c>       <c>uniform (6)</c><c>post-filter</c>
3879 <c>period</c>       <c>raw bits (4+octave)</c><c>post-filter</c>
3880 <c>gain</c>         <c>raw bits (3)</c><c>post-filter</c>
3881 <c>tapset</c>       <c>{2, 1, 1}/4</c><c>post-filter</c>
3882 <c>transient</c>    <c>{7, 1}/8</c><c></c>
3883 <c>intra</c>        <c>{7, 1}/8</c><c></c>
3884 <c>coarse energy</c><c><xref target="energy-decoding"/></c><c></c>
3885 <c>tf_change</c>    <c><xref target="transient-decoding"/></c><c></c>
3886 <c>tf_select</c>    <c>{1, 1}/2</c><c><xref target="transient-decoding"/></c>
3887 <c>spread</c>       <c>{7, 2, 21, 2}/32</c><c></c>
3888 <c>dyn. alloc.</c>  <c><xref target="allocation"/></c><c></c>
3889 <c>alloc. trim</c>  <c>{2, 2, 5, 10, 22, 46, 22, 10, 5, 2, 2}/128</c><c></c>
3890 <c>skip</c>         <c>{1, 1}/2</c><c><xref target="allocation"/></c>
3891 <c>intensity</c>    <c>uniform</c><c><xref target="allocation"/></c>
3892 <c>dual</c>         <c>{1, 1}/2</c><c></c>
3893 <c>fine energy</c>  <c><xref target="energy-decoding"/></c><c></c>
3894 <c>residual</c>     <c><xref target="PVQ-decoder"/></c><c></c>
3895 <c>anti-collapse</c><c>{1, 1}/2</c><c><xref target="anti-collapse"/></c>
3896 <c>finalize</c>     <c><xref target="energy-decoding"/></c><c></c>
3897 <postamble>Order of the symbols in the CELT section of the bitstream.</postamble>
3898 </texttable>
3899
3900 <t>
3901 The decoder extracts information from the range-coded bitstream in the order
3902 described in the figure above. In some circumstances, it is
3903 possible for a decoded value to be out of range due to a very small amount of redundancy
3904 in the encoding of large integers by the range coder.
3905 In that case, the decoder should assume there has been an error in the coding,
3906 decoding, or transmission and SHOULD take measures to conceal the error and/or report
3907 to the application that a problem has occurred.
3908 </t>
3909
3910 <section anchor="transient-decoding" title="Transient Decoding">
3911 <t>
3912 The "transient" flag encoded in the bitstream has a probability of 1/8.
3913 When it is set, then the MDCT coefficients represent multiple
3914 short MDCTs in the frame. When not set, the coefficients represent a single
3915 long MDCT for the frame. In addition to the global transient flag is a per-band
3916 binary flag to change the time-frequency (tf) resolution independently in each band. The
3917 change in tf resolution is defined in tf_select_table[][] in celt.c and depends
3918 on the frame size, whether the transient flag is set, and the value of tf_select.
3919 The tf_select flag uses a 1/2 probability, but is only decoded
3920 if it can have an impact on the result knowing the value of all per-band
3921 tf_change flags.
3922 </t>
3923 </section>
3924
3925 <section anchor="energy-decoding" title="Energy Envelope Decoding">
3926
3927 <t>
3928 It is important to quantize the energy with sufficient resolution because
3929 any energy quantization error cannot be compensated for at a later
3930 stage. Regardless of the resolution used for encoding the shape of a band,
3931 it is perceptually important to preserve the energy in each band. CELT uses a
3932 three-step coarse-fine-fine strategy for encoding the energy in the base-2 log
3933 domain, as implemented in quant_bands.c</t>
3934
3935 <section anchor="coarse-energy-decoding" title="Coarse energy decoding">
3936 <t>
3937 Coarse quantization of the energy uses a fixed resolution of 6 dB
3938 (integer part of base-2 log). To minimize the bitrate, prediction is applied
3939 both in time (using the previous frame) and in frequency (using the previous
3940 bands). The part of the prediction that is based on the
3941 previous frame can be disabled, creating an "intra" frame where the energy
3942 is coded without reference to prior frames. The decoder first reads the intra flag
3943 to determine what prediction is used.
3944 The 2-D z-transform of
3945 the prediction filter is:
3946 <figure align="center">
3947 <artwork align="center"><![CDATA[
3948                             -1          -1
3949               (1 - alpha*z_l  )*(1 - z_b  )
3950 A(z_l, z_b) = -----------------------------
3951                                  -1
3952                      1 - beta*z_b
3953 ]]></artwork>
3954 </figure>
3955 where b is the band index and l is the frame index. The prediction coefficients
3956 applied depend on the frame size in use when not using intra energy and are alpha=0, beta=4915/32768
3957 when using intra energy.
3958 The time-domain prediction is based on the final fine quantization of the previous
3959 frame, while the frequency domain (within the current frame) prediction is based
3960 on coarse quantization only (because the fine quantization has not been computed
3961 yet). The prediction is clamped internally so that fixed point implementations with
3962 limited dynamic range do not suffer desynchronization.
3963 We approximate the ideal
3964 probability distribution of the prediction error using a Laplace distribution
3965 with separate parameters for each frame size in intra- and inter-frame modes. The
3966 coarse energy quantization is performed by unquant_coarse_energy() and
3967 unquant_coarse_energy_impl() (quant_bands.c). The encoding of the Laplace-distributed values is
3968 implemented in ec_laplace_decode() (laplace.c).
3969 </t>
3970
3971 </section>
3972
3973 <section anchor="fine-energy-decoding" title="Fine energy quantization">
3974 <t>
3975 The number of bits assigned to fine energy quantization in each band is determined
3976 by the bit allocation computation described in <xref target="allocation"></xref>.
3977 Let B_i be the number of fine energy bits
3978 for band i; the refinement is an integer f in the range [0,2**B_i-1]. The mapping between f
3979 and the correction applied to the coarse energy is equal to (f+1/2)/2**B_i - 1/2. Fine
3980 energy quantization is implemented in quant_fine_energy() (quant_bands.c).
3981 </t>
3982 <t>
3983 When some bits are left "unused" after all other flags have been decoded, these bits
3984 are assigned to a "final" step of fine allocation. In effect, these bits are used
3985 to add one extra fine energy bit per band per channel. The allocation process