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