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