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