ref: ad4ae86b591402a9b1fc41a88be741d2138d61f4
parent: de0b97754756df349a8dc066816f3075f1afcc0f
author: Kat Walsh <[email protected]>
date: Mon Aug 22 23:48:43 EDT 2011
Copyedited draft (up to line 4015). Edited for correctness, clarity, and consistent usage. No meaning should have been changed by this edit.
--- a/doc/draft-ietf-codec-opus.xml
+++ b/doc/draft-ietf-codec-opus.xml
@@ -292,7 +292,7 @@
To compensate for the different look-aheads required by each layer, the CELT
encoder input is delayed by an additional 2.7 ms.
This ensures that low frequencies and high frequencies arrive at the same time.
-This extra delay MAY be reduced by an encoder by using less lookahead for noise
+This extra delay MAY be reduced by an encoder by using less look-ahead for noise
shaping or using a simpler resampler in the LP layer, but this will reduce
quality.
However, the base 2.5 ms look-ahead in the CELT layer cannot be reduced in
@@ -322,9 +322,9 @@
</list>
</t>
<t>
-A single packet may contain multiple audio frames, however they must share a
- common set of parameters, including the operating mode, audio bandwidth, frame
- size, and channel count.
+A single packet may contain multiple audio frames.
+However, they must share a common set of parameters, including the operating
+ mode, audio bandwidth, frame size, and channel count.
This section describes the possible combinations of these parameters and the
internal framing used to pack multiple frames into a single packet.
This framing is not self-delimiting.
@@ -438,7 +438,7 @@
</t>
<t>
-No length is transmitted for the last frame in a VBR packet, or any of the
+No length is transmitted for the last frame in a VBR packet, or for any of the
frames in a CBR packet, as it can be inferred from the total size of the
packet and the size of all other data in the packet.
However, the length of any individual frame MUST NOT exceed 1275 bytes, to
@@ -528,7 +528,7 @@
<section title="An Arbitrary Number of Frames in the Packet (Code 3)">
<t>
-Code 3 packets may encode an arbitrary number of packets, as well as additional
+Code 3 packets may encode an arbitrary number of frames, as well as additional
padding, called "Opus padding" to indicate that this padding is added at the
Opus layer, rather than at the transport layer.
For code 3 packets, the TOC byte is followed by a byte encoding the number of
@@ -559,8 +559,8 @@
If the value is 255, then the size of the additional padding is 254 bytes,
plus the padding value encoded in the next byte.
The additional padding bytes appear at the end of the packet, and SHOULD be set
- to zero by the encoder, however the decoder MUST accept any value for the
- padding bytes.
+ to zero by the encoder.
+The decoder MUST accept any value for the padding bytes, however.
By using code 255 multiple times, it is possible to create a packet of any
specific, desired size.
Let P be the total amount of padding, including both the trailing padding bytes
@@ -871,8 +871,8 @@
</figure>
</t>
<t>
-Using a special case for the first symbol, rather than the last symbol, as is
- commonly done in other arithmetic coders, ensures that all the truncation
+Using a special case for the first symbol (rather than the last symbol, as is
+ commonly done in other arithmetic coders) ensures that all the truncation
error from the finite precision arithmetic accumulates in symbol 0.
This makes the cost of coding a 0 slightly smaller, on average, than its
estimated probability indicates and makes the cost of coding any other symbol
@@ -1050,7 +1050,7 @@
value, and, if necessary, raw bits representing the remaining bits.
The limit of 8 bits in the range coded symbol is a trade-off between
implementation complexity, modeling error (since the symbols no longer truly
- have equal coding cost) and rounding error introduced by the range coder
+ have equal coding cost), and rounding error introduced by the range coder
itself (which gets larger as more bits are included).
Using raw bits reduces the maximum number of divisions required in the worst
case, but means that it may be possible to decode a value outside the range
@@ -1108,22 +1108,22 @@
However, this error is bounded, and periodic calls to ec_tell() or
ec_tell_frac() at precisely defined points in the decoding process prevent it
from accumulating.
-For a symbol that requires a whole number of bits (i.e., ft/(fh[k]-fl[k]) is a
- power of two, including values of ft larger than 2**8 with ec_dec_uint()), and
- there are at least p 1/8th bits available, decoding the symbol will never
- advance the decoder past the end of the frame, i.e., will never "bust" the
- budget.
-Frames contain a whole number of bits, and the return value of ec_tell_frac()
- will only advance by more than p 1/8th bits in this case if there was a
- fractional number of bits remaining, and by no more than the fractional part.
+For a range coder symbol that requires a whole number of bits (i.e.,
+ ft/(fh[k]-fl[k]) is a power of two), where there are at least p 1/8th bits
+ available, decoding the symbol will never advance the decoder past the end of
+ the frame ("bust the budget").+In this case the return value of ec_tell_frac() will only advance by more than
+ p 1/8th bits if there was an additional, fractional number of bits remaining,
+ and it will never advance beyond the next whole-bit boundary, which is safe,
+ since frames always contain a whole number of bits.
However, when p is not a whole number of bits, an extra 1/8th bit is required
- to ensure decoding the symbol will not bust.
+ to ensure that decoding the symbol will not bust the budget.
</t>
<t>
The reference implementation keeps track of the total number of whole bits that
- have been processed by the decoder so far in a variable nbits_total, including
- the (possibly fractional number of bits) that are currently buffered (but not
- consumed) inside the range coder.
+ have been processed by the decoder so far in the variable nbits_total,
+ including the (possibly fractional) number of bits that are currently
+ buffered, but not consumed, inside the range coder.
nbits_total is initialized to 33 just after the initial range renormalization
process completes (or equivalently, it can be initialized to 9 before the
first renormalization).
@@ -1223,7 +1223,7 @@
<c>Frame Type</c> <c><xref target="silk_frame_type"/></c> <c></c>
<c>Gain index</c> <c><xref target="silk_gains"/></c> <c></c>
<postamble>
-Order of the symbols in the SILK section of the bit-stream.
+Order of the symbols in the SILK section of the bitstream.
</postamble>
</texttable>
@@ -1259,7 +1259,7 @@
<section title='Range Decoder'>
<t>
- The range decoder decodes the encoded parameters from the received bitstream. Output from this function includes the pulses and gains for the excitation signal generation, as well as LTP and LSF codebook indices, which are needed for decoding LTP and LPC coefficients needed for LTP and LPC synthesis filtering the excitation signal, respectively.
+ The range decoder decodes the encoded parameters from the received bitstream. Output from this function includes the pulses and gains for generating the excitation signal, as well as LTP and LSF codebook indices, which are needed for decoding LTP and LPC coefficients needed for LTP and LPC synthesis filtering the excitation signal, respectively.
</t>
</section>
@@ -1270,7 +1270,7 @@
<t>
When a voiced frame is decoded and LTP codebook selection and indices are received, LTP coefficients are decoded using the selected codebook by choosing the vector that corresponds to the given codebook index in that codebook. This is done for each of the four subframes.
- The LPC coefficients are decoded from the LSF codebook by first adding the chosen LSF vector and the decoded LSF residual signal. The resulting LSF vector is stabilized using the same method that was used in the encoder, see
+ The LPC coefficients are decoded from the LSF codebook by first adding the chosen LSF vector and the decoded LSF residual signal. The resulting LSF vector is stabilized using the same method that was used in the encoder; see
<xref target='lsf_stabilizer_overview_section' />. The LSF coefficients are then converted to LPC coefficients, and passed on to the LPC synthesis filter.
</t>
</section>
@@ -1283,7 +1283,7 @@
<section title='LTP Synthesis'>
<t>
- For voiced speech, the excitation signal e(n) is input to an LTP synthesis filter that will recreate the long term correlation that was removed in the LTP analysis filter and generate an LPC excitation signal e_LPC(n), according to
+ For voiced speech, the excitation signal e(n) is input to an LTP synthesis filter that recreates the long-term correlation removed in the LTP analysis filter and generates an LPC excitation signal e_LPC(n), according to
<figure align="center">
<artwork align="center">
<![CDATA[
@@ -1360,7 +1360,7 @@
<t>
LBRR frames do not include their own separate VAD flags.
-An LBRR frame is only meant to be transmitted for active speech, thus all LBRR
+LBRR frames are only meant to be transmitted for active speech, thus all LBRR
frames are treated as active.
</t>
</section>
@@ -1378,11 +1378,12 @@
Each SILK frame begins with a single "frame type" symbol that jointly codes the
signal type and quantization offset type of the corresponding frame.
If the current frame is a regular SILK frame whose VAD bit was not set (an
- "inactive" frame), then the frame type symbol takes on the value either 0 or 1
- and is decoded using the first PDF in <xref target="silk_frame_type_pdfs"/>.
+ "inactive" frame), then the frame type symbol takes on a value of either 0 or
+ 1 and is decoded using the first PDF in <xref target="silk_frame_type_pdfs"/>.
If the frame is an LBRR frame or a regular SILK frame whose VAD flag was set
- (an "active" frame), then the symbol ranges from 2 to 5, inclusive, and is
- decoded using the second PDF in <xref target="silk_frame_type_pdfs"/>.
+ (an "active" frame), then the value of the symbol may range from 2 to 5,
+ inclusive, and is decoded using the second PDF in
+ <xref target="silk_frame_type_pdfs"/>.
<xref target="silk_frame_type_table"/> translates between the value of the
frame type symbol and the corresponding signal type and quantization offset
type.
@@ -1759,7 +1760,7 @@
For each coefficient, the decoder reads a symbol using the PDF corresponding to
I1 from either <xref target="silk_nlsf_nbmb_stage2_cb_sel"/> or
<xref target="silk_nlsf_wb_stage2_cb_sel"/>, and subtracts 4 from the result
- to given an index in the range -4 to 4, inclusive.
+ to give an index in the range -4 to 4, inclusive.
If the index is either -4 or 4, it reads a second symbol using the PDF in
<xref target="silk_nlsf_ext_pdf"/>, and adds the value of this second symbol
to the index, using the same sign.
@@ -2169,9 +2170,10 @@
]]></artwork>
</figure>
where the division is exact integer division.
-However, nothing thus far in the reconstruction process, nor in the
- quantization process in the encoder, guarantees that the coefficients are
- monotonically increasing and separated well enough to ensure a stable filter.
+However, nothing in either the reconstruction process or the
+ quantization process in the encoder thus far guarantees that the coefficients
+ are monotonically increasing and separated well enough to ensure a stable
+ filter.
When using the reference encoder, roughly 2% of frames violate this constraint.
The next section describes a stabilization procedure used to make these
guarantees.
@@ -2255,12 +2257,12 @@
NLSF_Q15[i] = NLSF_Q15[i-1] + NDeltaMin_Q15[i] .
]]></artwork>
</figure>
-Then the procedure repeats again, until it has executed 20 times, or until
- it stops because the coefficients satisfy all the constraints.
+Then the procedure repeats again, until it has either executed 20 times or
+ has stopped because the coefficients satisfy all the constraints.
</t>
<t>
-After the 20th repetition of the above, the following fallback procedure
- executes once.
+After the 20th repetition of the above procedure, the following fallback
+ procedure executes once.
First, the values of NLSF_Q15[k] for 0 <= k < d_LPC
are sorted in ascending order.
Then for each value of k from 0 to d_LPC-1, NLSF_Q15[k] is set to
@@ -2282,7 +2284,7 @@
<section anchor="silk_nlsf_interpolation" title="Normalized LSF Interpolation">
<t>
For 20 ms SILK frames, the first half of the frame (i.e., the first two
- sub-frames) may use normalized LSF coefficients that are interpolated between
+ subframes) may use normalized LSF coefficients that are interpolated between
the decoded LSFs for the previous frame and the current frame.
A Q2 interpolation factor follows the LSF coefficient indices in the bitstream,
which is decoded using the PDF in <xref target="silk_nlsf_interp_pdf"/>.
@@ -2369,7 +2371,7 @@
To start, it approximates cos(pi*n[k]) using a table lookup with linear
interpolation.
The encoder SHOULD use the inverse of this piecewise linear approximation,
- rather than true the inverse of the cosine function, when deriving the
+ rather than the true inverse of the cosine function, when deriving the
normalized LSF coefficients.
</t>
<t>
@@ -2528,7 +2530,7 @@
</t>
<t>
For each round, the process first finds the index k such that abs(a32_Q17[k])
- is the largest, breaking ties by using the lower value of k.
+ is largest, breaking ties by choosing the lowest value of k.
Then, it computes the corresponding Q12 precision value, maxabs_Q12, subject to
an upper bound to avoid overflow in subsequent computations:
<figure align="center">
@@ -2581,8 +2583,8 @@
Because this performs the actual saturation in the Q12 domain, but converts the
coefficients back to the Q17 domain for the purposes of prediction gain
limiting, this step must be performed after the 10th round of bandwidth
- expansion, regardless of whether or not the Q12 version of any of the
- coefficients still overflow a 16-bit integer.
+ expansion, regardless of whether or not the Q12 version of any coefficient
+ still overflows a 16-bit integer.
This saturation is not performed if maxabs_Q12 drops to 32767 or less prior to
the 10th round.
</t>
@@ -2718,7 +2720,7 @@
The primary lag index is coded either relative to the primary lag of the prior
frame or as an absolute index.
Like the quantization gains, the first LBRR frame, an LBRR frame where the
- previous LBRR frame was not coded, or the first regular SILK frame in an Opus
+ previous LBRR frame was not coded, and the first regular SILK frame in an Opus
frame all code the pitch lag as an absolute index.
When the prior frame was not voiced, this also forces absolute coding.
</t>
@@ -3106,7 +3108,7 @@
<section anchor="silk_ltp_scaling" title="LTP Scaling Parameter">
<t>
After the LTP filter coefficients, an LTP scaling parameter may appear.
-This allows the encoder to trade-off the prediction gain between
+This allows the encoder to trade off the prediction gain between
packets against the recovery time after packet loss.
Like the quantization gains, only the first LBRR frame in an Opus frame,
an LBRR frame where the prior LBRR frame was not coded, and the first regular
@@ -3295,7 +3297,7 @@
Unlike many other codecs, SILK places no restriction on the distribution of
pulses within a shell block.
All of the pulses may be placed in a single location, or each one in a unique
- location, or anything in-between.
+ location, or anything in between.
</t>
<t>
@@ -3307,7 +3309,7 @@
The PDF to use is chosen by the size of the current partition (16, 8, 4, or 2)
and the number of pulses in the partition (1 to 16, inclusive).
<xref target="silk_shell_code3_pdfs"/> through
- <xref target="silk_shell_code0_pdfs"/> list the PDFs use for each partition
+ <xref target="silk_shell_code0_pdfs"/> list the PDFs used for each partition
size and pulse count.
This process skips partitions without any pulses, i.e., where the initial pulse
count from <xref target="silk_pulse_counts"/> was zero, or where the split in
@@ -3452,11 +3454,11 @@
<c>residual</c> <c><xref target="PVQ-decoder"/></c><c></c>
<c>anti-collapse</c><c>{1, 1}/2</c><c><xref target="anti-collapse"/></c><c>finalize</c> <c><xref target="energy-decoding"/></c><c></c>
-<postamble>Order of the symbols in the CELT section of the bit-stream.</postamble>
+<postamble>Order of the symbols in the CELT section of the bitstream.</postamble>
</texttable>
<t>
-The decoder extracts information from the range-coded bit-stream in the order
+The decoder extracts information from the range-coded bitstream in the order
described in the figure above. In some circumstances, it is
possible for a decoded value to be out of range due to a very small amount of redundancy
in the encoding of large integers by the range coder.
@@ -3467,7 +3469,7 @@
<section anchor="transient-decoding" title="Transient Decoding">
<t>
-The "transient" flag encoded in the bit-stream has a probability of 1/8.
+The "transient" flag encoded in the bitstream has a probability of 1/8.
When it is set, then the MDCT coefficients represent multiple
short MDCTs in the frame. When not set, the coefficients represent a single
long MDCT for the frame. In addition to the global transient flag is a per-band
@@ -3520,7 +3522,7 @@
limited dynamic range do not suffer desynchronization.
We approximate the ideal
probability distribution of the prediction error using a Laplace distribution
-with separate parameters for each frame size in intra and inter-frame modes. The
+with separate parameters for each frame size in intra- and inter-frame modes. The
coarse energy quantization is performed by unquant_coarse_energy() and
unquant_coarse_energy_impl() (quant_bands.c). The encoding of the Laplace-distributed values is
implemented in ec_laplace_decode() (laplace.c).
@@ -3545,7 +3547,7 @@
Any remaining bits are first assigned only to bands of priority 0, starting
from band 0 and going up. If all bands of priority 0 have received one bit per
channel, then bands of priority 1 are assigned an extra bit per channel,
-starting from band 0. If any bit is left after this, they are left unused.
+starting from band 0. If any bits are left after this, they are left unused.
This is implemented in unquant_energy_finalise() (quant_bands.c).
</t>
@@ -3563,8 +3565,8 @@
constant bit allocation for the shape content of a band will result in a
roughly constant tone to noise ratio, which provides for fairly consistent
perceptual performance. The effectiveness of this approach is the result of
-two factors: The band energy, which is understood to be perceptually
-important on its own, is always preserved regardless of the shape precision and because
+two factors: that the band energy, which is understood to be perceptually
+important on its own, is always preserved regardless of the shape precision, and because
the constant tone-to-noise ratio implies a constant intra-band noise to masking ratio.
Intra-band masking is the strongest of the perceptual masking effects. This structure
means that the ideal allocation is more consistent from frame to frame than
@@ -3571,27 +3573,27 @@
it is for other codecs without an equivalent structure.</t>
<t>Because the bit allocation is used to drive the decoding of the range-coder
-stream it MUST be recovered exactly so that identical coding decisions are
+stream, it MUST be recovered exactly so that identical coding decisions are
made in the encoder and decoder. Any deviation from the reference's resulting
bit allocation will result in corrupted output, though implementers are
free to implement the procedure in any way which produces identical results.</t>
<t>Because all of the information required to decode a frame must be derived
-from that frame alone in order to retain robustness to packet loss the
+from that frame alone in order to retain robustness to packet loss, the
overhead of explicitly signaling the allocation would be considerable,
especially for low-latency (small frame size) applications,
even though the allocation is relatively static.</t>
<t>For this reason, in the MDCT mode Opus uses a primarily implicit bit
-allocation. The available bit-stream capacity is known in advance to both
+allocation. The available bitstream capacity is known in advance to both
the encoder and decoder without additional signaling, ultimately from the
-packet sizes expressed by a higher level protocol. Using this information
+packet sizes expressed by a higher-level protocol. Using this information
the codec interpolates an allocation from a hard-coded table.</t>
<t>While the band-energy structure effectively models intra-band masking,
it ignores the weaker inter-band masking, band-temporal masking, and
other less significant perceptual effects. While these effects can
-often be ignored they can become significant for particular samples. One
+often be ignored, they can become significant for particular samples. One
mechanism available to encoders would be to simply increase the overall
rate for these frames, but this is not possible in a constant rate mode
and can be fairly inefficient. As a result three explicitly signaled
@@ -3601,7 +3603,7 @@
<list style="symbols">
<t>Band boost</t>
<t>Allocation trim</t>
-<t>band skipping</t>
+<t>Band skipping</t>
</list>
</t>
@@ -3611,7 +3613,7 @@
skipping, selects which low-precision high frequency bands
will be allocated no shape bits at all.</t>
-<t>In stereo mode there are also two additional parameters
+<t>In stereo mode there are two additional parameters
potentially coded as part of the allocation procedure: a parameter to allow the
selective elimination of allocation for the 'side' in jointly coded bands,
and a flag to deactivate joint coding. These values are not signaled if
@@ -3618,51 +3620,51 @@
they would be meaningless in the overall context of the allocation.</t>
<t>Because every signaled adjustment increases overhead and implementation
-complexity none were included speculatively: The reference encoder makes use
+complexity, none were included speculatively: the reference encoder makes use
of all of these mechanisms. While the decision logic in the reference was
-found to be effective enough to justify the overhead and complexity further
+found to be effective enough to justify the overhead and complexity, further
analysis techniques may be discovered which increase the effectiveness of these
-parameters. As with other signaled parameters, encoder is free to choose the
-values in any manner but unless a technique is known to deliver superior
+parameters. As with other signaled parameters, an encoder is free to choose the
+values in any manner, but unless a technique is known to deliver superior
perceptual results the methods used by the reference implementation should be
used.</t>
-<t>The process of allocation consists of the following steps: determining the per-band
+<t>The allocation process consists of the following steps: determining the per-band
maximum allocation vector, decoding the boosts, decoding the tilt, determining
-the remaining capacity the frame, searching the mode table for the
+the remaining capacity of the frame, searching the mode table for the
entry nearest but not exceeding the available space (subject to the tilt, boosts, band
maximums, and band minimums), linear interpolation, reallocation of
unused bits with concurrent skip decoding, determination of the
-fine-energy vs shape split, and final reallocation. This process results
-in an shape allocation per-band (in 1/8th bit units), a per-band fine-energy
+fine-energy vs. shape split, and final reallocation. This process results
+in a per-band shape allocation (in 1/8th bit units), a per-band fine-energy
allocation (in 1 bit per channel units), a set of band priorities for
controlling the use of remaining bits at the end of the frame, and a
-remaining balance of unallocated space which is usually zero except
+remaining balance of unallocated space, which is usually zero except
at very high rates.</t>
<t>The maximum allocation vector is an approximation of the maximum space
-which can be used by each band for a given mode. The value is
+that can be used by each band for a given mode. The value is
approximate because the shape encoding is variable rate (due
to entropy coding of splitting parameters). Setting the maximum too low reduces the
maximum achievable quality in a band while setting it too high
-may result in waste: bit-stream capacity available at the end
+may result in waste: bitstream capacity available at the end
of the frame which can not be put to any use. The maximums
specified by the codec reflect the average maximum. In the reference
-the maximums are provided partially computed form, in order to fit in less
-memory, as a static table (XXX cache.caps). Implementations are expected
-to simply use the same table data but the procedure for generating
+the maximums are provided in partially computed form, in order to fit in less
+memory as a static table (XXX cache.caps). Implementations are expected
+to simply use the same table data, but the procedure for generating
this table is included in rate.c as part of compute_pulse_cache().</t>
-<t>To convert the values in cache.caps into the actual maximums: First
-set nbBands to the maximum number of bands for this mode and stereo to
-zero if stereo is not in use and one otherwise. For each band assign N
+<t>To convert the values in cache.caps into the actual maximums: first
+set nbBands to the maximum number of bands for this mode, and stereo to
+zero if stereo is not in use and one otherwise. For each band set N
to the number of MDCT bins covered by the band (for one channel), set LM
-to the shift value for the frame size (e.g. 0 for 120, 1 for 240, 3 for 480)
+to the shift value for the frame size (e.g. 0 for 120, 1 for 240, 3 for 480),
then set i to nbBands*(2*LM+stereo). Then set the maximum for the band to
the i-th index of cache.caps + 64 and multiply by the number of channels
-in the current frame (one or two) and by N then divide the result by 4
+in the current frame (one or two) and by N, then divide the result by 4
using truncating integer division. The resulting vector will be called
-cap[]. The elements fit in signed 16 bit integers but do not fit in 8 bits.
+cap[]. The elements fit in signed 16-bit integers but do not fit in 8 bits.
This procedure is implemented in the reference in the function init_caps() in celt.c.
</t>
@@ -3673,15 +3675,15 @@
coding cost for a boost starts out at six bits, but subsequent boosts
in a band cost only a single bit and every time a band is boosted the
initial cost is reduced (down to a minimum of two). Since the initial
-cost of coding a boost is 6 bits the coding cost of the boost symbols when
+cost of coding a boost is 6 bits, the coding cost of the boost symbols when
completely unused is 0.48 bits/frame for a 21 band mode (21*-log2(1-1/2**6)).</t>
<t>To decode the band boosts: First set 'dynalloc_logp' to 6, the initial
amount of storage required to signal a boost in bits, 'total_bits' to the
-size of the frame in 8th-bits, 'total_boost' to zero, and 'tell' to the total number
+size of the frame in 8th bits, 'total_boost' to zero, and 'tell' to the total number
of 8th bits decoded
so far. For each band from the coding start (0 normally, but 17 in hybrid mode)
-to the coding end (which changes depending on the signaled bandwidth): Set 'width'
+to the coding end (which changes depending on the signaled bandwidth): set 'width'
to the number of MDCT bins in this band for all channels. Take the larger of width
and 64, then the minimum of that value and the width times eight and set 'quanta'
to the result. This represents a boost step size of six bits subject to limits
@@ -3693,16 +3695,16 @@
is zero break the loop otherwise add quanta to boost and total_boost, subtract quanta from
total_bits, and set dynalloc_loop_log to 1. When the while loop finishes
boost contains the boost for this band. If boost is non-zero and dynalloc_logp
-is greater than 2 decrease dynalloc_logp. Once this process has been
-execute on all bands the band boosts have been decoded. This procedure
+is greater than 2, decrease dynalloc_logp. Once this process has been
+executed on all bands, the band boosts have been decoded. This procedure
is implemented around line 2352 of celt.c.</t>
-<t>At very low rates it's possible that there won't be enough available
+<t>At very low rates it is possible that there won't be enough available
space to execute the inner loop even once. In these cases band boost
is not possible but its overhead is completely eliminated. Because of the
-high cost of band boost when activated a reasonable encoder should not be
+high cost of band boost when activated, a reasonable encoder should not be
using it at very low rates. The reference implements its dynalloc decision
-logic at around 1269 of celt.c</t>
+logic around line 1269 of celt.c.</t>
<t>The allocation trim is a integer value from 0-10. The default value of
5 indicates no trim. The trim parameter is entropy coded in order to
@@ -3710,10 +3712,10 @@
5 bias the allocation towards lower frequencies and values above 5
bias it towards higher frequencies. Like other signaled parameters, signaling
of the trim is gated so that it is not included if there is insufficient space
-available in the bitstream. To decode the trim first set
-the trim value to 5 then iff the count of decoded 8th bits so far (ec_tell_frac)
+available in the bitstream. To decode the trim, first set
+the trim value to 5, then iff the count of decoded 8th bits so far (ec_tell_frac)
plus 48 (6 bits) is less than or equal to the total frame size in 8th
-bits minus total_boost (a product of the above band boost procedure) then
+bits minus total_boost (a product of the above band boost procedure),
decode the trim value using the inverse CDF {127, 126, 124, 119, 109, 87, 41, 19, 9, 4, 2, 0}.</t><t>Stereo parameters</t>
@@ -3720,10 +3722,10 @@
<t>Anti-collapse reservation</t>
-<t>The allocation computation first begins by setting up some initial conditions.
-'total' is set to the available remaining 8th bits, computed by taking the
-size of the coded frame times 8 and subtracting ec_tell_frac(). From this value one (8th bit)
-is subtracted to assure that the resulting allocation will be conservative. 'anti_collapse_rsv'
+<t>The allocation computation begins by setting up some initial conditions.
+'total' is set to the remaining available 8th bits, computed by taking the
+size of the coded frame times 8 and subtracting ec_tell_frac(). From this value, one (8th bit)
+is subtracted to ensure that the resulting allocation will be conservative. 'anti_collapse_rsv'
is set to 8 (8th bits) iff the frame is a transient, LM is greater than 1, and total is
greater than or equal to (LM+2) * 8. Total is then decremented by anti_collapse_rsv and clamped
to be equal to or greater than zero. 'skip_rsv' is set to 8 (8th bits) if total is greater than
@@ -3730,28 +3732,28 @@
8, otherwise it is zero. Total is then decremented by skip_rsv. This reserves space for the
final skipping flag.</t>
-<t>If the current frame is stereo intensity_rsv is set to the conservative log2 in 8th bits
+<t>If the current frame is stereo, intensity_rsv is set to the conservative log2 in 8th bits
of the number of coded bands for this frame (given by the table LOG2_FRAC_TABLE). If
-intensity_rsv is greater than total then intensity_rsv is set to zero otherwise total is
-decremented by intensity_rsv, and if total is still greater than 8 dual_stereo_rsv is
+intensity_rsv is greater than total then intensity_rsv is set to zero. Otherwise total is
+decremented by intensity_rsv, and if total is still greater than 8, dual_stereo_rsv is
set to 8 and total is decremented by dual_stereo_rsv.</t>
<t>The allocation process then computes a vector representing the hard minimum amounts allocation
any band will receive for shape. This minimum is higher than the technical limit of the PVQ
-process, but very low rate allocations produce excessively an sparse spectrum and these bands
-are better served by having no allocation at all. For each coded band set thresh[band] to
+process, but very low rate allocations produce an excessively sparse spectrum and these bands
+are better served by having no allocation at all. For each coded band, set thresh[band] to
twenty-four times the number of MDCT bins in the band and divide by 16. If 8 times the number
of channels is greater, use that instead. This sets the minimum allocation to one bit per channel
-or 48 128th bits per MDCT bin, whichever is greater. The band size dependent part of this
-value is not scaled by the channel count because at the very low rates where this limit is
+or 48 128th bits per MDCT bin, whichever is greater. The band-size dependent part of this
+value is not scaled by the channel count, because at the very low rates where this limit is
applicable there will usually be no bits allocated to the side.</t>
<t>The previously decoded allocation trim is used to derive a vector of per-band adjustments,
-'trim_offsets[]'. For each coded band take the alloc_trim and subtract 5 and LM then multiply
-the result by number of channels, the number MDCT bins in the shortest frame size for this mode,
-the number remaining bands, 2**LM, and 8. Then divide this value by 64. Finally, if the
-number of MDCT bins in the band per channel is only one 8 times the number of channels is subtracted
-in order to diminish the allocation by one bit because width 1 bands receive greater benefit
+'trim_offsets[]'. For each coded band take the alloc_trim and subtract 5 and LM. Then multiply
+the result by the number of channels, the number of MDCT bins in the shortest frame size for this mode,
+the number of remaining bands, 2**LM, and 8. Then divide this value by 64. Finally, if the
+number of MDCT bins in the band per channel is only one, 8 times the number of channels is subtracted
+in order to diminish the allocation by one bit, because width 1 bands receive greater benefit
from the coarse energy coding.</t>
@@ -3760,7 +3762,7 @@
<section anchor="PVQ-decoder" title="Shape Decoder">
<t>
In each band, the normalized "shape" is encoded
-using a vector quantization scheme called a "Pyramid vector quantizer".
+using a vector quantization scheme called a "pyramid vector quantizer".
</t>
<t>In
@@ -3778,15 +3780,15 @@
<t>
Although the allocation is performed in 1/8th bit units, the quantization requires
an integer number of pulses K. To do this, the encoder searches for the value
-of K that produces the number of bits that is the nearest to the allocated value
-(rounding down if exactly half-way between two values), subject to not exceeding
-the total number of bits available. For efficiency reasons the search is performed against a
+of K that produces the number of bits nearest to the allocated value
+(rounding down if exactly halfway between two values), not to exceed
+the total number of bits available. For efficiency reasons, the search is performed against a
precomputed allocation table which only permits some K values for each N. The number of
-codebooks entries can be computed as explained in <xref target="cwrs-encoding"></xref>. The difference
+codebook entries can be computed as explained in <xref target="cwrs-encoding"></xref>. The difference
between the number of bits allocated and the number of bits used is accumulated to a
-"balance" (initialized to zero) that helps adjusting the
+"balance" (initialized to zero) that helps adjust the
allocation for the next bands. One third of the balance is applied to the
-bit allocation of the each band to help achieving the target allocation. The only
+bit allocation of each band to help achieve the target allocation. The only
exceptions are the band before the last and the last band, for which half the balance
and the whole balance are applied, respectively.
</t>
@@ -3797,13 +3799,13 @@
<t>
The codeword is decoded as a uniformly-distributed integer value
by decode_pulses() (cwrs.c).
-The codeword is converted from a unique index in the same way as specified in
+The codeword is converted from a unique index in the same way specified in
<xref target="PVQ"></xref>. The indexing is based on the calculation of V(N,K)
(denoted N(L,K) in <xref target="PVQ"></xref>), which is the number of possible
combinations of K pulses
in N samples. The number of combinations can be computed recursively as
V(N,K) = V(N-1,K) + V(N,K-1) + V(N-1,K-1), with V(N,0) = 1 and V(0,K) = 0, K != 0.
-There are many different ways to compute V(N,K), including pre-computed tables and direct
+There are many different ways to compute V(N,K), including precomputed tables and direct
use of the recursive formulation. The reference implementation applies the recursive
formulation one line (or column) at a time to save on memory use,
along with an alternate,
@@ -3833,7 +3835,7 @@
needed, the vector is instead split in two sub-vectors of size N/2.
A quantized gain parameter with precision
derived from the current allocation is entropy coded to represent the relative
-gains of each side of the split and the entire decoding process is recursively
+gains of each side of the split, and the entire decoding process is recursively
applied. Multiple levels of splitting may be applied up to a frame size
dependent limit. The same recursive mechanism is applied for the joint coding
of stereo audio.
@@ -3852,7 +3854,7 @@
<section anchor="anti-collapse" title="Anti-collapse processing">
<t>
When the frame has the transient bit set, an anti-collapse bit is decoded.
-When anti-collapse is set, then the energy in each small MDCT is prevented
+When anti-collapse is set, the energy in each small MDCT is prevented
from collapsing to zero. For each band of each MDCT where a collapse is
detected, a pseudo-random signal is inserted with an energy corresponding
to the min energy over the two previous frames. A renormalization step is
@@ -3891,7 +3893,7 @@
within the octave is decoded using 4+octave raw bits. The final pitch period
is equal to (16<<octave)+fine_pitch-1 so it is bounded between 15 and 1022,
inclusively. Next, the gain is decoded as three raw bits and is equal to
-G=3*(int_gain+1)/32. The set of post-filter taps is decoded last using
+G=3*(int_gain+1)/32. The set of post-filter taps is decoded last, using
a pdf equal to {2, 1, 1}/4. Tapset zero corresponds to the filter coefficientsg0 = 0.3066406250, g1 = 0.2170410156, g2 = 0.1296386719. Tapset one
corresponds to the filter coefficients g0 = 0.4638671875, g1 = 0.2680664062,
@@ -3939,7 +3941,7 @@
<t>
Packet loss concealment (PLC) is an optional decoder-side feature which
SHOULD be included when transmitting over an unreliable channel. Because
-PLC is not part of the bit-stream, there are several possible ways to
+PLC is not part of the bitstream, there are several possible ways to
implement PLC with different complexity/quality trade-offs. The PLC in
the reference implementation finds a periodicity in the decoded
signal and repeats the windowed waveform using the pitch offset. The windowed
@@ -3963,11 +3965,11 @@
<t>
There are two ways to avoid or reduce glitches during the problematic mode
-transitions: with, or without side information. Only transitions with side
+transitions: with side information or without it. Only transitions with side
information are normatively specified. For transitions with no side
information, it is RECOMMENDED for the decoder to use a concealment technique
(e.g. make use of the PLC algorithm) to "fill in"
-the gap or the discontinuity caused by the mode transition. Note that this
+the gap or discontinuity caused by the mode transition. Note that this
concealment MUST NOT be applied when switching between the SILK mode and the
hybrid mode or vice versa. Similarly, it MUST NOT be applied when merely
changing the bandwidth within the same mode.
@@ -3977,7 +3979,7 @@
<t>
Switching with side information involves transmitting in-band a 5-ms
"redundant" CELT frame within the Opus frame.
-This frame is designed to fill-in the gap or discontinuity without requiring
+This frame is designed to fill in the gap or discontinuity without requiring
the decoder to conceal it. For transitions from a CELT-only frame to a
SILK-only or hybrid frame, the redundant frame is inserted in the frame
following the transition (i.e. the SILK-only/hybrid frame). For transitions
@@ -3984,9 +3986,9 @@
from a SILK-only/hybrid frame to a CELT-only frame, the redundant frame is
inserted in the first frame. For all SILK-only and hybrid frames (not only
those involved in a mode transition), a binary symbol of probability 2^-12
-needs to be decoded just after the SILK part of the bit-stream. When the
-symbol value is 1, then the frame includes an embedded redundant frame. The
-redundant frame always starts and ends on byte boundaries. For SILK-only
+needs to be decoded just after the SILK part of the bitstream. When the
+symbol value is 1, the frame then includes an embedded redundant frame. The
+redundant frame always starts and ends on a byte boundary. For SILK-only
frames, the number of bytes is simply the number of whole remaining bytes.
For hybrid frames, the number of bytes is equal to 2, plus a decoded unsigned
integer (ec_dec_uint()) between 0 and 255. For hybrid frames, the redundant
@@ -4031,7 +4033,7 @@
audio | +----------+ +-------+ | +-------+
------+ +--->| Range |
| +-------+ |encoder|---->
- | | CELT | +--->| | bit-stream
+ | | CELT | +--->| | bitstream
+->|encoder|------------------+ +-------+
| |
+-------+
@@ -4808,7 +4810,7 @@
<t>
The search for the best codevector y is performed by alg_quant()
(vq.c). There are several possible approaches to the
-search with a tradeoff between quality and complexity. The method used in the reference
+search with a trade-off between quality and complexity. The method used in the reference
implementation computes an initial codeword y1 by projecting the residual signal
R = X - p' onto the codebook pyramid of K-1 pulses:
</t>