8c72bee9d65ec8d3bfca56e3aa3d346a000da647
[flac.git] / doc / html / ogg_mapping.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <!-- Copyright (c)  2004  Josh Coalson -->
3 <!-- Permission is granted to copy, distribute and/or modify this document -->
4 <!-- under the terms of the GNU Free Documentation License, Version 1.1 -->
5 <!-- or any later version published by the Free Software Foundation; -->
6 <!-- with no invariant sections. -->
7 <!-- A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html -->
8 <HTML>
9 <HEAD>
10         <TITLE>FLAC - Ogg mapping</TITLE>
11 </HEAD>
12
13 <BODY MARGINWIDTH="0" MARGINHEIGHT="0" LEFTMARGIN="0" RIGHTMARGIN="0" TOPMARGIN="0" BGCOLOR="#99CC99" TEXT="#000000" LINK="#336699" VLINK="#336699" ALINK="#336699">
14
15 <TABLE BORDER=0 WIDTH="100%" CELLPADDING=1 CELLSPACING=0>
16         <TR>
17                 <TD ALIGN="CENTER" BGCOLOR="#000000"><A HREF="http://flac.sourceforge.net/"><IMG SRC="images/logo130.gif" ALIGN=CENTER ALT="FLAC Logo" BORDER=0 HSPACE=0></a></TD>
18         </TR>
19 </TABLE>
20
21 <TABLE WIDTH="100%" CELLPADDING="0" CELLSPACING="0" BORDER="0"><TR BGCOLOR="#99CC99"><TD><IMG SRC="images/1x1.gif" WIDTH="1" HEIGHT="25" ALT=""></TD></TR></TABLE>
22
23 <TABLE WIDTH="100%" CELLPADDING="0" CELLSPACING="0" BORDER="0"><TR BGCOLOR="#000000"><TD><IMG SRC="images/1x1.gif" WIDTH="1" HEIGHT="2" ALT=""></TD></TR></TABLE>
24
25 <TABLE WIDTH="100%" CELLPADDING=0 CELLSPACING=0 BORDER=0>
26         <TR>
27                 <TD ALIGN="CENTER" BGCOLOR="#D3D4C5">
28                         <TABLE CELLPADDING=0 CELLSPACING=0 BORDER=0>
29                                 <TR>
30                                         <TD HEIGHT=22 BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="index.html">home</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
31                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="faq.html">faq</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
32                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="news.html">news</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
33                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="download.html">download</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
34                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="features.html">features</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
35                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="goals.html">goals</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
36                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="format,html">format</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
37                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="id.html">id</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
38                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="comparison.html">comparison</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
39                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="documentation.html">documentation</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
40                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="changelog.html">changelog</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
41                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="links.html">links</A>&nbsp;&nbsp;</TD><TD BGCOLOR="#D3D4C5" ALIGN=CENTER>|</TD>
42                                         <TD           BGCOLOR="#D3D4C5" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="developers.html">developers</A>&nbsp;&nbsp;</TD>
43                                 </TR>
44                         </TABLE>
45                 </TD>
46         </TR>
47 </TABLE>
48
49 <TABLE WIDTH="100%" CELLPADDING="0" CELLSPACING="0" BORDER="0"><TR BGCOLOR="#000000"><TD><IMG SRC="images/1x1.gif" WIDTH="1" HEIGHT="2" ALT=""></TD></TR></TABLE>
50
51 <TABLE WIDTH="100%" CELLPADDING=0 CELLSPACING=0 BORDER=0>
52         <TR>
53                 <TD ALIGN="CENTER" BGCOLOR="#EEEED4">
54                         <TABLE CELLPADDING=0 CELLSPACING=0 BORDER=0>
55                                 <TR>
56                                         <TD HEIGHT=22 BGCOLOR="#EEEED4" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;english&nbsp;&nbsp;</TD><TD BGCOLOR="#EEEED4" ALIGN=CENTER>|</TD>
57                                         <TD           BGCOLOR="#EEEED4" ALIGN=CENTER NOWRAP>&nbsp;&nbsp;<A CLASS="topnav" HREF="ru/ogg_mapping.html">russian</A>&nbsp;&nbsp;</TD>
58                                 </TR>
59                         </TABLE>
60                 </TD>
61         </TR>
62 </TABLE>
63
64 <TABLE WIDTH="100%" CELLPADDING="0" CELLSPACING="0" BORDER="0"><TR BGCOLOR="#000000"><TD><IMG SRC="images/1x1.gif" WIDTH="1" HEIGHT="2" ALT=""></TD></TR></TABLE>
65
66 <CENTER>
67
68 <TABLE WIDTH="100%" CELLPADDING="0" CELLSPACING="0" BORDER="0"><TR BGCOLOR="#99CC99"><TD><IMG SRC="images/1x1.gif" WIDTH="1" HEIGHT="15" ALT=""></TD></TR></TABLE>
69
70
71 <TABLE WIDTH="100%" CELLPADDING="5" CELLSPACING="5" BORDER="0">
72 <TR><TD>
73         <TABLE WIDTH="100%" CELLPADDING="0" CELLSPACING="0" BORDER="0"><TR BGCOLOR="#000000"><TD><IMG SRC="images/1x1.gif" WIDTH="1" HEIGHT="1" ALT=""></TD></TR></TABLE>
74         <TABLE CELLSPACING="0" CELLPADDING="3" WIDTH="100%" BORDER="0" BGCOLOR="#D3D4C5">
75                 <TR><TD><FONT FACE="Lucida,Verdana,Helvetica,Arial">
76                 <B><FONT SIZE="+2">ogg mapping</FONT></B>
77                 </FONT></TD></TR>
78         </TABLE>
79         <TABLE WIDTH="100%" CELLPADDING="0" CELLSPACING="0" BORDER="0"><TR BGCOLOR="#000000"><TD><IMG SRC="images/1x1.gif" WIDTH="1" HEIGHT="1" ALT=""></TD></TR></TABLE>
80         <TABLE CELLSPACING="0" CELLPADDING="3" WIDTH="100%" BORDER="0" BGCOLOR="#EEEED4">
81         <TR><TD><FONT FACE="Lucida,Verdana,Helvetica,Arial">
82         <P>
83                 This page specifies the way in which compressed FLAC data is encapsulated in an Ogg transport layer.  It assumes basic knowledge of the <A HREF="format.html">FLAC format</A> and <A HREF="http://www.xiph.org/ogg/vorbis/doc/oggstream.html">Ogg structure</A> and <A HREF="http://www.xiph.org/ogg/vorbis/doc/framing.html">framing</A>.
84         </P>
85         <P>
86                 The original FLAC format includes a very thin transport system.  This system of compressed FLAC audio data mixed with a thin transport has come to be known as 'native FLAC'.  The transport consists of audio frame headers and footers which contain synchronization patterns, timecodes, and checksums (but notably not frame lengths), and a metadata system.  It is very lightweight and does not support more elaborate transport mechanisms such as multiple logical streams, but it has served its purpose well.
87         </P>
88         <P>
89                 The native FLAC transport is not a transport "layer" in the way of standard codec design because it cannot be entirely separated from the payload.  Though the metadata system can be separated, the frame header includes both data that belongs in the transport (sync pattern, timecode, checksum) and data that belongs in the compressed packets (audio parameters like channel assignments, sample rate, etc).
90         </P>
91         <P>
92                 This presents a problem when trying to encapsulate FLAC in other true transport layers; the choice has to be made between redundancy and complexity.  In pursuit of correctness, a mapping could be created that removed from native FLAC the transport data, and merged the remaining frame header information into the audio packets.  The disadvantage is that current native FLAC decoder software could not be used to decode because of the tight coupling with the transport.  Either a separate decoding implementation would have to be created and maintained, or an Ogg FLAC decoder would have to synthesize native FLAC frames from Ogg FLAC packets and feed them to a native FLAC decoder.
93         </P>
94         <P>
95                 The alternative is to treat native FLAC frames as Ogg packets and accept the transport redundancy.  It turns out that this is not much of a penalty; a maximum of 12 bytes per frame will be wasted.  Given the common case of stereo CD audio encoded with a blocksize of 4608 samples, a compressed frame will be 4-16 Kbytes.  The redundancy amounts to a fraction of a percent.
96         </P>
97         <P>
98                 In the interest of simplicity and expediency, the second method was chosen for the first official FLAC-&gt;Ogg mapping.  A mapping version is included in the first packet so that a less redundant mapping can be defined in the future.
99         </P>
100         <P>
101                 It should also be noted that support for encapsulating FLAC in Ogg has been present in the FLAC tools since version 1.0.1.  However, the mappings used were never formalized and have insurmountable problems.  For that reason, Ogg FLAC streams created with <B><TT>flac</TT></B> versions before 1.1.1 should be decoded and re-encoded with <B><TT>flac</TT></B> 1.1.1 or later (<B><TT>flac</TT></B> 1.1.1 can decode all previous Ogg FLAC files, but files made prior to 1.1.0 don't support seeking).  Since the support for Ogg FLAC before FLAC 1.1.1 was limited, we hope this will not result in too much inconvenience.
102         </P>
103         <P>
104                 Version 1.0 of the FLAC-to-Ogg mapping then is a simple identifying header followed by pure native FLAC data, as follows:
105                 <UL>
106                         <LI>
107                                 The first packet of a stream consists of:
108                                 <UL>
109                                         <LI>The one-byte packet type 0x7F</LI>
110                                         <LI>The four-byte ASCII signature "FLAC", i.e. 0x46, 0x4C, 0x41, 0x43</LI>
111                                         <LI>A one-byte binary major version number for the mapping, e.g. 0x01 for mapping version 1.0</LI>
112                                         <LI>A one-byte binary minor version number for the mapping, e.g. 0x00 for mapping version 1.0</LI>
113                                         <LI>A two-byte, big-endian binary number signifying the number of header (non-audio) packets, including this one.  This number may be zero (0x0000) to signify 'unknown' but be aware that some decoders may not be able to handle such streams.@@@@@@</LI>
114                                         <LI>The four-byte ASCII native FLAC signature "fLaC" according to the <A HREF="format.html#stream">FLAC format specification</A></LI>
115                                         <LI>The <A HREF="format.html#metadata_block">STREAMINFO</A> metadata block for the stream.</LI>
116                                 </UL>
117                                 This first packet is the only packet in the first page of the stream.  This results in a first Ogg page of exactly 79 bytes at the very beginning of the logical stream.
118                         </LI>
119                         <LI>
120                                 This first page is marked 'beginning of stream' in the page flags.
121                         </LI>
122                         <LI>
123                                 The first packet is followed by one or more header packets.  Each such packet will contain a single <A HREF="format.html#metadata_block">native FLAC metadata block</A>.  The first of these must be a VORBIS_COMMENT block.  These packets may span page boundaries but the last will finish the page on which it ends, so that the first audio packet begins a page.  The first byte of these metadata packets serves also as the packet type, and has a legal range of (0x01-0x7E,0x81-0xFE).
124                         </LI>
125                         <LI>
126                                 The granule position of these first pages containing only headers is zero.
127                         </LI>
128                         <LI>
129                                 The first audio packet of the logical stream begins a fresh Ogg page.
130                         </LI>
131                         <LI>
132                                 Native FLAC audio frames appear as subsequent packets in the stream.  Each packet corresponds to one FLAC audio frame.  The first byte of each packet serves as the packet type.  Since audio packets are native FLAC frames, this first byte will be always 0xFF according to the <A HREF="format.html#frame_header">native FLAC format specification</A>.
133                         </LI>
134                         <LI>
135                                 The last page is marked 'end of stream' in the page flags.
136                         </LI>
137                         <LI>
138                                 FLAC packets may span page boundaries.
139                         </LI>
140                         <LI>
141                                 The granule position of pages containing FLAC audio follows the same semantics as that for Ogg-encapsulated Vorbis as described <A HREF="http://www.xiph.org/ogg/vorbis/doc/vorbis-ogg.html">here</A>.
142                         </LI>
143                         <LI>
144                                 Redundant fields in the STREAMINFO packet may be set to zero (indicating "unknown" in native FLAC), which also facilitates single-pass encoding.  These fields are: the minimum and maximum frame sizes, the total samples count, and the MD5 signature.  "Unknown" values for these fields will not prevent a compliant native FLAC or Ogg FLAC decoder from decoding the stream.
145                         </LI>
146                 </UL>
147         </P>
148         <P>
149                 It is intended that the first six bytes of any version of FLAC-to-Ogg mapping will share the same structure, namely, the four-byte signature and two-byte version number.
150         </P>
151         <P>
152                 There is an implicit hint to the decoder in the mapping version number; mapping versions which share the same major version number should be decodable by decoders of the same major version number, e.g. a 1.x Ogg FLAC decoder should be able to decode any 1.y Ogg FLAC stream, even when x&lt;y.  If a mapping breaks this forward compatibility the major version number will be incremented.
153         </P>
154
155 </TD></TR>
156 </TABLE>
157
158
159 </CENTER>
160
161 <P>&nbsp;Copyright (c) 2004 Josh Coalson</P>
162
163 </BODY>
164 </HTML>