doc/oggstream.html

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