OGG

Ogg bitstreams and pages

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.

continued

The first packet is continued from the previous page.

classmethod find_last(klass, 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.

first

This is the first page of a logical bitstream.

classmethod from_packets(klass, 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.

last

This is the last page of a logical bitstream.

classmethod renumber(klass, 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).

classmethod replace(klass, 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.

size

Total frame size.

classmethod to_packets(klass, 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.

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.

Ogg Vorbis

Read and write Ogg Vorbis comments.

This module handles Vorbis files wrapped in an Ogg bitstream. The first Vorbis stream found is used.

Read more about Ogg Vorbis at http://vorbis.com/. This module is based on the specification at http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html.

exception mutagen.oggvorbis.error

Bases: mutagen.ogg.error

exception mutagen.oggvorbis.OggVorbisHeaderError

Bases: mutagen.oggvorbis.error

class mutagen.oggvorbis.OggVorbis(filename)

Bases: mutagen.ogg.OggFileType

An Ogg Vorbis file.

class mutagen.oggvorbis.OggVorbisInfo(fileobj)

Ogg Vorbis stream information.

Attributes:

  • length - file length in seconds, as a float
  • bitrate - nominal (‘average’) bitrate in bits per second, as an int

Ogg Opus

Read and write Ogg Opus comments.

This module handles Opus files wrapped in an Ogg bitstream. The first Opus stream found is used.

Based on http://tools.ietf.org/html/draft-terriberry-oggopus-01

exception mutagen.oggopus.error

Bases: mutagen.ogg.error

exception mutagen.oggopus.OggOpusHeaderError

Bases: mutagen.oggopus.error

class mutagen.oggopus.OggOpus(filename)

Bases: mutagen.ogg.OggFileType

An Ogg Opus file.

class mutagen.oggopus.OggOpusInfo(fileobj)

Ogg Opus stream information.

Attributes:

  • length - file length in seconds, as a float
  • channels - number of channels

Ogg Speex

Read and write Ogg Speex comments.

This module handles Speex files wrapped in an Ogg bitstream. The first Speex stream found is used.

Read more about Ogg Speex at http://www.speex.org/. This module is based on the specification at http://www.speex.org/manual2/node7.html and clarifications after personal communication with Jean-Marc, http://lists.xiph.org/pipermail/speex-dev/2006-July/004676.html.

exception mutagen.oggspeex.error

Bases: mutagen.ogg.error

exception mutagen.oggspeex.OggSpeexHeaderError

Bases: mutagen.oggspeex.error

class mutagen.oggspeex.OggSpeex(filename)

Bases: mutagen.ogg.OggFileType

An Ogg Speex file.

class mutagen.oggspeex.OggSpeexInfo(fileobj)

Ogg Speex stream information.

Attributes:

  • bitrate - nominal bitrate in bits per second
  • channels - number of channels
  • length - file length in seconds, as a float

The reference encoder does not set the bitrate; in this case, the bitrate will be 0.

Ogg Theora

Read and write Ogg Theora comments.

This module handles Theora files wrapped in an Ogg bitstream. The first Theora stream found is used.

Based on the specification at http://theora.org/doc/Theora_I_spec.pdf.

exception mutagen.oggtheora.error

Bases: mutagen.ogg.error

exception mutagen.oggtheora.OggTheoraHeaderError

Bases: mutagen.oggtheora.error

class mutagen.oggtheora.OggTheora(filename)

Bases: mutagen.ogg.OggFileType

An Ogg Theora file.

class mutagen.oggtheora.OggTheoraInfo(fileobj)

Ogg Theora stream information.

Attributes:

  • length - file length in seconds, as a float
  • fps - video frames per second, as a float

Ogg FLAC

Read and write Ogg FLAC comments.

This module handles FLAC files wrapped in an Ogg bitstream. The first FLAC stream found is used. For ‘naked’ FLACs, see mutagen.flac.

This module is based off the specification at http://flac.sourceforge.net/ogg_mapping.html.

exception mutagen.oggflac.error

Bases: mutagen.ogg.error

exception mutagen.oggflac.OggFLACHeaderError

Bases: mutagen.oggflac.error

class mutagen.oggflac.OggFLAC(filename)

Bases: mutagen.ogg.OggFileType

An Ogg FLAC file.

class mutagen.oggflac.OggFLACStreamInfo(data)

Ogg FLAC general header and stream info.

This encompasses the Ogg wrapper for the FLAC STREAMINFO metadata block, as well as the Ogg codec setup that precedes it.

Attributes (in addition to StreamInfo’s):

  • packets – number of metadata packets
  • serial – Ogg logical stream serial number

Table Of Contents

Previous topic

FLAC

Next topic

APEv2

This Page