ogg

Documentation

Overview

Package ogg reads Vorbis Comment metadata from Ogg Vorbis and Ogg Opus streams.

Both codecs use Vorbis Comment for tags. The encapsulating difference is the codec-specific magic that prefixes the comment packet:

• Vorbis : 0x03 + "vorbis" (7 bytes), followed by the Vorbis comment block, followed by a trailing framing bit (0x01).
• Opus : "OpusTags" (8 bytes), followed by the Vorbis comment block (no framing bit).

Read parses only the first logical bitstream's header packets (the identification packet and the comment packet) and captures enough state for WriteFile to splice in a re-paged replacement comment packet. The audio packets are not decoded; their bytes round-trip with sequence numbers adjusted and per-page CRCs recomputed when the comment packet's page count changes.

A *File is not safe for concurrent use.

Index

• Constants
• Variables
• type Codec
  • func (c Codec) String() string
• type File
  • func Read(rs io.ReadSeeker) (*File, error)
  • func ReadFile(path string) (*File, error)
  • func (f *File) AddPicture(p *flac.Picture) error
  • func (f *File) Album() string
  • func (f *File) AlbumArtist() string
  • func (f *File) Artist() string
  • func (f *File) Comment() string
  • func (f *File) Composer() string
  • func (f *File) DiscNumber() (n, total int)
  • func (f *File) Genre() string
  • func (f *File) Pictures() []*flac.Picture
  • func (f *File) RemovePictures()
  • func (f *File) Title() string
  • func (f *File) TrackNumber() (n, total int)
  • func (f *File) WriteFile(path string) error
  • func (f *File) Year() int

Constants

const (
	FieldTitle       = "TITLE"
	FieldArtist      = "ARTIST"
	FieldAlbum       = "ALBUM"
	FieldAlbumArtist = "ALBUMARTIST"
	FieldDate        = "DATE"
	FieldGenre       = "GENRE"
	FieldComposer    = "COMPOSER"
	FieldTrack       = "TRACKNUMBER"
	FieldTrackTotal  = "TRACKTOTAL"
	FieldDisc        = "DISCNUMBER"
	FieldDiscTotal   = "DISCTOTAL"
	FieldDescription = "DESCRIPTION"
)

Vorbis Comment standard field names (case-insensitive on lookup).

const FieldMetadataBlockPicture = "METADATA_BLOCK_PICTURE"

FieldMetadataBlockPicture is the Vorbis Comment field name reserved by Xiph for embedded cover art. The value is the base64 encoding of a FLAC METADATA_BLOCK_PICTURE block body, so any Vorbis Comment-bearing container (Ogg Vorbis, Ogg Opus, FLAC) can carry cover art using the same on-disk bytes.

Variables

var (
	// ErrNoOgg is returned when the input does not begin with an
	// "OggS" page.
	ErrNoOgg = errors.New("ogg: not an Ogg stream")

	// ErrUnsupportedCodec is returned when the first logical
	// bitstream is neither Vorbis nor Opus.
	ErrUnsupportedCodec = errors.New("ogg: unsupported codec (only Vorbis and Opus are recognised)")

	// ErrTruncated is returned when the stream ends before the
	// comment packet has been fully read.
	ErrTruncated = errors.New("ogg: stream ended before comment header was complete")
)

Errors returned by this package.

Types

type Codec

type Codec int

Codec identifies the audio codec inside the Ogg container.

const (
	CodecUnknown Codec = iota
	CodecVorbis
	CodecOpus
)

func (Codec) String

func (c Codec) String() string

type File

type File struct {
	Codec    Codec
	Vendor   string
	Comments *flac.VorbisComment // shares the same on-disk format

	// Serial is the bitstream serial number of the first logical
	// stream. Provided for callers that want to verify identity.
	Serial uint32
}

File holds the parsed Vorbis-Comment metadata of an Ogg stream. The original raw bytes are not retained; this is a read-only view.

func Read

func Read(rs io.ReadSeeker) (*File, error)

Read parses the first logical bitstream of rs and returns its codec + comment metadata.

func ReadFile

func ReadFile(path string) (*File, error)

ReadFile is a convenience wrapper around Read.

func (*File) AddPicture

func (f *File) AddPicture(p *flac.Picture) error

AddPicture appends a METADATA_BLOCK_PICTURE entry encoding p. The picture bytes are FLAC-encoded then base64-wrapped per the Xiph convention.

func (*File) Album

func (f *File) Album() string

func (*File) AlbumArtist

func (f *File) AlbumArtist() string

func (*File) Artist

func (f *File) Artist() string

func (*File) Comment

func (f *File) Comment() string

func (*File) Composer

func (f *File) Composer() string

func (*File) DiscNumber

func (f *File) DiscNumber() (n, total int)

func (*File) Genre

func (f *File) Genre() string

func (*File) Pictures

func (f *File) Pictures() []*flac.Picture

Pictures decodes every METADATA_BLOCK_PICTURE entry in the Vorbis Comment block. Entries whose base64 / FLAC body fails to decode are silently skipped; the raw text remains accessible via f.Comments.

func (*File) RemovePictures

func (f *File) RemovePictures()

RemovePictures deletes every METADATA_BLOCK_PICTURE entry.

func (*File) Title

func (f *File) Title() string

func (*File) TrackNumber

func (f *File) TrackNumber() (n, total int)

func (*File) WriteFile

func (f *File) WriteFile(path string) error

WriteFile rewrites path with the current Vorbis Comment.

The implementation relies on the Ogg-spec requirement that the two (Opus) or three (Vorbis) header packets each begin on a fresh page. That gives a clean byte boundary at which to splice in a freshly re-paged comment packet. Pages following the comment packet are emitted with their sequence numbers shifted by (new comment page count − old comment page count) and the per-page CRC recomputed.

Pages belonging to a different (concurrently-multiplexed) logical bitstream are passed through unchanged, which is the correct behaviour for the rare case of an Ogg file with multiple streams sharing the same physical file.

Limits: the new comment packet must fit in fewer than ~16 MiB (255 * 255 * 255 ≈ 16M bytes is the theoretical maximum per page; we emit at most one page per group of 255 segments).

func (*File) Year

func (f *File) Year() int