Mercurial > hg > sv-dependency-builds

annotate src/libogg-1.3.0/doc/oggstream.html @ 86:98c1576536ae

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bring in flac, ogg, vorbis
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 19 Mar 2013 17:37:49 +0000
parents
children
rev   line source
cannam@86 1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
cannam@86 2 <html>
cannam@86 3 <head>
cannam@86 4
cannam@86 5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
cannam@86 6 <title>Ogg Documentation</title>
cannam@86 7
cannam@86 8 <style type="text/css">
cannam@86 9 body {
cannam@86 10 margin: 0 18px 0 18px;
cannam@86 11 padding-bottom: 30px;
cannam@86 12 font-family: Verdana, Arial, Helvetica, sans-serif;
cannam@86 13 color: #333333;
cannam@86 14 font-size: .8em;
cannam@86 15 }
cannam@86 16
cannam@86 17 a {
cannam@86 18 color: #3366cc;
cannam@86 19 }
cannam@86 20
cannam@86 21 img {
cannam@86 22 border: 0;
cannam@86 23 }
cannam@86 24
cannam@86 25 #xiphlogo {
cannam@86 26 margin: 30px 0 16px 0;
cannam@86 27 }
cannam@86 28
cannam@86 29 #content p {
cannam@86 30 line-height: 1.4;
cannam@86 31 }
cannam@86 32
cannam@86 33 h1, h1 a, h2, h2 a, h3, h3 a {
cannam@86 34 font-weight: bold;
cannam@86 35 color: #ff9900;
cannam@86 36 margin: 1.3em 0 8px 0;
cannam@86 37 }
cannam@86 38
cannam@86 39 h1 {
cannam@86 40 font-size: 1.3em;
cannam@86 41 }
cannam@86 42
cannam@86 43 h2 {
cannam@86 44 font-size: 1.2em;
cannam@86 45 }
cannam@86 46
cannam@86 47 h3 {
cannam@86 48 font-size: 1.1em;
cannam@86 49 }
cannam@86 50
cannam@86 51 li {
cannam@86 52 line-height: 1.4;
cannam@86 53 }
cannam@86 54
cannam@86 55 #copyright {
cannam@86 56 margin-top: 30px;
cannam@86 57 line-height: 1.5em;
cannam@86 58 text-align: center;
cannam@86 59 font-size: .8em;
cannam@86 60 color: #888888;
cannam@86 61 clear: both;
cannam@86 62 }
cannam@86 63
cannam@86 64 .caption {
cannam@86 65 color: #000000;
cannam@86 66 background-color: #aabbff;
cannam@86 67 margin: 1em;
cannam@86 68 margin-left: 2em;
cannam@86 69 margin-right: 2em;
cannam@86 70 padding: 1em;
cannam@86 71 padding-bottom: 0em;
cannam@86 72 overflow: hidden;
cannam@86 73 }
cannam@86 74
cannam@86 75 .caption p {
cannam@86 76 clear: none;
cannam@86 77 }
cannam@86 78
cannam@86 79 .caption img {
cannam@86 80 display: block;
cannam@86 81 margin: 0px;
cannam@86 82 margin-left: auto;
cannam@86 83 margin-right: auto;
cannam@86 84 margin-bottom: 1.5em;
cannam@86 85 background-color: #ffffff;
cannam@86 86 padding: 10px;
cannam@86 87 }
cannam@86 88
cannam@86 89 #thepage {
cannam@86 90 margin-left: auto;
cannam@86 91 margin-right: auto;
cannam@86 92 width: 840px;
cannam@86 93 }
cannam@86 94
cannam@86 95 </style>
cannam@86 96
cannam@86 97 </head>
cannam@86 98
cannam@86 99 <body>
cannam@86 100 <div id="thepage">
cannam@86 101
cannam@86 102 <div id="xiphlogo">
cannam@86 103 <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
cannam@86 104 </div>
cannam@86 105
cannam@86 106 <h1>Ogg bitstream overview</h1>
cannam@86 107
cannam@86 108 <p>This document serves as starting point for understanding the design
cannam@86 109 and implementation of the Ogg container format. If you're new to Ogg
cannam@86 110 or merely want a high-level technical overview, start reading here.
cannam@86 111 Other documents linked from the <a href="index.html">index page</a>
cannam@86 112 give distilled technical descriptions and references of the container
cannam@86 113 mechanisms. This document is intended to aid understanding.
cannam@86 114
cannam@86 115 <h2>Container format design points</h2>
cannam@86 116
cannam@86 117 <p>Ogg is intended to be a simplest-possible container, concerned only
cannam@86 118 with framing, ordering, and interleave. It can be used as a stream delivery
cannam@86 119 mechanism, for media file storage, or as a building block toward
cannam@86 120 implementing a more complex, non-linear container (for example, see
cannam@86 121 the <a href="skeleton.html">Skeleton</a> or <a
cannam@86 122 href="http://en.wikipedia.org/wiki/Annodex">Annodex/CMML</a>).
cannam@86 123
cannam@86 124 <p>The Ogg container is not intended to be a monolithic
cannam@86 125 'kitchen-sink'. It exists only to frame and deliver in-order stream
cannam@86 126 data and as such is vastly simpler than most other containers.
cannam@86 127 Elementary and multiplexed streams are both constructed entirely from a
cannam@86 128 single building block (an Ogg page) comprised of eight fields
cannam@86 129 totalling twenty-eight bytes (the page header) a list of packet lengths
cannam@86 130 (up to 255 bytes) and payload data (up to 65025 bytes). The structure
cannam@86 131 of every page is the same. There are no optional fields or alternate
cannam@86 132 encodings.
cannam@86 133
cannam@86 134 <p>Stream and media metadata is contained in Ogg and not built into
cannam@86 135 the Ogg container itself. Metadata is thus compartmentalized and
cannam@86 136 layered rather than part of a monolithic design, an especially good
cannam@86 137 idea as no two groups seem able to agree on what a complete or
cannam@86 138 complete-enough metadata set should be. In this way, the container and
cannam@86 139 container implementation are isolated from unnecessary metadata design
cannam@86 140 flux.
cannam@86 141
cannam@86 142 <h3>Streaming</h3>
cannam@86 143
cannam@86 144 <p>The Ogg container is primarily a streaming format,
cannam@86 145 encapsulating chronological, time-linear mixed media into a single
cannam@86 146 delivery stream or file. The design is such that an application can
cannam@86 147 always encode and/or decode all features of a bitstream in one pass
cannam@86 148 with no seeking and minimal buffering. Seeking to provide optimized
cannam@86 149 encoding (such as two-pass encoding) or interactive decoding (such as
cannam@86 150 scrubbing or instant replay) is not disallowed or discouraged, however
cannam@86 151 no container feature requires nonlinear access of the bitstream.
cannam@86 152
cannam@86 153 <h3>Variable Bit Rate, Variable Payload Size</h3>
cannam@86 154
cannam@86 155 <p>Ogg is designed to contain any size data payload with bounded,
cannam@86 156 predictable efficiency. Ogg packets have no maximum size and a
cannam@86 157 zero-byte minimum size. There is no restriction on size changes from
cannam@86 158 packet to packet. Variable size packets do not require the use of any
cannam@86 159 optional or additional container features. There is no optimal
cannam@86 160 suggested packet size, though special consideration was paid to make
cannam@86 161 sure 50-200 byte packets were no less efficient than larger packet
cannam@86 162 sizes. The original design criteria was a 2% overhead at 50 byte
cannam@86 163 packets, dropping to a maximum working overhead of 1% with larger
cannam@86 164 packets, and a typical working overhead of .5-.7% for most practical
cannam@86 165 uses.
cannam@86 166
cannam@86 167 <h3>Simple pagination</h3>
cannam@86 168
cannam@86 169 <p>Ogg is a byte-aligned container with no context-dependent, optional
cannam@86 170 or variable-length fields. Ogg requires no repacking of codec data.
cannam@86 171 The page structure is written out in-line as packet data is submitted
cannam@86 172 to the streaming abstraction. In addition, it is possible to
cannam@86 173 implement both Ogg mux and demux as MT-hot zero-copy abstractions (as
cannam@86 174 is done in the Tremor sourcebase).
cannam@86 175
cannam@86 176 <h3>Capture</h3>
cannam@86 177
cannam@86 178 <p>Ogg is designed for efficient and immediate stream capture with
cannam@86 179 high confidence. Although packets have no size limit in Ogg, pages
cannam@86 180 are a maximum of just under 64kB meaning that any Ogg stream can be
cannam@86 181 captured with confidence after seeing 128kB of data or less [worst
cannam@86 182 case; typical figure is 6kB] from any random starting point in the
cannam@86 183 stream.
cannam@86 184
cannam@86 185 <h3>Seeking</h3>
cannam@86 186
cannam@86 187 <p>Ogg implements simple coarse- and fine-grained seeking by design.
cannam@86 188
cannam@86 189 <p>Coarse seeking may be performed by simply 'moving the tone arm' to a
cannam@86 190 new position and 'dropping the needle'. Rapid capture with
cannam@86 191 accompanying timecode from any location in an Ogg file is guaranteed
cannam@86 192 by the stream design. From the acquisition of the first timecode,
cannam@86 193 all data needed to play back from that time code forward is ahead of
cannam@86 194 the stream cursor.
cannam@86 195
cannam@86 196 <p>Ogg implements full sample-granularity seeking using an
cannam@86 197 interpolated bisection search built on the capture and timecode
cannam@86 198 mechanisms used by coarse seeking. As above, once a search finds
cannam@86 199 the desired timecode, all data needed to play back from that time code
cannam@86 200 forward is ahead of the stream cursor.
cannam@86 201
cannam@86 202 <p>Both coarse and fine seeking use the page structure and sequencing
cannam@86 203 inherent to the Ogg format. All Ogg streams are fully seekable from
cannam@86 204 creation; seekability is unaffected by truncation or missing data, and
cannam@86 205 is tolerant of gross corruption. Seek operations are neither 'fuzzy' nor
cannam@86 206 heuristic.
cannam@86 207
cannam@86 208 <p>Seeking without use of an index is a major point of the Ogg
cannam@86 209 design. There two primary reasons why Ogg transport forgoes an index:
cannam@86 210
cannam@86 211 <ol>
cannam@86 212
cannam@86 213 <li>An index is only marginally useful in Ogg for the complexity
cannam@86 214 added; it adds no new functionality and seldom improves performance
cannam@86 215 noticeably. Empirical testing shows that indexless interpolation
cannam@86 216 search does not require many more seeks in practice than using an
cannam@86 217 index would.
cannam@86 218
cannam@86 219 <li>'Optional' indexes encourage lazy implementations that can seek
cannam@86 220 only when indexes are present, or that implement indexless seeking
cannam@86 221 only by building an internal index after reading the entire file
cannam@86 222 beginning to end. This has been the fate of other containers that
cannam@86 223 specify optional indexing.
cannam@86 224
cannam@86 225 </ol>
cannam@86 226
cannam@86 227 <p>In addition, it must be possible to create an Ogg stream in a
cannam@86 228 single pass. Although an optional index can simply be tacked on the
cannam@86 229 end of the created stream, some software groups object to
cannam@86 230 end-positioned indexes and claim to be unwilling to support indexes
cannam@86 231 not located at the stream beginning.
cannam@86 232
cannam@86 233 <p><i>All this said, it's become clear that an optional index is a
cannam@86 234 demanded feature. For this reason, the <a
cannam@86 235 href="http://wiki.xiph.org/Ogg_Index">OggSkeleton now defines a
cannam@86 236 proposed index.</a></i>
cannam@86 237
cannam@86 238 <h3>Simple multiplexing</h3>
cannam@86 239
cannam@86 240 <p>Ogg multiplexes streams by interleaving pages from multiple elementary streams into a
cannam@86 241 multiplexed stream in time order. The multiplexed pages are not
cannam@86 242 altered. Muxing an Ogg AV stream out of separate audio,
cannam@86 243 video and data streams is akin to shuffling several decks of cards
cannam@86 244 together into a single deck; the cards themselves remain unchanged.
cannam@86 245 Demultiplexing is similarly simple (as the cards are marked).
cannam@86 246
cannam@86 247 <p>The goal of this design is to make the mux/demux operation as
cannam@86 248 trivial as possible to allow live streaming systems to build and
cannam@86 249 rebuild streams on the fly with minimal CPU usage and no additional
cannam@86 250 storage or latency requirements.
cannam@86 251
cannam@86 252 <h3>Continuous and Discontinuous Media</h3>
cannam@86 253
cannam@86 254 <p>Ogg streams belong to one of two categories, "Continuous" streams and
cannam@86 255 "Discontinuous" streams.
cannam@86 256
cannam@86 257 <p>A stream that provides a gapless, time-continuous media type with a
cannam@86 258 fine-grained timebase is considered to be 'Continuous'. A continuous
cannam@86 259 stream should never be starved of data. Examples of continuous data
cannam@86 260 types include broadcast audio and video.
cannam@86 261
cannam@86 262 <p>A stream that delivers data in a potentially irregular pattern or
cannam@86 263 with widely spaced timing gaps is considered to be 'Discontinuous'. A
cannam@86 264 discontinuous stream may be best thought of as data representing
cannam@86 265 scattered events; although they happen in order, they are typically
cannam@86 266 unconnected data often located far apart. One example of a
cannam@86 267 discontinuous stream types would be captioning such as <a
cannam@86 268 href="http://wiki.xiph.org/OggKate">Ogg Kate</a>. Although it's
cannam@86 269 possible to design captions as a continuous stream type, it's most
cannam@86 270 natural to think of captions as widely spaced pieces of text with
cannam@86 271 little happening between.
cannam@86 272
cannam@86 273 <p>The fundamental reason for distinction between continuous and
cannam@86 274 discontinuous streams concerns buffering.
cannam@86 275
cannam@86 276 <h3>Buffering</h3>
cannam@86 277
cannam@86 278 <p>A continuous stream is, by definition, gapless. Ogg buffering is based
cannam@86 279 on the simple premise of never allowing an active continuous stream
cannam@86 280 to starve for data during decode; buffering works ahead until all
cannam@86 281 continuous streams in a physical stream have data ready and no further.
cannam@86 282
cannam@86 283 <p>Discontinuous stream data is not assumed to be predictable. The
cannam@86 284 buffering design takes discontinuous data 'as it comes' rather than
cannam@86 285 working ahead to look for future discontinuous data for a potentially
cannam@86 286 unbounded period. Thus, the buffering process makes no attempt to fill
cannam@86 287 discontinuous stream buffers; their pages simply 'fall out' of the
cannam@86 288 stream when continuous streams are handled properly.
cannam@86 289
cannam@86 290 <p>Buffering requirements in this design need not be explicitly
cannam@86 291 declared or managed in the encoded stream. The decoder simply reads as
cannam@86 292 much data as is necessary to keep all continuous stream types gapless
cannam@86 293 and no more, with discontinuous data processed as it arrives in the
cannam@86 294 continuous data. Buffering is implicitly optimal for the given
cannam@86 295 stream. Because all pages of all data types are stamped with absolute
cannam@86 296 timing information within the stream, inter-stream synchronization
cannam@86 297 timing is always maintained without the need for explicitly declared
cannam@86 298 buffer-ahead hinting.
cannam@86 299
cannam@86 300 <h3>Codec metadata</h3>
cannam@86 301
cannam@86 302 <p>Ogg does not replicate codec-specific metadata into the mux layer
cannam@86 303 in an attempt to make the mux and codec layer implementations 'fully
cannam@86 304 separable'. Things like specific timebase, keyframing strategy, frame
cannam@86 305 duration, etc, do not appear in the Ogg container. The mux layer is,
cannam@86 306 instead, expected to query a codec through a centralized interface,
cannam@86 307 left to the implementation, for this data when it is needed.
cannam@86 308
cannam@86 309 <p>Though modern design wisdom usually prefers to predict all possible
cannam@86 310 needs of current and future codecs then embed these dependencies and
cannam@86 311 the required metadata into the container itself, this strategy
cannam@86 312 increases container specification complexity, fragility, and rigidity.
cannam@86 313 The mux and codec code becomes more independent, but the
cannam@86 314 specifications become logically less independent. A codec can't do
cannam@86 315 what a container hasn't already provided for. Novel codecs are harder
cannam@86 316 to support, and you can do fewer useful things with the ones you've
cannam@86 317 already got (eg, try to make a good splitter without using any codecs.
cannam@86 318 Such a splitter is limited to splitting at keyframes only, or building
cannam@86 319 yet another new mechanism into the container layer to mark what frames
cannam@86 320 to skip displaying).
cannam@86 321
cannam@86 322 <p>Ogg's design goes the opposite direction, where the specification
cannam@86 323 is to be as simple, easy to understand, and 'proofed' against novel
cannam@86 324 codecs as possible. When an Ogg mux layer requires codec-specific
cannam@86 325 information, it queries the codec (or a codec stub). This trades a
cannam@86 326 more complex implementation for a simpler, more flexible
cannam@86 327 specification.
cannam@86 328
cannam@86 329 <h3>Stream structure metadata</h3>
cannam@86 330
cannam@86 331 <p>The Ogg container itself does not define a metadata system for
cannam@86 332 declaring the structure and interrelations between multiple media
cannam@86 333 types in a muxed stream. That is, the Ogg container itself does not
cannam@86 334 specify data like 'which steam is the subtitle stream?' or 'which
cannam@86 335 video stream is the primary angle?'. This metadata still exists, but
cannam@86 336 is stored by the Ogg container rather than being built into the Ogg
cannam@86 337 container itself. Xiph specifies the 'Skeleton' metadata format for Ogg
cannam@86 338 streams, but this decoupling of container and stream structure
cannam@86 339 metadata means it is possible to use Ogg with any metadata
cannam@86 340 specification without altering the container itself, or without stream
cannam@86 341 structure metadata at all.
cannam@86 342
cannam@86 343 <h3>Frame accurate absolute position</h3>
cannam@86 344
cannam@86 345 <p>Every Ogg page is stamped with a 64 bit 'granule position' that
cannam@86 346 serves as an absolute timestamp for mux and seeking. A few nifty
cannam@86 347 little tricks are usually also embedded in the granpos state, but
cannam@86 348 we'll leave those aside for the moment (strictly speaking, they're
cannam@86 349 part of each codec's mapping, not Ogg).
cannam@86 350
cannam@86 351 <p>As previously mentioned above, granule positions are mapped into
cannam@86 352 absolute timestamps by the codec, rather than being a hard timestamp.
cannam@86 353 This allows maximally efficient use of the available 64 bits to
cannam@86 354 address every sample/frame position without approximation while
cannam@86 355 supporting new and previously unknown timebase encodings without
cannam@86 356 needing to extend or update the mux layer. When a codec needs a novel
cannam@86 357 timebase, it simply brings the code for that mapping along with it.
cannam@86 358 This is not a theoretical curiosity; new, wholly novel timebases were
cannam@86 359 deployed with the adoption of both Theora and Dirac. "Rolling INTRA"
cannam@86 360 (keyframeless video) also benefits from novel use of the granule
cannam@86 361 position.
cannam@86 362
cannam@86 363 <h2>Ogg stream arrangement</h2>
cannam@86 364
cannam@86 365 <h3>Packets, pages, and bitstreams</h3>
cannam@86 366
cannam@86 367 <p>Ogg codecs place raw compressed data into <em>packets</em>.
cannam@86 368 Packets are octet payloads containing the data needed for a single
cannam@86 369 decompressed unit, eg, one video frame. Packets have no maximum size
cannam@86 370 and may be zero length. They do not generally have any framing
cannam@86 371 information; strung together, the unframed packets form a <em>logical
cannam@86 372 bitstream</em> of codec data with no internal landmarks.
cannam@86 373
cannam@86 374 <div class="caption">
cannam@86 375 <img src="packets.png">
cannam@86 376
cannam@86 377 <p> Packets of raw codec data are not typically internally framed.
cannam@86 378 When they are strung together into a stream without any container to
cannam@86 379 provide framing, they lose their individual boundaries. Seek and
cannam@86 380 capture are not possible within an unframed stream, and for many
cannam@86 381 codecs with variable length payloads and/or early-packet termination
cannam@86 382 (such as Vorbis), it may become impossible to recover the original
cannam@86 383 frame boundaries even if the stream is scanned linearly from
cannam@86 384 beginning to end.
cannam@86 385
cannam@86 386 </div>
cannam@86 387
cannam@86 388 <p>Logical bitstream packets are grouped and framed into Ogg pages
cannam@86 389 along with a unique stream <em>serial number</em> to produce a
cannam@86 390 <em>physical bitstream</em>. An <em>elementary stream</em> is a
cannam@86 391 physical bitstream containing only a single logical bitstream. Each
cannam@86 392 page is a self contained entity, although a packet may be split and
cannam@86 393 encoded across one or more pages. The page decode mechanism is
cannam@86 394 designed to recognize, verify and handle single pages at a time from
cannam@86 395 the overall bitstream.
cannam@86 396
cannam@86 397 <div class="caption">
cannam@86 398 <img src="pages.png">
cannam@86 399
cannam@86 400 <p> The primary purpose of a container is to provide framing for raw
cannam@86 401 packets, marking the packet boundaries so the exact packets can be
cannam@86 402 retrieved for decode later. The container also provides secondary
cannam@86 403 functions such as capture, timestamping, sequencing, stream
cannam@86 404 identification and so on. Not all of these functions are represented in the diagram.
cannam@86 405
cannam@86 406 <p>In the Ogg container, pages do not necessarily contain
cannam@86 407 integer numbers of packets. Packets may span across page boundaries
cannam@86 408 or even multiple pages. This is necessary as pages have a maximum
cannam@86 409 possible size in order to provide capture guarantees, but packet
cannam@86 410 size is unbounded.
cannam@86 411 </div>
cannam@86 412
cannam@86 413
cannam@86 414 <p><a href="framing.html">Ogg Bitstream Framing</a> specifies
cannam@86 415 the page format of an Ogg bitstream, the packet coding process
cannam@86 416 and elementary bitstreams in detail.
cannam@86 417
cannam@86 418 <h3>Multiplexed bitstreams</h3>
cannam@86 419
cannam@86 420 <p>Multiple logical/elementary bitstreams can be combined into a single
cannam@86 421 <em>multiplexed bitstream</em> by interleaving whole pages from each
cannam@86 422 contributing elementary stream in time order. The result is a single
cannam@86 423 physical stream that multiplexes and frames multiple logical streams.
cannam@86 424 Each logical stream is identified by the unique stream serial number
cannam@86 425 stamped in its pages. A physical stream may include a 'meta-header'
cannam@86 426 (such as the <a href="skeleton.html">Ogg Skeleton</a>) comprising its
cannam@86 427 own Ogg page at the beginning of the physical stream. A decoder
cannam@86 428 recovers the original logical/elementary bitstreams out of the
cannam@86 429 physical bitstream by taking the pages in order from the physical
cannam@86 430 bitstream and redirecting them into the appropriate logical decoding
cannam@86 431 entity.
cannam@86 432
cannam@86 433 <div class="caption">
cannam@86 434 <img src="multiplex1.png">
cannam@86 435
cannam@86 436 <p>Multiple media types are mutliplexed into a single Ogg stream by
cannam@86 437 interleaving the pages from each elementary physical stream.
cannam@86 438
cannam@86 439 </div>
cannam@86 440
cannam@86 441 <p><a href="ogg-multiplex.html">Ogg Bitstream Multiplexing</a> specifies
cannam@86 442 proper multiplexing of an Ogg bitstream in detail.
cannam@86 443
cannam@86 444 <h3>Chaining</h3>
cannam@86 445
cannam@86 446 <p>Multiple Ogg physical bitstreams may be concatenated into a single new
cannam@86 447 stream; this is <em>chaining</em>. The bitstreams do not overlap; the
cannam@86 448 final page of a given logical bitstream is immediately followed by the
cannam@86 449 initial page of the next.</p>
cannam@86 450
cannam@86 451 <p>Each logical bitstream in a chain must have a unique serial number
cannam@86 452 within the scope of the full physical bitstream, not only within a
cannam@86 453 particular <em>link</em> or <em>segment</em> of the chain.</p>
cannam@86 454
cannam@86 455 <h3>Continuous and discontinuous streams</h3>
cannam@86 456
cannam@86 457 <p>Within Ogg, each stream must be declared (by the codec) to be
cannam@86 458 continuous- or discontinuous-time. Most codecs treat all streams they
cannam@86 459 use as either inherently continuous- or discontinuous-time, although
cannam@86 460 this is not a requirement. A codec may, as part of its mapping, choose
cannam@86 461 according to data in the initial header.
cannam@86 462
cannam@86 463 <p>Continuous-time pages are stamped by end-time, discontinuous pages
cannam@86 464 are stamped by begin-time. Pages in a multiplexed stream are
cannam@86 465 interleaved in order of the time stamp regardless of stream type.
cannam@86 466 Both continuous and discontinuous logical streams are used to seek
cannam@86 467 within a physical stream, however only continuous streams are used to
cannam@86 468 determine buffering depth; because discontinuous streams are stamped
cannam@86 469 by start time, they will always 'fall out' at the proper time when
cannam@86 470 buffering the continuous streams. See 'Examples' for an illustration
cannam@86 471 of the buffering mechanism.
cannam@86 472
cannam@86 473 <h2>Multiplexing Requirements</h2>
cannam@86 474
cannam@86 475 <p>Multiplexing requirements within Ogg are straightforward. When
cannam@86 476 constructing a single-link (unchained) physical bitstream consisting
cannam@86 477 of multiple elementary streams:
cannam@86 478
cannam@86 479 <ol>
cannam@86 480
cannam@86 481 <li><p> The initial header for each stream appears in sequence, each
cannam@86 482 header on a single page. All initial headers must appear with no
cannam@86 483 intervening data (no auxiliary header pages or packets, no data pages
cannam@86 484 or packets). Order of the initial headers is unspecified. The
cannam@86 485 'beginning of stream' flag is set on each initial header.
cannam@86 486
cannam@86 487 <li><p> All auxiliary headers for all streams must follow. Order
cannam@86 488 is unspecified. The final auxiliary header of each stream must flush
cannam@86 489 its page.
cannam@86 490
cannam@86 491 <li><p>Data pages for each stream follow, interleaved in time order.
cannam@86 492
cannam@86 493 <li><p>The final page of each stream sets the 'end of stream' flag.
cannam@86 494 Unlike initial pages, terminal pages for the logical bitstreams need
cannam@86 495 not occur contiguously; indeed it may not be possible for them to do so.
cannam@86 496 </oL>
cannam@86 497
cannam@86 498 <p><p>Each grouped bitstream must have a unique serial number within the
cannam@86 499 scope of the physical bitstream.</p>
cannam@86 500
cannam@86 501 <h3>chaining and multiplexing</h3>
cannam@86 502
cannam@86 503 <p>Multiplexed and/or unmultiplexed bitstreams may be chained
cannam@86 504 consecutively. Such a physical bitstream obeys all the rules of both
cannam@86 505 chained and multiplexed streams. Each link, when unchained, must
cannam@86 506 stand on its own as a valid physical bitstream. Chained streams do
cannam@86 507 not mix or interleave; a new segment may not begin until all streams
cannam@86 508 in the preceding segment have terminated. </p>
cannam@86 509
cannam@86 510 <h2>Codec Mapping Requirements</h2>
cannam@86 511
cannam@86 512 <p>Each codec is allowed some freedom in deciding how its logical
cannam@86 513 bitstream is encapsulated into an Ogg bitstream (even if it is a
cannam@86 514 trivial mapping, eg, 'plop the packets in and go'). This is the
cannam@86 515 codec's <em>mapping</em>. Ogg imposes a few mapping requirements
cannam@86 516 on any codec.
cannam@86 517
cannam@86 518 <ol>
cannam@86 519
cannam@86 520 <li><p>The <a href="framing.html">framing specification</a> defines
cannam@86 521 'beginning of stream' and 'end of stream' page markers via a header
cannam@86 522 flag (it is possible for a stream to consist of a single page). A
cannam@86 523 correct stream always consists of an integer number of pages, an easy
cannam@86 524 requirement given the variable size nature of pages.</p>
cannam@86 525
cannam@86 526 <li><p>The first page of an elementary Ogg bitstream consists of a single,
cannam@86 527 small 'initial header' packet that must include sufficient information
cannam@86 528 to identify the exact CODEC type. From this initial header, the codec
cannam@86 529 must also be able to determine its timebase and whether or not it is a
cannam@86 530 continuous- or discontinuous-time stream. The initial header must fit
cannam@86 531 on a single page. If a codec makes use of auxiliary headers (for
cannam@86 532 example, Vorbis uses two auxiliary headers), these headers must follow
cannam@86 533 the initial header immediately. The last header finishes its page;
cannam@86 534 data begins on a fresh page.
cannam@86 535
cannam@86 536 <p><p>As an example, Ogg Vorbis places the name and revision of the
cannam@86 537 Vorbis CODEC, the audio rate and the audio quality into this initial
cannam@86 538 header. Vorbis comments and detailed codec setup appears in the larger
cannam@86 539 auxiliary headers.</p>
cannam@86 540
cannam@86 541 <li><p>Granule positions must be translatable to an exact absolute
cannam@86 542 time value. As described above, the mux layer is permitted to query a
cannam@86 543 codec or codec stub plugin to perform this mapping. It is not
cannam@86 544 necessary for an absolute time to be mappable into a single unique
cannam@86 545 granule position value.
cannam@86 546
cannam@86 547 <li><p>Codecs are not required to use a fixed duration-per-packet (for
cannam@86 548 example, Vorbis does not). the mux layer is permitted to query a
cannam@86 549 codec or codec stub plugin for the time duration of a packet.
cannam@86 550
cannam@86 551 <li><p>Although an absolute time need not be translatable to a unique
cannam@86 552 granule position, a codec must be able to determine the unique granule
cannam@86 553 position of the current packet using the granule position of a
cannam@86 554 preceeding packet.
cannam@86 555
cannam@86 556 <li><p>Packets and pages must be arranged in ascending
cannam@86 557 granule-position and time order.
cannam@86 558
cannam@86 559 </ol>
cannam@86 560
cannam@86 561 <h2>Examples</h2>
cannam@86 562
cannam@86 563 <em>[More to come shortly; this section is currently being revised and expanded]</em>
cannam@86 564
cannam@86 565 <p>Below, we present an example of a multiplexed and chained bitstream:</p>
cannam@86 566
cannam@86 567 <p><img src="stream.png" alt="stream"/></p>
cannam@86 568
cannam@86 569 <p>In this example, we see pages from five total logical bitstreams
cannam@86 570 multiplexed into a physical bitstream. Note the following
cannam@86 571 characteristics:</p>
cannam@86 572
cannam@86 573 <ol>
cannam@86 574 <li>Multiplexed bitstreams in a given link begin together; all of the
cannam@86 575 initial pages must appear before any data pages. When concurrently
cannam@86 576 multiplexed groups are chained, the new group does not begin until all
cannam@86 577 the bitstreams in the previous group have terminated.</li>
cannam@86 578
cannam@86 579 <li>The ordering of pages of concurrently multiplexed bitstreams is
cannam@86 580 goverened by timestamp (not shown here); there is no regular
cannam@86 581 interleaving order. Pages within a logical bitstream appear in
cannam@86 582 sequence order.</li>
cannam@86 583 </ol>
cannam@86 584
cannam@86 585 <div id="copyright">
cannam@86 586 The Xiph Fish Logo is a
cannam@86 587 trademark (&trade;) of Xiph.Org.<br/>
cannam@86 588
cannam@86 589 These pages &copy; 1994 - 2010 Xiph.Org. All rights reserved.
cannam@86 590 </div>
cannam@86 591
cannam@86 592 </div>
cannam@86 593 </body>
cannam@86 594 </html>