1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 2<html> 3<head> 4 5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/> 6<title>Ogg Documentation</title> 7 8<style type="text/css"> 9body { 10 margin: 0 18px 0 18px; 11 padding-bottom: 30px; 12 font-family: Verdana, Arial, Helvetica, sans-serif; 13 color: #333333; 14 font-size: .8em; 15} 16 17a { 18 color: #3366cc; 19} 20 21img { 22 border: 0; 23} 24 25#xiphlogo { 26 margin: 30px 0 16px 0; 27} 28 29#content p { 30 line-height: 1.4; 31} 32 33h1, h1 a, h2, h2 a, h3, h3 a, h4, h4 a { 34 font-weight: bold; 35 color: #ff9900; 36 margin: 1.3em 0 8px 0; 37} 38 39h1 { 40 font-size: 1.3em; 41} 42 43h2 { 44 font-size: 1.2em; 45} 46 47h3 { 48 font-size: 1.1em; 49} 50 51li { 52 line-height: 1.4; 53} 54 55#copyright { 56 margin-top: 30px; 57 line-height: 1.5em; 58 text-align: center; 59 font-size: .8em; 60 color: #888888; 61 clear: both; 62} 63</style> 64 65</head> 66 67<body> 68 69<div id="xiphlogo"> 70 <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a> 71</div> 72 73<h1>Page Multiplexing and Ordering in a Physical Ogg Stream</h1> 74 75<p>The low-level mechanisms of an Ogg stream (as described in the Ogg 76Bitstream Overview) provide means for mixing multiple logical streams 77and media types into a single linear-chronological stream. This 78document specifies the high-level arrangement and use of page 79structure to multiplex multiple streams of mixed media type within a 80physical Ogg stream.</p> 81 82<h2>Design Elements</h2> 83 84<p>The design and arrangement of the Ogg container format is governed by 85several high-level design decisions that form the reasoning behind 86specific low-level design decisions.</p> 87 88<h3>Linear media</h3> 89 90<p>The Ogg bitstream is intended to encapsulate chronological, 91time-linear mixed media into a single delivery stream or file. The 92design is such that an application can always encode and/or decode a 93full-featured bitstream in one pass with no seeking and minimal 94buffering. Seeking to provide optimized encoding (such as two-pass 95encoding) or interactive decoding (such as scrubbing or instant 96replay) is not disallowed or discouraged, however no bitstream feature 97must require nonlinear operation on the bitstream.</p> 98 99<h3>Multiplexing</h3> 100 101<p>Ogg bitstreams multiplex multiple logical streams into a single 102physical stream at the page level. Each page contains an abstract 103time stamp (the Granule Position) that represents an absolute time 104landmark within the stream. After the pages representing stream 105headers (all logical stream headers occur at the beginning of a 106physical bitstream section before any logical stream data), logical 107stream data pages are arranged in a physical bitstream in strict 108non-decreasing order by chronological absolute time as 109specified by the granule position.</p> 110 111<p>The only exception to arranging pages in strictly ascending time order 112by granule position is those pages that do not set the granule 113position value. This is a special case when exceptionally large 114packets span multiple pages; the specifics of handling this special 115case are described later under 'Continuous and Discontinuous 116Streams'.</p> 117 118<h3>Seeking</h3> 119 120<p>Ogg is designed to use an interpolated bisection search to 121implement exact positional seeking. Interpolated bisection search is 122a spec-mandated mechanism.</p> 123 124<p><i>An index may improve objective performance, but it seldom 125improves subjective performance outside of a few high-latency use 126cases and adds no additional functionality as bisection search 127delivers the same functionality for both one- and two-pass stream 128types. For these reasons, use of indexes is discouraged, except in 129cases where an index provides demonstrable and noticeable performance 130improvement.</i></p> 131 132<p>Seek operations are by absolute time; a direct bisection search must 133find the exact time position requested. Information in the Ogg 134bitstream is arranged such that all information to be presented for 135playback from the desired seek point will occur at or after the 136desired seek point. Seek operations are neither 'fuzzy' nor 137heuristic.</p> 138 139<p><i>Although key frame handling in video appears to be an exception to 140"all needed playback information lies ahead of a given seek", 141key frames can still be handled directly within this indexless 142framework. Seeking to a key frame in video (as well as seeking in other 143media types with analogous restraints) is handled as two seeks; first 144a seek to the desired time which extracts state information that 145decodes to the time of the last key frame, followed by a second seek 146directly to the key frame. The location of the previous key frame is 147embedded as state information in the granulepos; this mechanism is 148described in more detail later.</i></p> 149 150<h3>Continuous and Discontinuous Streams</h3> 151 152<p>Logical streams within a physical Ogg stream belong to one of two 153categories, "Continuous" streams and "Discontinuous" streams. 154Although these are discussed in more detail later, the distinction is 155important to a high-level understanding of how to buffer an Ogg 156stream.</p> 157 158<p>A stream that provides a gapless, time-continuous media type with a 159fine-grained timebase is considered to be 'Continuous'. A continuous 160stream should never be starved of data. Clear examples of continuous 161data types include broadcast audio and video.</p> 162 163<p>A stream that delivers data in a potentially irregular pattern or with 164widely spaced timing gaps is considered to be 'Discontinuous'. A 165discontinuous stream may be best thought of as data representing 166scattered events; although they happen in order, they are typically 167unconnected data often located far apart. One possible example of a 168discontinuous stream types would be captioning. Although it's 169possible to design captions as a continuous stream type, it's most 170natural to think of captions as widely spaced pieces of text with 171little happening between.</p> 172 173<p>The fundamental design distinction between continuous and 174discontinuous streams concerns buffering.</p> 175 176<h3>Buffering</h3> 177 178<p>Because a continuous stream is, by definition, gapless, Ogg buffering 179is based on the simple premise of never allowing any active continuous 180stream to starve for data during decode; buffering proceeds ahead 181until all continuous streams in a physical stream have data ready to 182decode on demand.</p> 183 184<p>Discontinuous stream data may occur on a fairly regular basis, but the 185timing of, for example, a specific caption is impossible to predict 186with certainty in most captioning systems. Thus the buffering system 187should take discontinuous data 'as it comes' rather than working ahead 188(for a potentially unbounded period) to look for future discontinuous 189data. As such, discontinuous streams are ignored when managing 190buffering; their pages simply 'fall out' of the stream when continuous 191streams are handled properly.</p> 192 193<p>Buffering requirements need not be explicitly declared or managed for 194the encoded stream; the decoder simply reads as much data as is 195necessary to keep all continuous stream types gapless (also ensuring 196discontinuous data arrives in time) and no more, resulting in optimum 197implicit buffer usage for a given stream. Because all pages of all 198data types are stamped with absolute timing information within the 199stream, inter-stream synchronization timing is always explicitly 200maintained without the need for explicitly declared buffer-ahead 201hinting.</p> 202 203<p>Further details, mechanisms and reasons for the differing arrangement 204and behavior of continuous and discontinuous streams is discussed 205later.</p> 206 207<h3>Whole-stream navigation</h3> 208 209<p>Ogg is designed so that the simplest navigation operations treat the 210physical Ogg stream as a whole summary of its streams, rather than 211navigating each interleaved stream as a separate entity.</p> 212 213<p>First Example: seeking to a desired time position in a multiplexed (or 214unmultiplexed) Ogg stream can be accomplished through a bisection 215search on time position of all pages in the stream (as encoded in the 216granule position). More powerful searches (such as a key frame-aware 217seek within video) are also possible with additional search 218complexity, but similar computational complexity.</p> 219 220<p>Second Example: A bitstream section may consist of three multiplexed 221streams of differing lengths. The result of multiplexing these 222streams should be thought of as a single mixed stream with a length 223equal to the longest of the three component streams. Although it is 224also possible to think of the multiplexed results as three concurrent 225streams of different lengths and it is possible to recover the three 226original streams, it will also become obvious that once multiplexed, 227it isn't possible to find the internal lengths of the component 228streams without a linear search of the whole bitstream section. 229However, it is possible to find the length of the whole bitstream 230section easily (in near-constant time per section) just as it is for a 231single-media unmultiplexed stream.</p> 232 233<h2>Granule Position</h2> 234 235<h3>Description</h3> 236 237<p>The Granule Position is a signed 64 bit field appearing in the header 238of every Ogg page. Although the granule position represents absolute 239time within a logical stream, its value does not necessarily directly 240encode a simple timestamp. It may represent frames elapsed (as in 241Vorbis), a simple timestamp, or a more complex bit-division encoding 242(such as in Theora). The exact encoding of the granule position is up 243to a specific codec.</p> 244 245<p>The granule position is governed by the following rules:</p> 246 247<ul> 248 249<li>Granule Position must always increase forward or remain equal from 250page to page, be unset, or be zero for a header page. The absolute 251time to which any correct sequence of granule position maps must 252similarly always increase forward or remain equal. <i>(A codec may 253make use of data, such as a control sequence, that only affects codec 254working state without producing data and thus advancing granule 255position and time. Although the packet sequence number increases in 256this case, the granule position, and thus the time position, do 257not.)</i></li> 258 259<li>Granule position may only be unset if there no packet defining a 260time boundary on the page (that is, if no packet in a continuous 261stream ends on the page, or no packet in a discontinuous stream begins 262on the page. This will be discussed in more detail under Continuous 263and Discontinuous streams).</li> 264 265<li>A codec must be able to translate a given granule position value 266to a unique, deterministic absolute time value through direct 267calculation. A codec is not required to be able to translate an 268absolute time value into a unique granule position value.</li> 269 270<li>Codecs shall choose a granule position definition that allows that 271codec means to seek as directly as possible to an immediately 272decodable point, such as the bit-divided granule position encoding of 273Theora allows the codec to seek efficiently to key frame without using 274an index. That is, additional information other than absolute time 275may be encoded into a granule position value so long as the granule 276position obeys the above points.</li> 277 278</ul> 279 280<h4>Example: timestamp</h4> 281 282<p>In general, a codec/stream type should choose the simplest granule 283position encoding that addresses its requirements. The examples here 284are by no means exhaustive of the possibilities within Ogg.</p> 285 286<p>A simple granule position could encode a timestamp directly. For 287example, a granule position that encoded milliseconds from beginning 288of stream would allow a logical stream length of over 100,000,000,000 289days before beginning a new logical stream (to avoid the granule 290position wrapping).</p> 291 292<h4>Example: framestamp</h4> 293 294<p>A simple millisecond timestamp granule encoding might suit many stream 295types, but a millisecond resolution is inappropriate to, eg, most 296audio encodings where exact single-sample resolution is generally a 297requirement. A millisecond is both too large a granule and often does 298not represent an integer number of samples.</p> 299 300<p>In the event that audio frames are always encoded as the same number of 301samples, the granule position could simply be a linear count of frames 302since beginning of stream. This has the advantages of being exact and 303efficient. Position in time would simply be <tt>[granule_position] * 304[samples_per_frame] / [samples_per_second]</tt>.</p> 305 306<h4>Example: samplestamp (Vorbis)</h4> 307 308<p>Frame counting is insufficient in codecs such as Vorbis where an audio 309frame [packet] encodes a variable number of samples. In Vorbis's 310case, the granule position is a count of the number of raw samples 311from the beginning of stream; the absolute time of 312a granule position is <tt>[granule_position] / 313[samples_per_second]</tt>.</p> 314 315<h4>Example: bit-divided framestamp (Theora)</h4> 316 317<p>Some video codecs may be able to use the simple framestamp scheme for 318granule position. However, most modern video codecs introduce at 319least the following complications:</p> 320 321<ul> 322 323<li>video frames are relatively far apart compared to audio samples; 324for this reason, the point at which a video frame changes to the next 325frame is usually a strictly defined offset within the frame 'period'. 326That is, video at 50fps could just as easily define frame transitions 327<.015, .035, .055...> as at <.00, .02, .04...>.</li> 328 329<li>frame rates often include drop-frames, leap-frames or other 330rational-but-non-integer timings.</li> 331 332<li>Decode must begin at a 'key frame' or 'I frame'. Keyframes usually 333occur relatively seldom.</li> 334 335</ul> 336 337<p>The first two points can be handled straightforwardly via the fact 338that the codec has complete control mapping granule position to 339absolute time; non-integer frame rates and offsets can be set in the 340codec's initial header, and the rest is just arithmetic.</p> 341 342<p>The third point appears trickier at first glance, but it too can be 343handled through the granule position mapping mechanism. Here we 344arrange the granule position in such a way that granule positions of 345key frames are easy to find. Divide the granule position into two 346fields; the most-significant bits are an absolute frame counter, but 347it's only updated at each key frame. The least significant bits encode 348the number of frames since the last key frame. In this way, each 349granule position both encodes the absolute time of the current frame 350as well as the absolute time of the last key frame.</p> 351 352<p>Seeking to a most recent preceding key frame is then accomplished by 353first seeking to the original desired point, inspecting the granulepos 354of the resulting video page, extracting from that granulepos the 355absolute time of the desired key frame, and then seeking directly to 356that key frame's page. Of course, it's still possible for an 357application to ignore key frames and use a simpler seeking algorithm 358(decode would be unable to present decoded video until the next 359key frame). Surprisingly many player applications do choose the 360simpler approach.</p> 361 362<h3>granule position, packets and pages</h3> 363 364<p>Although each packet of data in a logical stream theoretically has a 365specific granule position, only one granule position is encoded 366per page. It is possible to encode a logical stream such that each 367page contains only a single packet (so that granule positions are 368preserved for each packet), however a one-to-one packet/page mapping 369is not intended to be the general case.</p> 370 371<p>Because Ogg functions at the page, not packet, level, this 372once-per-page time information provides Ogg with the finest-grained 373time information is can use. Ogg passes this granule positioning data 374to the codec (along with the packets extracted from a page); it is the 375responsibility of codecs to track timing information at granularities 376finer than a single page.</p> 377 378<h3>start-time and end-time positioning</h3> 379 380<p>A granule position represents the <em>instantaneous time location 381between two pages</em>. However, continuous streams and discontinuous 382streams differ on whether the granulepos represents the end-time of 383the data on a page or the start-time. Continuous streams are 384'end-time' encoded; the granulepos represents the point in time 385immediately after the last data decoded from a page. Discontinuous 386streams are 'start-time' encoded; the granulepos represents the point 387in time of the first data decoded from the page.</p> 388 389<p>An Ogg stream type is declared continuous or discontinuous by its 390codec. A given codec may support both continuous and discontinuous 391operation so long as any given logical stream is continuous or 392discontinuous for its entirety and the codec is able to ascertain (and 393inform the Ogg layer) as to which after decoding the initial stream 394header. The majority of codecs will always be continuous (such as 395Vorbis) or discontinuous (such as Writ).</p> 396 397<p>Start- and end-time encoding do not affect multiplexing sort-order; 398pages are still sorted by the absolute time a given granulepos maps to 399regardless of whether that granulepos represents start- or 400end-time.</p> 401 402<h2>Multiplex/Demultiplex Division of Labor</h2> 403 404<p>The Ogg multiplex/demultiplex layer provides mechanisms for encoding 405raw packets into Ogg pages, decoding Ogg pages back into the original 406codec packets, determining the logical structure of an Ogg stream, and 407navigating through and synchronizing with an Ogg stream at a desired 408stream location. Strict multiplex/demultiplex operations are entirely 409in the Ogg domain and require no intervention from codecs.</p> 410 411<p>Implementation of more complex operations does require codec 412knowledge, however. Unlike other framing systems, Ogg maintains 413strict separation between framing and the framed bitstream data; Ogg 414does not replicate codec-specific information in the page/framing 415data, nor does Ogg blur the line between framing and stream 416data/metadata. Because Ogg is fully data-agnostic toward the data it 417frames, operations which require specifics of bitstream data (such as 418'seek to key frame') also require interaction with the codec layer 419(because, in this example, the Ogg layer is not aware of the concept 420of key frames). This is different from systems that blur the 421separation between framing and stream data in order to simplify the 422separation of code. The Ogg system purposely keeps the distinction in 423data simple so that later codec innovations are not constrained by 424framing design.</p> 425 426<p>For this reason, however, complex seeking operations require 427interaction with the codecs in order to decode the granule position of 428a given stream type back to absolute time or in order to find 429'decodable points' such as key frames in video.</p> 430 431<h2>Unsorted Discussion Points</h2> 432 433<p>flushes around key frames? RFC suggestion: repaginating or building a 434stream this way is nice but not required</p> 435 436<h2>Appendix A: multiplexing examples</h2> 437 438<div id="copyright"> 439 The Xiph Fish Logo is a 440 trademark (™) of Xiph.Org.<br/> 441 442 These pages © 1994 - 2005 Xiph.Org. All rights reserved. 443</div> 444 445</body> 446</html> 447
