OGG

Read and write Ogg bitstreams and pages.

This module reads and writes a subset of the Ogg bitstream format version 0. It does not read or write Ogg Vorbis files! For that, you should use mutagen.oggvorbis.

This implementation is based on the RFC 3533 standard found at http://www.xiph.org/ogg/doc/rfc3533.txt.

exception mutagen.ogg.error

Ogg stream parsing errors.

class mutagen.ogg.OggFileType(filename)

Bases: mutagen.FileType

An generic Ogg file.

class mutagen.ogg.OggPage(fileobj=None)

A single Ogg page (not necessarily a single encoded packet).

A page is a header of 26 bytes, followed by the length of the data, followed by the data.

The constructor is givin a file-like object pointing to the start of an Ogg page. After the constructor is finished it is pointing to the start of the next page.

Attributes:

  • version – stream structure version (currently always 0)
  • position – absolute stream position (default -1)
  • serial – logical stream serial number (default 0)
  • sequence – page sequence number within logical stream (default 0)
  • offset – offset this page was read from (default None)
  • complete – if the last packet on this page is complete (default True)
  • packets – list of raw packet data (default [])

Note that if ‘complete’ is false, the next page’s ‘continued’ property must be true (so set both when constructing pages).

If a file-like object is supplied to the constructor, the above attributes will be filled in based on it.

write()

Return a string encoding of the page header and data.

A ValueError is raised if the data is too big to fit in a single page.

size

Total frame size.

continued

The first packet is continued from the previous page.

first

This is the first page of a logical bitstream.

last

This is the last page of a logical bitstream.

static renumber(fileobj, serial, start)

Renumber pages belonging to a specified logical stream.

fileobj must be opened with mode r+b or w+b.

Starting at page number ‘start’, renumber all pages belonging to logical stream ‘serial’. Other pages will be ignored.

fileobj must point to the start of a valid Ogg page; any occuring after it and part of the specified logical stream will be numbered. No adjustment will be made to the data in the pages nor the granule position; only the page number, and so also the CRC.

If an error occurs (e.g. non-Ogg data is found), fileobj will be left pointing to the place in the stream the error occured, but the invalid data will be left intact (since this function does not change the total file size).

static to_packets(pages, strict=False)

Construct a list of packet data from a list of Ogg pages.

If strict is true, the first page must start a new packet, and the last page must end the last packet.

static from_packets(packets, sequence=0, default_size=4096, wiggle_room=2048)

Construct a list of Ogg pages from a list of packet data.

The algorithm will generate pages of approximately default_size in size (rounded down to the nearest multiple of 255). However, it will also allow pages to increase to approximately default_size + wiggle_room if allowing the wiggle room would finish a packet (only one packet will be finished in this way per page; if the next packet would fit into the wiggle room, it still starts on a new page).

This method reduces packet fragmentation when packet sizes are slightly larger than the default page size, while still ensuring most pages are of the average size.

Pages are numbered started at ‘sequence’; other information is uninitialized.

classmethod replace(fileobj, old_pages, new_pages)

Replace old_pages with new_pages within fileobj.

old_pages must have come from reading fileobj originally. new_pages are assumed to have the ‘same’ data as old_pages, and so the serial and sequence numbers will be copied, as will the flags for the first and last pages.

fileobj will be resized and pages renumbered as necessary. As such, it must be opened r+b or w+b.

static find_last(fileobj, serial)

Find the last page of the stream ‘serial’.

If the file is not multiplexed this function is fast. If it is, it must read the whole the stream.

This finds the last page in the actual file object, or the last page in the stream (with eos set), whichever comes first.