oggopus: use https where possible.
[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-02">
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="17" month="January" 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, e.g., 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 The PCM sample position is determined from the granule position using the
379  formula
380 <figure align="center">
381 <artwork align="center"><![CDATA[
382 'PCM sample position' = 'granule position' - 'pre-skip' .
383 ]]></artwork>
384 </figure>
385 </t>
386
387 <t>
388 For example, if the granule position of the first audio data page is 59,971,
389  and the pre-skip is 11,971, then the PCM sample position of the last decoded
390  sample from that page is 48,000.
391 This can be converted into a playback time using the formula
392 <figure align="center">
393 <artwork align="center"><![CDATA[
394                   'PCM sample position'
395 'playback time' = --------------------- .
396                          48000.0
397 ]]></artwork>
398 </figure>
399 </t>
400
401 <t>
402 The initial PCM sample position before any samples are played is normally '0'.
403 In this case, the PCM sample position of the first audio sample to be played
404  starts at '1', because it marks the time on the clock
405  <spanx style="emph">after</spanx> that sample has been played, and a stream
406  that is exactly one second long has a final PCM sample position of '48000',
407  as in the example here.
408 </t>
409
410 <t>
411 Vorbis streams use a granule position smaller than the number of audio samples
412  contained in the first audio data page to indicate that some of those samples
413  must be trimmed from the output (see <xref target="vorbis-trim"/>).
414 However, to do so, Vorbis requires that the first audio data page contains
415  exactly two packets, in order to allow the decoder to perform PCM position
416  adjustments before needing to return any PCM data.
417 Opus uses the pre-skip mechanism for this purpose instead, since the encoder
418  may introduce more than a single packet's worth of latency, and since very
419  large packets in streams with a very large number of channels might not fit
420  on a single page.
421 </t>
422 </section>
423
424 <section anchor="end_trimming" title="End Trimming">
425 <t>
426 The page with the 'end of stream' flag set MAY have a granule position that
427  indicates the page contains less audio data than would normally be returned by
428  decoding up through the final packet.
429 This is used to end the stream somewhere other than an even frame boundary.
430 The granule position of the most recent audio data page with completed packets
431  is used to make this determination, or '0' is used if there were no previous
432  audio data pages with a completed packet.
433 The difference between these granule positions indicates how many samples to
434  keep after decoding the packets that completed on the final page.
435 The remaining samples are discarded.
436 The number of discarded samples SHOULD be no larger than the number decoded
437  from the last packet.
438 </t>
439 </section>
440
441 <section anchor="start_granpos_restrictions"
442  title="Restrictions on the Initial Granule Position">
443 <t>
444 The granule position of the first audio data page with a completed packet MAY
445  be larger than the number of samples contained in packets that complete on
446  that page, however it MUST NOT be smaller, unless that page has the 'end of
447  stream' flag set.
448 Allowing a granule position larger than the number of samples allows the
449  beginning of a stream to be cropped or a live stream to be joined without
450  rewriting the granule position of all the remaining pages.
451 This means that the PCM sample position just before the first sample to be
452  played may be larger than '0'.
453 Synchronization when multiplexing with other logical streams still uses the PCM
454  sample position relative to '0' to compute sample times.
455 This does not affect the behavior of pre-skip: exactly 'pre-skip' samples
456  should be skipped from the beginning of the decoded output, even if the
457  initial PCM sample position is greater than zero.
458 </t>
459
460 <t>
461 On the other hand, a granule position that is smaller than the number of
462  decoded samples prevents a demuxer from working backwards to assign each
463  packet or each individual sample a valid granule position, since granule
464  positions must be non-negative.
465 A decoder MUST reject as invalid any stream where the granule position is
466  smaller than the number of samples contained in packets that complete on the
467  first audio data page with a completed packet, unless that page has the 'end
468  of stream' flag set.
469 It MAY defer this action until it decodes the last packet completed on that
470  page.
471 </t>
472
473 <t>
474 If that page has the 'end of stream' flag set, a demuxer MUST reject as invalid
475  any stream where its granule position is smaller than the 'pre-skip' amount.
476 This would indicate that more samples should be skipped from the initial
477  decoded output than exist in the stream.
478 If the granule position is smaller than the number of decoded samples produced
479  by the packets that complete on that page, then a demuxer MUST use an initial
480  granule position of '0', and can work forwards from '0' to timestamp
481  individual packets.
482 If the granule position is larger than the number of decoded samples available,
483  then the demuxer MUST still work backwards as described above, even if the
484  'end of stream' flag is set, to determine the initial granule position, and
485  thus the initial PCM sample position.
486 Both of these will be greater than '0' in this case.
487 </t>
488 </section>
489
490 <section anchor="seeking_and_preroll" title="Seeking and Pre-roll">
491 <t>
492 Seeking in Ogg files is best performed using a bisection search for a page
493  whose granule position corresponds to a PCM position at or before the seek
494  target.
495 With appropriately weighted bisection, accurate seeking can be performed with
496  just three or four bisections even in multi-gigabyte files.
497 See <xref target="seeking"/> for general implementation guidance.
498 </t>
499
500 <t>
501 When seeking within an Ogg Opus stream, the decoder SHOULD start decoding (and
502  discarding the output) at least 3840&nbsp;samples (80&nbsp;ms) prior to the
503  seek target in order to ensure that the output audio is correct by the time it
504  reaches the seek target.
505 This 'pre-roll' is separate from, and unrelated to, the 'pre-skip' used at the
506  beginning of the stream.
507 If the point 80&nbsp;ms prior to the seek target comes before the initial PCM
508  sample position, the decoder SHOULD start decoding from the beginning of the
509  stream, applying pre-skip as normal, regardless of whether the pre-skip is
510  larger or smaller than 80&nbsp;ms, and then continue to discard the samples
511  required to reach the seek target (if any).
512 </t>
513 </section>
514
515 </section>
516
517 <section anchor="headers" title="Header Packets">
518 <t>
519 An Opus stream contains exactly two mandatory header packets:
520  an identification header and a comment header.
521 </t>
522
523 <section anchor="id_header" title="Identification Header">
524
525 <figure anchor="id_header_packet" title="ID Header Packet" align="center">
526 <artwork align="center"><![CDATA[
527  0                   1                   2                   3
528  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
529 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
530 |      'O'      |      'p'      |      'u'      |      's'      |
531 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
532 |      'H'      |      'e'      |      'a'      |      'd'      |
533 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
534 |  Version = 1  | Channel Count |           Pre-skip            |
535 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
536 |                     Input Sample Rate (Hz)                    |
537 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
538 |   Output Gain (Q7.8 in dB)    | Mapping Family|               |
539 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               :
540 |                                                               |
541 :               Optional Channel Mapping Table...               :
542 |                                                               |
543 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
544 ]]></artwork>
545 </figure>
546
547 <t>
548 The fields in the identification (ID) header have the following meaning:
549 <list style="numbers">
550 <t><spanx style="strong">Magic Signature</spanx>:
551 <vspace blankLines="1"/>
552 This is an 8-octet (64-bit) field that allows codec identification and is
553  human-readable.
554 It contains, in order, the magic numbers:
555 <list style="empty">
556 <t>0x4F 'O'</t>
557 <t>0x70 'p'</t>
558 <t>0x75 'u'</t>
559 <t>0x73 's'</t>
560 <t>0x48 'H'</t>
561 <t>0x65 'e'</t>
562 <t>0x61 'a'</t>
563 <t>0x64 'd'</t>
564 </list>
565 Starting with "Op" helps distinguish it from audio data packets, as this is an
566  invalid TOC sequence.
567 <vspace blankLines="1"/>
568 </t>
569 <t><spanx style="strong">Version</spanx> (8 bits, unsigned):
570 <vspace blankLines="1"/>
571 The version number MUST always be '1' for this version of the encapsulation
572  specification.
573 Implementations SHOULD treat streams where the upper four bits of the version
574  number match that of a recognized specification as backwards-compatible with
575  that specification.
576 That is, the version number can be split into "major" and "minor" version
577  sub-fields, with changes to the "minor" sub-field (in the lower four bits)
578  signaling compatible changes.
579 For example, a decoder implementing this specification SHOULD accept any stream
580  with a version number of '15' or less, and SHOULD assume any stream with a
581  version number '16' or greater is incompatible.
582 The initial version '1' was chosen to keep implementations from relying on this
583  octet as a null terminator for the "OpusHead" string.
584 <vspace blankLines="1"/>
585 </t>
586 <t><spanx style="strong">Output Channel Count</spanx> 'C' (8 bits, unsigned):
587 <vspace blankLines="1"/>
588 This is the number of output channels.
589 This might be different than the number of encoded channels, which can change
590  on a packet-by-packet basis.
591 This value MUST NOT be zero.
592 The maximum allowable value depends on the channel mapping family, and might be
593  as large as 255.
594 See <xref target="channel_mapping"/> for details.
595 <vspace blankLines="1"/>
596 </t>
597 <t><spanx style="strong">Pre-skip</spanx> (16 bits, unsigned, little
598  endian):
599 <vspace blankLines="1"/>
600 This is the number of samples (at 48&nbsp;kHz) to discard from the decoder
601  output when starting playback, and also the number to subtract from a page's
602  granule position to calculate its PCM sample position.
603 When cropping the beginning of existing Ogg Opus streams, a pre-skip of at
604  least 3,840&nbsp;samples (80&nbsp;ms) is RECOMMENDED to ensure complete
605  convergence in the decoder.
606 <vspace blankLines="1"/>
607 </t>
608 <t><spanx style="strong">Input Sample Rate</spanx> (32 bits, unsigned, little
609  endian):
610 <vspace blankLines="1"/>
611 This field is <spanx style="emph">not</spanx> the sample rate to use for
612  playback of the encoded data.
613 <vspace blankLines="1"/>
614 Opus can switch between internal audio bandwidths of 4, 6, 8, 12, and
615  20&nbsp;kHz.
616 Each packet in the stream may have a different audio bandwidth.
617 Regardless of the audio bandwidth, the reference decoder supports decoding any
618  stream at a sample rate of 8, 12, 16, 24, or 48&nbsp;kHz.
619 The original sample rate of the encoder input is not preserved by the lossy
620  compression.
621 <vspace blankLines="1"/>
622 An Ogg Opus player SHOULD select the playback sample rate according to the
623  following procedure:
624 <list style="numbers">
625 <t>If the hardware supports 48&nbsp;kHz playback, decode at 48&nbsp;kHz.</t>
626 <t>Otherwise, if the hardware's highest available sample rate is a supported
627  rate, decode at this sample rate.</t>
628 <t>Otherwise, if the hardware's highest available sample rate is less than
629  48&nbsp;kHz, decode at the highest supported rate above this and resample.</t>
630 <t>Otherwise, decode at 48&nbsp;kHz and resample.</t>
631 </list>
632 However, the 'Input Sample Rate' field allows the encoder to pass the sample
633  rate of the original input stream as metadata.
634 This may be useful when the user requires the output sample rate to match the
635  input sample rate.
636 For example, a non-player decoder writing PCM format samples to disk might
637  choose to resample the output audio back to the original input sample rate to
638  reduce surprise to the user, who might reasonably expect to get back a file
639  with the same sample rate as the one they fed to the encoder.
640 <vspace blankLines="1"/>
641 A value of zero indicates 'unspecified'.
642 Encoders SHOULD write the actual input sample rate or zero, but decoder
643  implementations which do something with this field SHOULD take care to behave
644  sanely if given crazy values (e.g., do not actually upsample the output to
645  10 MHz if requested).
646 <vspace blankLines="1"/>
647 </t>
648 <t><spanx style="strong">Output Gain</spanx> (16 bits, signed, little
649  endian):
650 <vspace blankLines="1"/>
651 This is a gain to be applied by the decoder.
652 It is 20*log10 of the factor to scale the decoder output by to achieve the
653  desired playback volume, stored in a 16-bit, signed, two's complement
654  fixed-point value with 8 fractional bits (i.e., Q7.8).
655 To apply the gain, a decoder could use
656 <figure align="center">
657 <artwork align="center"><![CDATA[
658 sample *= pow(10, output_gain/(20.0*256)) ,
659 ]]></artwork>
660 </figure>
661  where output_gain is the raw 16-bit value from the header.
662 <vspace blankLines="1"/>
663 Virtually all players and media frameworks should apply it by default.
664 If a player chooses to apply any volume adjustment or gain modification, such
665  as the R128_TRACK_GAIN (see <xref target="comment_header"/>) or a user-facing
666  volume knob, the adjustment MUST be applied in addition to this output gain in
667  order to achieve playback at the desired volume.
668 <vspace blankLines="1"/>
669 An encoder SHOULD set this field to zero, and instead apply any gain prior to
670  encoding, when this is possible and does not conflict with the user's wishes.
671 The output gain should only be nonzero when the gain is adjusted after
672  encoding, or when the user wishes to adjust the gain for playback while
673  preserving the ability to recover the original signal amplitude.
674 <vspace blankLines="1"/>
675 Although the output gain has enormous range (+/- 128 dB, enough to amplify
676  inaudible sounds to the threshold of physical pain), most applications can
677  only reasonably use a small portion of this range around zero.
678 The large range serves in part to ensure that gain can always be losslessly
679  transferred between OpusHead and R128_TRACK_GAIN (see below) without
680  saturating.
681 <vspace blankLines="1"/>
682 </t>
683 <t><spanx style="strong">Channel Mapping Family</spanx> (8 bits,
684  unsigned):
685 <vspace blankLines="1"/>
686 This octet indicates the order and semantic meaning of the various channels
687  encoded in each Ogg packet.
688 <vspace blankLines="1"/>
689 Each possible value of this octet indicates a mapping family, which defines a
690  set of allowed channel counts, and the ordered set of channel names for each
691  allowed channel count.
692 The details are described in <xref target="channel_mapping"/>.
693 </t>
694 <t><spanx style="strong">Channel Mapping Table</spanx>:
695 This table defines the mapping from encoded streams to output channels.
696 It is omitted when the channel mapping family is 0, but REQUIRED otherwise.
697 Its contents are specified in <xref target="channel_mapping"/>.
698 </t>
699 </list>
700 </t>
701
702 <t>
703 All fields in the ID headers are REQUIRED, except for the channel mapping
704  table, which is omitted when the channel mapping family is 0.
705 Implementations SHOULD reject ID headers which do not contain enough data for
706  these fields, even if they contain a valid Magic Signature.
707 Future versions of this specification, even backwards-compatible versions,
708  might include additional fields in the ID header.
709 If an ID header has a compatible major version, but a larger minor version,
710  an implementation MUST NOT reject it for containing additional data not
711  specified here.
712 However, implementations MAY reject streams in which the ID header does not
713  complete on the first page.
714 </t>
715
716 <section anchor="channel_mapping" title="Channel Mapping">
717 <t>
718 An Ogg Opus stream allows mapping one number of Opus streams (N) to a possibly
719  larger number of decoded channels (M+N) to yet another number of output
720  channels (C), which might be larger or smaller than the number of decoded
721  channels.
722 The order and meaning of these channels are defined by a channel mapping,
723  which consists of the 'channel mapping family' octet and, for channel mapping
724  families other than family&nbsp;0, a channel mapping table, as illustrated in
725  <xref target="channel_mapping_table"/>.
726 </t>
727
728 <figure anchor="channel_mapping_table" title="Channel Mapping Table"
729  align="center">
730 <artwork align="center"><![CDATA[
731  0                   1                   2                   3
732  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
733                                                 +-+-+-+-+-+-+-+-+
734                                                 | Stream Count  |
735 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
736 | Coupled Count |              Channel Mapping...               :
737 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
738 ]]></artwork>
739 </figure>
740
741 <t>
742 The fields in the channel mapping table have the following meaning:
743 <list style="numbers" counter="8">
744 <t><spanx style="strong">Stream Count</spanx> 'N' (8 bits, unsigned):
745 <vspace blankLines="1"/>
746 This is the total number of streams encoded in each Ogg packet.
747 This value is required to correctly parse the packed Opus packets inside an
748  Ogg packet, as described in <xref target="packet_organization"/>.
749 This value MUST NOT be zero, as without at least one Opus packet with a valid
750  TOC sequence, a demuxer cannot recover the duration of an Ogg packet.
751 <vspace blankLines="1"/>
752 For channel mapping family&nbsp;0, this value defaults to 1, and is not coded.
753 <vspace blankLines="1"/>
754 </t>
755 <t><spanx style="strong">Coupled Stream Count</spanx> 'M' (8 bits, unsigned):
756 This is the number of streams whose decoders should be configured to produce
757  two channels.
758 This MUST be no larger than the total number of streams, N.
759 <vspace blankLines="1"/>
760 Each packet in an Opus stream has an internal channel count of 1 or 2, which
761  can change from packet to packet.
762 This is selected by the encoder depending on the bitrate and the audio being
763  encoded.
764 The original channel count of the encoder input is not preserved by the lossy
765  compression.
766 <vspace blankLines="1"/>
767 Regardless of the internal channel count, any Opus stream can be decoded as
768  mono (a single channel) or stereo (two channels) by appropriate initialization
769  of the decoder.
770 The 'coupled stream count' field indicates that the first M Opus decoders are
771  to be initialized for stereo output, and the remaining N-M decoders are to be
772  initialized for mono only.
773 The total number of decoded channels, (M+N), MUST be no larger than 255, as
774  there is no way to index more channels than that in the channel mapping.
775 <vspace blankLines="1"/>
776 For channel mapping family&nbsp;0, this value defaults to C-1 (i.e., 0 for mono
777  and 1 for stereo), and is not coded.
778 <vspace blankLines="1"/>
779 </t>
780 <t><spanx style="strong">Channel Mapping</spanx> (8*C bits):
781 This contains one octet per output channel, indicating which decoded channel
782  should be used for each one.
783 Let 'index' be the value of this octet for a particular output channel.
784 This value MUST either be smaller than (M+N), or be the special value 255.
785 If 'index' is less than 2*M, the output MUST be taken from decoding stream
786  ('index'/2) as stereo and selecting the left channel if 'index' is even, and
787  the right channel if 'index' is odd.
788 If 'index' is 2*M or larger, the output MUST be taken from decoding stream
789  ('index'-M) as mono.
790 If 'index' is 255, the corresponding output channel MUST contain pure silence.
791 <vspace blankLines="1"/>
792 The number of output channels, C, is not constrained to match the number of
793  decoded channels (M+N).
794 A single index value MAY appear multiple times, i.e., the same decoded channel
795  might be mapped to multiple output channels.
796 Some decoded channels might not be assigned to any output channel, as well.
797 <vspace blankLines="1"/>
798 For channel mapping family&nbsp;0, the first index defaults to 0, and if C==2,
799  the second index defaults to 1.
800 Neither index is coded.
801 </t>
802 </list>
803 </t>
804
805 <t>
806 After producing the output channels, the channel mapping family determines the
807  semantic meaning of each one.
808 Currently there are three defined mapping families, although more may be added.
809 </t>
810
811 <section anchor="channel_mapping_0" title="Channel Mapping Family 0">
812 <t>
813 Allowed numbers of channels: 1 or 2.
814 RTP mapping.
815 </t>
816 <t>
817 <list style="symbols">
818 <t>1 channel: monophonic (mono).</t>
819 <t>2 channels: stereo (left, right).</t>
820 </list>
821 <spanx style="strong">Special mapping</spanx>: This channel mapping value also
822  indicates that the contents consists of a single Opus stream that is stereo if
823  and only if C==2, with stream index 0 mapped to output channel 0 (mono, or
824  left channel) and stream index 1 mapped to output channel 1 (right channel)
825  if stereo.
826 When the 'channel mapping family' octet has this value, the channel mapping
827  table MUST be omitted from the ID header packet.
828 </t>
829 </section>
830
831 <section anchor="channel_mapping_1" title="Channel Mapping Family 1">
832 <t>
833 Allowed numbers of channels: 1...8.
834 Vorbis channel order.
835 </t>
836 <t>
837 Each channel is assigned to a speaker location in a conventional surround
838  arrangement.
839 Specific locations depend on the number of channels, and are given below
840  in order of the corresponding channel indicies.
841 <list style="symbols">
842   <t>1 channel: monophonic (mono).</t>
843   <t>2 channels: stereo (left, right).</t>
844   <t>3 channels: linear surround (left, center, right)</t>
845   <t>4 channels: quadraphonic (front&nbsp;left, front&nbsp;right, rear&nbsp;left, rear&nbsp;right).</t>
846   <t>5 channels: 5.0 surround (front&nbsp;left, front&nbsp;center, front&nbsp;right, rear&nbsp;left, rear&nbsp;right).</t>
847   <t>6 channels: 5.1 surround (front&nbsp;left, front&nbsp;center, front&nbsp;right, rear&nbsp;left, rear&nbsp;right, LFE).</t>
848   <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>
849   <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>
850 </list>
851 This set of surround options and speaker location orderings is the same
852  as those used by the Vorbis codec <xref target="vorbis-mapping"/>.
853 The ordering is different from the one used by the
854  WAVE <xref target="wave-multichannel"/> and
855  FLAC <xref target="flac"/> formats,
856  so correct ordering requires permutation of the output channels when encoding
857  from or decoding to those formats.
858 'LFE' here refers to a Low Frequency Effects, often mapped to a subwoofer
859  with no particular spacial position.
860 Implementations SHOULD identify 'side' or 'rear' speaker locations with
861  'surround' and 'back' as appropriate when interfacing with audio formats
862  or systems which prefer that terminology.
863 </t>
864 </section>
865
866 <section anchor="channel_mapping_255"
867  title="Channel Mapping Family 255">
868 <t>
869 Allowed numbers of channels: 1...255.
870 No defined channel meaning.
871 </t>
872 <t>
873 Channels are unidentified.
874 General-purpose players SHOULD NOT attempt to play these streams, and offline
875  decoders MAY deinterleave the output into separate PCM files, one per channel.
876 Decoders SHOULD NOT produce output for channels mapped to stream index 255
877  (pure silence) unless they have no other way to indicate the index of
878  non-silent channels.
879 </t>
880 </section>
881
882 <section anchor="channel_mapping_undefined"
883  title="Undefined Channel Mappings">
884 <t>
885 The remaining channel mapping families (2...254) are reserved.
886 A decoder encountering a reserved channel mapping family value SHOULD act as
887  though the value is 255.
888 </t>
889 </section>
890
891 <section anchor="downmix" title="Downmixing">
892 <t>
893 An Ogg Opus player MUST play any Ogg Opus stream with a channel mapping family
894  of 0 or 1, even if the number of channels does not match the physically
895  connected audio hardware.
896 Players SHOULD perform channel mixing to increase or reduce the number of
897  channels as needed.
898 </t>
899
900 <t>
901 Implementations MAY use the following matricies to implement downmixing from
902  multichannel files using <xref target="channel_mapping_1">Channel Mapping
903  Family 1</xref>, which are known to give acceptable results for stereo.
904 Matricies for 3 and 4 channels are normalized so each coefficent row sums
905  to 1 to avoid clipping.
906 For 5 or more channels they are normalized to 2 as a compromize between
907  clipping and dynamic range reduction.
908 </t>
909 <t>
910 In these matricies the front left and front right channels are generally
911 passed through directly.
912 When a surround channel is split between both the left and right stereo
913  channels, coefficients are chosen so their squares sum to 1, which
914  helps preserve the perceived intensity.
915 Rear channels are mixed more diffusely or attenuated to maintain focus
916  on the front channels.
917 </t>
918
919 <figure anchor="downmix-matrix-3"
920  title="Stereo downmix matrix for the linear surround channel mapping"
921  align="center">
922 <artwork align="center"><![CDATA[
923 L output = ( 0.585786 * left + 0.414214 * center                    )
924 R output = (                   0.414214 * center + 0.585786 * right )
925 ]]></artwork>
926 <postamble>
927 Exact coefficient values are 1 and 1/sqrt(2), multiplied by
928  1/(1 + 1/sqrt(2)) for normalization.
929 </postamble>
930 </figure>
931
932 <figure anchor="downmix-matrix-4"
933  title="Stereo downmix matrix for the quadraphonic channel mapping"
934  align="center">
935 <artwork align="center"><![CDATA[
936 /          \   /                                     \ / FL \
937 | L output |   | 0.422650 0.000000 0.366025 0.211325 | | FR |
938 | R output | = | 0.000000 0.422650 0.211325 0.366025 | | RL |
939 \          /   \                                     / \ RR /
940 ]]></artwork>
941 <postamble>
942 Exact coefficient values are 1, sqrt(3)/2 and 1/2, multiplied by
943  1/(1&nbsp;+&nbsp;sqrt(3)/2&nbsp;+&nbsp;1/2) for normalization.
944 </postamble>
945 </figure>
946
947 <figure anchor="downmix-matrix-5"
948  title="Stereo downmix matrix for the 5.0 surround mapping"
949  align="center">
950 <artwork align="center"><![CDATA[
951                                                          / FL \
952 /   \   /                                              \ | FC |
953 | L |   | 0.650802 0.460186 0.000000 0.563611 0.325401 | | FR |
954 | R | = | 0.000000 0.460186 0.650802 0.325401 0.563611 | | RL |
955 \   /   \                                              / | RR |
956                                                          \    /
957 ]]></artwork>
958 <postamble>
959 Exact coefficient values are 1, 1/sqrt(2), sqrt(3)/2 and 1/2, multiplied by
960  2/(1&nbsp;+&nbsp;1/sqrt(2)&nbsp;+&nbsp;sqrt(3)/2&nbsp;+&nbsp;1/2)
961  for normalization.
962 </postamble>
963 </figure>
964
965 <figure anchor="downmix-matrix-6"
966  title="Stereo downmix matrix for the 5.1 surround mapping"
967  align="center">
968 <artwork align="center"><![CDATA[
969                                                                 /FL \
970 / \   /                                                       \ |FC |
971 |L|   | 0.529067 0.374107 0.000000 0.458186 0.264534 0.374107 | |FR |
972 |R| = | 0.000000 0.374107 0.529067 0.264534 0.458186 0.374107 | |RL |
973 \ /   \                                                       / |RR |
974                                                                 \LFE/
975 ]]></artwork>
976 <postamble>
977 Exact coefficient values are 1, 1/sqrt(2), sqrt(3)/2 and 1/2, multiplied by
978 2/(1&nbsp;+&nbsp;1/sqrt(2)&nbsp;+&nbsp;sqrt(3)/2&nbsp;+&nbsp;1/2 + 1/sqrt(2))
979  for normalization.
980 </postamble>
981 </figure>
982
983 <figure anchor="downmix-matrix-7"
984  title="Stereo downmix matrix for the 6.1 surround mapping"
985  align="center">
986 <artwork align="center"><![CDATA[
987  /                                                                \
988  | 0.455310 0.321953 0.000000 0.394310 0.227655 0.278819 0.321953 |
989  | 0.000000 0.321953 0.455310 0.227655 0.394310 0.278819 0.321953 |
990  \                                                                /
991 ]]></artwork>
992 <postamble>
993 Exact coefficient values are 1, 1/sqrt(2), sqrt(3)/2, 1/2 and
994  sqrt(3)/2/sqrt(2), multiplied by
995  2/(1&nbsp;+&nbsp;1/sqrt(2)&nbsp;+&nbsp;sqrt(3)/2&nbsp;+&nbsp;1/2 +
996  sqrt(3)/2/sqrt(2) + 1/sqrt(2)) for normalization.
997 The coeffients are in the same order as in <xref target="channel_mapping_1" />,
998  and the matricies above.
999 </postamble>
1000 </figure>
1001
1002 <figure anchor="downmix-matrix-8"
1003  title="Stereo downmix matrix for the 7.1 surround mapping"
1004  align="center">
1005 <artwork align="center"><![CDATA[
1006 /                                                                 \
1007 | .388631 .274804 .000000 .336565 .194316 .336565 .194316 .274804 |
1008 | .000000 .274804 .388631 .194316 .336565 .194316 .336565 .274804 |
1009 \                                                                 /
1010 ]]></artwork>
1011 <postamble>
1012 Exact coefficient values are 1, 1/sqrt(2), sqrt(3)/2 and 1/2, multiplied by
1013  2/(2&nbsp;+&nbsp;2/sqrt(2)&nbsp;+&nbsp;sqrt(3)) for normalization.
1014 The coeffients are in the same order as in <xref target="channel_mapping_1" />,
1015  and the matricies above.
1016 </postamble>
1017 </figure>
1018
1019 </section>
1020
1021 </section> <!-- end channel_mapping_table -->
1022
1023 </section> <!-- end id_header -->
1024
1025 <section anchor="comment_header" title="Comment Header">
1026
1027 <figure anchor="comment_header_packet" title="Comment Header Packet"
1028  align="center">
1029 <artwork align="center"><![CDATA[
1030  0                   1                   2                   3
1031  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
1032 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1033 |      'O'      |      'p'      |      'u'      |      's'      |
1034 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1035 |      'T'      |      'a'      |      'g'      |      's'      |
1036 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1037 |                     Vendor String Length                      |
1038 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1039 |                                                               |
1040 :                        Vendor String...                       :
1041 |                                                               |
1042 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1043 |                   User Comment List Length                    |
1044 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1045 |                 User Comment #0 String Length                 |
1046 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1047 |                                                               |
1048 :                   User Comment #0 String...                   :
1049 |                                                               |
1050 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1051 |                 User Comment #1 String Length                 |
1052 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1053 :                                                               :
1054 ]]></artwork>
1055 </figure>
1056
1057 <t>
1058 The comment header consists of a 64-bit magic signature, followed by data in
1059  the same format as the <xref target="vorbis-comment"/> header used in Ogg
1060  Vorbis, except (like Ogg Theora and Speex) the final "framing bit" specified
1061  in the Vorbis spec is not present.
1062 <list style="numbers">
1063 <t><spanx style="strong">Magic Signature</spanx>:
1064 <vspace blankLines="1"/>
1065 This is an 8-octet (64-bit) field that allows codec identification and is
1066  human-readable.
1067 It contains, in order, the magic numbers:
1068 <list style="empty">
1069 <t>0x4F 'O'</t>
1070 <t>0x70 'p'</t>
1071 <t>0x75 'u'</t>
1072 <t>0x73 's'</t>
1073 <t>0x54 'T'</t>
1074 <t>0x61 'a'</t>
1075 <t>0x67 'g'</t>
1076 <t>0x73 's'</t>
1077 </list>
1078 Starting with "Op" helps distinguish it from audio data packets, as this is an
1079  invalid TOC sequence.
1080 <vspace blankLines="1"/>
1081 </t>
1082 <t><spanx style="strong">Vendor String Length</spanx> (32 bits, unsigned,
1083  little endian):
1084 <vspace blankLines="1"/>
1085 This field gives the length of the following vendor string, in octets.
1086 It MUST NOT indicate that the vendor string is longer than the rest of the
1087  packet.
1088 <vspace blankLines="1"/>
1089 </t>
1090 <t><spanx style="strong">Vendor String</spanx> (variable length, UTF-8 vector):
1091 <vspace blankLines="1"/>
1092 This is a simple human-readable tag for vendor information, encoded as a UTF-8
1093  string&nbsp;<xref target="RFC3629"/>.
1094 No terminating null octet is required.
1095 <vspace blankLines="1"/>
1096 This tag is intended to identify the codec encoder and encapsulation
1097  implementations, for tracing differences in technical behavior.
1098 User-facing encoding applications can use the 'ENCODER' user comment tag
1099  to identify themselves.
1100 <vspace blankLines="1"/>
1101 </t>
1102 <t><spanx style="strong">User Comment List Length</spanx> (32 bits, unsigned,
1103  little endian):
1104 <vspace blankLines="1"/>
1105 This field indicates the number of user-supplied comments.
1106 It MAY indicate there are zero user-supplied comments, in which case there are
1107  no additional fields in the packet.
1108 It MUST NOT indicate that there are so many comments that the comment string
1109  lengths would require more data than is available in the rest of the packet.
1110 <vspace blankLines="1"/>
1111 </t>
1112 <t><spanx style="strong">User Comment #i String Length</spanx> (32 bits,
1113  unsigned, little endian):
1114 <vspace blankLines="1"/>
1115 This field gives the length of the following user comment string, in octets.
1116 There is one for each user comment indicated by the 'user comment list length'
1117  field.
1118 It MUST NOT indicate that the string is longer than the rest of the packet.
1119 <vspace blankLines="1"/>
1120 </t>
1121 <t><spanx style="strong">User Comment #i String</spanx> (variable length, UTF-8
1122  vector):
1123 <vspace blankLines="1"/>
1124 This field contains a single user comment string.
1125 There is one for each user comment indicated by the 'user comment list length'
1126  field.
1127 </t>
1128 </list>
1129 </t>
1130
1131 <t>
1132 The vendor string length and user comment list length are REQUIRED, and
1133  implementations SHOULD reject comment headers that do not contain enough data
1134  for these fields, or that do not contain enough data for the corresponding
1135  vendor string or user comments they describe.
1136 Making this check before allocating the associated memory to contain the data
1137  may help prevent a possible Denial-of-Service (DoS) attack from small comment
1138  headers that claim to contain strings longer than the entire packet or more
1139  user comments than than could possibly fit in the packet.
1140 </t>
1141
1142 <t>
1143 The user comment strings follow the NAME=value format described by
1144  <xref target="vorbis-comment"/> with the same recommended tag names.
1145 One new comment tag is introduced for Ogg Opus:
1146 <figure align="center">
1147 <artwork align="left"><![CDATA[
1148 R128_TRACK_GAIN=-573
1149 ]]></artwork>
1150 </figure>
1151 representing the volume shift needed to normalize the track's volume.
1152 The gain is a Q7.8 fixed point number in dB, as in the ID header's 'output
1153  gain' field.
1154 This tag is similar to the REPLAYGAIN_TRACK_GAIN tag in
1155  Vorbis&nbsp;<xref target="replay-gain"/>, except that the normal volume
1156  reference is the <xref target="EBU-R128"/> standard.
1157 </t>
1158 <t>
1159 An Ogg Opus file MUST NOT have more than one such tag, and if present its
1160  value MUST be an integer from -32768 to 32767, inclusive, represented in
1161  ASCII with no whitespace.
1162 If present, it MUST correctly represent the R128 normalization gain relative
1163  to the 'output gain' field specified in the ID header.
1164 If a player chooses to make use of the R128_TRACK_GAIN tag, it MUST be
1165  applied <spanx style="emph">in addition</spanx> to the 'output gain' value.
1166 If an encoder wishes to use R128 normalization, and the output gain is not
1167  otherwise constrained or specified, the encoder SHOULD write the R128 gain
1168  into the 'output gain' field and store a tag containing "R128_TRACK_GAIN=0".
1169 That is, it should assume that by default tools will respect the 'output gain'
1170  field, and not the comment tag.
1171 If a tool modifies the ID header's 'output gain' field, it MUST also update or
1172  remove the R128_TRACK_GAIN comment tag.
1173 </t>
1174 <t>
1175 To avoid confusion with multiple normalization schemes, an Opus comment header
1176  SHOULD NOT contain any of the REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_TRACK_PEAK,
1177  REPLAYGAIN_ALBUM_GAIN, or REPLAYGAIN_ALBUM_PEAK tags.
1178 </t>
1179 <t>
1180 There is no Opus comment tag corresponding to REPLAYGAIN_ALBUM_GAIN.
1181 That information should instead be stored in the ID header's 'output gain'
1182  field.
1183 </t>
1184 </section>
1185
1186 </section>
1187
1188 <section anchor="packet_size_limits" title="Packet Size Limits">
1189 <t>
1190 Technically valid Opus packets can be arbitrarily large due to the padding
1191  format, although the amount of non-padding data they can contain is bounded.
1192 These packets might be spread over a similarly enormous number of Ogg pages.
1193 Encoders SHOULD use no more padding than required to make a variable bitrate
1194  (VBR) stream constant bitrate (CBR).
1195 Decoders SHOULD avoid attempting to allocate excessive amounts of memory when
1196  presented with a very large packet.
1197 The presence of an extremely large packet in the stream could indicate a
1198  memory exhaustion attack or stream corruption.
1199 Decoders SHOULD reject a packet that is too large to process, and display a
1200  warning message.
1201 </t>
1202 <t>
1203 In an Ogg Opus stream, the largest possible valid packet that does not use
1204  padding has a size of (61,298*N&nbsp;-&nbsp;2) octets, or about 60&nbsp;kB per
1205  Opus stream.
1206 With 255&nbsp;streams, this is 15,630,988&nbsp;octets (14.9&nbsp;MB) and can
1207  span up to 61,298&nbsp;Ogg pages, all but one of which will have a granule
1208  position of -1.
1209 This is of course a very extreme packet, consisting of 255&nbsp;streams, each
1210  containing 120&nbsp;ms of audio encoded as 2.5&nbsp;ms frames, each frame
1211  using the maximum possible number of octets (1275) and stored in the least
1212  efficient manner allowed (a VBR code&nbsp;3 Opus packet).
1213 Even in such a packet, most of the data will be zeros as 2.5&nbsp;ms frames
1214  cannot actually use all 1275&nbsp;octets.
1215 The largest packet consisting of entirely useful data is
1216  (15,326*N&nbsp;-&nbsp;2) octets, or about 15&nbsp;kB per stream.
1217 This corresponds to 120&nbsp;ms of audio encoded as 10&nbsp;ms frames in either
1218  SILK or Hybrid mode, but at a data rate of over 1&nbsp;Mbps, which makes little
1219  sense for the quality achieved.
1220 A more reasonable limit is (7,664*N&nbsp;-&nbsp;2) octets, or about 7.5&nbsp;kB
1221  per stream.
1222 This corresponds to 120&nbsp;ms of audio encoded as 20&nbsp;ms stereo CELT mode
1223  frames, with a total bitrate just under 511&nbsp;kbps (not counting the Ogg
1224  encapsulation overhead).
1225 With N=8, the maximum number of channels currently defined by mapping
1226  family&nbsp;1, this gives a maximum packet size of 61,310&nbsp;octets, or just
1227  under 60&nbsp;kB.
1228 This is still quite conservative, as it assumes each output channel is taken
1229  from one decoded channel of a stereo packet.
1230 An implementation could reasonably choose any of these numbers for its internal
1231  limits.
1232 </t>
1233 </section>
1234
1235 <section anchor="encoder" title="Encoder Guidelines">
1236 <t>
1237 When encoding Opus files, Ogg encoders should take into account the
1238  algorithmic delay of the Opus encoder.
1239 </t>
1240 <figure align="center">
1241 <preamble>
1242 In encoders derived from the reference implementation, the number of
1243  samples can be queried with:
1244 </preamble>
1245 <artwork align="center"><![CDATA[
1246  opus_encoder_ctl(encoder_state, OPUS_GET_LOOKAHEAD, &delay_samples);
1247 ]]></artwork>
1248 </figure>
1249 <t>
1250 To achieve good quality in the very first samples of a stream, the Ogg encoder
1251  MAY use linear predictive coding (LPC) extrapolation
1252  <xref target="linear-prediction"/> to generate at least 120 extra samples at
1253  the beginning to avoid the Opus encoder having to encode a discontinuous
1254  signal.
1255 For an input file containing 'length' samples, the Ogg encoder SHOULD set the
1256  pre-skip header value to delay_samples+extra_samples, encode at least
1257  length+delay_samples+extra_samples samples, and set the granulepos of the last
1258  page to length+delay_samples+extra_samples.
1259 This ensures that the encoded file has the same duration as the original, with
1260  no time offset. The best way to pad the end of the stream is to also use LPC
1261  extrapolation, but zero-padding is also acceptable.
1262 </t>
1263
1264 <section anchor="lpc" title="LPC Extrapolation">
1265 <t>
1266 The first step in LPC extrapolation is to compute linear prediction
1267  coefficients. <xref target="lpc-sample"/>
1268 When extending the end of the signal, order-N (typically with N ranging from 8
1269  to 40) LPC analysis is performed on a window near the end of the signal.
1270 The last N samples are used as memory to an infinite impulse response (IIR)
1271  filter.
1272 </t>
1273 <figure align="center">
1274 <preamble>
1275 The filter is then applied on a zero input to extrapolate the end of the signal.
1276 Let a(k) be the kth LPC coefficient and x(n) be the nth sample of the signal,
1277  each new sample past the end of the signal is computed as:
1278 </preamble>
1279 <artwork align="center"><![CDATA[
1280         N
1281        ---
1282 x(n) = \   a(k)*x(n-k)
1283        /
1284        ---
1285        k=1
1286 ]]></artwork>
1287 </figure>
1288 <t>
1289 The process is repeated independently for each channel.
1290 It is possible to extend the beginning of the signal by applying the same
1291  process backward in time.
1292 When extending the beginning of the signal, it is best to apply a "fade in" to
1293  the extrapolated signal, e.g. by multiplying it by a half-Hanning window
1294  <xref target="hanning"/>.
1295 </t>
1296
1297 </section>
1298
1299 <section anchor="continuous_chaining" title="Continuous Chaining">
1300 <t>
1301 In some applications, such as Internet radio, it is desirable to cut a long
1302  stream into smaller chains, e.g. so the comment header can be updated.
1303 This can be done simply by separating the input streams into segments and
1304  encoding each segment independently.
1305 The drawback of this approach is that it creates a small discontinuity
1306  at the boundary due to the lossy nature of Opus.
1307 An encoder MAY avoid this discontinuity by using the following procedure:
1308 <list style="numbers">
1309 <t>Encode the last frame of the first segment as an independent frame by
1310  turning off all forms of inter-frame prediction.
1311 De-emphasis is allowed.</t>
1312 <t>Set the granulepos of the last page to a point near the end of the last
1313  frame.</t>
1314 <t>Begin the second segment with a copy of the last frame of the first
1315  segment.</t>
1316 <t>Set the pre-skip value of the second stream in such a way as to properly
1317  join the two streams.</t>
1318 <t>Continue the encoding process normally from there, without any reset to
1319  the encoder.</t>
1320 </list>
1321 </t>
1322 <figure align="center">
1323 <preamble>
1324 In encoders derived from the reference implementation, inter-frame prediction
1325  can be turned off by calling:
1326 </preamble>
1327 <artwork align="center"><![CDATA[
1328  opus_encoder_ctl(encoder_state, OPUS_SET_PREDICTION_DISABLED, 1);
1329 ]]></artwork>
1330 <postamble>
1331 Prediction should be enabled again before resuming normal encoding, even
1332  after a reset.
1333 </postamble>
1334 </figure>
1335
1336 </section>
1337
1338 </section>
1339
1340 <section anchor="implementation" title="Implementation Status">
1341 <t>
1342 A brief summary of major implementations of this draft is available
1343  at <eref target="https://wiki.xiph.org/OggOpusImplementation"/>,
1344   along with their status.
1345 </t>
1346 <t>
1347 [Note to RFC Editor: please remove this entire section before
1348  final publication per <xref target="RFC6982"/>.]
1349 </t>
1350 </section>
1351
1352 <section anchor="security" title="Security Considerations">
1353 <t>
1354 Implementations of the Opus codec need to take appropriate security
1355  considerations into account, as outlined in <xref target="RFC4732"/>.
1356 This is just as much a problem for the container as it is for the codec itself.
1357 It is extremely important for the decoder to be robust against malicious
1358  payloads.
1359 Malicious payloads must not cause the decoder to overrun its allocated memory
1360  or to take an excessive amount of resources to decode.
1361 Although problems in encoders are typically rarer, the same applies to the
1362  encoder.
1363 Malicious audio streams must not cause the encoder to misbehave because this
1364  would allow an attacker to attack transcoding gateways.
1365 </t>
1366
1367 <t>
1368 Like most other container formats, Ogg Opus files should not be used with
1369  insecure ciphers or cipher modes that are vulnerable to known-plaintext
1370  attacks.
1371 Elements such as the Ogg page capture pattern and the magic signatures in the
1372  ID header and the comment header all have easily predictable values, in
1373  addition to various elements of the codec data itself.
1374 </t>
1375 </section>
1376
1377 <section anchor="content_type" title="Content Type">
1378 <t>
1379 An "Ogg Opus file" consists of one or more sequentially multiplexed segments,
1380  each containing exactly one Ogg Opus stream.
1381 The RECOMMENDED mime-type for Ogg Opus files is "audio/ogg".
1382 </t>
1383
1384 <figure>
1385 <preamble>
1386 If more specificity is desired, one MAY indicate the presence of Opus streams
1387  using the codecs parameter defined in <xref target="RFC6381"/>, e.g.,
1388 </preamble>
1389 <artwork align="center"><![CDATA[
1390     audio/ogg; codecs=opus
1391 ]]></artwork>
1392 <postamble>
1393  for an Ogg Opus file.
1394 </postamble>
1395 </figure>
1396
1397 <t>
1398 The RECOMMENDED filename extension for Ogg Opus files is '.opus'.
1399 </t>
1400
1401 <t>
1402 When Opus is concurrently multiplexed with other streams in an Ogg container,
1403  one SHOULD use one of the "audio/ogg", "video/ogg", or "application/ogg"
1404  mime-types, as defined in <xref target="RFC5334"/>.
1405 Such streams are not strictly "Ogg Opus files" as described above,
1406  since they contain more than a single Opus stream per sequentially
1407  multiplexed segment, e.g. video or multiple audio tracks.
1408 In such cases the the '.opus' filename extension is NOT RECOMMENDED.
1409 </t>
1410 </section>
1411
1412 <section title="IANA Considerations">
1413 <t>
1414 This document has no actions for IANA.
1415 </t>
1416 </section>
1417
1418 <section anchor="Acknowledgments" title="Acknowledgments">
1419 <t>
1420 Thanks to Greg Maxwell, Christopher "Monty" Montgomery, and Jean-Marc Valin for
1421  their valuable contributions to this document.
1422 Additional thanks to Andrew D'Addesio, Greg Maxwell, and Vincent Penqeurc'h for
1423  their feedback based on early implementations.
1424 </t>
1425 </section>
1426
1427 <section title="Copying Conditions">
1428 <t>
1429 The authors agree to grant third parties the irrevocable right to copy, use,
1430  and distribute the work, with or without modification, in any medium, without
1431  royalty, provided that, unless separate permission is granted, redistributed
1432  modified works do not contain misleading author, version, name of work, or
1433  endorsement information.
1434 </t>
1435 </section>
1436
1437 </middle>
1438 <back>
1439 <references title="Normative References">
1440  &rfc2119;
1441  &rfc3533;
1442  &rfc3629;
1443  &rfc5334;
1444  &rfc6381;
1445  &rfc6716;
1446
1447 <reference anchor="EBU-R128" target="https://tech.ebu.ch/loudness">
1448 <front>
1449   <title>Loudness Recommendation EBU R128</title>
1450   <author>
1451     <organization>EBU Technical Committee</organization>
1452   </author>
1453   <date month="August" year="2011"/>
1454 </front>
1455 </reference>
1456
1457 <reference anchor="vorbis-comment"
1458  target="https://www.xiph.org/vorbis/doc/v-comment.html">
1459 <front>
1460 <title>Ogg Vorbis I Format Specification: Comment Field and Header
1461  Specification</title>
1462 <author initials="C." surname="Montgomery"
1463  fullname="Christopher &quot;Monty&quot; Montgomery"/>
1464 <date month="July" year="2002"/>
1465 </front>
1466 </reference>
1467
1468 </references>
1469
1470 <references title="Informative References">
1471
1472 <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.3550.xml"?-->
1473  &rfc4732;
1474  &rfc6982;
1475
1476 <reference anchor="flac"
1477  target="https://xiph.org/flac/format.html">
1478   <front>
1479     <title>FLAC - Free Lossless Audio Codec Format Description</title>
1480     <author initials="J." surname="Coalson" fullname="Josh Coalson"/>
1481     <date month="January" year="2008"/>
1482   </front>
1483 </reference>
1484
1485 <reference anchor="hanning"
1486  target="https://en.wikipedia.org/wiki/Hamming_function#Hann_.28Hanning.29_window">
1487   <front>
1488     <title>Hann window</title>
1489     <author>
1490       <organization>Wikipedia</organization>
1491     </author>
1492     <date month="May" year="2013"/>
1493   </front>
1494 </reference>
1495
1496 <reference anchor="linear-prediction"
1497  target="https://en.wikipedia.org/wiki/Linear_predictive_coding">
1498   <front>
1499     <title>Linear Predictive Coding</title>
1500     <author>
1501       <organization>Wikipedia</organization>
1502     </author>
1503     <date month="January" year="2014"/>
1504   </front>
1505 </reference>
1506
1507 <reference anchor="lpc-sample"
1508   target="https://svn.xiph.org/trunk/vorbis/lib/lpc.c">
1509 <front>
1510   <title>Autocorrelation LPC coeff generation algorithm
1511     (Vorbis source code)</title>
1512 <author initials="J." surname="Degener" fullname="Jutta Degener"/>
1513 <author initials="C." surname="Bormann" fullname="Carsten Bormann"/>
1514 <date month="November" year="1994"/>
1515 </front>
1516 </reference>
1517
1518
1519 <reference anchor="replay-gain"
1520  target="https://wiki.xiph.org/VorbisComment#Replay_Gain">
1521 <front>
1522 <title>VorbisComment: Replay Gain</title>
1523 <author initials="C." surname="Parker" fullname="Conrad Parker"/>
1524 <author initials="M." surname="Leese" fullname="Martin Leese"/>
1525 <date month="June" year="2009"/>
1526 </front>
1527 </reference>
1528
1529 <reference anchor="seeking"
1530  target="https://wiki.xiph.org/Seeking">
1531 <front>
1532 <title>Granulepos Encoding and How Seeking Really Works</title>
1533 <author initials="S." surname="Pfeiffer" fullname="Silvia Pfeiffer"/>
1534 <author initials="C." surname="Parker" fullname="Conrad Parker"/>
1535 <author initials="G." surname="Maxwell" fullname="Greg Maxwell"/>
1536 <date month="May" year="2012"/>
1537 </front>
1538 </reference>
1539
1540 <reference anchor="vorbis-mapping"
1541  target="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9">
1542 <front>
1543 <title>The Vorbis I Specification, Section 4.3.9 Output Channel Order</title>
1544 <author initials="C." surname="Montgomery"
1545  fullname="Christopher &quot;Monty&quot; Montgomery"/>
1546 <date month="January" year="2010"/>
1547 </front>
1548 </reference>
1549
1550 <reference anchor="vorbis-trim"
1551  target="https://xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-130000A.2">
1552   <front>
1553     <title>The Vorbis I Specification, Appendix&nbsp;A: Embedding Vorbis
1554       into an Ogg stream</title>
1555     <author initials="C." surname="Montgomery"
1556      fullname="Christopher &quot;Monty&quot; Montgomery"/>
1557     <date month="November" year="2008"/>
1558   </front>
1559 </reference>
1560
1561 <reference anchor="wave-multichannel"
1562  target="http://msdn.microsoft.com/en-us/windows/hardware/gg463006.aspx">
1563   <front>
1564     <title>Multiple Channel Audio Data and WAVE Files</title>
1565     <author>
1566       <organization>Microsoft Corporation</organization>
1567     </author>
1568     <date month="March" year="2007"/>
1569   </front>
1570 </reference>
1571
1572 </references>
1573
1574 </back>
1575 </rfc>