Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:Ogg

From ReverseEngineering.wiki
Format
Developer Xiph.Org Foundation
Uses Library:Libogg
Versions stream structure version 0 (RFC 3533, 2003)
Magic 4F 67 67 53 00 ("OggS", version 0) at the start of every page
Extensions .ogg, .oga, .ogv, .ogx, .opus, .spx
Endianness little
Website https://xiph.org/ogg/
On this wiki Facts · Code · Notes · Topics

Xiph.Org's multimedia container (RFC 3533; .ogg, .oga, .ogv, .opus, .spx): a sequence of pages, each a 27-byte little-endian header ("OggS", version 0, flags, 64-bit granule position, serial number, page number, CRC-32 with polynomial 0x04C11DB7 and initial value 0) plus a segment table whose lacing values cut the body into packets of one logical stream. The first packet of each stream identifies the codec (Vorbis, Opus, FLAC, Theora, Speex).

Overview

Ogg is the Xiph.Org Foundation's container (RFC 3533, stream structure version 0). A physical Ogg file or stream is a sequence of pages; each page belongs to one logical bitstream (identified by a 32-bit serial number) and carries pieces of that stream's packets. The container knows nothing about codecs: the first packet of each logical stream identifies the codec (#Codec identification), and the codec mapping defines what the 64-bit granule position on each page means. Files are usually .ogg (Vorbis audio, historically any content), .oga (audio), .ogv (video, usually Theora), .ogx (application/ogg), .opus (Ogg Opus) and .spx (Speex); RFC 5334 defines the media types audio/ogg, video/ogg and application/ogg. The reference implementation is Library:Libogg.

Page header

All multi-byte fields are little endian. A page is 27 fixed bytes, a segment table of page_segments bytes, then the body (the sum of the segment table).

Offset Size Field Notes
0x00 4 capture_pattern "OggS" (4F 67 67 53)
0x04 1 stream_structure_version always 0; libogg rejects pages with another value in ogg_stream_pagein
0x05 1 header_type bit 0 (0x01) continued packet, bit 1 (0x02) first page of the logical stream (BOS), bit 2 (0x04) last page (EOS)
0x06 8 granule_position codec-defined position after the last packet that ends on this page; -1 (FF x 8) when no packet ends here
0x0E 4 bitstream_serial_number identifies the logical stream; chosen at random by encoders
0x12 4 page_sequence_number per logical stream, from 0; a gap means a lost page
0x16 4 CRC_checksum see #CRC
0x1A 1 page_segments number of lacing values (0-255)
0x1B n segment_table lacing values

Maximum page: 27 + 255 + 255 x 255 = 65,307 bytes. libogg's encoder aims at about 4 KiB pages; FFmpeg's muxer, in the files checked here, at about one second of audio per page.

Lacing and packets

A packet of n bytes is coded as floor(n/255) lacing values of 255 followed by one value n mod 255 (so a packet whose length is a multiple of 255, including an empty packet, ends with a 0). A lacing value below 255 ends a packet. If the last lacing value of a page is 255 the packet continues on the next page of the same logical stream, and that page has header_type bit 0 set. A packet can span any number of pages; a page whose segments all are 255 has granule position -1.

Example (libogg self-test): packets of 254, 255, 256, 500, 510 and 600 bytes give the segment table 254 / 255 0 / 255 1 / 255 245 / 255 255 0 / 255 255 90 (13 values).

CRC

CRC-32 with polynomial 0x04C11DB7, MSB first (not reflected), initial value 0 and no final XOR, over the whole page (header with the CRC field set to zero, segment table and body), stored little endian at offset 0x16. This is not the zlib/PNG CRC-32 (reflected 0xEDB88320) and not bzip2's or MPEG-2's (initial value 0xFFFFFFFF): its check value for "123456789" is 0x89A1897F (CRC-32/POSIX before its final inversion). A table-driven implementation uses the same 256-entry table as bzip2, MPEG-2, POSIX cksum and FFmpeg's AV_CRC_32_IEEE, so the table alone does not identify Ogg code (Library:Libogg#Identification).

libogg (ogg_sync_pageseek) drops any page whose CRC does not match and resynchronises on the next "OggS"; a hand-edited Ogg file must get its CRCs recomputed or players skip the edited pages silently.

Granule position

The granule position is codec-defined: for Format:Vorbis and FLAC it is the PCM sample count (per channel) at the end of the last packet completed on the page; for Opus it is the number of 48 kHz samples, from which the pre-skip is subtracted (#Ogg Opus); for Theora it is split into a key-frame number and an offset (granule shift from the identification header). The granule position of the last page therefore gives the stream length: a Vorbis stream at 44,100 Hz whose last page has granule 196,153 is 4.448 s long. Header pages of Vorbis and Opus have granule 0.

Multiplexing

  • Grouping (concurrent streams, e.g. Theora video + Vorbis audio, or a Skeleton track): all BOS pages come first, then the pages of all streams interleaved in time order. A demuxer reads pages until the first non-BOS page to know every stream.
  • Chaining (sequential streams, e.g. internet radio or concatenated files): a new group of BOS pages starts after all streams of the previous group have ended (EOS). Each link has its own serial numbers and headers; tools that only read the first link report the wrong duration.

Codec identification

The first packet (on the BOS page) of each logical stream starts with the codec's magic:

First packet starts with Codec Granule
01 "vorbis" Format:Vorbis identification header PCM samples
"OpusHead" Opus (RFC 7845) 48 kHz samples incl. pre-skip
7F "FLAC" FLAC (Ogg mapping 1.0: major, minor, 16-bit BE header-packet count, "fLaC", STREAMINFO) PCM samples
80 "theora" Theora video key frame << shift | offset
"Speex " (Speex and 3 spaces) Speex PCM samples
"fishead" 00 Ogg Skeleton (a metadata track; fisbone 00 packets describe the other streams) none
80 "kate" 00 00 00 Kate (subtitles/karaoke) time
80 "daala" Daala (experimental video) as Theora
"PCM " OggPCM (draft) PCM samples

Ogg Opus

RFC 7845 maps Opus into Ogg with two header packets: the identification header "OpusHead" (version 1, which is the first byte after the magic so it cannot act as a NUL terminator; channel count; pre-skip u16 in 48 kHz samples; original input sample rate u32 for information only; output gain s16 in Q7.8 dB; channel mapping family u8, 19 bytes in total for family 0, followed by a stream count, a coupled count and a mapping table for other families) alone on the BOS page, then the comment header "OpusTags" (the same vendor + comment list layout as the Vorbis comment header, without the framing bit), which must end its page. Audio data starts on a new page. PCM sample position = granule position - pre-skip; the decoder always runs at 48 kHz, whatever the input sample rate says. The codec library is Library:Libopus.

Details of the channel mapping table, mapping families, OpusTags and the R128 gain tags: Format:Ogg Opus.

Where it appears

Ogg Vorbis is the most common music and sound format of PC games (engines and middleware read it through libvorbisfile, stb_vorbis or their own code), Ogg Opus is used for voice and streaming audio, and Ogg FLAC and Ogg Theora are rarer. Inside game archives Ogg files are often stored whole: scan for "OggS" followed by a zero version byte and check the CRC to find them and their end (the EOS page). Some middleware stores Vorbis packets without Ogg framing (unverified: Wwise Vorbis and FMOD FSB5 Vorbis store raw packets and rebuild or hard-code the setup header), so a missing "OggS" does not rule Vorbis out; look for the Vorbis header packets instead.

Files written by FFmpeg's Ogg muxer replace the encoder's vendor string with libavformat's ident ("Lavf61.7.100") and add an ENCODER=Lavc... comment; 7,766 of the 7,835 Ogg Vorbis files of one commercial PC game checked here carry "Lavf61.7.100" or "Lavf60.3.100", the other 69 keep libvorbis's own vendor string (1.3.3 and 1.3.7).

Code & repositories

  • https://github.com/xiph/ogg @ 06a5e0262cdc28aa4ae6797627a783b5010440f0 · license: BSD-3-Clause
    libogg, the reference Ogg container library (src/framing.c pages and streams, src/bitwise.c bit packer, src/crctable.h CRC tables), with the format documents (doc/rfc3533.txt, doc/framing.html, doc/skeleton.html, doc/rfc5334.txt) and release tags v1.1.1-v1.3.6.
    Tested on: Read at this commit and at tags v1.1.4, v1.2.0, v1.2.2, v1.3.0, v1.3.2, v1.3.3, v1.3.4, v1.3.6 (ogg.def, crc_lookup layout, CHANGES); the self-test page vectors of src/framing.c reproduced by the Python dumper on Format:Ogg. Not built. · checked 2026-10-17; last activity 2026-03-03; Note: the latest release ships binaries; the wiki links only the source, never the binaries
  • Ogg page and packet dumper (Python) — Dependency-free Ogg reader: lists pages (flags, granule, serial, sequence), verifies every page CRC, rebuilds the packets of each logical stream across pages, identifies the codec of each stream…
  • https://github.com/xiph/opus @ 51bd2e649f4516d103ab9a7f22a768595621e847 · license: BSD-3-Clause (declared by the contributor; GitHub's detector did not recognize COPYING)
    libopus source (silk/, celt/, src/, dnn/), the public API (include/opus*.h) and the Ogg Opus encapsulation draft doc/draft-ietf-codec-oggopus.xml (draft 14 = RFC 7845: OpusHead, OpusTags, granule position and pre-skip rules).
    Tested on: Read at this commit (celt/celt.c version and error strings, include/opus.h, the Ogg Opus draft); OpusHead/OpusTags parsing tested on a generated sample with the Python dumper on Format:Ogg; version strings found in libsndfile 1.2.2 (libopus 1.4) and an FFmpeg 9.0 static build. Not built. · checked 2026-10-17; last activity 2026-10-17

Pitfalls

  • The granule position of a page refers to the last packet that ends on it, not to the first byte of the page; pages where no packet ends have -1.
  • Serial numbers are random, and two logical streams in different links of a chain may reuse one; track streams by link.
  • The CRC is checked by libogg: a page with a bad CRC is skipped silently.
  • Do not rely on the EOS flag: 3 of the 68 files encoded with libvorbis 1.3.3 in the game set checked here end on a complete page with valid CRC but no page has the EOS flag (the encoding tool did not mark the last packet). Treat the end of the file as the end of the stream and take the length from the last granule position.
  • The first audio page of a Vorbis or Opus stream may have a granule smaller than the samples it would decode: the codec mapping uses this for start trimming (Opus: pre-skip).

Evidence & references

  • RFC 3533 (doc/rfc3533.txt), doc/framing.html (CRC parameters, maximum page size), doc/skeleton.html and RFC 5334 (doc/rfc5334.txt) in https://github.com/xiph/ogg at 06a5e0262cdc28aa4ae6797627a783b5010440f0; page building and parsing in src/framing.c (ogg_page_* accessors lines 33-99, CRC lines 237-272, page construction lines 349-479, ogg_sync_pageseek lines 642-740, version and serial check in ogg_stream_pagein lines 820-821, self-test vectors from line 1138).
  • Ogg Opus: doc/draft-ietf-codec-oggopus.xml (draft 14, published as RFC 7845) in https://github.com/xiph/opus at 51bd2e649f4516d103ab9a7f22a768595621e847.
  • Tested with the Python dumper on this page: the libogg self-test page vectors (CRC bytes 15 ED EC 91, 59 10 6C 2C, 89 33 85 CE), a generated two-stream sample, and 7,835 Ogg Vorbis files of a commercial PC game (69,198 pages, all CRCs valid, one logical stream per file, 51 pages with granule -1 inside packets that span pages, 3 files whose last page lacks the EOS flag).