RTP draft edits (no normative changes).
[opus.git] / doc / draft-ietf-codec-oggopus.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
3 <!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
4 <!ENTITY rfc3533 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3533.xml'>
5 <!ENTITY rfc3629 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml'>
6 <!ENTITY rfc4732 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4732.xml'>
7 <!ENTITY rfc5334 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5334.xml'>
8 <!ENTITY rfc6381 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6381.xml'>
9 <!ENTITY rfc6716 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6716.xml'>
10 <!ENTITY rfc6982 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6982.xml'>
11 ]>
12 <?rfc toc="yes" symrefs="yes" ?>
13
14 <rfc ipr="trust200902" category="std" docName="draft-ietf-codec-oggopus-03">
15
16 <front>
17 <title abbrev="Ogg Opus">Ogg Encapsulation for the Opus Audio Codec</title>
18 <author initials="T.B." surname="Terriberry" fullname="Timothy B. Terriberry">
19 <organization>Mozilla Corporation</organization>
20 <address>
21 <postal>
22 <street>650 Castro Street</street>
23 <city>Mountain View</city>
24 <region>CA</region>
25 <code>94041</code>
26 <country>USA</country>
27 </postal>
28 <phone>+1 650 903-0800</phone>
29 <email>tterribe@xiph.org</email>
30 </address>
31 </author>
32
33 <author initials="R." surname="Lee" fullname="Ron Lee">
34 <organization>Voicetronix</organization>
35 <address>
36 <postal>
37 <street>246 Pulteney Street, Level 1</street>
38 <city>Adelaide</city>
39 <region>SA</region>
40 <code>5000</code>
41 <country>Australia</country>
42 </postal>
43 <phone>+61 8 8232 9112</phone>
44 <email>ron@debian.org</email>
45 </address>
46 </author>
47
48 <author initials="R." surname="Giles" fullname="Ralph Giles">
49 <organization>Mozilla Corporation</organization>
50 <address>
51 <postal>
52 <street>163 West Hastings Street</street>
53 <city>Vancouver</city>
54 <region>BC</region>
55 <code>V6B 1H5</code>
56 <country>Canada</country>
57 </postal>
58 <phone>+1 778 785 1540</phone>
59 <email>giles@xiph.org</email>
60 </address>
61 </author>
62
63 <date day="7" month="February" year="2014"/>
64 <area>RAI</area>
65 <workgroup>codec</workgroup>
66
67 <abstract>
68 <t>
69 This document defines the Ogg encapsulation for the Opus interactive speech and
70  audio codec.
71 This allows data encoded in the Opus format to be stored in an Ogg logical
72  bitstream.
73 Ogg encapsulation provides Opus with a long-term storage format supporting
74  all of the essential features, including metadata, fast and accurate seeking,
75  corruption detection, recapture after errors, low overhead, and the ability to
76  multiplex Opus with other codecs (including video) with minimal buffering.
77 It also provides a live streamable format, capable of delivery over a reliable
78  stream-oriented transport, without requiring all the data, or even the total
79  length of the data, up-front, in a form that is identical to the on-disk
80  storage format.
81 </t>
82 </abstract>
83 </front>
84
85 <middle>
86 <section anchor="intro" title="Introduction">
87 <t>
88 The IETF Opus codec is a low-latency audio codec optimized for both voice and
89  general-purpose audio.
90 See <xref target="RFC6716"/> for technical details.
91 This document defines the encapsulation of Opus in a continuous, logical Ogg
92  bitstream&nbsp;<xref target="RFC3533"/>.
93 </t>
94 <t>
95 Ogg bitstreams are made up of a series of 'pages', each of which contains data
96  from one or more 'packets'.
97 Pages are the fundamental unit of multiplexing in an Ogg stream.
98 Each page is associated with a particular logical stream and contains a capture
99  pattern and checksum, flags to mark the beginning and end of the logical
100  stream, and a 'granule position' that represents an absolute position in the
101  stream, to aid seeking.
102 A single page can contain up to 65,025 octets of packet data from up to 255
103  different packets.
104 Packets may be split arbitrarily across pages, and continued from one page to
105  the next (allowing packets much larger than would fit on a single page).
106 Each page contains 'lacing values' that indicate how the data is partitioned
107  into packets, allowing a demuxer to recover the packet boundaries without
108  examining the encoded data.
109 A packet is said to 'complete' on a page when the page contains the final
110  lacing value corresponding to that packet.
111 </t>
112 <t>
113 This encapsulation defines the required contents of the packet data, including
114  the necessary headers, the organization of those packets into a logical
115  stream, and the interpretation of the codec-specific granule position field.
116 It does not attempt to describe or specify the existing Ogg container format.
117 Readers unfamiliar with the basic concepts mentioned above are encouraged to
118  review the details in <xref target="RFC3533"/>.
119 </t>
120
121 </section>
122
123 <section anchor="terminology" title="Terminology">
124 <t>
125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
126  "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
127  document are to be interpreted as described in <xref target="RFC2119"/>.
128 </t>
129
130 <t>
131 Implementations that fail to satisfy one or more "MUST" requirements are
132  considered non-compliant.
133 Implementations that satisfy all "MUST" requirements, but fail to satisfy one
134  or more "SHOULD" requirements are said to be "conditionally compliant".
135 All other implementations are "unconditionally compliant".
136 </t>
137
138 </section>
139
140 <section anchor="packet_organization" title="Packet Organization">
141 <t>
142 An Opus stream is organized as follows.
143 </t>
144 <t>
145 There are two mandatory header packets.
146 The granule position of the pages on which these packets complete MUST be zero.
147 </t>
148 <t>
149 The first packet in the logical Ogg bitstream MUST contain the identification
150  (ID) header, which uniquely identifies a stream as Opus audio.
151 The format of this header is defined in <xref target="id_header"/>.
152 It MUST be placed alone (without any other packet data) on the first page of
153  the logical Ogg bitstream, and must complete on that page.
154 This page MUST have its 'beginning of stream' flag set.
155 </t>
156 <t>
157 The second packet in the logical Ogg bitstream MUST contain the comment header,
158  which contains user-supplied metadata.
159 The format of this header is defined in <xref target="comment_header"/>.
160 It MAY span one or more pages, beginning on the second page of the logical
161  stream.
162 However many pages it spans, the comment header packet MUST finish the page on
163  which it completes.
164 </t>
165 <t>
166 All subsequent pages are audio data pages, and the Ogg packets they contain are
167  audio data packets.
168 Each audio data packet contains one Opus packet for each of N different
169  streams, where N is typically one for mono or stereo, but may be greater than
170  one for multichannel audio.
171 The value N is specified in the ID header (see
172  <xref target="channel_mapping"/>), and is fixed over the entire length of the
173  logical Ogg bitstream.
174 </t>
175 <t>
176 The first N-1 Opus packets, if any, are packed one after another into the Ogg
177  packet, using the self-delimiting framing from Appendix&nbsp;B of
178  <xref target="RFC6716"/>.
179 The remaining Opus packet is packed at the end of the Ogg packet using the
180  regular, undelimited framing from Section&nbsp;3 of <xref target="RFC6716"/>.
181 All of the Opus packets in a single Ogg packet MUST be constrained to have the
182  same duration.
183 A decoder SHOULD treat any Opus packet whose duration is different from that of
184  the first Opus packet in an Ogg packet as if it were an Opus packet with an
185  illegal TOC sequence.
186 </t>
187 <t>
188 The coding mode (SILK, Hybrid, or CELT), audio bandwidth, channel count,
189  duration (frame size), and number of frames per packet, are indicated in the
190  TOC (table of contents) in the first byte of each Opus packet, as described
191  in Section&nbsp;3.1 of&nbsp;<xref target="RFC6716"/>.
192 The combination of mode, audio bandwidth, and frame size is referred to as
193  the configuration of an Opus packet.
194 </t>
195 <t>
196 The first audio data page SHOULD NOT have the 'continued packet' flag set
197  (which would indicate the first audio data packet is continued from a previous
198  page).
199 Packets MUST be placed into Ogg pages in order until the end of stream.
200 Audio packets MAY span page boundaries.
201 A decoder MUST treat a zero-octet audio data packet as if it were an Opus
202  packet with an illegal TOC sequence.
203 The last page SHOULD have the 'end of stream' flag set, but implementations
204  should be prepared to deal with truncated streams that do not have a page
205  marked 'end of stream'.
206 The final packet on the last page SHOULD NOT be a continued packet, i.e., the
207  final lacing value should be less than 255.
208 There MUST NOT be any more pages in an Opus logical bitstream after a page
209  marked 'end of stream'.
210 </t>
211 </section>
212
213 <section anchor="granpos" title="Granule Position">
214 <t>
215 The granule position of an audio data page encodes the total number of PCM
216  samples in the stream up to and including the last fully-decodable sample from
217  the last packet completed on that page.
218 A page that is entirely spanned by a single packet (that completes on a
219  subsequent page) has no granule position, and the granule position field MUST
220  be set to the special value '-1' in two's complement.
221 </t>
222
223 <t>
224 The granule position of an audio data page is in units of PCM audio samples at
225  a fixed rate of 48&nbsp;kHz (per channel; a stereo stream's granule position
226  does not increment at twice the speed of a mono stream).
227 It is possible to run an Opus decoder at other sampling rates, but the value
228  in the granule position field always counts samples assuming a 48&nbsp;kHz
229  decoding rate, and the rest of this specification makes the same assumption.
230 </t>
231
232 <t>
233 The duration of an Opus packet may be any multiple of 2.5&nbsp;ms, up to a
234  maximum of 120&nbsp;ms.
235 This duration is encoded in the TOC sequence at the beginning of each packet.
236 The number of samples returned by a decoder corresponds to this duration
237  exactly, even for the first few packets.
238 For example, a 20&nbsp;ms packet fed to a decoder running at 48&nbsp;kHz will
239  always return 960&nbsp;samples.
240 A demuxer can parse the TOC sequence at the beginning of each Ogg packet to
241  work backwards or forwards from a packet with a known granule position (i.e.,
242  the last packet completed on some page) in order to assign granule positions
243  to every packet, or even every individual sample.
244 The one exception is the last page in the stream, as described below.
245 </t>
246
247 <t>
248 All other pages with completed packets after the first MUST have a granule
249  position equal to the number of samples contained in packets that complete on
250  that page plus the granule position of the most recent page with completed
251  packets.
252 This guarantees that a demuxer can assign individual packets the same granule
253  position when working forwards as when working backwards.
254 For this to work, there cannot be any gaps.
255 </t>
256
257 <section anchor="gap-repair" title="Repairing Gaps in Real-time Streams">
258 <t>
259 In order to support capturing a real-time stream that has lost or not
260  transmitted packets, a muxer SHOULD emit packets that explicitly request the
261  use of Packet Loss Concealment (PLC) in place of the missing packets.
262 Only gaps that are a multiple of 2.5&nbsp;ms are repairable, as these are the
263  only durations that can be created by packet loss or discontinuous
264  transmission.
265 Muxers need not handle other gap sizes.
266 Creating the necessary packets involves synthesizing a TOC byte (defined in
267 Section&nbsp;3.1 of&nbsp;<xref target="RFC6716"/>)&mdash;and whatever
268  additional internal framing is needed&mdash;to indicate the packet duration
269  for each stream.
270 The actual length of each missing Opus frame inside the packet is zero bytes,
271  as defined in Section&nbsp;3.2.1 of&nbsp;<xref target="RFC6716"/>.
272 </t>
273
274 <t>
275 Zero-byte frames MAY be packed into packets using any of codes&nbsp;0, 1,
276  2, or&nbsp;3.
277 When successive frames have the same configuration, the higher code packings
278  reduce overhead.
279 Likewise, if the TOC configuration matches, the muxer MAY further combine the
280  empty frames with previous or subsequent non-zero-length frames (using
281  code&nbsp;2 or VBR code&nbsp;3).
282 </t>
283
284 <t>
285 <xref target="RFC6716"/> does not impose any requirements on the PLC, but this
286  section outlines choices that are expected to have a positive influence on
287  most PLC implementations, including the reference implementation.
288 Synthesized TOC bytes SHOULD maintain the same mode, audio bandwidth,
289  channel count, and frame size as the previous packet (if any).
290 This is the simplest and usually the most well-tested case for the PLC to
291  handle and it covers all losses that do not include a configuration switch,
292  as defined in Section&nbsp;4.5 of&nbsp;<xref target="RFC6716"/>.
293 </t>
294
295 <t>
296 When a previous packet is available, keeping the audio bandwidth and channel
297  count the same allows the PLC to provide maximum continuity in the concealment
298  data it generates.
299 However, if the size of the gap is not a multiple of the most recent frame
300  size, then the frame size will have to change for at least some frames.
301 Such changes SHOULD be delayed as long as possible to simplify
302  things for PLC implementations.
303 </t>
304
305 <t>
306 As an example, a 95&nbsp;ms gap could be encoded as nineteen 5&nbsp;ms frames
307  in two bytes with a single CBR code&nbsp;3 packet.
308 If the previous frame size was 20&nbsp;ms, using four 20&nbsp;ms frames
309  followed by three 5&nbsp;ms frames requires 4&nbsp;bytes (plus an extra byte
310  of Ogg lacing overhead), but allows the PLC to use its well-tested steady
311  state behavior for as long as possible.
312 The total bitrate of the latter approach, including Ogg overhead, is about
313  0.4&nbsp;kbps, so the impact on file size is minimal.
314 </t>
315
316 <t>
317 Changing modes is discouraged, since this causes some decoder implementations
318  to reset their PLC state.
319 However, SILK and Hybrid mode frames cannot fill gaps that are not a multiple
320  of 10&nbsp;ms.
321 If switching to CELT mode is needed to match the gap size, a muxer SHOULD do
322  so at the end of the gap to allow the PLC to function for as long as possible.
323 </t>
324
325 <t>
326 In the example above, if the previous frame was a 20&nbsp;ms SILK mode frame,
327  the better solution is to synthesize a packet describing four 20&nbsp;ms SILK
328  frames, followed by a packet with a single 10&nbsp;ms SILK
329  frame, and finally a packet with a 5&nbsp;ms CELT frame, to fill the 95&nbsp;ms
330  gap.
331 This also requires four bytes to describe the synthesized packet data (two
332  bytes for a CBR code 3 and one byte each for two code 0 packets) but three
333  bytes of Ogg lacing overhead are required to mark the packet boundaries.
334 At 0.6 kbps, this is still a minimal bitrate impact over a naive, low quality
335  solution.
336 </t>
337
338 <t>
339 Since medium-band audio is an option only in the SILK mode, wideband frames
340  SHOULD be generated if switching from that configuration to CELT mode, to
341  ensure that any PLC implementation which does try to migrate state between
342  the modes will be able to preserve all of the available audio bandwidth.
343 </t>
344
345 </section>
346
347 <section anchor="preskip" title="Pre-skip">
348 <t>
349 There is some amount of latency introduced during the decoding process, to
350  allow for overlap in the CELT mode, stereo mixing in the SILK mode, and
351  resampling.
352 The encoder will also introduce latency (though the exact amount is not
353  specified).
354 Therefore, the first few samples produced by the decoder do not correspond to
355  real input audio, but are instead composed of padding inserted by the encoder
356  to compensate for this latency.
357 These samples need to be stored and decoded, as Opus is an asymptotically
358  convergent predictive codec, meaning the decoded contents of each frame depend
359  on the recent history of decoder inputs.
360 However, a decoder will want to skip these samples after decoding them.
361 </t>
362
363 <t>
364 A 'pre-skip' field in the ID header (see <xref target="id_header"/>) signals
365  the number of samples which SHOULD be skipped (decoded but discarded) at the
366  beginning of the stream.
367 This provides sufficient history to the decoder so that it has already
368  converged before the stream's output begins.
369 It may also be used to perform sample-accurate cropping of existing encoded
370  streams.
371 This amount need not be a multiple of 2.5&nbsp;ms, may be smaller than a single
372  packet, or may span the contents of several packets.
373 </t>
374 </section>
375
376 <section anchor="pcm_sample_position" title="PCM Sample Position">
377 <t>
378 <figure align="center">
379 <preamble>
380 The PCM sample position is determined from the granule position using the
381  formula
382 </preamble>
383 <artwork align="center"><![CDATA[
384 'PCM sample position' = 'granule position' - 'pre-skip' .
385 ]]></artwork>
386 </figure>
387 </t>
388
389 <t>
390 For example, if the granule position of the first audio data page is 59,971,
391  and the pre-skip is 11,971, then the PCM sample position of the last decoded
392  sample from that page is 48,000.
393 <figure align="center">
394 <preamble>
395 This can be converted into a playback time using the formula
396 </preamble>
397 <artwork align="center"><![CDATA[
398                   'PCM sample position'
399 'playback time' = --------------------- .
400                          48000.0
401 ]]></artwork>
402 </figure>
403 </t>
404
405 <t>
406 The initial PCM sample position before any samples are played is normally '0'.
407 In this case, the PCM sample position of the first audio sample to be played
408  starts at '1', because it marks the time on the clock
409  <spanx style="emph">after</spanx> that sample has been played, and a stream
410  that is exactly one second long has a final PCM sample position of '48000',
411  as in the example here.
412 </t>
413
414 <t>
415 Vorbis streams use a granule position smaller than the number of audio samples
416  contained in the first audio data page to indicate that some of those samples
417  must be trimmed from the output (see <xref target="vorbis-trim"/>).
418 However, to do so, Vorbis requires that the first audio data page contains
419  exactly two packets, in order to allow the decoder to perform PCM position
420  adjustments before needing to return any PCM data.
421 Opus uses the pre-skip mechanism for this purpose instead, since the encoder
422  may introduce more than a single packet's worth of latency, and since very
423  large packets in streams with a very large number of channels might not fit
424  on a single page.
425 </t>
426 </section>
427
428 <section anchor="end_trimming" title="End Trimming">
429 <t>
430 The page with the 'end of stream' flag set MAY have a granule position that
431  indicates the page contains less audio data than would normally be returned by
432  decoding up through the final packet.
433 This is used to end the stream somewhere other than an even frame boundary.
434 The granule position of the most recent audio data page with completed packets
435  is used to make this determination, or '0' is used if there were no previous
436  audio data pages with a completed packet.
437 The difference between these granule positions indicates how many samples to
438  keep after decoding the packets that completed on the final page.
439 The remaining samples are discarded.
440 The number of discarded samples SHOULD be no larger than the number decoded
441  from the last packet.
442 </t>
443 </section>
444
445 <section anchor="start_granpos_restrictions"
446  title="Restrictions on the Initial Granule Position">
447 <t>
448 The granule position of the first audio data page with a completed packet MAY
449  be larger than the number of samples contained in packets that complete on
450  that page, however it MUST NOT be smaller, unless that page has the 'end of
451  stream' flag set.
452 Allowing a granule position larger than the number of samples allows the
453  beginning of a stream to be cropped or a live stream to be joined without
454  rewriting the granule position of all the remaining pages.
455 This means that the PCM sample position just before the first sample to be
456  played may be larger than '0'.
457 Synchronization when multiplexing with other logical streams still uses the PCM
458  sample position relative to '0' to compute sample times.
459 This does not affect the behavior of pre-skip: exactly 'pre-skip' samples
460  should be skipped from the beginning of the decoded output, even if the
461  initial PCM sample position is greater than zero.
462 </t>
463
464 <t>
465 On the other hand, a granule position that is smaller than the number of
466  decoded samples prevents a demuxer from working backwards to assign each
467  packet or each individual sample a valid granule position, since granule
468  positions must be non-negative.
469 A decoder MUST reject as invalid any stream where the granule position is
470  smaller than the number of samples contained in packets that complete on the
471  first audio data page with a completed packet, unless that page has the 'end
472  of stream' flag set.
473 It MAY defer this action until it decodes the last packet completed on that
474  page.
475 </t>
476
477 <t>
478 If that page has the 'end of stream' flag set, a demuxer MUST reject as invalid
479  any stream where its granule position is smaller than the 'pre-skip' amount.
480 This would indicate that more samples should be skipped from the initial
481  decoded output than exist in the stream.
482 If the granule position is smaller than the number of decoded samples produced
483  by the packets that complete on that page, then a demuxer MUST use an initial
484  granule position of '0', and can work forwards from '0' to timestamp
485  individual packets.
486 If the granule position is larger than the number of decoded samples available,
487  then the demuxer MUST still work backwards as described above, even if the
488  'end of stream' flag is set, to determine the initial granule position, and
489  thus the initial PCM sample position.
490 Both of these will be greater than '0' in this case.
491 </t>
492 </section>
493
494 <section anchor="seeking_and_preroll" title="Seeking and Pre-roll">
495 <t>
496 Seeking in Ogg files is best performed using a bisection search for a page
497  whose granule position corresponds to a PCM position at or before the seek
498  target.
499 With appropriately weighted bisection, accurate seeking can be performed with
500  just three or four bisections even in multi-gigabyte files.
501 See <xref target="seeking"/> for general implementation guidance.
502 </t>
503
504 <t>
505 When seeking within an Ogg Opus stream, the decoder SHOULD start decoding (and
506  discarding the output) at least 3840&nbsp;samples (80&nbsp;ms) prior to the
507  seek target in order to ensure that the output audio is correct by the time it
508  reaches the seek target.
509 This 'pre-roll' is separate from, and unrelated to, the 'pre-skip' used at the
510  beginning of the stream.
511 If the point 80&nbsp;ms prior to the seek target comes before the initial PCM
512  sample position, the decoder SHOULD start decoding from the beginning of the
513  stream, applying pre-skip as normal, regardless of whether the pre-skip is
514  larger or smaller than 80&nbsp;ms, and then continue to discard the samples
515  required to reach the seek target (if any).
516 </t>
517 </section>
518
519 </section>
520
521 <section anchor="headers" title="Header Packets">
522 <t>
523 An Opus stream contains exactly two mandatory header packets:
524  an identification header and a comment header.
525 </t>
526
527 <section anchor="id_header" title="Identification Header">
528
529 <figure anchor="id_header_packet" title="ID Header Packet" align="center">
530 <artwork align="center"><![CDATA[
531  0                   1                   2                   3
532  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
533 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
534 |      'O'      |      'p'      |      'u'      |      's'      |
535 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
536 |      'H'      |      'e'      |      'a'      |      'd'      |
537 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
538 |  Version = 1  | Channel Count |           Pre-skip            |
539 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
540 |                     Input Sample Rate (Hz)                    |
541 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
542 |   Output Gain (Q7.8 in dB)    | Mapping Family|               |
543 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               :
544 |                                                               |
545 :               Optional Channel Mapping Table...               :
546 |                                                               |
547 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
548 ]]></artwork>
549 </figure>
550
551 <t>
552 The fields in the identification (ID) header have the following meaning:
553 <list style="numbers">
554 <t><spanx style="strong">Magic Signature</spanx>:
555 <vspace blankLines="1"/>
556 This is an 8-octet (64-bit) field that allows codec identification and is
557  human-readable.
558 It contains, in order, the magic numbers:
559 <list style="empty">
560 <t>0x4F 'O'</t>
561 <t>0x70 'p'</t>
562 <t>0x75 'u'</t>
563 <t>0x73 's'</t>
564 <t>0x48 'H'</t>
565 <t>0x65 'e'</t>
566 <t>0x61 'a'</t>
567 <t>0x64 'd'</t>
568 </list>
569 Starting with "Op" helps distinguish it from audio data packets, as this is an
570  invalid TOC sequence.
571 <vspace blankLines="1"/>
572 </t>
573 <t><spanx style="strong">Version</spanx> (8 bits, unsigned):
574 <vspace blankLines="1"/>
575 The version number MUST always be '1' for this version of the encapsulation
576  specification.
577 Implementations SHOULD treat streams where the upper four bits of the version
578  number match that of a recognized specification as backwards-compatible with
579  that specification.
580 That is, the version number can be split into "major" and "minor" version
581  sub-fields, with changes to the "minor" sub-field (in the lower four bits)
582  signaling compatible changes.
583 For example, a decoder implementing this specification SHOULD accept any stream
584  with a version number of '15' or less, and SHOULD assume any stream with a
585  version number '16' or greater is incompatible.
586 The initial version '1' was chosen to keep implementations from relying on this
587  octet as a null terminator for the "OpusHead" string.
588 <vspace blankLines="1"/>
589 </t>
590 <t><spanx style="strong">Output Channel Count</spanx> 'C' (8 bits, unsigned):
591 <vspace blankLines="1"/>
592 This is the number of output channels.
593 This might be different than the number of encoded channels, which can change
594  on a packet-by-packet basis.
595 This value MUST NOT be zero.
596 The maximum allowable value depends on the channel mapping family, and might be
597  as large as 255.
598 See <xref target="channel_mapping"/> for details.
599 <vspace blankLines="1"/>
600 </t>
601 <t><spanx style="strong">Pre-skip</spanx> (16 bits, unsigned, little
602  endian):
603 <vspace blankLines="1"/>
604 This is the number of samples (at 48&nbsp;kHz) to discard from the decoder
605  output when starting playback, and also the number to subtract from a page's
606  granule position to calculate its PCM sample position.
607 When cropping the beginning of existing Ogg Opus streams, a pre-skip of at
608  least 3,840&nbsp;samples (80&nbsp;ms) is RECOMMENDED to ensure complete
609  convergence in the decoder.
610 <vspace blankLines="1"/>
611 </t>
612 <t><spanx style="strong">Input Sample Rate</spanx> (32 bits, unsigned, little
613  endian):
614 <vspace blankLines="1"/>
615 This field is <spanx style="emph">not</spanx> the sample rate to use for
616  playback of the encoded data.
617 <vspace blankLines="1"/>
618 Opus can switch between internal audio bandwidths of 4, 6, 8, 12, and
619  20&nbsp;kHz.
620 Each packet in the stream may have a different audio bandwidth.
621 Regardless of the audio bandwidth, the reference decoder supports decoding any
622  stream at a sample rate of 8, 12, 16, 24, or 48&nbsp;kHz.
623 The original sample rate of the encoder input is not preserved by the lossy
624  compression.
625 <vspace blankLines="1"/>
626 An Ogg Opus player SHOULD select the playback sample rate according to the
627  following procedure:
628 <list style="numbers">
629 <t>If the hardware supports 48&nbsp;kHz playback, decode at 48&nbsp;kHz.</t>
630 <t>Otherwise, if the hardware's highest available sample rate is a supported
631  rate, decode at this sample rate.</t>
632 <t>Otherwise, if the hardware's highest available sample rate is less than
633  48&nbsp;kHz, decode at the next highest supported rate above this and
634  resample.</t>
635 <t>Otherwise, decode at 48&nbsp;kHz and resample.</t>
636 </list>
637 However, the 'Input Sample Rate' field allows the encoder to pass the sample
638  rate of the original input stream as metadata.
639 This may be useful when the user requires the output sample rate to match the
640  input sample rate.
641 For example, a non-player decoder writing PCM format samples to disk might
642  choose to resample the output audio back to the original input sample rate to
643  reduce surprise to the user, who might reasonably expect to get back a file
644  with the same sample rate as the one they fed to the encoder.
645 <vspace blankLines="1"/>
646 A value of zero indicates 'unspecified'.
647 Encoders SHOULD write the actual input sample rate or zero, but decoder
648  implementations which do something with this field SHOULD take care to behave
649  sanely if given crazy values (e.g., do not actually upsample the output to
650  10 MHz if requested).
651 <vspace blankLines="1"/>
652 </t>
653 <t><spanx style="strong">Output Gain</spanx> (16 bits, signed, little
654  endian):
655 <vspace blankLines="1"/>
656 This is a gain to be applied by the decoder.
657 It is 20*log10 of the factor to scale the decoder output by to achieve the
658  desired playback volume, stored in a 16-bit, signed, two's complement
659  fixed-point value with 8 fractional bits (i.e., Q7.8).
660 <figure align="center">
661 <preamble>
662 To apply the gain, a decoder could use
663 </preamble>
664 <artwork align="center"><![CDATA[
665 sample *= pow(10, output_gain/(20.0*256)) ,
666 ]]></artwork>
667 <postamble>
668  where output_gain is the raw 16-bit value from the header.
669 </postamble>
670 </figure>
671 <vspace blankLines="1"/>
672 Virtually all players and media frameworks should apply it by default.
673 If a player chooses to apply any volume adjustment or gain modification, such
674  as the R128_TRACK_GAIN (see <xref target="comment_header"/>) or a user-facing
675  volume knob, the adjustment MUST be applied in addition to this output gain in
676  order to achieve playback at the desired volume.
677 <vspace blankLines="1"/>
678 An encoder SHOULD set this field to zero, and instead apply any gain prior to
679  encoding, when this is possible and does not conflict with the user's wishes.
680 The output gain should only be nonzero when the gain is adjusted after
681  encoding, or when the user wishes to adjust the gain for playback while
682  preserving the ability to recover the original signal amplitude.
683 <vspace blankLines="1"/>
684 Although the output gain has enormous range (+/- 128 dB, enough to amplify
685  inaudible sounds to the threshold of physical pain), most applications can
686  only reasonably use a small portion of this range around zero.
687 The large range serves in part to ensure that gain can always be losslessly
688  transferred between OpusHead and R128_TRACK_GAIN (see below) without
689  saturating.
690 <vspace blankLines="1"/>
691 </t>
692 <t><spanx style="strong">Channel Mapping Family</spanx> (8 bits,
693  unsigned):
694 <vspace blankLines="1"/>
695 This octet indicates the order and semantic meaning of the various channels
696  encoded in each Ogg packet.
697 <vspace blankLines="1"/>
698 Each possible value of this octet indicates a mapping family, which defines a
699  set of allowed channel counts, and the ordered set of channel names for each
700  allowed channel count.
701 The details are described in <xref target="channel_mapping"/>.
702 </t>
703 <t><spanx style="strong">Channel Mapping Table</spanx>:
704 This table defines the mapping from encoded streams to output channels.
705 It is omitted when the channel mapping family is 0, but REQUIRED otherwise.
706 Its contents are specified in <xref target="channel_mapping"/>.
707 </t>
708 </list>
709 </t>
710
711 <t>
712 All fields in the ID headers are REQUIRED, except for the channel mapping
713  table, which is omitted when the channel mapping family is 0.
714 Implementations SHOULD reject ID headers which do not contain enough data for
715  these fields, even if they contain a valid Magic Signature.
716 Future versions of this specification, even backwards-compatible versions,
717  might include additional fields in the ID header.
718 If an ID header has a compatible major version, but a larger minor version,
719  an implementation MUST NOT reject it for containing additional data not
720  specified here.
721 However, implementations MAY reject streams in which the ID header does not
722  complete on the first page.
723 </t>
724
725 <section anchor="channel_mapping" title="Channel Mapping">
726 <t>
727 An Ogg Opus stream allows mapping one number of Opus streams (N) to a possibly
728  larger number of decoded channels (M+N) to yet another number of output
729  channels (C), which might be larger or smaller than the number of decoded
730  channels.
731 The order and meaning of these channels are defined by a channel mapping,
732  which consists of the 'channel mapping family' octet and, for channel mapping
733  families other than family&nbsp;0, a channel mapping table, as illustrated in
734  <xref target="channel_mapping_table"/>.
735 </t>
736
737 <figure anchor="channel_mapping_table" title="Channel Mapping Table"
738  align="center">
739 <artwork align="center"><![CDATA[
740  0                   1                   2                   3
741  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
742                                                 +-+-+-+-+-+-+-+-+
743                                                 | Stream Count  |
744 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
745 | Coupled Count |              Channel Mapping...               :
746 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
747 ]]></artwork>
748 </figure>
749
750 <t>
751 The fields in the channel mapping table have the following meaning:
752 <list style="numbers" counter="8">
753 <t><spanx style="strong">Stream Count</spanx> 'N' (8 bits, unsigned):
754 <vspace blankLines="1"/>
755 This is the total number of streams encoded in each Ogg packet.
756 This value is required to correctly parse the packed Opus packets inside an
757  Ogg packet, as described in <xref target="packet_organization"/>.
758 This value MUST NOT be zero, as without at least one Opus packet with a valid
759  TOC sequence, a demuxer cannot recover the duration of an Ogg packet.
760 <vspace blankLines="1"/>
761 For channel mapping family&nbsp;0, this value defaults to 1, and is not coded.
762 <vspace blankLines="1"/>
763 </t>
764 <t><spanx style="strong">Coupled Stream Count</spanx> 'M' (8 bits, unsigned):
765 This is the number of streams whose decoders should be configured to produce
766  two channels.
767 This MUST be no larger than the total number of streams, N.
768 <vspace blankLines="1"/>
769 Each packet in an Opus stream has an internal channel count of 1 or 2, which
770  can change from packet to packet.
771 This is selected by the encoder depending on the bitrate and the audio being
772  encoded.
773 The original channel count of the encoder input is not preserved by the lossy
774  compression.
775 <vspace blankLines="1"/>
776 Regardless of the internal channel count, any Opus stream can be decoded as
777  mono (a single channel) or stereo (two channels) by appropriate initialization
778  of the decoder.
779 The 'coupled stream count' field indicates that the first M Opus decoders are
780  to be initialized for stereo output, and the remaining N-M decoders are to be
781  initialized for mono only.
782 The total number of decoded channels, (M+N), MUST be no larger than 255, as
783  there is no way to index more channels than that in the channel mapping.
784 <vspace blankLines="1"/>
785 For channel mapping family&nbsp;0, this value defaults to C-1 (i.e., 0 for mono
786  and 1 for stereo), and is not coded.
787 <vspace blankLines="1"/>
788 </t>
789 <t><spanx style="strong">Channel Mapping</spanx> (8*C bits):
790 This contains one octet per output channel, indicating which decoded channel
791  should be used for each one.
792 Let 'index' be the value of this octet for a particular output channel.
793 This value MUST either be smaller than (M+N), or be the special value 255.
794 If 'index' is less than 2*M, the output MUST be taken from decoding stream
795  ('index'/2) as stereo and selecting the left channel if 'index' is even, and
796  the right channel if 'index' is odd.
797 If 'index' is 2*M or larger, the output MUST be taken from decoding stream
798  ('index'-M) as mono.
799 If 'index' is 255, the corresponding output channel MUST contain pure silence.
800 <vspace blankLines="1"/>
801 The number of output channels, C, is not constrained to match the number of
802  decoded channels (M+N).
803 A single index value MAY appear multiple times, i.e., the same decoded channel
804  might be mapped to multiple output channels.
805 Some decoded channels might not be assigned to any output channel, as well.
806 <vspace blankLines="1"/>
807 For channel mapping family&nbsp;0, the first index defaults to 0, and if C==2,
808  the second index defaults to 1.
809 Neither index is coded.
810 </t>
811 </list>
812 </t>
813
814 <t>
815 After producing the output channels, the channel mapping family determines the
816  semantic meaning of each one.
817 Currently there are three defined mapping families, although more may be added.
818 </t>
819
820 <section anchor="channel_mapping_0" title="Channel Mapping Family 0">
821 <t>
822 Allowed numbers of channels: 1 or 2.
823 RTP mapping.
824 </t>
825 <t>
826 <list style="symbols">
827 <t>1 channel: monophonic (mono).</t>
828 <t>2 channels: stereo (left, right).</t>
829 </list>
830 <spanx style="strong">Special mapping</spanx>: This channel mapping value also
831  indicates that the contents consists of a single Opus stream that is stereo if
832  and only if C==2, with stream index 0 mapped to output channel 0 (mono, or
833  left channel) and stream index 1 mapped to output channel 1 (right channel)
834  if stereo.
835 When the 'channel mapping family' octet has this value, the channel mapping
836  table MUST be omitted from the ID header packet.
837 </t>
838 </section>
839
840 <section anchor="channel_mapping_1" title="Channel Mapping Family 1">
841 <t>
842 Allowed numbers of channels: 1...8.
843 Vorbis channel order.
844 </t>
845 <t>
846 Each channel is assigned to a speaker location in a conventional surround
847  arrangement.
848 Specific locations depend on the number of channels, and are given below
849  in order of the corresponding channel indicies.
850 <list style="symbols">
851   <t>1 channel: monophonic (mono).</t>
852   <t>2 channels: stereo (left, right).</t>
853   <t>3 channels: linear surround (left, center, right)</t>
854   <t>4 channels: quadraphonic (front&nbsp;left, front&nbsp;right, rear&nbsp;left, rear&nbsp;right).</t>
855   <t>5 channels: 5.0 surround (front&nbsp;left, front&nbsp;center, front&nbsp;right, rear&nbsp;left, rear&nbsp;right).</t>
856   <t>6 channels: 5.1 surround (front&nbsp;left, front&nbsp;center, front&nbsp;right, rear&nbsp;left, rear&nbsp;right, LFE).</t>
857   <t>7 channels: 6.1 surround (front&nbsp;left, front&nbsp;center, front&nbsp;right, side&nbsp;left, side&nbsp;right, rear&nbsp;center, LFE).</t>
858   <t>8 channels: 7.1 surround (front&nbsp;left, front&nbsp;center, front&nbsp;right, side&nbsp;left, side&nbsp;right, rear&nbsp;left, rear&nbsp;right, LFE)</t>
859 </list>
860 </t>
861 <t>
862 This set of surround options and speaker location orderings is the same
863  as those used by the Vorbis codec <xref target="vorbis-mapping"/>.
864 The ordering is different from the one used by the
865  WAVE <xref target="wave-multichannel"/> and
866  FLAC <xref target="flac"/> formats,
867  so correct ordering requires permutation of the output channels when decoding
868  to or encoding from those formats.
869 'LFE' here refers to a Low Frequency Effects, often mapped to a subwoofer
870  with no particular spatial position.
871 Implementations SHOULD identify 'side' or 'rear' speaker locations with
872  'surround' and 'back' as appropriate when interfacing with audio formats
873  or systems which prefer that terminology.
874 </t>
875 </section>
876
877 <section anchor="channel_mapping_255"
878  title="Channel Mapping Family 255">
879 <t>
880 Allowed numbers of channels: 1...255.
881 No defined channel meaning.
882 </t>
883 <t>
884 Channels are unidentified.
885 General-purpose players SHOULD NOT attempt to play these streams, and offline
886  decoders MAY deinterleave the output into separate PCM files, one per channel.
887 Decoders SHOULD NOT produce output for channels mapped to stream index 255
888  (pure silence) unless they have no other way to indicate the index of
889  non-silent channels.
890 </t>
891 </section>
892
893 <section anchor="channel_mapping_undefined"
894  title="Undefined Channel Mappings">
895 <t>
896 The remaining channel mapping families (2...254) are reserved.
897 A decoder encountering a reserved channel mapping family value SHOULD act as
898  though the value is 255.
899 </t>
900 </section>
901
902 <section anchor="downmix" title="Downmixing">
903 <t>
904 An Ogg Opus player MUST play any Ogg Opus stream with a channel mapping family
905  of 0 or 1, even if the number of channels does not match the physically
906  connected audio hardware.
907 Players SHOULD perform channel mixing to increase or reduce the number of
908  channels as needed.
909 </t>
910
911 <t>
912 Implementations MAY use the following matricies to implement downmixing from
913  multichannel files using <xref target="channel_mapping_1">Channel Mapping
914  Family 1</xref>, which are known to give acceptable results for stereo.
915 Matricies for 3 and 4 channels are normalized so each coefficent row sums
916  to 1 to avoid clipping.
917 For 5 or more channels they are normalized to 2 as a compromise between
918  clipping and dynamic range reduction.
919 </t>
920 <t>
921 In these matricies the front left and front right channels are generally
922 passed through directly.
923 When a surround channel is split between both the left and right stereo
924  channels, coefficients are chosen so their squares sum to 1, which
925  helps preserve the perceived intensity.
926 Rear channels are mixed more diffusely or attenuated to maintain focus
927  on the front channels.
928 </t>
929
930 <figure anchor="downmix-matrix-3"
931  title="Stereo downmix matrix for the linear surround channel mapping"
932  align="center">
933 <artwork align="center"><![CDATA[
934 L output = ( 0.585786 * left + 0.414214 * center                    )
935 R output = (                   0.414214 * center + 0.585786 * right )
936 ]]></artwork>
937 <postamble>
938 Exact coefficient values are 1 and 1/sqrt(2), multiplied by
939  1/(1 + 1/sqrt(2)) for normalization.
940 </postamble>
941 </figure>
942
943 <figure anchor="downmix-matrix-4"
944  title="Stereo downmix matrix for the quadraphonic channel mapping"
945  align="center">
946 <artwork align="center"><![CDATA[
947 /          \   /                                     \ / FL \
948 | L output |   | 0.422650 0.000000 0.366025 0.211325 | | FR |
949 | R output | = | 0.000000 0.422650 0.211325 0.366025 | | RL |
950 \          /   \                                     / \ RR /
951 ]]></artwork>
952 <postamble>
953 Exact coefficient values are 1, sqrt(3)/2 and 1/2, multiplied by
954  1/(1&nbsp;+&nbsp;sqrt(3)/2&nbsp;+&nbsp;1/2) for normalization.
955 </postamble>
956 </figure>
957
958 <figure anchor="downmix-matrix-5"
959  title="Stereo downmix matrix for the 5.0 surround mapping"
960  align="center">
961 <artwork align="center"><![CDATA[
962                                                          / FL \
963 /   \   /                                              \ | FC |
964 | L |   | 0.650802 0.460186 0.000000 0.563611 0.325401 | | FR |
965 | R | = | 0.000000 0.460186 0.650802 0.325401 0.563611 | | RL |
966 \   /   \                                              / | RR |
967                                                          \    /
968 ]]></artwork>
969 <postamble>
970 Exact coefficient values are 1, 1/sqrt(2), sqrt(3)/2 and 1/2, multiplied by
971  2/(1&nbsp;+&nbsp;1/sqrt(2)&nbsp;+&nbsp;sqrt(3)/2&nbsp;+&nbsp;1/2)
972  for normalization.
973 </postamble>
974 </figure>
975
976 <figure anchor="downmix-matrix-6"
977  title="Stereo downmix matrix for the 5.1 surround mapping"
978  align="center">
979 <artwork align="center"><![CDATA[
980                                                                 /FL \
981 / \   /                                                       \ |FC |
982 |L|   | 0.529067 0.374107 0.000000 0.458186 0.264534 0.374107 | |FR |
983 |R| = | 0.000000 0.374107 0.529067 0.264534 0.458186 0.374107 | |RL |
984 \ /   \                                                       / |RR |
985                                                                 \LFE/
986 ]]></artwork>
987 <postamble>
988 Exact coefficient values are 1, 1/sqrt(2), sqrt(3)/2 and 1/2, multiplied by
989 2/(1&nbsp;+&nbsp;1/sqrt(2)&nbsp;+&nbsp;sqrt(3)/2&nbsp;+&nbsp;1/2 + 1/sqrt(2))
990  for normalization.
991 </postamble>
992 </figure>
993
994 <figure anchor="downmix-matrix-7"
995  title="Stereo downmix matrix for the 6.1 surround mapping"
996  align="center">
997 <artwork align="center"><![CDATA[
998  /                                                                \
999  | 0.455310 0.321953 0.000000 0.394310 0.227655 0.278819 0.321953 |
1000  | 0.000000 0.321953 0.455310 0.227655 0.394310 0.278819 0.321953 |
1001  \                                                                /
1002 ]]></artwork>
1003 <postamble>
1004 Exact coefficient values are 1, 1/sqrt(2), sqrt(3)/2, 1/2 and
1005  sqrt(3)/2/sqrt(2), multiplied by
1006  2/(1&nbsp;+&nbsp;1/sqrt(2)&nbsp;+&nbsp;sqrt(3)/2&nbsp;+&nbsp;1/2 +
1007  sqrt(3)/2/sqrt(2) + 1/sqrt(2)) for normalization.
1008 The coeffients are in the same order as in <xref target="channel_mapping_1" />,
1009  and the matricies above.
1010 </postamble>
1011 </figure>
1012
1013 <figure anchor="downmix-matrix-8"
1014  title="Stereo downmix matrix for the 7.1 surround mapping"
1015  align="center">
1016 <artwork align="center"><![CDATA[
1017 /                                                                 \
1018 | .388631 .274804 .000000 .336565 .194316 .336565 .194316 .274804 |
1019 | .000000 .274804 .388631 .194316 .336565 .194316 .336565 .274804 |
1020 \                                                                 /
1021 ]]></artwork>
1022 <postamble>
1023 Exact coefficient values are 1, 1/sqrt(2), sqrt(3)/2 and 1/2, multiplied by
1024  2/(2&nbsp;+&nbsp;2/sqrt(2)&nbsp;+&nbsp;sqrt(3)) for normalization.
1025 The coeffients are in the same order as in <xref target="channel_mapping_1" />,
1026  and the matricies above.
1027 </postamble>
1028 </figure>
1029
1030 </section>
1031
1032 </section> <!-- end channel_mapping_table -->
1033
1034 </section> <!-- end id_header -->
1035
1036 <section anchor="comment_header" title="Comment Header">
1037
1038 <figure anchor="comment_header_packet" title="Comment Header Packet"
1039  align="center">
1040 <artwork align="center"><![CDATA[
1041  0                   1                   2                   3
1042  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
1043 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1044 |      'O'      |      'p'      |      'u'      |      's'      |
1045 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1046 |      'T'      |      'a'      |      'g'      |      's'      |
1047 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1048 |                     Vendor String Length                      |
1049 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1050 |                                                               |
1051 :                        Vendor String...                       :
1052 |                                                               |
1053 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1054 |                   User Comment List Length                    |
1055 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1056 |                 User Comment #0 String Length                 |
1057 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1058 |                                                               |
1059 :                   User Comment #0 String...                   :
1060 |                                                               |
1061 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1062 |                 User Comment #1 String Length                 |
1063 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1064 :                                                               :
1065 ]]></artwork>
1066 </figure>
1067
1068 <t>
1069 The comment header consists of a 64-bit magic signature, followed by data in
1070  the same format as the <xref target="vorbis-comment"/> header used in Ogg
1071  Vorbis, except (like Ogg Theora and Speex) the final "framing bit" specified
1072  in the Vorbis spec is not present.
1073 <list style="numbers">
1074 <t><spanx style="strong">Magic Signature</spanx>:
1075 <vspace blankLines="1"/>
1076 This is an 8-octet (64-bit) field that allows codec identification and is
1077  human-readable.
1078 It contains, in order, the magic numbers:
1079 <list style="empty">
1080 <t>0x4F 'O'</t>
1081 <t>0x70 'p'</t>
1082 <t>0x75 'u'</t>
1083 <t>0x73 's'</t>
1084 <t>0x54 'T'</t>
1085 <t>0x61 'a'</t>
1086 <t>0x67 'g'</t>
1087 <t>0x73 's'</t>
1088 </list>
1089 Starting with "Op" helps distinguish it from audio data packets, as this is an
1090  invalid TOC sequence.
1091 <vspace blankLines="1"/>
1092 </t>
1093 <t><spanx style="strong">Vendor String Length</spanx> (32 bits, unsigned,
1094  little endian):
1095 <vspace blankLines="1"/>
1096 This field gives the length of the following vendor string, in octets.
1097 It MUST NOT indicate that the vendor string is longer than the rest of the
1098  packet.
1099 <vspace blankLines="1"/>
1100 </t>
1101 <t><spanx style="strong">Vendor String</spanx> (variable length, UTF-8 vector):
1102 <vspace blankLines="1"/>
1103 This is a simple human-readable tag for vendor information, encoded as a UTF-8
1104  string&nbsp;<xref target="RFC3629"/>.
1105 No terminating null octet is required.
1106 <vspace blankLines="1"/>
1107 This tag is intended to identify the codec encoder and encapsulation
1108  implementations, for tracing differences in technical behavior.
1109 User-facing encoding applications can use the 'ENCODER' user comment tag
1110  to identify themselves.
1111 <vspace blankLines="1"/>
1112 </t>
1113 <t><spanx style="strong">User Comment List Length</spanx> (32 bits, unsigned,
1114  little endian):
1115 <vspace blankLines="1"/>
1116 This field indicates the number of user-supplied comments.
1117 It MAY indicate there are zero user-supplied comments, in which case there are
1118  no additional fields in the packet.
1119 It MUST NOT indicate that there are so many comments that the comment string
1120  lengths would require more data than is available in the rest of the packet.
1121 <vspace blankLines="1"/>
1122 </t>
1123 <t><spanx style="strong">User Comment #i String Length</spanx> (32 bits,
1124  unsigned, little endian):
1125 <vspace blankLines="1"/>
1126 This field gives the length of the following user comment string, in octets.
1127 There is one for each user comment indicated by the 'user comment list length'
1128  field.
1129 It MUST NOT indicate that the string is longer than the rest of the packet.
1130 <vspace blankLines="1"/>
1131 </t>
1132 <t><spanx style="strong">User Comment #i String</spanx> (variable length, UTF-8
1133  vector):
1134 <vspace blankLines="1"/>
1135 This field contains a single user comment string.
1136 There is one for each user comment indicated by the 'user comment list length'
1137  field.
1138 </t>
1139 </list>
1140 </t>
1141
1142 <t>
1143 The vendor string length and user comment list length are REQUIRED, and
1144  implementations SHOULD reject comment headers that do not contain enough data
1145  for these fields, or that do not contain enough data for the corresponding
1146  vendor string or user comments they describe.
1147 Making this check before allocating the associated memory to contain the data
1148  helps prevent a possible Denial-of-Service (DoS) attack from small comment
1149  headers that claim to contain strings longer than the entire packet or more
1150  user comments than than could possibly fit in the packet.
1151 </t>
1152
1153 <t>
1154 The user comment strings follow the NAME=value format described by
1155  <xref target="vorbis-comment"/> with the same recommended tag names.
1156 </t>
1157 <figure align="center">
1158   <preamble>One new comment tag is introduced for Ogg Opus:</preamble>
1159 <artwork align="left"><![CDATA[
1160 R128_TRACK_GAIN=-573
1161 ]]></artwork>
1162 <postamble>
1163 representing the volume shift needed to normalize the track's volume.
1164 The gain is a Q7.8 fixed point number in dB, as in the ID header's 'output
1165  gain' field.
1166 </postamble>
1167 </figure>
1168 <t>
1169 This tag is similar to the REPLAYGAIN_TRACK_GAIN tag in
1170  Vorbis&nbsp;<xref target="replay-gain"/>, except that the normal volume
1171  reference is the <xref target="EBU-R128"/> standard.
1172 </t>
1173 <t>
1174 An Ogg Opus file MUST NOT have more than one such tag, and if present its
1175  value MUST be an integer from -32768 to 32767, inclusive, represented in
1176  ASCII with no whitespace.
1177 If present, it MUST correctly represent the R128 normalization gain relative
1178  to the 'output gain' field specified in the ID header.
1179 If a player chooses to make use of the R128_TRACK_GAIN tag, it MUST be
1180  applied <spanx style="emph">in addition</spanx> to the 'output gain' value.
1181 If an encoder wishes to use R128 normalization, and the output gain is not
1182  otherwise constrained or specified, the encoder SHOULD write the R128 gain
1183  into the 'output gain' field and store a tag containing "R128_TRACK_GAIN=0".
1184 That is, it should assume that by default tools will respect the 'output gain'
1185  field, and not the comment tag.
1186 If a tool modifies the ID header's 'output gain' field, it MUST also update or
1187  remove the R128_TRACK_GAIN comment tag.
1188 </t>
1189 <t>
1190 To avoid confusion with multiple normalization schemes, an Opus comment header
1191  SHOULD NOT contain any of the REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_TRACK_PEAK,
1192  REPLAYGAIN_ALBUM_GAIN, or REPLAYGAIN_ALBUM_PEAK tags.
1193 </t>
1194 <t>
1195 There is no Opus comment tag corresponding to REPLAYGAIN_ALBUM_GAIN.
1196 That information should instead be stored in the ID header's 'output gain'
1197  field.
1198 </t>
1199 </section>
1200
1201 </section>
1202
1203 <section anchor="packet_size_limits" title="Packet Size Limits">
1204 <t>
1205 Technically valid Opus packets can be arbitrarily large due to the padding
1206  format, although the amount of non-padding data they can contain is bounded.
1207 These packets might be spread over a similarly enormous number of Ogg pages.
1208 Encoders SHOULD use no more padding than required to make a variable bitrate
1209  (VBR) stream constant bitrate (CBR).
1210 Decoders SHOULD avoid attempting to allocate excessive amounts of memory when
1211  presented with a very large packet.
1212 The presence of an extremely large packet in the stream could indicate a
1213  memory exhaustion attack or stream corruption.
1214 Decoders SHOULD reject a packet that is too large to process, and display a
1215  warning message.
1216 </t>
1217 <t>
1218 In an Ogg Opus stream, the largest possible valid packet that does not use
1219  padding has a size of (61,298*N&nbsp;-&nbsp;2) octets, or about 60&nbsp;kB per
1220  Opus stream.
1221 With 255&nbsp;streams, this is 15,630,988&nbsp;octets (14.9&nbsp;MB) and can
1222  span up to 61,298&nbsp;Ogg pages, all but one of which will have a granule
1223  position of -1.
1224 This is of course a very extreme packet, consisting of 255&nbsp;streams, each
1225  containing 120&nbsp;ms of audio encoded as 2.5&nbsp;ms frames, each frame
1226  using the maximum possible number of octets (1275) and stored in the least
1227  efficient manner allowed (a VBR code&nbsp;3 Opus packet).
1228 Even in such a packet, most of the data will be zeros as 2.5&nbsp;ms frames
1229  cannot actually use all 1275&nbsp;octets.
1230 The largest packet consisting of entirely useful data is
1231  (15,326*N&nbsp;-&nbsp;2) octets, or about 15&nbsp;kB per stream.
1232 This corresponds to 120&nbsp;ms of audio encoded as 10&nbsp;ms frames in either
1233  SILK or Hybrid mode, but at a data rate of over 1&nbsp;Mbps, which makes little
1234  sense for the quality achieved.
1235 A more reasonable limit is (7,664*N&nbsp;-&nbsp;2) octets, or about 7.5&nbsp;kB
1236  per stream.
1237 This corresponds to 120&nbsp;ms of audio encoded as 20&nbsp;ms stereo CELT mode
1238  frames, with a total bitrate just under 511&nbsp;kbps (not counting the Ogg
1239  encapsulation overhead).
1240 With N=8, the maximum number of channels currently defined by mapping
1241  family&nbsp;1, this gives a maximum packet size of 61,310&nbsp;octets, or just
1242  under 60&nbsp;kB.
1243 This is still quite conservative, as it assumes each output channel is taken
1244  from one decoded channel of a stereo packet.
1245 An implementation could reasonably choose any of these numbers for its internal
1246  limits.
1247 </t>
1248 </section>
1249
1250 <section anchor="encoder" title="Encoder Guidelines">
1251 <t>
1252 When encoding Opus files, Ogg encoders should take into account the
1253  algorithmic delay of the Opus encoder.
1254 </t>
1255 <figure align="center">
1256 <preamble>
1257 In encoders derived from the reference implementation, the number of
1258  samples can be queried with:
1259 </preamble>
1260 <artwork align="center"><![CDATA[
1261  opus_encoder_ctl(encoder_state, OPUS_GET_LOOKAHEAD, &delay_samples);
1262 ]]></artwork>
1263 </figure>
1264 <t>
1265 To achieve good quality in the very first samples of a stream, the Ogg encoder
1266  MAY use linear predictive coding (LPC) extrapolation
1267  <xref target="linear-prediction"/> to generate at least 120 extra samples at
1268  the beginning to avoid the Opus encoder having to encode a discontinuous
1269  signal.
1270 For an input file containing 'length' samples, the Ogg encoder SHOULD set the
1271  pre-skip header value to delay_samples+extra_samples, encode at least
1272  length+delay_samples+extra_samples samples, and set the granulepos of the last
1273  page to length+delay_samples+extra_samples.
1274 This ensures that the encoded file has the same duration as the original, with
1275  no time offset. The best way to pad the end of the stream is to also use LPC
1276  extrapolation, but zero-padding is also acceptable.
1277 </t>
1278
1279 <section anchor="lpc" title="LPC Extrapolation">
1280 <t>
1281 The first step in LPC extrapolation is to compute linear prediction
1282  coefficients. <xref target="lpc-sample"/>
1283 When extending the end of the signal, order-N (typically with N ranging from 8
1284  to 40) LPC analysis is performed on a window near the end of the signal.
1285 The last N samples are used as memory to an infinite impulse response (IIR)
1286  filter.
1287 </t>
1288 <figure align="center">
1289 <preamble>
1290 The filter is then applied on a zero input to extrapolate the end of the signal.
1291 Let a(k) be the kth LPC coefficient and x(n) be the nth sample of the signal,
1292  each new sample past the end of the signal is computed as:
1293 </preamble>
1294 <artwork align="center"><![CDATA[
1295         N
1296        ---
1297 x(n) = \   a(k)*x(n-k)
1298        /
1299        ---
1300        k=1
1301 ]]></artwork>
1302 </figure>
1303 <t>
1304 The process is repeated independently for each channel.
1305 It is possible to extend the beginning of the signal by applying the same
1306  process backward in time.
1307 When extending the beginning of the signal, it is best to apply a "fade in" to
1308  the extrapolated signal, e.g. by multiplying it by a half-Hanning window
1309  <xref target="hanning"/>.
1310 </t>
1311
1312 </section>
1313
1314 <section anchor="continuous_chaining" title="Continuous Chaining">
1315 <t>
1316 In some applications, such as Internet radio, it is desirable to cut a long
1317  stream into smaller chains, e.g. so the comment header can be updated.
1318 This can be done simply by separating the input streams into segments and
1319  encoding each segment independently.
1320 The drawback of this approach is that it creates a small discontinuity
1321  at the boundary due to the lossy nature of Opus.
1322 An encoder MAY avoid this discontinuity by using the following procedure:
1323 <list style="numbers">
1324 <t>Encode the last frame of the first segment as an independent frame by
1325  turning off all forms of inter-frame prediction.
1326 De-emphasis is allowed.</t>
1327 <t>Set the granulepos of the last page to a point near the end of the last
1328  frame.</t>
1329 <t>Begin the second segment with a copy of the last frame of the first
1330  segment.</t>
1331 <t>Set the pre-skip value of the second stream in such a way as to properly
1332  join the two streams.</t>
1333 <t>Continue the encoding process normally from there, without any reset to
1334  the encoder.</t>
1335 </list>
1336 </t>
1337 <figure align="center">
1338 <preamble>
1339 In encoders derived from the reference implementation, inter-frame prediction
1340  can be turned off by calling:
1341 </preamble>
1342 <artwork align="center"><![CDATA[
1343  opus_encoder_ctl(encoder_state, OPUS_SET_PREDICTION_DISABLED, 1);
1344 ]]></artwork>
1345 <postamble>
1346 Prediction should be enabled again before resuming normal encoding, even
1347  after a reset.
1348 </postamble>
1349 </figure>
1350
1351 </section>
1352
1353 </section>
1354
1355 <section anchor="implementation" title="Implementation Status">
1356 <t>
1357 A brief summary of major implementations of this draft is available
1358  at <eref target="https://wiki.xiph.org/OggOpusImplementation"/>,
1359   along with their status.
1360 </t>
1361 <t>
1362 [Note to RFC Editor: please remove this entire section before
1363  final publication per <xref target="RFC6982"/>.]
1364 </t>
1365 </section>
1366
1367 <section anchor="security" title="Security Considerations">
1368 <t>
1369 Implementations of the Opus codec need to take appropriate security
1370  considerations into account, as outlined in <xref target="RFC4732"/>.
1371 This is just as much a problem for the container as it is for the codec itself.
1372 It is extremely important for the decoder to be robust against malicious
1373  payloads.
1374 Malicious payloads must not cause the decoder to overrun its allocated memory
1375  or to take an excessive amount of resources to decode.
1376 Although problems in encoders are typically rarer, the same applies to the
1377  encoder.
1378 Malicious audio streams must not cause the encoder to misbehave because this
1379  would allow an attacker to attack transcoding gateways.
1380 </t>
1381
1382 <t>
1383 Like most other container formats, Ogg Opus files should not be used with
1384  insecure ciphers or cipher modes that are vulnerable to known-plaintext
1385  attacks.
1386 Elements such as the Ogg page capture pattern and the magic signatures in the
1387  ID header and the comment header all have easily predictable values, in
1388  addition to various elements of the codec data itself.
1389 </t>
1390 </section>
1391
1392 <section anchor="content_type" title="Content Type">
1393 <t>
1394 An "Ogg Opus file" consists of one or more sequentially multiplexed segments,
1395  each containing exactly one Ogg Opus stream.
1396 The RECOMMENDED mime-type for Ogg Opus files is "audio/ogg".
1397 </t>
1398
1399 <figure>
1400 <preamble>
1401 If more specificity is desired, one MAY indicate the presence of Opus streams
1402  using the codecs parameter defined in <xref target="RFC6381"/>, e.g.,
1403 </preamble>
1404 <artwork align="center"><![CDATA[
1405     audio/ogg; codecs=opus
1406 ]]></artwork>
1407 <postamble>
1408  for an Ogg Opus file.
1409 </postamble>
1410 </figure>
1411
1412 <t>
1413 The RECOMMENDED filename extension for Ogg Opus files is '.opus'.
1414 </t>
1415
1416 <t>
1417 When Opus is concurrently multiplexed with other streams in an Ogg container,
1418  one SHOULD use one of the "audio/ogg", "video/ogg", or "application/ogg"
1419  mime-types, as defined in <xref target="RFC5334"/>.
1420 Such streams are not strictly "Ogg Opus files" as described above,
1421  since they contain more than a single Opus stream per sequentially
1422  multiplexed segment, e.g. video or multiple audio tracks.
1423 In such cases the the '.opus' filename extension is NOT RECOMMENDED.
1424 </t>
1425 </section>
1426
1427 <section title="IANA Considerations">
1428 <t>
1429 This document has no actions for IANA.
1430 </t>
1431 </section>
1432
1433 <section anchor="Acknowledgments" title="Acknowledgments">
1434 <t>
1435 Thanks to Greg Maxwell, Christopher "Monty" Montgomery, and Jean-Marc Valin for
1436  their valuable contributions to this document.
1437 Additional thanks to Andrew D'Addesio, Greg Maxwell, and Vincent Penqeurc'h for
1438  their feedback based on early implementations.
1439 </t>
1440 </section>
1441
1442 <section title="Copying Conditions">
1443 <t>
1444 The authors agree to grant third parties the irrevocable right to copy, use,
1445  and distribute the work, with or without modification, in any medium, without
1446  royalty, provided that, unless separate permission is granted, redistributed
1447  modified works do not contain misleading author, version, name of work, or
1448  endorsement information.
1449 </t>
1450 </section>
1451
1452 </middle>
1453 <back>
1454 <references title="Normative References">
1455  &rfc2119;
1456  &rfc3533;
1457  &rfc3629;
1458  &rfc5334;
1459  &rfc6381;
1460  &rfc6716;
1461
1462 <reference anchor="EBU-R128" target="https://tech.ebu.ch/loudness">
1463 <front>
1464   <title>Loudness Recommendation EBU R128</title>
1465   <author>
1466     <organization>EBU Technical Committee</organization>
1467   </author>
1468   <date month="August" year="2011"/>
1469 </front>
1470 </reference>
1471
1472 <reference anchor="vorbis-comment"
1473  target="https://www.xiph.org/vorbis/doc/v-comment.html">
1474 <front>
1475 <title>Ogg Vorbis I Format Specification: Comment Field and Header
1476  Specification</title>
1477 <author initials="C." surname="Montgomery"
1478  fullname="Christopher &quot;Monty&quot; Montgomery"/>
1479 <date month="July" year="2002"/>
1480 </front>
1481 </reference>
1482
1483 </references>
1484
1485 <references title="Informative References">
1486
1487 <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.3550.xml"?-->
1488  &rfc4732;
1489  &rfc6982;
1490
1491 <reference anchor="flac"
1492  target="https://xiph.org/flac/format.html">
1493   <front>
1494     <title>FLAC - Free Lossless Audio Codec Format Description</title>
1495     <author initials="J." surname="Coalson" fullname="Josh Coalson"/>
1496     <date month="January" year="2008"/>
1497   </front>
1498 </reference>
1499
1500 <reference anchor="hanning"
1501  target="https://en.wikipedia.org/wiki/Hamming_function#Hann_.28Hanning.29_window">
1502   <front>
1503     <title>Hann window</title>
1504     <author>
1505       <organization>Wikipedia</organization>
1506     </author>
1507     <date month="May" year="2013"/>
1508   </front>
1509 </reference>
1510
1511 <reference anchor="linear-prediction"
1512  target="https://en.wikipedia.org/wiki/Linear_predictive_coding">
1513   <front>
1514     <title>Linear Predictive Coding</title>
1515     <author>
1516       <organization>Wikipedia</organization>
1517     </author>
1518     <date month="January" year="2014"/>
1519   </front>
1520 </reference>
1521
1522 <reference anchor="lpc-sample"
1523   target="https://svn.xiph.org/trunk/vorbis/lib/lpc.c">
1524 <front>
1525   <title>Autocorrelation LPC coeff generation algorithm
1526     (Vorbis source code)</title>
1527 <author initials="J." surname="Degener" fullname="Jutta Degener"/>
1528 <author initials="C." surname="Bormann" fullname="Carsten Bormann"/>
1529 <date month="November" year="1994"/>
1530 </front>
1531 </reference>
1532
1533
1534 <reference anchor="replay-gain"
1535  target="https://wiki.xiph.org/VorbisComment#Replay_Gain">
1536 <front>
1537 <title>VorbisComment: Replay Gain</title>
1538 <author initials="C." surname="Parker" fullname="Conrad Parker"/>
1539 <author initials="M." surname="Leese" fullname="Martin Leese"/>
1540 <date month="June" year="2009"/>
1541 </front>
1542 </reference>
1543
1544 <reference anchor="seeking"
1545  target="https://wiki.xiph.org/Seeking">
1546 <front>
1547 <title>Granulepos Encoding and How Seeking Really Works</title>
1548 <author initials="S." surname="Pfeiffer" fullname="Silvia Pfeiffer"/>
1549 <author initials="C." surname="Parker" fullname="Conrad Parker"/>
1550 <author initials="G." surname="Maxwell" fullname="Greg Maxwell"/>
1551 <date month="May" year="2012"/>
1552 </front>
1553 </reference>
1554
1555 <reference anchor="vorbis-mapping"
1556  target="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">
1557 <front>
1558 <title>The Vorbis I Specification, Section 4.3.9 Output Channel Order</title>
1559 <author initials="C." surname="Montgomery"
1560  fullname="Christopher &quot;Monty&quot; Montgomery"/>
1561 <date month="January" year="2010"/>
1562 </front>
1563 </reference>
1564
1565 <reference anchor="vorbis-trim"
1566  target="https://xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-130000A.2">
1567   <front>
1568     <title>The Vorbis I Specification, Appendix&nbsp;A: Embedding Vorbis
1569       into an Ogg stream</title>
1570     <author initials="C." surname="Montgomery"
1571      fullname="Christopher &quot;Monty&quot; Montgomery"/>
1572     <date month="November" year="2008"/>
1573   </front>
1574 </reference>
1575
1576 <reference anchor="wave-multichannel"
1577  target="http://msdn.microsoft.com/en-us/windows/hardware/gg463006.aspx">
1578   <front>
1579     <title>Multiple Channel Audio Data and WAVE Files</title>
1580     <author>
1581       <organization>Microsoft Corporation</organization>
1582     </author>
1583     <date month="March" year="2007"/>
1584   </front>
1585 </reference>
1586
1587 </references>
1588
1589 </back>
1590 </rfc>