flac/doc/isoflac.txt

667 lines
31 KiB
Plaintext

Encapsulation of FLAC in ISO Base Media File Format
Version 0.0.4
Table of Contents
1 Scope
2 Supporting Normative References
3 Design Rules of Encapsulation
3.1 File Type Identification
3.2 Overview of Track Structure
3.3 Definition of FLAC sample
3.3.1 Sample entry format
3.3.2 FLAC Specific Box
3.3.3 Sample format
3.3.4 Duration of FLAC sample
3.3.5 Sub-sample
3.3.6 Random Access
3.3.6.1 Random Access Point
3.4 Basic Structure (informative)
3.4.1 Initial Movie
3.5 Example of Encapsulation (informative)
4 Acknowledgements
5 Author's Address
1 Scope
This document specifies the normative mapping for encapsulation of
FLAC coded audio bitstreams in ISO Base Media file format and its
derivatives. The encapsulation of FLAC coded bitstreams in
QuickTime file format is outside the scope of this specification.
2 Supporting Normative References
[1] ISO/IEC 14496-12:2012 Corrected version
Information technology — Coding of audio-visual objects — Part
12: ISO base media file format
[2] ISO/IEC 14496-12:2012/Amd.1:2013
Information technology — Coding of audio-visual objects — Part
12: ISO base media file format AMENDMENT 1: Various
enhancements including support for large metadata
[3] FLAC format specification
https://xiph.org/flac/format.html
Definition of the FLAC Audio Codec stream format
[4] FLAC-in-Ogg mapping specification
https://xiph.org/flac/ogg_mapping.html
Ogg Encapsulation for the FLAC Audio Codec
[5] Matroska specification
3 Design Rules of Encapsulation
3.1 File Type Identification
This specification does not define any brand to declare files
which conform to this specification. Files which conform 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. The minimal support of the
encapsulation of FLAC bitstreams in ISO Base Media file format
requires the 'isom' brand.
3.2 Overview of Track Structure
FLAC coded audio shall be encapsulated into the ISO Base
Media File Format as media data within an audio track.
+ 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 'fLaC'.
This specification does not define any encapsulation
using MP4AudioSampleEntry with objectTypeIndication
specified by the MPEG-4 Registration Authority
(http://www.mp4ra.org/). See section 'Sample entry
format' for the definition of the sample entry.
+ The 'dfLa' box is added to the sample entry to convey
initializing information for the decoder.
See section 'FLAC Specific Box' for the definition of
the box contents.
+ A FLAC sample is exactly one FLAC frame as described
in the format specification[3]. See section
'Sample format' for details of the frame contents.
+ Every FLAC sample is a sync sample. No pre-roll or
lapping is required. See section 'Random Access' for
further details.
3.3 Definition of a FLAC sample
3.3.1 Sample entry format
For any track containing one or more FLAC bitstreams, a
sample entry describing the corresponding FLAC bitstream
shall be present inside the Sample Table Box. This version
of the specification defines only one sample entry format
named FLACSampleEntry whose codingname is 'fLaC'. This
sample entry includes exactly one FLAC Specific Box
defined in section 'FLAC specific box' as a mandatory box
and indicates that FLAC samples described by this sample
entry are stored by the sample format described in section
'Sample format'.
The syntax and semantics of the FLACSampleEntry is shown
as follows. The data fields of this box and native
FLAC[3] structures encoded within FLAC blocks are both
stored in big-endian format, though for purposes of the
ISO BMFF container, FLAC native metadata and data blocks
are treated as unstructured octet streams.
class FLACSampleEntry() extends AudioSampleEntry ('fLaC'){
FLACSpecificBox();
}
The fields of the AudioSampleEntry portion shall be set as
follows:
+ channelcount:
The channelcount field shall be set equal to the
channel count specified by the FLAC bitstream's native
METADATA_BLOCK_STREAMINFO header as described in [3].
Note that the FLAC FRAME_HEADER structure that begins
each FLAC sample redundantly encodes channel number;
the number of channels declared in each FRAME_HEADER
MUST match the number of channels declared here and in
the METADATA_BLOCK_STREAMINFO header.
+ samplesize:
The samplesize field shall be set equal to the bits
per sample specified by the FLAC bitstream's native
METADATA_BLOCK_STREAMINFO header as described in [3].
Note that the FLAC FRAME_HEADER structure that begins
each FLAC sample redundantly encodes the number of
bits per sample; the bits per sample declared in each
FRAME_HEADER MUST match the samplesize declared here
and the bits per sample field declared in the
METADATA_BLOCK_STREAMINFO header.
+ samplerate:
When possible, the samplerate field shall be set
equal to the sample rate specified by the FLAC
bitstream's native METADATA_BLOCK_STREAMINFO header
as described in [3], left-shifted by 16 bits to
create the appropriate 16.16 fixed-point
representation.
When the bitstream's native sample rate is greater
than the maximum expressible value of 65535 Hz,
the samplerate field shall hold the greatest
expressible regular division of that rate. I.e.
the samplerate field shall hold 48000.0 for
native sample rates of 96 and 192 kHz. In the
case of unusual sample rates which do not have
an expressible regular division, the maximum value
of 65535.0 Hz should be used.
High-rate FLAC bitstreams are common, and the native
value from the METADATA_BLOCK_STREAMINFO header in
the FLACSpecificBox MUST be read to determine the
correct sample rate of the bitstream.
Note that the FLAC FRAME_HEADER structure that begins
each FLAC sample redundantly encodes the sample rate;
the sample rate declared in each FRAME_HEADER MUST
match the sample rate declared in the
METADATA_BLOCK_STREAMINFO header, and here in the
AudioSampleEntry portion of the FLACSampleEntry
as much as is allowed by the encoding restrictions
described above.
Finally, the FLACSpecificBox carries codec headers:
+ FLACSpecificBox
This box contains initializing information for the
decoder as defined in section 'FLAC specific box'.
3.3.2 FLAC Specific Box
Exactly one FLAC Specific Box shall be present in each
FLACSampleEntry. This specification defines version 0
of this box. If incompatible changes occur in future
versions of this specification, another version number
will be defined. The data fields of this box and native
FLAC[3] structures encoded within FLAC blocks are both
stored in big-endian format, though for purposes of the
ISO BMFF container, FLAC native metadata and data blocks
are treated as unstructured octet streams.
The syntax and semantics of the FLAC Specific Box is shown
as follows.
class FLACMetadataBlock {
unsigned int(1) LastMetadataBlockFlag;
unsigned int(7) BlockType;
unsigned int(24) Length;
unsigned int(8) BlockData[Length];
}
aligned(8) class FLACSpecificBox
extends FullBox('dfLa', version=0, 0){
for (i=0; ; i++) { // to end of box
FLACMetadataBlock();
}
}
+ 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 FLACSpecificBox.
+ Flags:
The Flags field shall be set to 0.
After the FullBox header, the box contains a sequence of
FLAC[3] native-metadata block structures that fill the
remainder of the box.
Each FLACMetadataBlock structure consists of three fields
filling a total of four bytes that form a FLAC[3] native
METADATA_BLOCK_HEADER, followed by raw octet bytes that
comprise the FLAC[3] native METADATA_BLOCK_DATA.
+ LastMetadataBlockFlag:
The LastMetadataBlockFlag field maps semantically to
the FLAC[3] native METADATA_BLOCK_HEADER
Last-metadata-block flag as defined in the FLAC[3]
file specification.
The LastMetadataBlockFlag is set to 1 if this
MetadataBlock is the last metadata block in the
FLACSpecificBox. It is set to 0 otherwise.
+ BlockType:
The BlockType field maps semantically to the FLAC[3]
native METADATA_BLOCK_HEADER BLOCK_TYPE field as
defined in the FLAC[3] file specification.
The BlockType is set to a valid FLAC[3] BLOCK_TYPE
value that identifies the type of this native metadata
block. The BlockType of the first FLACMetadataBlock
must be set to 0, signifying this is a FLAC[3] native
METADATA_BLOCK_STREAMINFO block.
+ Length:
The Length field maps semantically to the FLAC[3]
native METADATA_BLOCK_HEADER Length field as
defined in the FLAC[3] file specification.
The length field specifies the number of bytes of
MetadataBlockData to follow.
+ BlockData
The BlockData field maps semantically to the FLAC[3]
native METADATA_BLOCK_HEADER METADATA_BLOCK_DATA as
defined in the FLAC[3] file specification.
Taken together, the bytes of the FLACMetadataBlock form a
complete FLAC[3] native METADATA_BLOCK structure.
Note that a minimum of a single FLACMetadataBlock,
consisting of a FLAC[3] native METADATA_BLOCK_STREAMINFO
structure, is required. Should the FLACSpecificBox
contain more than a single FLACMetadataBlock structure,
the FLACMetadataBlock containing the FLAC[3] native
METADATA_BLOCK_STREAMINFO must occur first in the list.
Other containers that package FLAC audio streams, such as
Ogg[4] and Matroska[5], wrap FLAC[3] native metadata without
modification similar to this specification. When
repackaging or remuxing FLAC[3] streams from another
format that contains FLAC[3] native metadata into an ISO
BMFF file, the complete FLAC[3] native metadata should be
preserved in the ISO BMFF stream as described above. It
is also allowed to parse this native metadata and include
contextually redundant ISO BMFF-native repackagings and/or
reparsings of FLAC[3] native metadata, so long as the
native metadata is also preserved.
3.3.3 Sample format
A FLAC sample is exactly one FLAC audio FRAME (as defined
in the FLAC[3] file specification) belonging to a FLAC
bitstreams. The FLAC sample data begins with a complete
FLAC FRAME_HEADER, followed by one FLAC SUBFRAME per
channel, any necessary bit padding, and ends with the
usual FLAC FRAME_FOOTER.
Note that the FLAC native FRAME_HEADER structure that
begins each FLAC sample redundantly encodes channel count,
sample rate, and sample size. The values of these fields
must agree both with the values declared in the FLAC
METADATA_BLOCK_STREAMINFO structure as well as the
FLACSampleEntry box.
3.3.4 Duration of a FLAC sample
The duration of any given FLAC sample is determined by
dividing the decoded block size of a FLAC frame, as
encoded in the FLAC FRAME's FRAME_HEADER structure, by the
value of the timescale field in the Media Header Box.
FLAC samples are permitted to have variable durations
within a given audio stream. FLAC does not use padding
values.
3.3.5 Sub-sample
Sub-samples are not defined for FLAC samples in this
specification.
3.3.6 Random Access
This subclause describes the nature of the random access
of FLAC sample.
3.3.6.1 Random Access Point
All FLAC samples can be independently decoded
i.e. every FLAC sample is a sync sample. The Sync
Sample Box shall not be present as long as there are
no samples other than FLAC samples in the same
track. The sample_is_non_sync_sample field for FLAC
samples shall be set to 0.
3.4 Basic Structure (informative)
3.4.1 Initial Movie
This subclause shows a basic structure of the Movie Box as follows:
+----+----+----+----+----+----+----+----+------------------------------+
|moov| | | | | | | | Movie Box |
+----+----+----+----+----+----+----+----+------------------------------+
| |mvhd| | | | | | | Movie Header Box |
+----+----+----+----+----+----+----+----+------------------------------+
| |trak| | | | | | | Track Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | |tkhd| | | | | | Track Header Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | |edts|* | | | | | Edit Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | |elst|* | | | | Edit List Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | |mdia| | | | | | Media Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | |mdhd| | | | | Media Header Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | |hdlr| | | | | Handler Reference Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | |minf| | | | | Media Information Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | |smhd| | | | Sound Media Header Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | |dinf| | | | Data Information Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | |dref| | | Data Reference Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | | |url | | DataEntryUrlBox |
+----+----+----+----+----+----+ or +----+------------------------------+
| | | | | | |urn | | DataEntryUrnBox |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | |stbl| | | | Sample Table |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | |stsd| | | Sample Description Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | | |fLaC| | FLACSampleEntry |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | | | |dfLa| FLAC Specific Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | |stts| | | Decoding Time to Sample Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | |stsc| | | Sample To Chunk Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | |stsz| | | Sample Size Box |
+----+----+----+----+----+ or +----+----+------------------------------+
| | | | | |stz2| | | Compact Sample Size Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | | | | |stco| | | Chunk Offset Box |
+----+----+----+----+----+ or +----+----+------------------------------+
| | | | | |co64| | | Chunk Large Offset Box |
+----+----+----+----+----+----+----+----+------------------------------+
| |mvex|* | | | | | | Movie Extends Box |
+----+----+----+----+----+----+----+----+------------------------------+
| | |trex|* | | | | | Track Extends Box |
+----+----+----+----+----+----+----+----+------------------------------+
Figure 1 - Basic structure of Movie Box
It is strongly recommended that the order of boxes should
follow the above structure. Boxes marked with an asterisk
(*) may or may not be present depending on context. For
most boxes listed above, the definition is as is defined
in ISO/IEC 14496-12 [1]. The additional boxes and the
additional requirements, restrictions and recommendations
to the other boxes are described in this specification.
3.5 Example of Encapsulation (informative)
[File]
size = 17790
[ftyp: File Type Box]
position = 0
size = 24
major_brand = mp42 : MP4 version 2
minor_version = 0
compatible_brands
brand[0] = mp42 : MP4 version 2
brand[1] = isom : ISO Base Media file format
[moov: Movie Box]
position = 24
size = 757
[mvhd: Movie Header Box]
position = 32
size = 108
version = 0
flags = 0x000000
creation_time = UTC 2014/12/12, 18:41:19
modification_time = UTC 2014/12/12, 18:41:19
timescale = 48000
duration = 33600 (00:00:00.700)
rate = 1.000000
volume = 1.000000
reserved = 0x0000
reserved = 0x00000000
reserved = 0x00000000
transformation matrix
| a, b, u | | 1.000000, 0.000000, 0.000000 |
| c, d, v | = | 0.000000, 1.000000, 0.000000 |
| x, y, w | | 0.000000, 0.000000, 1.000000 |
pre_defined = 0x00000000
pre_defined = 0x00000000
pre_defined = 0x00000000
pre_defined = 0x00000000
pre_defined = 0x00000000
pre_defined = 0x00000000
next_track_ID = 2
[iods: Object Descriptor Box]
position = 140
size = 33
version = 0
flags = 0x000000
[tag = 0x10: MP4_IOD]
expandableClassSize = 16
ObjectDescriptorID = 1
URL_Flag = 0
includeInlineProfileLevelFlag = 0
reserved = 0xf
ODProfileLevelIndication = 0xff
sceneProfileLevelIndication = 0xff
audioProfileLevelIndication = 0xfe
visualProfileLevelIndication = 0xff
graphicsProfileLevelIndication = 0xff
[tag = 0x0e: ES_ID_Inc]
expandableClassSize = 4
Track_ID = 1
[trak: Track Box]
position = 173
size = 608
[tkhd: Track Header Box]
position = 181
size = 92
version = 0
flags = 0x000007
Track enabled
Track in movie
Track in preview
creation_time = UTC 2014/12/12, 18:41:19
modification_time = UTC 2014/12/12, 18:41:19
track_ID = 1
reserved = 0x00000000
duration = 33600 (00:00:00.700)
reserved = 0x00000000
reserved = 0x00000000
layer = 0
alternate_group = 0
volume = 1.000000
reserved = 0x0000
transformation matrix
| a, b, u | | 1.000000, 0.000000, 0.000000 |
| c, d, v | = | 0.000000, 1.000000, 0.000000 |
| x, y, w | | 0.000000, 0.000000, 1.000000 |
width = 0.000000
height = 0.000000
[mdia: Media Box]
position = 273
size = 472
[mdhd: Media Header Box]
position = 281
size = 32
version = 0
flags = 0x000000
creation_time = UTC 2014/12/12, 18:41:19
modification_time = UTC 2014/12/12, 18:41:19
timescale = 48000
duration = 34560 (00:00:00.720)
language = und
pre_defined = 0x0000
[hdlr: Handler Reference Box]
position = 313
size = 51
version = 0
flags = 0x000000
pre_defined = 0x00000000
handler_type = soun
reserved = 0x00000000
reserved = 0x00000000
reserved = 0x00000000
name = Xiph Audio Handler
[minf: Media Information Box]
position = 364
size = 381
[smhd: Sound Media Header Box]
position = 372
size = 16
version = 0
flags = 0x000000
balance = 0.000000
reserved = 0x0000
[dinf: Data Information Box]
position = 388
size = 36
[dref: Data Reference Box]
position = 396
size = 28
version = 0
flags = 0x000000
entry_count = 1
[url : Data Entry Url Box]
position = 412
size = 12
version = 0
flags = 0x000001
location = in the same file
[stbl: Sample Table Box]
position = 424
size = 321
[stsd: Sample Description Box]
position = 432
size = 79
version = 0
flags = 0x000000
entry_count = 1
[fLaC: Audio Description]
position = 448
size = 63
reserved = 0x000000000000
data_reference_index = 1
reserved = 0x0000
reserved = 0x0000
reserved = 0x00000000
channelcount = 2
samplesize = 16
pre_defined = 0
reserved = 0
samplerate = 48000.000000
[dfLa: FLAC Specific Box]
position = 484
size = 50
version = 0
flags = 0x000000
[FLACMetadataBlock]
LastMetadataBlockFlag = 1
BlockType = 0
Length = 34
BlockData[34];
[stts: Decoding Time to Sample Box]
position = 492
size = 24
version = 0
flags = 0x000000
entry_count = 1
entry[0]
sample_count = 18
sample_delta = 1920
[stsc: Sample To Chunk Box]
position = 516
size = 40
version = 0
flags = 0x000000
entry_count = 2
entry[0]
first_chunk = 1
samples_per_chunk = 13
sample_description_index = 1
entry[1]
first_chunk = 2
samples_per_chunk = 5
sample_description_index = 1
[stsz: Sample Size Box]
position = 556
size = 92
version = 0
flags = 0x000000
sample_size = 0 (variable)
sample_count = 18
entry_size[0] = 977
entry_size[1] = 938
entry_size[2] = 939
entry_size[3] = 938
entry_size[4] = 934
entry_size[5] = 945
entry_size[6] = 948
entry_size[7] = 956
entry_size[8] = 955
entry_size[9] = 930
entry_size[10] = 933
entry_size[11] = 934
entry_size[12] = 972
entry_size[13] = 977
entry_size[14] = 958
entry_size[15] = 949
entry_size[16] = 962
entry_size[17] = 848
[stco: Chunk Offset Box]
position = 648
size = 24
version = 0
flags = 0x000000
entry_count = 2
chunk_offset[0] = 686
chunk_offset[1] = 12985
[free: Free Space Box]
position = 672
size = 8
[mdat: Media Data Box]
position = 680
size = 17001
4 Acknowledgements
This spec draws heavily from the Opus-in-ISOBMFF specification
work done by Yusuke Nakamura <muken.the.vfrmaniac |at| gmail.com>
Thank you to Tim Terriberry, David Evans, and Yusuke Nakamura
for valuable feedback. Thank you to Ralph Giles for editorial
help.
5 Author Address
Monty Montgomery <cmontgomery@mozilla.com>