third_party/opus/src/doc/opus_in_isobmff.html - Issue 2962373002: [Opus] Update to v1.2.1

Unified Diff: third_party/opus/src/doc/opus_in_isobmff.html

Issue 2962373002: [Opus] Update to v1.2.1 (Closed)

Patch Set: Pre-increment instead of post-increment Created 3 years, 5 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Index: third_party/opus/src/doc/opus_in_isobmff.html

diff --git a/third_party/opus/src/doc/opus_in_isobmff.html b/third_party/opus/src/doc/opus_in_isobmff.html

new file mode 100644

index 0000000000000000000000000000000000000000..a1175dbfdde25e8372ed6fc4d0401fca922c599e

--- /dev/null

+++ b/third_party/opus/src/doc/opus_in_isobmff.html

@@ -0,0 +1,684 @@

+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

+<html>

+ <head>

+ <link rel="stylesheet" type="text/css" href="opus_in_isobmff.css"/>

+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

+ <title>Encapsulation of Opus in ISO Base Media File Format</title>

+ </head>

+ <body bgcolor="0x333333" text="#60B0C0">

+ <b><u>Encapsulation of Opus in ISO Base Media File Format</u></b><br>

+ <font size="2">last updated: April 28, 2016</font><br>

+ <br>

+ <div class="normal_link pre frame_box">

+ Encapsulation of Opus in ISO Base Media File Format

+ Version 0.6.8 (incomplete)

+Table of Contents

+<a href="#1">1</a> Scope

+<a href="#2">2</a> Normative References

+<a href="#3">3</a> Terms and Definitions

+<a href="#4">4</a> Design Rules of Encapsulation

+ <a href="#4.1">4.1</a> File Type Indentification

+ <a href="#4.2">4.2</a> Overview of Track Structure

+ <a href="#4.3">4.3</a> Definitions of Opus sample

+ <a href="#4.3.1">4.3.1</a> Sample entry format

+ <a href="#4.3.2">4.3.2</a> Opus Specific Box

+ <a href="#4.3.3">4.3.3</a> Sample format

+ <a href="#4.3.4">4.3.4</a> Duration of Opus sample

+ <a href="#4.3.5">4.3.5</a> Sub-sample

+ <a href="#4.3.6">4.3.6</a> Random Access

+ <a href="#4.3.6.1">4.3.6.1</a> Random Access Point

+ <a href="#4.3.6.2">4.3.6.2</a> Pre-roll

+ <a href="#4.4">4.4</a> Trimming of Actual Duration

+ <a href="#4.5">4.5</a> Channel Layout (informative)

+ <a href="#4.6">4.6</a> Basic Structure (informative)

+ <a href="#4.6.1">4.6.2</a> Initial Movie

+ <a href="#4.6.2">4.6.3</a> Movie Fragments

+ <a href="#4.7">4.7</a> Example of Encapsulation (informative)

+<a href="#5">5</a> Author's Address

+<a name="1"></a>

+1 Scope

+ This specification specifies the fundamental way of the encapsulation of Opus coded bitstreams in ISO Base Media

+ file format and its derivatives. The encapsulation of Opus coded bitstreams in QuickTime file format is outside

+ the scope of this specification.

+<a name="2"></a>

+2 Normative References

+ [1] ISO/IEC 14496-12:2015 Corrected version

+ Information technology — Coding of audio-visual objects — Part 12: ISO base media file format

+ [2] RFC 6716

+ Definition of the Opus Audio Codec

+ [3] draft-ietf-codec-oggopus-06

+ Ogg Encapsulation for the Opus Audio Codec

+<a name="3"></a>

+3 Terms and Definitions

+ 3.1 active track

+ enabled track from the non-alternate group or selected track from alternate group

+ 3.2 actual duration

+ duration constructed from valid samples

+ 3.3 edit

+ entry in the Edit List Box

+ 3.4 padded samples

+ PCM samples after decoding Opus sample(s) which are not valid samples

+ An Opus bitstream always contains them partially at the beginning and may contain them in part at the end, as

+ long as not physically removed yet at the beginning and/or the end.

+ 3.5 priming samples

+ padded samples at the beginning of the Opus bitstream

+ 3.6 sample-accurate

+ for any PCM sample, a timestamp exactly matching its sampling timestamp is present in the media timeline.

+ 3.7 valid samples

+ PCM samples after decoding Opus sample(s) corresponding to input PCM samples

+<a name="4"></a>

+4 Design Rules of Encapsulation

+ 4.1 File Type Indentification<a name="4.1"></a>

+ This specification does not define any brand to declare files are conformant to this specification. However,

