ogg

README

Ogg

The codeberg.org/samwhited/ogg package contains a stream-based interface for reading data from Ogg files without needing to understand the underlying structure of the Ogg bitstream. Lower-level access will also be provided for writing tools to handle invalid Ogg encodings.

License

Licensed under the Apache License, Version 2.0 with the Commons Clause addendum. A copy of the licenses can be found in the LICENSE and NOTICE files.

All documentation including Go documentation comments and this README file are licensed under a Creative Comments Attribution 4.0 license (CC-BY 4.0).

Documentation

Overview

package ogg implements demultiplexing of Ogg bitstreams.

Index

• func Streams(r io.ReadSeeker) iter.Seq[*Stream]
• type Page
  • func (p *Page) AppendBinary(b []byte) ([]byte, error)
  • func (p *Page) DataSize() int
  • func (p *Page) HeaderSize() int
  • func (p *Page) MarshalBinary() ([]byte, error)
  • func (p *Page) PageSize() int
  • func (p *Page) String() string
  • func (p *Page) UnmarshalBinary(data []byte) error
• type PageHeaderType
• type Stream
  • func (s *Stream) Read(p []byte) (int, error)
  • func (s *Stream) String() string
• type StreamError
  • func (err StreamError) Error() string
  • func (err StreamError) Is(target error) bool

Functions

func Streams

func Streams(r io.ReadSeeker) iter.Seq[*Stream]

Streams returns an iterator over the various streams contained in the file. It does not return the data in the stream, instead it returns an io.Reader that can be used to read from the stream later. Any errors encountered while reading the stream header are deferred until the first read from the returned stream.

Types

type Page

type Page struct {
	Version    byte
	Type       PageHeaderType
	GranulePos int64
	Serial     uint32
	Sequence   uint32
	Checksum   uint32
	SegNum     uint8
	SegTable   []uint8
}

Page is an Ogg page header and segment table. This is a low-level construct used by Ogg for data storage, most users of this package will want to use the Streams iterator instead.

func (*Page) AppendBinary

func (p *Page) AppendBinary(b []byte) ([]byte, error)

AppendBinary implements encoding.BinaryAppender for Page.

func (*Page) DataSize

func (p *Page) DataSize() int

DataSize is the size of the actual data packet for the page (everything after the header). If the segment table has not been read 0 is returned.

func (*Page) HeaderSize

func (p *Page) HeaderSize() int

HeaderSize returns the total size of the page header including the segment table.

func (*Page) MarshalBinary

func (p *Page) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler for Page.

func (*Page) PageSize

func (p *Page) PageSize() int

PageSize returns the total size of the page including headers and data.

func (*Page) String

func (p *Page) String() string

String implements the fmt.Stringer interface and returns the unique serial number of the stream this page belongs to in hex format.

func (*Page) UnmarshalBinary

func (p *Page) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler for Page.

It will unmarshal either the first 27 bytes of the header, or the full header including the segment table if included in the data. It will not read partial segment tables, or partial header data. For partial header data, io.ErrShortBuffer (or an error wrapping it) is returned. For partial segment table data no error is returned and the header is only unmarshaled up to the start of the segment table.

type PageHeaderType

type PageHeaderType byte

PageHeaderType is a bitmask that identifies the type of a page.

const (
	PageContinuation PageHeaderType = 1 << iota // page contains data of a packet continued from the previous page.
	PageBoS                                     // page is the first page of a logical bitstream (bos)
	PageEoS                                     // page is the last page of a logical bitstream (eos)
)

Bitmask for pageHeaderType

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

Stream is a track (a logical bitstream, in Ogg terms) being read from a file.

func (*Stream) Read

func (s *Stream) Read(p []byte) (int, error)

Read reads data from the specific stream, regardless of the current position in the overall Ogg bitstream. It implements io.Reader for the Stream.

func (*Stream) String

func (s *Stream) String() string

String implements the fmt.Stringer interface and returns the unique serial number of the stream in hex format.

type StreamError

type StreamError struct {
	Page *Page

	// True if this is a duplicate BoS page (rather than an invalid page)
	Duplicate bool
}

StreamError is an error type that may be returned by the Streams iterator or when reading from a stream and a page is encountered that has not had a corresponding Beginning of Stream (BoS) page or where a duplicate BoS page has already been read. This error is not necessarily terminal, but does indicate a badly encoded bitstream.

func (StreamError) Error

func (err StreamError) Error() string

Error returns the message from the stream error.

func (StreamError) Is

func (err StreamError) Is(target error) bool

Is implements equality checks by comparing the page serial numbers and the value of Duplicate.