d208f65b4866b5e6f0c4a0d0dc523388bcaeef89
[opus.git] / doc / opus_in_isobmff.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2 <html>
3     <head>
4         <link rel="stylesheet" type="text/css" href="opus_in_isobmff.css"/>
5         <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6         <title>Encapsulation of Opus in ISO Base Media File Format</title>
7     </head>
8     <body bgcolor="0x333333" text="#60B0C0">
9         <b><u>Encapsulation of Opus in ISO Base Media File Format</u></b><br>
10         <font size="2">last updated: October 1, 2014</font><br>
11         <br>
12         <div class="normal_link pre frame_box">
13
14                                 Encapsulation of Opus in ISO Base Media File Format
15                                         Version 0.5.3 (incomplete)
16
17
18 Table of Contents
19 <a href="#1">1</a> Scope
20 <a href="#2">2</a> Normative References
21 <a href="#3">3</a> Terms and Definitions
22 <a href="#4">4</a> Design Rules of Encapsulation
23     <a href="#4.1">4.1</a> File Type Indentification
24     <a href="#4.2">4.2</a> Basic Structure
25         <a href="#4.2.1">4.2.1</a> Initial Movie
26         <a href="#4.2.2">4.2.2</a> Movie Fragments
27     <a href="#4.3">4.3</a> Byte Order
28     <a href="#4.4">4.4</a> Definition of Opus sample
29         <a href="#4.4.1">4.4.1</a> Opus sample
30         <a href="#4.4.2">4.4.2</a> Duration of Opus sample
31         <a href="#4.4.3">4.4.3</a> Sub-sample
32     <a href="#4.5">4.5</a> Random Access
33         <a href="#4.5.1">4.5.1</a> Random Access Point
34         <a href="#4.5.2">4.5.2</a> Pre-roll
35     <a href="#4.6">4.6</a> Trimming of Actual Duration
36     <a href="#4.7">4.7</a> Channel Layout
37     <a href="#4.8">4.8</a> Additional Requirements, Restrictions, Recommendations and Definitions for Boxes
38         <a href="#4.8.1">4.8.1</a> File Type Box
39         <a href="#4.8.2">4.8.2</a> Segment Type Box
40         <a href="#4.8.3">4.8.3</a> Movie Header Box
41         <a href="#4.8.4">4.8.4</a> Track Header Box
42         <a href="#4.8.5">4.8.5</a> Edit Box
43         <a href="#4.8.6">4.8.6</a> Edit List Box
44         <a href="#4.8.7">4.8.7</a> Media Header Box
45         <a href="#4.8.8">4.8.8</a> Handler Reference Box
46         <a href="#4.8.9">4.8.9</a> Sound Media Header Box
47         <a href="#4.8.10">4.8.10</a> Sample Table Box
48         <a href="#4.8.11">4.8.11</a> OpusSampleEntry
49         <a href="#4.8.12">4.8.12</a> Opus Specific Box
50         <a href="#4.8.13">4.8.13</a> Sample Group Description Box
51         <a href="#4.8.14">4.8.14</a> Sample to Group Box
52         <a href="#4.8.15">4.8.15</a> Track Extends Box
53         <a href="#4.8.16">4.8.16</a> Track Fragment Box
54         <a href="#4.8.17">4.8.17</a> Track Fragment Header Box
55         <a href="#4.8.18">4.8.18</a> Track Fragment Run Box
56     <a href="#4.9">4.9</a> Example of Encapsulation
57 <a href="#5">5</a> Author's Address
58
59 <a name="1"></a>
60 1 Scope
61     This specification specifies the fundamental way of the encapsulation of Opus coded bitstreams in ISO Base Media
62     file formats and its derivatives.
63
64 <a name="2"></a>
65 2 Normative References
66     [1] ISO/IEC 14496-12:2012 Corrected version
67         Information technology — Coding of audio-visual objects — Part 12: ISO base media file format
68
69     [2] ISO/IEC 14496-12:2012/Amd.1:2013
70         Information technology — Coding of audio-visual objects — Part 12: ISO base media file format
71         AMENDMENT 1: Various enhancements including support for large metadata
72
73     [3] RFC 6716
74         Definition of the Opus Audio Codec
75
76     [4] draft-ietf-codec-oggopus-04
77         Ogg Encapsulation for the Opus Audio Codec
78
79 <a name="3"></a>
80 3 Terms and Definitions
81     3.1 active track
82         enabled track from the non-alternate group or selected track from alternate group
83         TODO: For alternate group, how about handling of disabled tracks?
84               Some implementations treat disabled tracks in alternate group as a non-default track.
85               Under the such implementations, the selected track behaves as an enabled track.
86               Should we define the implementation in this specification?
87               Or leave it as implementation-defined?
88
89     3.2 actual duration
90         duration constructed from valid samples
91
92     3.3 edit
93         entry in the Edit List Box
94
95     3.4 padded samples
96         PCM samples after decoding Opus sample(s) which are not valid samples
97         An Opus bitstream always contains them partially at the beginning and may contain them in part at the end, as
98         long as not physically removed yet at the beginning and/or the end.
99
100     3.5 priming samples
101         padded samples at the beginning of the Opus bitstream
102
103     3.6 sample-accurate
104         for any PCM sample, a timestamp exactly matching its sampling timestamp is present in the media timeline.
105
106     3.7 valid samples
107         PCM samples after decoding Opus sample(s) corresponding to input PCM samples
108
109 <a name="4"></a>
110 4 Design Rules of Encapsulation
111     4.1 File Type Indentification<a name="4.1"></a>
112         This specification does not define any brand to declare files are conformant to this specification.
113         TODO: Should we define such brands, e.g. 'Opus'? If we define the brand(s), we can utilize files conformant to
114               this specification for the storage of Opus coded bitstreams without other derived file formats.
115               It is not preferable that encapsulation of Opus bitstreams with only the brands of the ISO Base Media File
116               Format, though files conformant to this specification are compatible with certain versions of the ISO
117               Base Media File Format. See ISO/IEC 14496-12 [3] E.1 Introduction.
118               If you desire that this file format is an alternative file format to the Ogg Opus, I recommend you define.
119 <a name="4.2"></a>
120     4.2 Basic Structure
121         4.2.1 Initial Movie<a name="4.2.1"></a>
122             This subclause specifies a basic structure of the Movie Box as follows:
123
124             +----+----+----+----+----+----+----+----+------------------------------+
125             |moov|    |    |    |    |    |    |    | Movie Box                    |
126             +----+----+----+----+----+----+----+----+------------------------------+
127             |    |mvhd|    |    |    |    |    |    | Movie Header Box             |
128             +----+----+----+----+----+----+----+----+------------------------------+
129             |    |trak|    |    |    |    |    |    | Track Box                    |
130             +----+----+----+----+----+----+----+----+------------------------------+
131             |    |    |tkhd|    |    |    |    |    | Track Header Box             |
132             +----+----+----+----+----+----+----+----+------------------------------+
133             |    |    |edts|    |    |    |    |    | Edit Box                     |
134             +----+----+----+----+----+----+----+----+------------------------------+
135             |    |    |    |elst|    |    |    |    | Edit List Box                |
136             +----+----+----+----+----+----+----+----+------------------------------+
137             |    |    |mdia|    |    |    |    |    | Media Box                    |
138             +----+----+----+----+----+----+----+----+------------------------------+
139             |    |    |    |mdhd|    |    |    |    | Media Header Box             |
140             +----+----+----+----+----+----+----+----+------------------------------+
141             |    |    |    |hdlr|    |    |    |    | Handler Reference Box        |
142             +----+----+----+----+----+----+----+----+------------------------------+
143             |    |    |    |minf|    |    |    |    | Media Information Box        |
144             +----+----+----+----+----+----+----+----+------------------------------+
145             |    |    |    |    |smhd|    |    |    | Sound Media Information Box  |
146             +----+----+----+----+----+----+----+----+------------------------------+
147             |    |    |    |    |dinf|    |    |    | Data Information Box         |
148             +----+----+----+----+----+----+----+----+------------------------------+
149             |    |    |    |    |    |dref|    |    | Data Reference Box           |
150             +----+----+----+----+----+----+----+----+------------------------------+
151             |    |    |    |    |    |    |url |    | DataEntryUrlBox              |
152             +----+----+----+----+----+----+ or +----+------------------------------+
153             |    |    |    |    |    |    |urn |    | DataEntryUrnBox              |
154             +----+----+----+----+----+----+----+----+------------------------------+
155             |    |    |    |    |stbl|    |    |    | Sample Table                 |
156             +----+----+----+----+----+----+----+----+------------------------------+
157             |    |    |    |    |    |stsd|    |    | Sample Description Box       |
158             +----+----+----+----+----+----+----+----+------------------------------+
159             |    |    |    |    |    |    |Opus|    | OpusSampleEntry              |
160             +----+----+----+----+----+----+----+----+------------------------------+
161             |    |    |    |    |    |    |    |dOps| Opus Specific Box            |
162             +----+----+----+----+----+----+----+----+------------------------------+
163             |    |    |    |    |    |stts|    |    | Decoding Time to Sample Box  |
164             +----+----+----+----+----+----+----+----+------------------------------+
165             |    |    |    |    |    |stsc|    |    | Sample To Chunk Box          |
166             +----+----+----+----+----+----+----+----+------------------------------+
167             |    |    |    |    |    |stsz|    |    | Sample Size Box              |
168             +----+----+----+----+----+ or +----+----+------------------------------+
169             |    |    |    |    |    |stz2|    |    | Compact Sample Size Box      |
170             +----+----+----+----+----+----+----+----+------------------------------+
171             |    |    |    |    |    |stco|    |    | Chunk Offset Box             |
172             +----+----+----+----+----+ or +----+----+------------------------------+
173             |    |    |    |    |    |co64|    |    | Chunk Large Offset Box       |
174             +----+----+----+----+----+----+----+----+------------------------------+
175             |    |    |    |    |    |sgpd|    |    | Sample Group Description Box |
176             +----+----+----+----+----+----+----+----+------------------------------+
177             |    |    |    |    |    |sbgp|    |    | Sample to Group Box          |
178             +----+----+----+----+----+----+----+----+------------------------------+
179             |    |mvex|*   |    |    |    |    |    | Movie Extends Box            |
180             +----+----+----+----+----+----+----+----+------------------------------+
181             |    |    |trex|*   |    |    |    |    | Track Extends Box            |
182             +----+----+----+----+----+----+----+----+------------------------------+
183
184                     Figure 1 - Basic structure of Movie Box
185
186             It is strongly recommended that the order of boxes should follow the above structure.
187             Boxes marked with an asterisk (*) may be present.
188             For some boxes listed above, the additional requirements, restrictions, recommendations and definitions
189             are specified in 4.8 Additional Requirements, Restrictions, Recommendations and Definitions for Boxes in
190             this specification. For the others, the definition is as is defined in ISO/IEC 14496-12 [1].
191
192         4.2.2 Movie Fragments<a name="4.2.2"></a>
193             This subclause specifies a basic structure of the Movie Fragment Box as follows:
194
195             +----+----+----+----+----+----+----+----+------------------------------+
196             |moof|    |    |    |    |    |    |    | Movie Fragment Box           |
197             +----+----+----+----+----+----+----+----+------------------------------+
198             |    |mfhd|    |    |    |    |    |    | Movie Fragment Header Box    |
199             +----+----+----+----+----+----+----+----+------------------------------+
200             |    |traf|    |    |    |    |    |    | Track Fragment Box           |
201             +----+----+----+----+----+----+----+----+------------------------------+
202             |    |    |tfhd|    |    |    |    |    | Track Fragment Header Box    |
203             +----+----+----+----+----+----+----+----+------------------------------+
204             |    |    |trun|    |    |    |    |    | Track Fragment Run Box       |
205             +----+----+----+----+----+----+----+----+------------------------------+
206             |    |    |sgpd|*   |    |    |    |    | Sample Group Description Box |
207             +----+----+----+----+----+----+----+----+------------------------------+
208             |    |    |sbgp|*   |    |    |    |    | Sample to Group Box          |
209             +----+----+----+----+----+----+----+----+------------------------------+
210
211                     Figure 2 - Basic structure of Movie Fragment Box
212
213             It is strongly recommended that the Movie Fragment Header Box and the Track Fragment Header Box be
214             placed first in their container.
215             Boxes marked with an asterisk (*) may be present.
216             For some boxes listed above, the additional requirements, restrictions, recommendations and definitions
217             are specified in 4.8 Additional Requirements, Restrictions, Recommendations and Definitions for Boxes in
218             this specification. For the others, the definition is as is defined in ISO/IEC 14496-12 [1].
219 <a name="4.3"></a>
220     4.3 Byte Order
221         The fields in the boxes are stored as big-endian format.
222         All Opus samples are processed byte-by-byte. Therefore, the endianness has nothing to do with any Opus sample.
223 <a name="4.4"></a>
224     4.4 Definition of Opus sample
225         4.4.1 Opus sample<a name="4.4.1"></a>
226             An Opus sample is exactly one Opus packet for each of different Opus bitstreams. Due to support more than
227             two channels, an Opus sample can contain frames from multiple Opus bitstreams but all Opus packets shall
228             share with the total of frame sizes in a single Opus sample. The way of how to pack an Opus packet from
229             each of Opus bitstreams into a single Opus sample follows Appendix B. in RFC 6716 [3].
230             In this specification, 'sample' means 'Opus sample' except for 'padded samples', 'priming samples', 'valid
231             sample' and 'sample-accurate', i.e. 'sample' is 'sample' in the term defined in ISO/IEC 14496-12 [1].
232
233                 +-----------------------------------------+-------------------------------------+
234                 | Opus packet 0 (self-delimiting framing) | Opus packet 1 (undelimited framing) |
235                 +-----------------------------------------+-------------------------------------+
236                 |<---------------------------- the size of Opus sample ------------------------>|
237
238                     Figure 3 - Example structure of an Opus sample containing two Opus bitstreams
239
240         4.4.2 Duration of Opus sample<a name="4.4.2"></a>
241             The duration of Opus sample is given by multiplying the total of frame sizes for a single Opus bitstream
242             expressed in seconds by the value of the timescale field in the Media Header Box.
243             Let's say an Opus sample consists of two Opus bitstreams, where the frame size of one bitstream is 40 milli-
244             seconds and the frame size of another is 60 milliseconds, and the timescale field in the Media Header Box
245             is set to 48000, then the duration of that Opus sample shall be 120 milliseconds since three 40 millisecond
246             frame and two 60 millisecond frames shall be contained because of the maximum duration of Opus packet, 120
247             milliseconds, and 5760 in the timescale indicated in the Media Header Box.
248
249             To indicate the valid samples excluding the padded samples at the end of Opus bitstream, the duration of
250             the last Opus sample of an Opus bitstream is given by multiplying the number of the valid samples by the
251             value produced by dividing the value of the timescale field in the Media Header Box by 48000.
252
253         4.4.3 Sub-sample<a name="4.4.3"></a>
254             The structure of the last Opus packet in an Opus sample is different from the others in the same Opus sample,
255             and the others are invalid Opus packets as an Opus sample because of self-delimiting framing. To avoid
256             complexities, sub-sample is not defined for Opus sample in this specification.
257 <a name="4.5"></a>
258     4.5 Random Access
259         4.5.1 Random Access Point<a name="4.5.1"></a>
260             All Opus samples can be independently decoded i.e. every Opus sample is a sync sample. Therefore, the Sync
261             Sample Box shall not be present as long as there are no samples other than Opus samples in the same track.
262
263         4.5.2 Pre-roll<a name="4.5.2"></a>
264             Opus requires at least 80 millisecond pre-roll after each random access.
265             Pre-roll is indicated by the roll_distance field in AudioRollRecoveryEntry. AudioPreRollEntry shall not be
266             used since every Opus sample is a sync sample in Opus bitstream. Note that roll_distance is expressed in
267             sample units in a term of ISO Base Media File Format, and always takes negative values.
268
269             For the requirement of AudioRollRecoveryEntry, the compatible_brands field in the File Type Box and/or
270             the Segment Type Box shall contain at least one brand which requires support for roll groups. See also
271             4.8.1 File Type Box and 4.8.2 Segment Type Box in this specification.
272 <a name="4.6"></a>
273     4.6 Trimming of Actual Duration
274         Due to the priming samples (or the padding at the beginning) derived from the pre-roll for the startup and the
275         padded samples at the end, we need trim from media to get the actual duration. An edit in the Edit List Box can
276         achieve this demand.
277         For sample-accurate trimming, proper timescale should be set to the timescale field in the Movie Header Box
278         and the Media Header Box inside Track Box(es) for Opus bitstream.
279
280         The Edit List Box is applied to whole movie including all movie fragments. Therefore, it is impossible to tell
281         the actual duration in the case producing movie fragments on the fly such as live-streaming. In such cases,
282         the duration of the last Opus sample may be helpful.
283         TODO: Should we define a new box which indicates the last Opus samples?
284               Since this specification allows multiple sample descriptions, i.e. allows concatenation of multiple Opus
285               bitstreams in a track, each Opus bitstream may contain some padded samples.
286               Without such a box, we cannot know in container level whether an Opus sample is the last Opus sample in
287               an Opus bitstream or not. Is this preferable?
288
289         See also 4.8.6 Edit List Box in this specification.
290 <a name="4.7"></a>
291     4.7 Channel Layout
292         By the application of alternate_group in the Track Header Box, whole audio channels in all active tracks from
293         non-alternate group and/or different alternate group from each other are composited into the presentation. If
294         an Opus sample consists of multiple Opus bitstreams, it can be splitted into individual Opus bitstreams and
295         reconstructed into new Opus samples as long as every Opus bitstream has the same total duration in each Opus
296         sample. This nature can be utilized to encapsulate a single Opus bitstream in each track without breaking the
297         original channel layout.
298
299         As an example, let's say there is a following track:
300             OutputChannelCount = 6;
301             StreamCount        = 4;
302             CoupledCount       = 2;
303             ChannelMapping     = {0, 1, 2, 3, 4, 5}; // front left, front center, front right, rear left, rear right, LFE
304         You extract the four Opus bitstreams from this track and you encapsulate two of the four into a track and the
305         others into another track. The former track is as follows.
306             OutputChannelCount = 6;
307             StreamCount        = 2;
308             CoupledCount       = 2;
309             ChannelMapping     = {0, 255, 1, 2, 3, 255}; // front left, front center, front right, rear left, rear right, LFE
310         And the latter track is as follows.
311             OutputChannelCount = 6;
312             StreamCount        = 2;
313             CoupledCount       = 0;
314             ChannelMapping     = {255, 0, 255, 255, 255, 1}; // front left, front center, front right, rear left, rear right, LFE
315         In addition, the value of the alternate_group field in the both tracks is set to 0. As the result, the player
316         may play as if channels with 255 are not present, and play the presentation constructed from the both tracks
317         in the same channel layout as the one of the original track. Keep in mind that the way of the composition, i.e.
318         the mixing for playback, is not defined here, and maybe different results could occur except for the channel
319         layout of the original, depending on an implementation or the definition of a derived file format.
320
321         Note that some derived file formats may specify the restriction to ignore alternate grouping. In the context of
322         such file formats, this application is not available. This unavailability does not mean incompatibilities among
323         file formats unless the restriction to the value of the alternate_group field is specified and brings about
324         any conflict among their definitions.
325
326         TODO: The future amendments of ISO/IEC 14496-12 [1] will add further supports of channel layouts and it may be
327               able to exclude certain channels from the already mapped channels to remove pure silent channels. The
328               channel mapping defined in the Opus Specific Box should be designed as processed before the extensions,
329               and the extensions should be placed after the Opus Specific Box.
330 <a name="4.8"></a>
331     4.8 Additional Requirements, Restrictions, Recommendations and Definitions for Boxes
332         4.8.1 File Type Box<a name="4.8.1"></a>
333             For any track containing Opus bitstreams, the following requirements are applied.
334             + compatible_brands:
335                 The compatible_brands fields shall contain at least one brand which requires support for the structural
336                 boxes listed at 4.2 Basic Structure, and the additional requirements, restrictions, recommendations and
337                 definitions specified in 4.8 Additional Requirements, Restrictions, Recommendations and Definitions for
338                 Boxes in this specification.
339                 As an example, the minimal support of the encapsulation of Opus bitstreams in ISO Base Media file format
340                 requires the 'iso2' brand since support of roll groups is required.
341
342         4.8.2 Segment Type Box<a name="4.8.2"></a>
343             The same requirements are applied as specified at 4.8.1 File Type Box in this specification.
344
345         4.8.3 Movie Header Box<a name="4.8.3"></a>
346             If any track containing Opus bitstreams, the following recommendations are applied.
347             + timescale:
348                 The timescale field should be set to the same value of the timescale field in the Media Header Box
349                 inside Track Box(es) for Opus bitstream if no tracks for bitstreams other than Opus bitstream is present.
350
351         4.8.4 Track Header Box<a name="4.8.4"></a>
352             For any track containing Opus bitstreams, the following requirements are applied.
353             + layer:
354                 The layer field shall be set to 0.
355             + matrix:
356                 The matrix field shall be set to { 0x00010000,0,0,0,0x00010000,0,0,0,0x40000000 }.
357             + width:
358                 The width field shall be set to 0.
359             + height:
360                 The height field shall be set to 0.
361
362         4.8.5 Edit Box<a name="4.8.5"></a>
363             For any track containing Opus bitstreams, exactly one Edit Box shall be present.
364
365         4.8.6 Edit List Box<a name="4.8.6"></a>
366             For any track containing Opus bitstreams, exactly one Edit List Box shall be present. In addition, for
367             non-empty edits, the following recommendations are applied.
368             + segment_duration:
369                 The segment_duration field can be used to indicate the actual duration of Opus bitstream.
370                 When the value of the timescale field in the Movie Header Box is equal to 48000, the segment_duration
371                 field shall be set to the number of the valid samples to indicate the actual duration.
372                 When enabling movie fragments, the segment_duration field may be set to 0. The value 0 represents
373                 implicit duration equal to the sum of the duration of all samples. This would be helpful for excluding
374                 the padded samples from the presentation timeline when producing movie fragments on the fly.
375             + media_time:
376                 The media_time field can be used to remove the priming samples of Opus bitstreams.
377                 When the value of the timescale field in the Media Header Box is equal to 48000, the media_time field
378                 shall be set to the number of the priming samples to remove the priming samples.
379             + media_rate:
380                 If the segment_duration field is used to indicate the actual duration, the media_rate field shall be
381                 set to 1.
382
383         4.8.7 Media Header Box<a name="4.8.7"></a>
384             For any track containing Opus bitstreams, the following recommendation is applied.
385             + timescale:
386                 The timescale field should be set to 48000 to access sample-accurately.
387
388         4.8.8 Handler Reference Box<a name="4.8.8"></a>
389             For any track containing Opus bitstreams, the following requirement is applied.
390             + handler_type:
391                 The handler_type field shall be set to 'soun'.
392
393         4.8.9 Sound Media Header Box<a name="4.8.9"></a>
394             For any track containing Opus bitstreams, the Sound Media Header Box shall be present.
395
396         4.8.10 Sample Table Box<a name="4.8.10"></a>
397             For any track containing Opus bitstreams, at least one Sample Group Description Boxes and at least one
398             Sample to Group Boxes shall be present, and the Sync Sample Box shall not be present as long as there are
399             no samples other than Opus samples in the same track.
400
401         4.8.11 OpusSampleEntry<a name="4.8.11"></a>
402             For any track containing Opus bitstreams, at least one OpusSampleEntry shall be present.
403
404             The syntax and semantics of the OpusSampleEntry is shown as follows.
405
406             class OpusSampleEntry() extends AudioSampleEntry ('Opus'){
407                 OpusSpecificBox();
408             }
409
410             + channelcount:
411                 The channelcount field shall be set to the sum of the total number of Opus bitstreams and the number
412                 of Opus bitstreams producing two channels. This value is indentical with (M+N), where M is the value of
413                 the *Coupled Stream Count* field and N is the value of the *Stream Count* field in the *Channel Mapping
414                 Table* in the identification header defined in Ogg Opus [4].
415             + samplesize:
416                 The samplesize field shall be set to 16.
417             + samplerate:
418                 The samplerate field shall be set to 48000&lt&lt16.
419
420         4.8.12 Opus Specific Box<a name="4.8.12"></a>
421             Exactly one Opus Specific Box shall be present in each OpusSampleEntry.
422             The Opus Specific Box contains the version field and this specification defines version 0 of this box.
423             If incompatible changes occured in the fields after the version field within the OpusSpecificBox in the
424             future versions of this specification, another version will be defined.
425
426             The syntax and semantics of the Opus Specific Box is shown as follows.
427
428             class ChannelMappingTable (unsigned int(8) OutputChannelCount){
429                 unsigned int(8) StreamCount;
430                 unsigned int(8) CoupledCount;
431                 unsigned int(8 * OutputChannelCount) ChannelMapping;
432             }
433
434             aligned(8) class OpusSpecificBox extends FullBox('dOps', version, dflags){
435                 unsigned int(8) OutputChannelCount;
436                 if (dflags & 0x000001) {
437                     unsigned int(16) PreSkip;
438                 }
439                 if (dflags & 0x000002) {
440                     unsigned int(32) InputSampleRate;
441                 }
442                 if (dflags & 0x000004) {
443                     signed int(16) OutputGain;
444                 }
445                 unsigned int(8) ChannelMappingFamily;
446                 if (ChannelMappingFamily != 0) {
447                     ChannelMappingTable(OutputChannelCount);
448                 }
449             }
450
451             + version:
452                 The version field shall be set to 0.
453                 In the future versions of this specification, this field may be set to other values. And without support
454                 of those values, the reader shall not read the fields after this within the OpusSpecificBox.
455             + flags:
456                 The following flags are defined in the dflags:
457                     0x000001 pre-skip-present:
458                         This flag indicates the presence of the PreSkip field.
459                     0x000002 input-sample-rate-present:
460                         This flag indicates the presence of the InputSampleRate field.
461                     0x000004 output-gain-present:
462                         This flag indicates the presence of the OutputGain field.
463             + OutputChannelCount:
464                 The OutputChannelCount field shall be set to the same value as the *Output Channel Count* field in the
465                 identification header defined in Ogg Opus [4].
466             + PreSkip:
467                 The PreSkip field shall be set to the same value as the *Pre-skip* field in the identification header
468                 defined in Ogg Opus [4]. Note that the value is stored as big-endian format.
469                 The PreSkip field can be absent after removing Opus samples containing the number of PCM samples more
470                 than of the priming samples.
471                 The PreSkip field is not used for removing the priming samples at the whole playback at all since it is
472                 informative only, and that task falls on the Edit List Box.
473             + InputSampleRate:
474                 The InputSampleRate field shall be set to the same value as the *Input Sample Rate* field in the
475                 identification header defined in Ogg Opus [4]. Note that the value is stored as big-endian format.
476                 If the InputSampleRate field is absent, process as if it is set to 0, which indicates "unspecified".
477             + OutputGain:
478                 The OutputGain field shall be set to the same value as the *Output Gain* field in the identification
479                 header define in Ogg Opus [4]. Note that the value is stored as 8.8 fixed-point and big-endian format.
480                 If the OutputGain field is absent, process as if it is set to 0.
481             + ChannelMappingFamily:
482                 The ChannelMappingFamily field shall be set to the same value as the *Channel Mapping Family* field in
483                 the identification header defined in Ogg Opus [4].
484             + StreamCount:
485                 The StreamCount field shall be set to the same value as the *Stream Count* field in the identification
486                 header defined in Ogg Opus [4].
487             + CoupledCount:
488                 The CoupledCount field shall be set to the same value as the *Coupled Count* field in the identification
489                 header defined in Ogg Opus [4].
490             + ChannelMapping:
491                 The ChannelMapping field shall be set to the same octet string as *Channel Mapping* field in the identi-
492                 fication header defined in Ogg Opus [4].
493
494         4.8.13 Sample Group Description Box<a name="4.8.13"></a>
495             For any track containing Opus bitstreams, at least one Sample Group Description Box shall be present and have
496             the grouping_type field set to 'roll'. In addition, the following requirements and restriction are applied.
497             + version:
498                 The version field shall be set to 1 if the grouping_type field set to 'roll'.
499             + default_length
500                 The default_length field shall be set to 2 if the grouping_type field set to 'roll'.
501             + roll_distance:
502                 The roll_distance field in any AudioRollRecoveryEntry shall not be set to zero and positive values for
503                 any Opus sample.
504
505             See also 4.5.2 Pre-roll.
506
507         4.8.14 Sample to Group Box<a name="4.8.14"></a>
508             For any track containing Opus bitstreams, at least one Sample to Group Box shall be present and have the
509             grouping_type field set to 'roll'. In addition, the following requirement is applied.
510             + group_description_index:
511                 The group_description_index fields shall not be set to 0 if the grouping_type field set to 'roll'.
512
513         4.8.15 Track Extends Box<a name="4.8.15"></a>
514             For any track containing Opus bitstreams, the following requirement is applied.
515             + default_sample_flags:
516                 The sample_is_non_sync_sample field shall be set to 0.
517
518         4.8.16 Track Fragment Box<a name="4.8.16"></a>
519             For any track containing Opus bitstreams, if any sample is contained in track fragment, the Sample to
520             Group Box with the grouping_type field set to 'roll' shall be present for that track fragment.
521
522         4.8.17 Track Fragment Header Box<a name="4.8.17"></a>
523             For any track containing Opus bitstreams, the following requirement is applied.
524             + default_sample_flags:
525                 The sample_is_non_sync_sample field shall be set to 0.
526
527         4.8.18 Track Fragment Run Box<a name="4.8.18"></a>
528             For any track containing Opus bitstreams, the following requirements are applied.
529             + first_sample_flags:
530                 The sample_is_non_sync_sample field shall be set to 0.
531             + sample_flags:
532                 The sample_is_non_sync_sample field shall be set to 0.
533 <a name="4.9"></a>
534     4.9 Example of Encapsulation
535         [File]
536             size = 10349
537             [ftyp: File Type Box]
538                 position = 0
539                 size = 24
540                 major_brand = mp42 : MP4 version 2
541                 minor_version = 0
542                 compatible_brands
543                     brand[0] = mp42 : MP4 version 2
544                     brand[1] = iso2 : ISO Base Media file format version 2
545             [free: Free Space Box]
546                 position = 24
547                 size = 8
548             [mdat: Media Data Box]
549                 position = 32
550                 size = 9551
551             [moov: Movie Box]
552                 position = 9583
553                 size = 766
554                 [mvhd: Movie Header Box]
555                     position = 9591
556                     size = 108
557                     version = 0
558                     flags = 0x000000
559                     creation_time = UTC 2014/09/23, 15:23:21
560                     modification_time = UTC 2014/09/23, 15:23:21
561                     timescale = 48000
562                     duration = 33600 (00:00:00.700)
563                     rate = 1.000000
564                     volume = 1.000000
565                     reserved = 0x0000
566                     reserved = 0x00000000
567                     reserved = 0x00000000
568                     transformation matrix
569                         | a, b, u |   | 1.000000, 0.000000, 0.000000 |
570                         | c, d, v | = | 0.000000, 1.000000, 0.000000 |
571                         | x, y, w |   | 0.000000, 0.000000, 1.000000 |
572                     pre_defined = 0x00000000
573                     pre_defined = 0x00000000
574                     pre_defined = 0x00000000
575                     pre_defined = 0x00000000
576                     pre_defined = 0x00000000
577                     pre_defined = 0x00000000
578                     next_track_ID = 2
579                 [iods: Object Descriptor Box]
580                     position = 9699
581                     size = 33
582                     version = 0
583                     flags = 0x000000
584                     [tag = 0x10: MP4_IOD]
585                         expandableClassSize = 16
586                         ObjectDescriptorID = 1
587                         URL_Flag = 0
588                         includeInlineProfileLevelFlag = 0
589                         reserved = 0xf
590                         ODProfileLevelIndication = 0xff
591                         sceneProfileLevelIndication = 0xff
592                         audioProfileLevelIndication = 0xfe
593                         visualProfileLevelIndication = 0xff
594                         graphicsProfileLevelIndication = 0xff
595                         [tag = 0x0e: ES_ID_Inc]
596                             expandableClassSize = 4
597                             Track_ID = 1
598                 [trak: Track Box]
599                     position = 9732
600                     size = 617
601                     [tkhd: Track Header Box]
602                         position = 9740
603                         size = 92
604                         version = 0
605                         flags = 0x000007
606                             Track enabled
607                             Track in movie
608                             Track in preview
609                         creation_time = UTC 2014/09/23, 15:23:21
610                         modification_time = UTC 2014/09/23, 15:23:21
611                         track_ID = 1
612                         reserved = 0x00000000
613                         duration = 33600 (00:00:00.700)
614                         reserved = 0x00000000
615                         reserved = 0x00000000
616                         layer = 0
617                         alternate_group = 0
618                         volume = 1.000000
619                         reserved = 0x0000
620                         transformation matrix
621                             | a, b, u |   | 1.000000, 0.000000, 0.000000 |
622                             | c, d, v | = | 0.000000, 1.000000, 0.000000 |
623                             | x, y, w |   | 0.000000, 0.000000, 1.000000 |
624                         width = 0.000000
625                         height = 0.000000
626                     [edts: Edit Box]
627                         position = 9832
628                         size = 36
629                         [elst: Edit List Box]
630                             position = 9840
631                             size = 28
632                             version = 0
633                             flags = 0x000000
634                             entry_count = 1
635                             entry[0]
636                                 segment_duration = 33600
637                                 media_time = 3840
638                                 media_rate = 1.000000
639                     [mdia: Media Box]
640                         position = 9868
641                         size = 481
642                         [mdhd: Media Header Box]
643                             position = 9876
644                             size = 32
645                             version = 0
646                             flags = 0x000000
647                             creation_time = UTC 2014/09/23, 15:23:21
648                             modification_time = UTC 2014/09/23, 15:23:21
649                             timescale = 48000
650                             duration = 38400 (00:00:00.800)
651                             language = und
652                             pre_defined = 0x0000
653                         [hdlr: Handler Reference Box]
654                             position = 9908
655                             size = 51
656                             version = 0
657                             flags = 0x000000
658                             pre_defined = 0x00000000
659                             handler_type = soun
660                             reserved = 0x00000000
661                             reserved = 0x00000000
662                             reserved = 0x00000000
663                             name = Xiph Audio Handler
664                         [minf: Media Information Box]
665                             position = 9959
666                             size = 390
667                             [smhd: Sound Media Header Box]
668                                 position = 9967
669                                 size = 16
670                                 version = 0
671                                 flags = 0x000000
672                                 balance = 0.000000
673                                 reserved = 0x0000
674                             [dinf: Data Information Box]
675                                 position = 9983
676                                 size = 36
677                                 [dref: Data Reference Box]
678                                     position = 9991
679                                     size = 28
680                                     version = 0
681                                     flags = 0x000000
682                                     entry_count = 1
683                                     [url : Data Entry Url Box]
684                                         position = 10007
685                                         size = 12
686                                         version = 0
687                                         flags = 0x000001
688                                         location = in the same file
689                             [stbl: Sample Table Box]
690                                 position = 10019
691                                 size = 330
692                                 [stsd: Sample Description Box]
693                                     position = 10027
694                                     size = 72
695                                     version = 0
696                                     flags = 0x000000
697                                     entry_count = 1
698                                     [Opus: Audio Description]
699                                         position = 10043
700                                         size = 56
701                                         reserved = 0x000000000000
702                                         data_reference_index = 1
703                                         reserved = 0x0000
704                                         reserved = 0x0000
705                                         reserved = 0x00000000
706                                         channelcount = 2
707                                         samplesize = 16
708                                         pre_defined = 0
709                                         reserved = 0
710                                         samplerate = 48000.000000
711                                         [dOps: Opus Specific Box]
712                                             position = 10071
713                                             size = 20
714                                             version = 0
715                                             flags = 0x000006
716                                             OutputChannelCount = 2
717                                             InputSampleRate = 44100
718                                             OutputGain = 0.000000
719                                             ChannelMappingFamily = 0
720                                 [stts: Decoding Time to Sample Box]
721                                     position = 10099
722                                     size = 24
723                                     version = 0
724                                     flags = 0x000000
725                                     entry_count = 1
726                                     entry[0]
727                                         sample_count = 10
728                                         sample_delta = 3840
729                                 [stsc: Sample To Chunk Box]
730                                     position = 10123
731                                     size = 40
732                                     version = 0
733                                     flags = 0x000000
734                                     entry_count = 2
735                                     entry[0]
736                                         first_chunk = 1
737                                         samples_per_chunk = 4
738                                         sample_description_index = 1
739                                     entry[1]
740                                         first_chunk = 3
741                                         samples_per_chunk = 2
742                                         sample_description_index = 1
743                                 [stsz: Sample Size Box]
744                                     position = 10163
745                                     size = 60
746                                     version = 0
747                                     flags = 0x000000
748                                     sample_size = 0 (variable)
749                                     sample_count = 10
750                                     entry_size[0] = 780
751                                     entry_size[1] = 920
752                                     entry_size[2] = 963
753                                     entry_size[3] = 988
754                                     entry_size[4] = 1024
755                                     entry_size[5] = 951
756                                     entry_size[6] = 933
757                                     entry_size[7] = 1017
758                                     entry_size[8] = 992
759                                     entry_size[9] = 975
760                                 [stco: Chunk Offset Box]
761                                     position = 10223
762                                     size = 28
763                                     version = 0
764                                     flags = 0x000000
765                                     entry_count = 3
766                                     chunk_offset[0] = 40
767                                     chunk_offset[1] = 3691
768                                     chunk_offset[2] = 7616
769                                 [sgpd: Sample Group Description Box]
770                                     position = 10251
771                                     size = 30
772                                     version = 1
773                                     flags = 0x000000
774                                     grouping_type = roll
775                                     default_length = 2 (constant)
776                                     entry_count = 3
777                                     roll_distance[0] = -1
778                                     roll_distance[1] = -2
779                                     roll_distance[2] = -3
780                                 [sbgp: Sample to Group Box]
781                                     position = 10281
782                                     size = 68
783                                     version = 0
784                                     flags = 0x000000
785                                     grouping_type = roll
786                                     entry_count = 6
787                                     entry[0]
788                                         sample_count = 2
789                                         group_description_index = 1
790                                     entry[1]
791                                         sample_count = 1
792                                         group_description_index = 2
793                                     entry[2]
794                                         sample_count = 1
795                                         group_description_index = 3
796                                     entry[3]
797                                         sample_count = 1
798                                         group_description_index = 2
799                                     entry[4]
800                                         sample_count = 3
801                                         group_description_index = 3
802                                     entry[5]
803                                         sample_count = 2
804                                         group_description_index = 1
805
806 <a name="5"></a>
807 5 Authors' Address
808     Yusuke Nakamura
809         Email: muken.the.vfrmaniac |at| gmail.com
810         </div>
811     </body>
812 </html>