fix bug in cuesheet parsing where it would return an error if the last line of the...
[flac.git] / doc / html / ogg_mapping.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <!-- Copyright (c)  2004,2005  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         <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
11         <meta name="author" content="Josh Coalson" />
12         <meta name="description" content="A free, open source codec for lossless audio compression and decompression" />
13         <meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" />
14         <link rel="shortcut icon" type="image/x-icon" href="favicon.ico" />
15         <link rel="stylesheet" type="text/css" href="flac.css" />
16         <title>FLAC - ogg mapping</title>
17 </head>
18
19 <body>
20
21 <div class="logo">
22         <a href="http://flac.sourceforge.net/"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a>
23 </div>
24
25 <div class="above_nav"></div>
26
27 <div class="navbar">
28         &nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
29         &nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
30         &nbsp;<a href="news.html">news</a>&nbsp;&nbsp;|
31         &nbsp;<a href="download.html">download</a>&nbsp;&nbsp;|
32         &nbsp;<a href="features.html">features</a>&nbsp;&nbsp;|
33         &nbsp;<a href="goals.html">goals</a>&nbsp;&nbsp;|
34         &nbsp;<a href="format.html">format</a>&nbsp;&nbsp;|
35         &nbsp;<a href="id.html">id</a>&nbsp;&nbsp;|
36         &nbsp;<a href="comparison.html">comparison</a>&nbsp;&nbsp;|
37         &nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
38         &nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
39         &nbsp;<a href="links.html">links</a>&nbsp;&nbsp;|
40         &nbsp;<a href="developers.html">developers</a>&nbsp;
41 </div>
42
43 <div class="langbar">
44         &nbsp;english&nbsp;&nbsp;|
45         &nbsp;<a href="ru/ogg_mapping.html">russian</a>&nbsp;
46 </div>
47
48 <div class="below_nav"></div>
49
50 <div class="box">
51         <div class="box_title">
52                 ogg mapping
53         </div>
54         <div class="box_header"></div>
55         <div class="box_body">
56                 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>.<br />
57                 <br />
58                 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.<br />
59                 <br />
60                 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).<br />
61                 <br />
62                 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.<br />
63                 <br />
64                 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.<br />
65                 <br />
66                 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.<br />
67                 <br />
68                 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 <span class="commandname">flac</span> versions before 1.1.1 should be decoded and re-encoded with <span class="commandname">flac</span> 1.1.1 or later (<span class="commandname">flac</span> 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.<br />
69                 <br />
70                 Version 1.0 of the FLAC-to-Ogg mapping then is a simple identifying header followed by pure native FLAC data, as follows:
71                 <ul>
72                         <li>
73                                 The first packet of a stream consists of:
74                                 <ul>
75                                         <li>The one-byte packet type 0x7F</li>
76                                         <li>The four-byte ASCII signature "FLAC", i.e. 0x46, 0x4C, 0x41, 0x43</li>
77                                         <li>A one-byte binary major version number for the mapping, e.g. 0x01 for mapping version 1.0</li>
78                                         <li>A one-byte binary minor version number for the mapping, e.g. 0x00 for mapping version 1.0</li>
79                                         <li>A two-byte, big-endian binary number signifying the number of header (non-audio) packets, not 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>
80                                         <li>The four-byte ASCII native FLAC signature "fLaC" according to the <a href="format.html#stream">FLAC format specification</a></li>
81                                         <li>The <a href="format.html#metadata_block">STREAMINFO</a> metadata block for the stream.</li>
82                                 </ul>
83                                 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.
84                         </li>
85                         <li>
86                                 This first page is marked 'beginning of stream' in the page flags.
87                         </li>
88                         <li>
89                                 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).
90                         </li>
91                         <li>
92                                 The granule position of these first pages containing only headers is zero.
93                         </li>
94                         <li>
95                                 The first audio packet of the logical stream begins a fresh Ogg page.
96                         </li>
97                         <li>
98                                 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>.
99                         </li>
100                         <li>
101                                 The last page is marked 'end of stream' in the page flags.
102                         </li>
103                         <li>
104                                 FLAC packets may span page boundaries.
105                         </li>
106                         <li>
107                                 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>.
108                         </li>
109                         <li>
110                                 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.
111                         </li>
112                 </ul>
113                 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.<br />
114                 <br />
115                 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.
116         </div>
117         <div class="box_footer"></div>
118 </div>
119
120
121 <div class="copyright">
122         Copyright (c) 2004,2005  Josh Coalson
123 </div>
124
125 </body>
126 </html>