Copyedited draft (up to line 4015).
[opus.git] / doc / draft-ietf-codec-opus.xml
index 5497351..a1415cc 100644 (file)
@@ -292,7 +292,7 @@ At the decoder, the two decoder outputs are simply added together.
 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 @@ As described, the two layers can be combined in three possible operating modes:
 </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 @@ It is also roughly the maximum useful rate of the MDCT layer, as shortly
 </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&nbsp;bytes, to
@@ -528,7 +528,7 @@ The length of the first frame, N1, MUST be no larger than the size of the
 
 <section title="An Arbitrary Number of Frames in the Packet (Code&nbsp;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 @@ Values from 0...254 indicate that 0...254&nbsp;bytes of padding are included,
 If the value is 255, then the size of the additional padding is 254&nbsp;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 @@ rng = rng - (rng/ft)*(ft-fh[k]).
 </figure>
 </t>
 <t>
-Using a special case for the first symbolrather 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 @@ Because ec_decode() is limited to a total frequency of 2**16-1, this is split
  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 @@ In practice, although the number of bits used so far is an upper bound,
 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 @@ It would be required to do so anyway for hybrid Opus frames, or to support
 <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 @@ An overview of the decoder is given in <xref target="decoder_figure"/>.
 
           <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 @@ An overview of the decoder is given in <xref target="decoder_figure"/>.
 
             <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 @@ An overview of the decoder is given in <xref target="decoder_figure"/>.
 
           <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 @@ For each channel, the resulting 2- or 3-bit integer contains the corresponding
 
 <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 @@ The quantized excitation signal follows these at the end of the frame.
 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
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 @@ Decoding the second stage residual proceeds as follows.
 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 @@ NLSF_Q15[k] = (cb1_Q8[k]<<7) + (res_Q10[k]<<14)/w_Q9[k] ,
 ]]></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 @@ center_freq_Q15 = clamp(min_center_Q15[i],
    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&nbsp;&lt;=&nbsp;k&nbsp;&lt;&nbsp;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 @@ min(NLSF_Q15[k], NLSF_Q15[k+1] - NDeltaMin_Q15[k+1]) .
 <section anchor="silk_nlsf_interpolation" title="Normalized LSF Interpolation">
 <t>
 For 20&nbsp;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 @@ The function silk_NLSF2A() (silk_NLSF2A.c) implements this procedure.
 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 @@ Even floating-point decoders SHOULD perform these steps, to avoid mismatch.
 </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 @@ a32_Q17[k] = clamp(-32768, (a32_Q17[k]+16) >> 5, 32767) << 5 .
 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 @@ Each subframe also gets its own prediction gain coefficient.
 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 @@ They are all coded using the PDF from <xref target="silk_ltp_filter_pdfs"/>
 <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 @@ As with the pulse counts, these locations are coded for all the shell blocks
 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 process then recurses into the left half, and after that returns, the
 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 @@ The CELT layer is decoded based on the following symbols and sets of symbols:
 <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 @@ to the application that a problem has occurred.
 
 <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 @@ yet). The prediction is clamped internally so that fixed point implementations w
 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 @@ determines two "priorities" for the final fine bits.
 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,35 +3565,35 @@ selected to achieve the desired rate constraints.</t>
 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
 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 @@ mechanisms are provided to alter the implicit allocation:</t>
 <list style="symbols">
 <t>Band boost</t>
 <t>Allocation trim</t>
-<t>band skipping</t>
+<t>Band skipping</t>
 </list>
 </t>
 
@@ -3611,58 +3613,58 @@ biasing the overall allocation towards higher or lower frequency bands. The thir
 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
 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 @@ the boost and having enough room to code the boost symbol. The default
 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 @@ of a one, update tell to reflect the current used capacity, if the decoded value
 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,48 +3712,48 @@ lower the coding cost of less extreme adjustments. Values lower than
 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>
 
 <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
 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 @@ from the coarse energy coding.</t>
 <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 @@ This index is converted into the corresponding vector as explained in
 <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 @@ and the whole balance are applied, respectively.
 <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 @@ the maximum size allowed for codebooks is 32 bits. When larger codebooks are
 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 @@ of stereo audio.
 <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 @@ between 0 and 6 of uniform probability. Once the octave is known, the fine pitch
 within the octave is decoded using 4+octave raw bits. The final pitch period
 is equal to (16&lt;&lt;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 coefficients
 g0 = 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 @@ where alpha_p=0.8500061035.
 <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 @@ does not require any special treatment.
 
 <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,16 +3979,16 @@ changing the bandwidth within the same mode.
 <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
 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 @@ Opus encoder block diagram.
 audio |  +----------+    +-------+  |    +-------+
 ------+                             +--->| Range |
       |  +-------+                       |encoder|---->
-      |  | CELT  |                  +--->|       | bit-stream
+      |  | CELT  |                  +--->|       | bitstream
       +->|encoder|------------------+    +-------+
          |       |
          +-------+
@@ -4808,7 +4810,7 @@ L2 norm.
 <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>