+ files conformant to this specification shall contain at least one brand, which supports the requirements and the

+ requirements described in this clause without contradiction, in the compatible brands list of the File Type Box.

+ As an example, the minimal support of the encapsulation of Opus bitstreams in ISO Base Media file format requires

+ the 'iso2' brand in the compatible brands list since support of roll groups is required.

+<a name="4.2"></a>

+ 4.2 Overview of Track Structure

+ This clause summarizes requirements of the encapsulation of Opus coded bitstream as media data in audio tracks

+ in file formats compliant with the ISO Base Media File Format. The details are described in clauses after this

+ clause.

+ + The handler_type field in the Handler Reference Box shall be set to 'soun'.

+ + The Media Information Box shall contain the Sound Media Header Box.

+ + The codingname of the sample entry is 'Opus'.

+ This specification does not define any encapsulation using MP4AudioSampleEntry with objectTypeIndication

+ specified by the MPEG-4 Registration Authority (http://www.mp4ra.org/).

+ See 4.3.1 Sample entry format to get the details about the sample entry.

+ + The 'dOps' box is added to the sample entry to convey initializing information for the decoder.

+ See 4.3.2 Opus Specific Box to get the details.

+ + An Opus sample is exactly one Opus packet for each of different Opus bitstreams.

+ See 4.3.3 Sample format to get the details.

+ + Every Opus sample is a sync sample but requires pre-roll for every random access to get correct output.

+ See 4.3.6 Random Access to get the details.

+<a name="4.3"></a>

+ 4.3 Definitions of Opus sample

+ 4.3.1 Sample entry format<a name="4.3.1"></a>

+ For any track containing Opus bitstreams, at least one sample entry describing corresponding Opus bitstream

+ shall be present inside the Sample Table Box. This version of the specification defines only one sample

+ entry format named OpusSampleEntry whose codingname is 'Opus'. This sample entry includes exactly one Opus

+ Specific Box defined in 4.3.2 as a mandatory box and indicates that Opus samples described by this sample

+ entry are stored by the sample format described in 4.3.3.

+ The syntax and semantics of the OpusSampleEntry is shown as follows.

+ class OpusSampleEntry() extends AudioSampleEntry ('Opus'){

+ OpusSpecificBox();

+ }

+ + channelcount:

+ The channelcount field shall be set to the sum of the total number of Opus bitstreams and the number

+ of Opus bitstreams producing two channels. This value is indentical with (M+N), where M is the value of

+ the *Coupled Stream Count* field and N is the value of the *Stream Count* field in the *Channel Mapping

+ Table* in the identification header defined in Ogg Opus [3].

+ + samplesize:

+ The samplesize field shall be set to 16.

+ + samplerate:

+ The samplerate field shall be set to 48000&lt&lt16.

+ + OpusSpecificBox

+ This box contains initializing information for the decoder as defined in 4.3.2.

+ 4.3.2 Opus Specific Box<a name="4.3.2"></a>

+ Exactly one Opus Specific Box shall be present in each OpusSampleEntry.

+ The Opus Specific Box contains the Version field and this specification defines version 0 of this box.

+ If incompatible changes occured in the fields after the Version field within the OpusSpecificBox in the

+ future versions of this specification, another version will be defined.

+ This box refers to Ogg Opus [3] at many parts but all the data are stored as big-endian format.

+ The syntax and semantics of the Opus Specific Box is shown as follows.

+ class ChannelMappingTable (unsigned int(8) OutputChannelCount){

+ unsigned int(8) StreamCount;

+ unsigned int(8) CoupledCount;

+ unsigned int(8 * OutputChannelCount) ChannelMapping;

+ }

+ aligned(8) class OpusSpecificBox extends Box('dOps'){

+ unsigned int(8) Version;

+ unsigned int(8) OutputChannelCount;

+ unsigned int(16) PreSkip;

+ unsigned int(32) InputSampleRate;

+ signed int(16) OutputGain;

+ unsigned int(8) ChannelMappingFamily;

+ if (ChannelMappingFamily != 0) {

+ ChannelMappingTable(OutputChannelCount);

+ }

+ + Version:

+ The Version field shall be set to 0.

+ In the future versions of this specification, this field may be set to other values. And without support

+ of those values, the reader shall not read the fields after this within the OpusSpecificBox.

+ + OutputChannelCount:

+ The OutputChannelCount field shall be set to the same value as the *Output Channel Count* field in the

+ identification header defined in Ogg Opus [3].

+ + PreSkip:

+ The PreSkip field indicates the number of the priming samples, that is, the number of samples at 48000 Hz

+ to discard from the decoder output when starting playback. The value of the PreSkip field shall be at least

+ 80 milliseconds' worth of PCM samples even when removing any number of Opus samples which may or may not

+ contain the priming samples. The PreSkip field is not used for discarding the priming samples at the whole

+ playback at all since it is informative only, and that task falls on the Edit List Box.

+ + InputSampleRate:

+ The InputSampleRate field shall be set to the same value as the *Input Sample Rate* field in the

+ identification header defined in Ogg Opus [3].

+ + OutputGain:

+ The OutputGain field shall be set to the same value as the *Output Gain* field in the identification

+ header define in Ogg Opus [3]. Note that the value is stored as 8.8 fixed-point.

+ + ChannelMappingFamily:

+ The ChannelMappingFamily field shall be set to the same value as the *Channel Mapping Family* field in

+ the identification header defined in Ogg Opus [3].

+ + StreamCount:

+ The StreamCount field shall be set to the same value as the *Stream Count* field in the identification

+ header defined in Ogg Opus [3].

+ + CoupledCount:

+ The CoupledCount field shall be set to the same value as the *Coupled Count* field in the identification

+ header defined in Ogg Opus [3].

+ + ChannelMapping:

+ The ChannelMapping field shall be set to the same octet string as *Channel Mapping* field in the identi-

+ fication header defined in Ogg Opus [3].

+ 4.3.3 Sample format<a name="4.3.3"></a>

+ An Opus sample is exactly one Opus packet for each of different Opus bitstreams. Due to support more than

+ two channels, an Opus sample can contain frames from multiple Opus bitstreams but all Opus packets shall

+ share with the total of frame sizes in a single Opus sample. The way of how to pack an Opus packet from

+ each of Opus bitstreams into a single Opus sample follows Appendix B. in RFC 6716 [2].

+ The endianness has nothing to do with any Opus sample since every Opus packet is processed byte-by-byte.

+ In this specification, 'sample' means 'Opus sample' except for 'padded samples', 'priming samples', 'valid

+ sample' and 'sample-accurate', i.e. 'sample' is 'sample' in the term defined in ISO/IEC 14496-12 [1].

+ +-----------------------------------------+-------------------------------------+

+ | Opus packet 0 (self-delimiting framing) | Opus packet 1 (undelimited framing) |

+ +-----------------------------------------+-------------------------------------+

+ |<---------------------------- the size of Opus sample ------------------------>|

+ Figure 1 - Example structure of an Opus sample containing two Opus bitstreams

+ 4.3.4 Duration of Opus sample<a name="4.3.4"></a>

+ The duration of Opus sample is given by multiplying the total of frame sizes for a single Opus bitstream

+ expressed in seconds by the value of the timescale field in the Media Header Box.

+ Let's say an Opus sample consists of two Opus bitstreams, where the frame size of one bitstream is 40 milli-

+ seconds and the frame size of another is 60 milliseconds, and the timescale field in the Media Header Box

+ is set to 48000, then the duration of that Opus sample shall be 120 milliseconds since three 40 millisecond

+ frame and two 60 millisecond frames shall be contained because of the maximum duration of Opus packet, 120

+ milliseconds, and 5760 in the timescale indicated in the Media Header Box.

+ To indicate the valid samples excluding the padded samples at the end of Opus bitstream, the duration of

+ the last Opus sample of an Opus bitstream is given by multiplying the number of the valid samples by the

+ value produced by dividing the value of the timescale field in the Media Header Box by 48000.

+ 4.3.5 Sub-sample<a name="4.3.5"></a>

+ The structure of the last Opus packet in an Opus sample is different from the others in the same Opus sample,

+ and the others are invalid Opus packets as an Opus sample because of self-delimiting framing. To avoid

+ complexities, sub-sample is not defined for Opus sample in this specification.

+ 4.3.6 Random Access<a name="4.3.6"></a>

+ This subclause describes the nature of the random access of Opus sample.

+ 4.3.6.1 Random Access Point<a name="4.3.6.1"></a>

+ All Opus samples can be independently decoded i.e. every Opus sample is a sync sample. Therefore, the

+ Sync Sample Box shall not be present as long as there are no samples other than Opus samples in the same

+ track. And the sample_is_non_sync_sample field for Opus samples shall be set to 0.

+ 4.3.6.2 Pre-roll<a name="4.3.6.2"></a>

+ Opus bitstream requires at least 80 millisecond pre-roll after each random access to get correct output.

+ Pre-roll is indicated by the roll_distance field in AudioRollRecoveryEntry. AudioPreRollEntry shall not

+ be used since every Opus sample is a sync sample in Opus bitstream. Note that roll_distance is expressed

+ in sample units in a term of ISO Base Media File Format, and always takes negative values.

+ For any track containing Opus bitstreams, at least one Sample Group Description Box and at least one

+ Sample to Group Box within the Sample Table Box shall be present and these have the grouping_type field

+ set to 'roll'. If any Opus sample is contained in a track fragment, the Sample to Group Box with the

+ grouping_type field set to 'roll' shall be present for that track fragment.

+ For the requirement of AudioRollRecoveryEntry, the compatible_brands field in the File Type Box shall

+ contain at least one brand which requires support for roll groups.

+<a name="4.4"></a>

+ 4.4 Trimming of Actual Duration

+ Due to the priming samples (or the padding at the beginning) derived from the pre-roll for the startup and the

+ padded samples at the end, we need trim from media to get the actual duration. An edit in the Edit List Box can

+ achieve this demand, and the Edit Box and the Edit List Box shall be present.

+ For sample-accurate trimming, proper timescale should be set to the timescale field in the Movie Header Box

+ and the Media Header Box inside Track Box(es) for Opus bitstream. The timescale field in the Media Header Box is

+ typically set to 48000. It is recommended that the timescale field in the Movie Header Box be set to the same

+ value of the timescale field in the Media Header Box in order to avoid the rounding problem when specifying

+ duration of edit if the timescales in all of the Media Header Boxes are set to the same value.

+ For example, to indicate the actual duration of an Opus bitstream in a track with the timescale fields of both

+ the Movie Header Box and the Media Header Box set to 48000, we would use the following edit:

+ segment_duration = the number of the valid samples

+ media_time = the number of the priming samples

+ media_rate = 1 &lt&lt 16

+ The Edit List Box is applied to whole movie including all movie fragments. Therefore, it is impossible to tell

+ the actual duration in the case producing movie fragments on the fly such as live-streaming. In such cases,

+ the duration of the last Opus sample may be helpful by setting zero to the segment_duration field since the

+ value 0 represents implicit duration equal to the sum of the duration of all samples.

+<a name="4.5"></a>

+ 4.5 Channel Layout (informative)

+ By the application of alternate_group in the Track Header Box, whole audio channels in all active tracks from

+ non-alternate group and/or different alternate group from each other are composited into the presentation. If

+ an Opus sample consists of multiple Opus bitstreams, it can be splitted into individual Opus bitstreams and

+ reconstructed into new Opus samples as long as every Opus bitstream has the same total duration in each Opus

+ sample. This nature can be utilized to encapsulate a single Opus bitstream in each track without breaking the

+ original channel layout.

+ As an example, let's say there is a following track:

+ OutputChannelCount = 6;

+ StreamCount = 4;

+ CoupledCount = 2;

+ ChannelMapping = {0, 4, 1, 2, 3, 5}; // front left, front center, front right, rear left, rear right, LFE

+ Here, to couple front left to front right channels into the first stream, and couple rear left to rear right

+ channels into the second stream, reordering is needed since coupled streams must precede any non-coupled stream.

+ You extract the four Opus bitstreams from this track and you encapsulate two of the four into a track and the

+ others into another track. The former track is as follows.

+ OutputChannelCount = 6;

+ StreamCount = 2;

+ CoupledCount = 2;

+ ChannelMapping = {0, 255, 1, 2, 3, 255}; // front left, front center, front right, rear left, rear right, LFE

+ And the latter track is as follows.

+ OutputChannelCount = 6;

+ StreamCount = 2;

+ CoupledCount = 0;

+ ChannelMapping = {255, 0, 255, 255, 255, 1}; // front left, front center, front right, rear left, rear right, LFE

+ In addition, the value of the alternate_group field in the both tracks is set to 0. As the result, the player

+ may play as if channels with 255 are not present, and play the presentation constructed from the both tracks

+ in the same channel layout as the one of the original track. Keep in mind that the way of the composition, i.e.

+ the mixing for playback, is not defined here, and maybe different results could occur except for the channel

+ layout of the original, depending on an implementation or the definition of a derived file format.

+ Note that some derived file formats may specify the restriction to ignore alternate grouping. In the context of

+ such file formats, this application is not available. This unavailability does not mean incompatibilities among

+ file formats unless the restriction to the value of the alternate_group field is specified and brings about

+ any conflict among their definitions.

+<a name="4.6"></a>

+ 4.6 Basic Structure (informative)

+ 4.6.1 Initial Movie<a name="4.6.1"></a>

+ This subclause shows a basic structure of the Movie Box as follows:

+ +----+----+----+----+----+----+----+----+------------------------------+