oggopus: Refer to 'TOC sequence' instead of byte.
[opus.git] / doc / draft-ietf-codec-oggopus.xml
index f556200..d319bfb 100644 (file)
@@ -11,7 +11,7 @@
 ]>
 <?rfc toc="yes" symrefs="yes" ?>
 
-<rfc ipr="trust200902" category="std" docName="draft-ietf-codec-oggopus-04">
+<rfc ipr="trust200902" category="std" docName="draft-ietf-codec-oggopus-05">
 
 <front>
 <title abbrev="Ogg Opus">Ogg Encapsulation for the Opus Audio Codec</title>
@@ -60,7 +60,7 @@
 </address>
 </author>
 
-<date day="9" month="August" year="2014"/>
+<date day="15" month="October" year="2014"/>
 <area>RAI</area>
 <workgroup>codec</workgroup>
 
@@ -187,8 +187,8 @@ A decoder SHOULD treat any Opus packet whose duration is different from that of
 <t>
 The coding mode (SILK, Hybrid, or CELT), audio bandwidth, channel count,
  duration (frame size), and number of frames per packet, are indicated in the
- TOC (table of contents) in the first byte of each Opus packet, as described
- in Section&nbsp;3.1 of&nbsp;<xref target="RFC6716"/>.
+ TOC (table of contents) sequence at the beginning of each Opus packet, as
described in Section&nbsp;3.1 of&nbsp;<xref target="RFC6716"/>.
 The combination of mode, audio bandwidth, and frame size is referred to as
  the configuration of an Opus packet.
 </t>
@@ -330,7 +330,7 @@ In the example above, if the previous frame was a 20&nbsp;ms SILK mode frame,
  gap.
 This also requires four bytes to describe the synthesized packet data (two
  bytes for a CBR code 3 and one byte each for two code 0 packets) but three
- bytes of Ogg lacing overhead are necessary to mark the packet boundaries.
+ bytes of Ogg lacing overhead are needed to mark the packet boundaries.
 At 0.6 kbps, this is still a minimal bitrate impact over a naive, low quality
  solution.
 </t>
@@ -349,7 +349,7 @@ Since medium-band audio is an option only in the SILK mode, wideband frames
 There is some amount of latency introduced during the decoding process, to
  allow for overlap in the CELT mode, stereo mixing in the SILK mode, and
  resampling.
-The encoder introduces additional latency through its own resampling
+The encoder might have introduced additional latency through its own resampling
  and analysis (though the exact amount is not specified).
 Therefore, the first few samples produced by the decoder do not correspond to
  real input audio, but are instead composed of padding inserted by the encoder
@@ -364,9 +364,9 @@ However, a decoder will want to skip these samples after decoding them.
 A 'pre-skip' field in the ID header (see <xref target="id_header"/>) signals
  the number of samples which SHOULD be skipped (decoded but discarded) at the
  beginning of the stream.
-This amount MAY not be a multiple of 2.5&nbsp;ms, MAY be smaller than a single
+This amount need not be a multiple of 2.5&nbsp;ms, MAY be smaller than a single
  packet, or MAY span the contents of several packets.
-These samples are not valid audio, and SHOULD not be played.
+These samples are not valid audio, and SHOULD NOT be played.
 </t>
 
 <t>
@@ -804,7 +804,7 @@ For channel mapping family&nbsp;0, this value defaults to C-1 (i.e., 0 for mono
 </t>
 <t><spanx style="strong">Channel Mapping</spanx> (8*C bits):
 This contains one octet per output channel, indicating which decoded channel
- to be used for each one.
is to be used for each one.
 Let 'index' be the value of this octet for a particular output channel.
 This value MUST either be smaller than (M+N), or be the special value 255.
 If 'index' is less than 2*M, the output MUST be taken from decoding stream
@@ -1166,6 +1166,15 @@ Making this check before allocating the associated memory to contain the data
  user comments than than could possibly fit in the packet.
 </t>
 
+<t>
+Immediately following the user comment list, the comment header MAY
+ contain zero-padding or other binary data which is not specified here.
+If the least-significant bit of the first byte of this data is 1, then editors
+ SHOULD preserve the contents of this data when updating the tags, but if this
+ bit is 0, all such data MAY be treated as padding, and truncated or discarded
+ as desired.
+</t>
+
 <section anchor="comment_format" title="Tag Definitions">
 <t>
 The user comment strings follow the NAME=value format described by
@@ -1208,7 +1217,13 @@ The gain is also a Q7.8 fixed point number in dB, as in the ID header's
 <t>
 An Ogg Opus stream MUST NOT have more than one of each tag, and if present
  their values MUST be an integer from -32768 to 32767, inclusive,
- represented in ASCII with no whitespace.
+ represented in ASCII as a base 10 number with no whitespace.
+A leading '+' or '-' character is valid.
+Leading zeros are also permitted, but the value MUST be represented by
+ no more than 6 characters.
+Other non-digit characters MUST NOT be present.
+</t>
+<t>
 If present, R128_TRACK_GAIN and R128_ALBUM_GAIN MUST correctly represent
  the R128 normalization gain relative to the 'output gain' field specified
  in the ID header.
@@ -1226,7 +1241,7 @@ To avoid confusion with multiple normalization schemes, an Opus comment header
  REPLAYGAIN_ALBUM_GAIN, or REPLAYGAIN_ALBUM_PEAK tags.
 <xref target="EBU-R128"/> normalization is preferred to the earlier
  REPLAYGAIN schemes because of its clear definition and adoption by industry.
-PEAK normalizations are difficult to calculate reliably for lossy codecs
+Peak normalizations are difficult to calculate reliably for lossy codecs
  because of variation in excursion heights due to decoder differences.
 In the authors' investigations they were not applied consistently or broadly
  enough to merit inclusion here.
@@ -1294,7 +1309,7 @@ In encoders derived from the reference implementation, the number of
  samples can be queried with:
 </preamble>
 <artwork align="center"><![CDATA[
- opus_encoder_ctl(encoder_state, OPUS_GET_LOOKAHEAD, &delay_samples);
+ opus_encoder_ctl(encoder_state, OPUS_GET_LOOKAHEAD(&delay_samples));
 ]]></artwork>
 </figure>
 <t>
@@ -1376,7 +1391,7 @@ In encoders derived from the reference implementation, inter-frame prediction
  can be turned off by calling:
 </preamble>
 <artwork align="center"><![CDATA[
- opus_encoder_ctl(encoder_state, OPUS_SET_PREDICTION_DISABLED, 1);
+ opus_encoder_ctl(encoder_state, OPUS_SET_PREDICTION_DISABLED(1));
 ]]></artwork>
 <postamble>
 For best results, this implementation requires that prediction be explicitly
@@ -1416,7 +1431,7 @@ Malicious audio streams MUST NOT cause the encoder to misbehave because this
 </t>
 
 <t>
-Like most other container formats, Ogg Opus streams SHOULD not be used with
+Like most other container formats, Ogg Opus streams SHOULD NOT be used with
  insecure ciphers or cipher modes that are vulnerable to known-plaintext
  attacks.
 Elements such as the Ogg page capture pattern and the magic signatures in the