opusgo

README

opusgo

This is a pure go implementation of an Ogg/Opus parser, decoder, and encoder. It was produced by transpiling the libopus C sources to Go using ccgo, as well as using GPT 5.2 help. No cgo is used.

Directory structure:

• cmd/oggopusdump: command-line tool to dump Ogg/Opus headers and packet sizes
• cmd/oggopusextract: command-line tool to extract Opus audio packets
• cmd/oggopus2wav: command-line tool to decode Ogg/Opus
• cmd/wav2oggopus: command-line tool to encode WAV to Ogg/Opus
• ogg - Parser for the Ogg format and Opus packet reader
• opus - Encoder and decoder opus API
• opuscc - Transpiled libopus C source of the decoder logic
• opusccenc - Transpiled libopus C source of the encoder logic
• libcshim - Small libc shim for the transpiled C code, replaces some modernc.org/libc functionality
• examples - Example programs using the library

Minimal high level API example

Decoding an opus file to get PCM samples. Note the sample rate of the PCM data is always 48000 Hz.

player, _ := opusgo.NewPlayerFromFile("file.opus", true) // true means stream from disk
data := make([]byte, 48000*2*2) // 1 second buffer for stereo s16le
io.ReadFull(player, data)
// data now contains PCM samples

Minimal low level API example

Decoding an opus file to get PCM samples. Note the sample rate of the PCM data is always 48000 Hz.

// error handling omitted for brevity
input, _ := os.Open("file.opus")
reader, _ := ogg.NewOpusReader(input) // input can be any io.Reader
decoder, _ := opus.NewDecoderFromHead(reader.Head)
for {
  packet, err := reader.ReadAudioPacket()
  if err != nil {
    // no more audio packets
    break
  }
  decoded, n, _ := decoder.DecodePacket(packet, nil) // nil can instead be a pre-allocated []int16, otherwise new memory is allocated
  // decoded is an []int16 PCM audio buffer with n samples per channel, so total samples = n * reader.Head.Channels
  // use decoded PCM samples...
}

Example program usage

From this folder:

• Dump headers + packet sizes:

go run ./cmd/oggopusdump --no-crc path/to/file.ogg

• Extract length-prefixed audio packets:

go run ./cmd/oggopusextract --out packets.bin path/to/file.ogg

packets.bin format: repeating (u32le length, length bytes packet).

• Decode .opus to .wav (48kHz s16le):

go run ./cmd/oggopus2wav --out out.wav path/to/file.opus

• Profile decoding:

go run ./cmd/oggopus2wav --cpuprofile cpu.pprof --out out.wav path/to/file.opus
go tool pprof -top cpu.pprof

• Encoding .wav to .opus:

go run ./cmd/wav2oggopus --bitrate 64000 --out out.opus path/to/file.wav

Documentation

Index

• Constants
• type OpusPlayer
  • func NewPlayerF32FromFile(path string, stream bool) (*OpusPlayer[float32], error)
  • func NewPlayerF32FromReader(reader io.Reader) (*OpusPlayer[float32], error)
  • func NewPlayerFromFile(path string, stream bool) (*OpusPlayer[int16], error)
  • func NewPlayerFromReader(reader io.Reader) (*OpusPlayer[int16], error)

Constants

const OpusSampleRateHz = ogg.OpusSampleRateHz

the decoded sample rate for Opus streams

Types

type OpusPlayer

type OpusPlayer[T player.DataType] = player.OpusPlayer[T]

func NewPlayerF32FromFile

func NewPlayerF32FromFile(path string, stream bool) (*OpusPlayer[float32], error)

Similar to NewPlayerFromFile but produces float32 PCM samples in the range [-1.0, 1.0].

func NewPlayerF32FromReader

func NewPlayerF32FromReader(reader io.Reader) (*OpusPlayer[float32], error)

Similar to NewPlayerFromReader but produces float32 PCM samples in the range [-1.0, 1.0].

func NewPlayerFromFile

func NewPlayerFromFile(path string, stream bool) (*OpusPlayer[int16], error)

Create a new player from a file path. If stream is true, the file will be streamed instead of fully loaded into memory. This player produces int16 PCM samples. Note that internally the file object is closed when the garbage collector collects the player.

func NewPlayerFromReader

func NewPlayerFromReader(reader io.Reader) (*OpusPlayer[int16], error)

Create a new player from an existing reader. If the reader is seekable (implements io.Seeker), seeking will be supported. This player produces int16 PCM samples.