libogg 1.1.3

libogg is the bitstream and framing library for the Ogg project. libogg provides functions which are necessary to codec libraries like libvorbis.

Ogg codecs use octet vectors of raw, compressed data (packets). These compressed packets do not have any high-level structure or boundary information; strung together, they appear to be streams of random bytes with no landmarks.

Raw packets may be used directly by transport mechanisms that provide their own framing and packet-separation mechanisms (such as UDP datagrams).

For stream based storage (such as files) and transport (such as TCP streams or pipes), Vorbis and other future Ogg codecs use the Ogg bitstream format to provide framing/sync, sync recapture after error, landmarks during seeking, and enough information to properly separate data back into packets at the original packet boundaries without relying on decoding to find packet boundaries.

Raw packets are grouped and encoded into contiguous pages of structured bitstream data called logical bitstreams. A logical bitstream consists of pages, in order, belonging to a single codec instance.

Each page is a self contained entity (although it is possible that a packet may be split and encoded across one or more pages); that is, the page decode mechanism is designed to recognize, verify and handle single pages at a time from the overall bitstream.

Multiple logical bitstreams can be combined (with restrictions) into a single physical bitstream. A physical bitstream consists of multiple logical bitstreams multiplexed at the page level and may include a meta-header at the beginning of the multiplexed logical stream that serves as identification magic.

Whole pages are taken in order from multiple logical bitstreams and combined into a single physical stream of pages. The decoder reconstructs the original logical bitstreams from the physical bitstream by taking the pages in order from the physical bitstream and redirecting them into the appropriate logical decoding entity. The simplest physical bitstream is a single, unmultiplexed logical bitstream with no meta-header; this is referred to as a degenerate stream.

Ogg Logical Bitstream Framing discusses the page format of an Ogg bitstream, the packet coding process and logical bitstreams in detail. The remainder of this document specifies requirements for constructing finished, physical Ogg bitstreams.