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 is also be provided for writing tools to handle invalid Ogg
encodings.
This was mostly written to allow me to easily experiment with the Ogg Stem file
format defined in draft-swhited-ogg-stems and the Skeleton meta bitstream
defined in draft-swhited-ogg-skeleton.
It will likely never be production ready and you probably shouldn't use it in
anything important, but if you are interested in developing it further (or have
feedback about either of the aforementioned I-Ds) please reach out.
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 reading and writing Ogg bitstreams.
Index ¶
- Variables
- type Ogg
- 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) PacketLen() iter.Seq[int]
- func (p *Page) Packets() int
- func (p *Page) PageSize() int
- func (p *Page) String() string
- func (p *Page) UnmarshalBinary(data []byte) error
- type PageHeaderType
- type Stream
- type StreamError
- type StreamWriter
Constants ¶
This section is empty.
Variables ¶
var ErrClosedStream = errors.New("ogg: write on a closed stream")
ErrClosedStream is returned when attempting to write to a StreamWriter that has already had its StreamWriter.Close method called.
var ErrInvalidHeader = errors.New("ogg: data does not appear to be the start of a page header")
ErrInvalidHeader is returned when unmarshaling Ogg data if the initial page header cannot be found.
Functions ¶
This section is empty.
Types ¶
type Ogg ¶
type Ogg struct {
// contains filtered or unexported fields
}
Ogg represents an Ogg bitstream. It should be created with a call to Open.
func Open ¶
func Open(r io.ReadSeeker) Ogg
Open attempts to parse the given io.ReadSeeker as an Ogg file. Any errors are deferred until reading from the Ogg.Streams or Ogg.Pages iterator.
func (Ogg) Pages ¶
Pages returns an iterator over the pages in the Ogg bitstream (regardless of what individual stream they belong to). Unlike the [Streams] iterator, the Pages iterator does not verify that pages are in the correct order, ie. that pages belonging to a stream come after their Beginning-of-Stream (BoS) page or before their End-of-Stream (EoS) page. It is meant for lower-level access in tools that are meant to read (and possibly correct) invalid Ogg files. Most users will want to use Ogg.Streams instead.
func (Ogg) Streams ¶
Streams returns an iterator over the various streams contained in the file. The Stream values that are yielded do not contain the actual contents of the stream, instead they are an io.Reader that can be used to read the contents of the stream at a later time. Any errors encountered while reading the stream header are deferred until the first read from the stream.
type Page ¶
type Page struct {
Version byte
Type PageHeaderType
GranulePos int64
Serial uint32
Sequence uint32
Checksum uint32
SegTable []uint8
// contains filtered or unexported fields
}
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 ¶
AppendBinary implements encoding.BinaryAppender for Page.
func (*Page) DataSize ¶
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 ¶
HeaderSize returns the total size of the page header including the segment table.
func (*Page) MarshalBinary ¶
MarshalBinary implements encoding.BinaryMarshaler for Page.
func (*Page) Packets ¶
Packets returns the number of packets in the page data. If the segment table has not been read, or is invalid, 0 is returned.
func (*Page) 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 ¶
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 ( PageCont 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 ¶
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 ¶
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
// True if this error is the result of a checksum that does not match the
// calculated value.
Checksum 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 values of Duplicate and Checksum.
type StreamWriter ¶
type StreamWriter struct {
// contains filtered or unexported fields
}
StreamWriter can be used to write packets to an individual Ogg stream.
func New ¶
func New(w io.Writer) *StreamWriter
New creates a new StreamWriter that can be used to write data to an Ogg logical bitstream. To create a multi-stream Ogg file, create multiple stream writers pointing to the same io.Writer.
func (*StreamWriter) Close ¶
func (sw *StreamWriter) Close() error
Close flushes any buffered data to the underlying Ogg stream. Future writes to the stream will return an error after Close has been called.
At a low-level, Close writes the End-of-Stream (EoS) page to the Ogg file. If any data is still in the buffer it will be included in the EoS page. To write an empty EoS page, call StreamWriter.Flush first (which will write a normal page containing the data) before calling Close.
func (*StreamWriter) Flush ¶
func (sw *StreamWriter) Flush() error
Flush writes any buffered data to the underlying Ogg stream.
At a low-level, Flush creates a new page with each packet created by a previous call to Write (or an empty page if no data is buffered).
func (*StreamWriter) Serial ¶
func (sw *StreamWriter) Serial() uint32
Serial returns the unique (to the Ogg stream) serial number for this stream.
func (*StreamWriter) String ¶
func (sw *StreamWriter) String() string
String implements the fmt.Stringer interface and returns the unique serial number of the stream in hex format.
func (*StreamWriter) Write ¶
func (sw *StreamWriter) Write(p []byte) (int, error)
Write implements io.Writer for the stream. Writes are buffered until a call to StreamWriter.Flush.
At the Ogg level, each call to Write is a single packet in a page.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
crc32
Package crc32 implements the 32-bit cyclic redundancy check, or CRC-32, checksum.
|
Package crc32 implements the 32-bit cyclic redundancy check, or CRC-32, checksum. |
|
hextest
Package hextest contains functions for tests dealing with hex strings.
|
Package hextest contains functions for tests dealing with hex strings. |
|
The skeleton package provides structuring information for multitrack Ogg.
|
The skeleton package provides structuring information for multitrack Ogg. |