summaryrefslogtreecommitdiffstats
path: root/doc/isoflac.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/isoflac.txt')
-rw-r--r--doc/isoflac.txt666
1 files changed, 666 insertions, 0 deletions
diff --git a/doc/isoflac.txt b/doc/isoflac.txt
new file mode 100644
index 0000000..888aed7
--- /dev/null
+++ b/doc/isoflac.txt
@@ -0,0 +1,666 @@
+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>
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-21 13:19:08 +0000