opus

README

Pure Go Opus Codec

日本語 | English

A pure-Go implementation of the Opus audio codec (RFC 6716 / RFC 8251) with no runtime CGO dependency. The decoder passes all 12 official RFC 8251 test vectors (RMSE < 0.001) and matches the libopus 1.6.1 reference frame-by-frame. The encoder is still a simplified CELT-only path and is not yet bit-exact — see Status.

Honesty note: this project is decoder-complete and encoder-in-progress. It is suitable for decoding real Opus streams in Go; it is not yet a drop-in bit-exact replacement for libopus on the encode side.

Status

Area	State
Decoder	✅ Passes all 12 official RFC 8251 vectors (RMSE < 0.001); matches libopus 1.6.1 reference. SILK, CELT, and hybrid (SILK+CELT) modes are reconstructed, including hybrid SILK→CELT redundancy.
Encoder	🚧 Simplified CELT-only, fullband, 20 ms packets. Functional but not bit-exact against libopus. application/VBR settings are stored but do not yet drive full mode selection.
CGO	None at runtime. A libopus wrapper exists only for reference tests, behind the opusref build tag.
CI	test, race, bench, and fuzz workflows run on amd64 and arm64.

See docs/CURRENT_IMPLEMENTATION.md for the authoritative, code-derived snapshot.

Installation

go get github.com/darui3018823/opus

Requires Go 1.24 or newer (see go.mod).

Usage

Decoding (int16)

package main

import (
	"log"

	"github.com/darui3018823/opus"
)

func main() {
	// 48 kHz, stereo.
	dec, err := opus.NewDecoder(48000, 2)
	if err != nil {
		log.Fatal(err)
	}

	// packet is one Opus packet (e.g. read from a file or the network).
	var packet []byte

	// Buffer for the decoded PCM. 120 ms at 48 kHz (the largest Opus frame)
	// is 5760 samples per channel; size generously for the frames you expect.
	pcm := make([]int16, 5760*2)

	n, err := dec.Decode(packet, pcm)
	if err != nil {
		log.Fatal(err)
	}
	// pcm[:n*2] now holds interleaved stereo samples (n samples per channel).
	_ = n
}

Decoding (float64)

// DecodeFloat returns a freshly allocated, interleaved []float64.
samples, err := dec.DecodeFloat(packet)
if err != nil {
	log.Fatal(err)
}
_ = samples

Encoding

The encoder currently emits CELT-only fullband 20 ms packets and is not bit-exact with libopus. Use it for round-trip/experimentation, not for interoperability-critical encoding yet.

enc, err := opus.NewEncoder(48000, 2, opus.ApplicationAudio)
if err != nil {
	log.Fatal(err)
}
enc.SetBitrate(128000)
enc.SetComplexity(10)

// 20 ms frame = 960 samples per channel at 48 kHz, interleaved stereo.
pcm := make([]int16, 960*2)
// ... fill pcm ...

packet, err := enc.Encode(pcm, 960)
if err != nil {
	log.Fatal(err)
}
_ = packet

// Float64 input is also supported:
//   packet, err := enc.EncodeFloat(make([]float64, 960*2), 960)

Supported Configurations

• Sample rates: 8 kHz, 12 kHz, 16 kHz, 24 kHz, 48 kHz. Non-48 kHz input to the encoder is resampled to 48 kHz internally; the decoder resamples its output to the requested rate.
• Channels: mono and stereo.
• Decoder frame sizes: all Opus durations (2.5/5/10/20/40/60 ms), selected per packet by the TOC byte.
• Encoder frame size: 20 ms (960 samples per channel at 48 kHz).
• Application types (stored by the encoder; full mode selection is WIP):
  • opus.ApplicationVOIP
  • opus.ApplicationAudio
  • opus.ApplicationRestrictedLowDelay

Public API

Encoder

func NewEncoder(sampleRate, channels int, application Application) (*Encoder, error)

func (e *Encoder) Encode(pcm []int16, frameSize int) ([]byte, error)
func (e *Encoder) EncodeFloat(pcm []float64, frameSize int) ([]byte, error)

func (e *Encoder) SetBitrate(bitrate int) error      // 6000–510000 bps
func (e *Encoder) SetComplexity(complexity int) error // 0–10
func (e *Encoder) SetVBR(vbr bool)
func (e *Encoder) SetApplication(application Application)
func (e *Encoder) Reset() error

Decoder

func NewDecoder(sampleRate, channels int) (*Decoder, error)

func (d *Decoder) Decode(data []byte, pcm []int16) (int, error)
func (d *Decoder) DecodeFloat(data []byte) ([]float64, error)
func (d *Decoder) DecodeFEC(data []byte, pcm []int16) (int, error) // currently a CELT PLC fallback
func (d *Decoder) Reset() error
func (d *Decoder) GetLastPacketDuration() int

There is intentionally no EncodeFloat32, DecodeFloat32, or DecodePLC(pcm, frameSize) API. Use the float64 variants above.

Architecture

github.com/darui3018823/opus/
├── opus.go / constants.go / errors.go  # Public API (Encoder/Decoder)
├── internal/
│   ├── opus_framing.go                  # TOC byte parsing/generation (RFC 6716 §3)
│   ├── dsp/                             # FFT, MDCT/IMDCT, windows, math
│   ├── entcode/                         # Range encoder/decoder
│   ├── resampler/                       # Opus-rate sample rate conversion
│   ├── celt/                            # CELT decoder parity + simplified encoder
│   ├── silk/                            # SILK decoder/encoder, tables, helpers
│   └── cgoref/                          # libopus reference wrapper (build tag: opusref)
└── docs/                                # Design and status documentation

Decoding flow: Opus packet → TOC parsed → CELT or SILK/hybrid path → range decoder + reconstruction → optional resample/channel adjust → PCM.

Encoding flow: PCM → optional resample to 48 kHz → CELT encoder (MDCT, band processing, PVQ) → range coder → TOC prepended → Opus packet.

Building & Testing

go build ./...
go vet ./...
go test ./...                 # library packages + official vectors (when present)
go test -race ./...
go test -bench=. -benchmem -run='^$' ./...

Official RFC 8251 test vectors are not committed (testdata/ is git-ignored). Tests that need them call t.Skip when they are absent. To run them locally, download and extract the vectors so they land in testdata/opus_newvectors/:

curl -fSL -o /tmp/v.tar.gz https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz
mkdir -p testdata && tar -xzf /tmp/v.tar.gz -C testdata/
go test -run TestOfficialVectors ./...

libopus reference comparison (optional)

The TestCGORef test decodes every vector with both this codec and libopus and compares them frame-by-frame. It requires a C toolchain plus libopus and is gated behind the opusref build tag (so normal builds stay CGO-free):

go test -tags opusref -run TestCGORef .

On Windows, run CGO builds from PowerShell with a working MinGW/MSYS2 toolchain.

Fuzzing

go test -run='^$' -fuzz='^FuzzDecode$' -fuzztime=60s .

FuzzDecode and FuzzDecodeFloat assert that the decoder never panics on arbitrary input. The fuzz CI workflow runs them nightly and on demand.

Continuous Integration

Four GitHub Actions workflows, each running on a matrix of amd64 (ubuntu-latest) and arm64 (ubuntu-24.04-arm):

• test.yml — go vet, go test ./..., and the official RFC 8251 vectors.
• race.yml — go test -race ./....
• bench.yml — go test -bench=. -benchmem, uploading results as artifacts.
• fuzz.yml — nightly + manual go test -fuzz per target.

Documentation

• docs/CURRENT_IMPLEMENTATION.md — code-derived snapshot of the API, internals, tests, and known gaps (authoritative).
• docs/ARCHITECTURE.md — design decisions and libopus analysis.
• docs/ROADMAP.md — development phases and milestones.
• docs/DEVELOPER.md — code style, porting guidance, profiling tips.
• IMPLEMENTATION_STATUS.md — spec gap list and compliance/test plan.

Limitations

• The encoder is simplified CELT-only and not bit-exact; there is no SILK-only or hybrid encoder path.
• DecodeFEC is currently a PLC fallback, not packet FEC extraction.
• No multistream, surround, or Ogg Opus container API.
• application, VBR, and some CTL-style settings are stored but not yet wired to full libopus-compatible behavior.

Contributing

Before opening a PR, please ensure:

1. go build ./..., go vet ./..., and go test ./... pass.
2. Code is formatted (gofmt).
3. New behavior is covered by tests.

License

BSD 2-Clause License — see LICENSE.

Acknowledgments

• libopus — reference implementation by the Xiph.Org Foundation.
• RFC 6716 / RFC 8251 — the Opus specification and its updates.

Support

For issues and questions, please use the GitHub issue tracker.

Documentation

Overview

Package opus provides a Pure Go implementation of the Opus audio codec. This implementation is based on the official libopus reference implementation and aims for complete compatibility without using CGO.

Index

• Constants
• Variables
• type Application
• type Decoder
  • func NewDecoder(sampleRate, channels int) (*Decoder, error)
  • func (d *Decoder) Decode(data []byte, pcm []int16) (int, error)
  • func (d *Decoder) DecodeFEC(data []byte, pcm []int16) (int, error)
  • func (d *Decoder) DecodeFloat(data []byte) ([]float64, error)
  • func (d *Decoder) GetLastPacketDuration() int
  • func (d *Decoder) Reset() error
• type Encoder
  • func NewEncoder(sampleRate, channels int, application Application) (*Encoder, error)
  • func (e *Encoder) Encode(pcm []int16, frameSize int) ([]byte, error)
  • func (e *Encoder) EncodeFloat(pcm []float64, frameSize int) ([]byte, error)
  • func (e *Encoder) Reset() error
  • func (e *Encoder) SetApplication(application Application)
  • func (e *Encoder) SetBitrate(bitrate int) error
  • func (e *Encoder) SetComplexity(complexity int) error
  • func (e *Encoder) SetVBR(vbr bool)

Constants

const (
	Version      = "0.1.0"
	VersionMajor = 0
	VersionMinor = 1
	VersionPatch = 0
)

Opus version constants

const (
	SampleRate8kHz  = 8000
	SampleRate12kHz = 12000
	SampleRate16kHz = 16000
	SampleRate24kHz = 24000
	SampleRate48kHz = 48000
)

Sample rates supported by Opus

const (
	FrameSize2_5ms = 120  // 2.5ms at 48kHz
	FrameSize5ms   = 240  // 5ms at 48kHz
	FrameSize10ms  = 480  // 10ms at 48kHz
	FrameSize20ms  = 960  // 20ms at 48kHz (most common)
	FrameSize40ms  = 1920 // 40ms at 48kHz
	FrameSize60ms  = 2880 // 60ms at 48kHz
)

Frame sizes in samples (at 48kHz)

const (
	ApplicationVOIP               = 2048 // Voice over IP
	ApplicationAudio              = 2049 // General audio
	ApplicationRestrictedLowDelay = 2051 // Lowest latency
)

Application types

const (
	BandwidthNarrowband    = 1101 // 4kHz
	BandwidthMediumband    = 1102 // 6kHz
	BandwidthWideband      = 1103 // 8kHz
	BandwidthSuperWideband = 1104 // 12kHz
	BandwidthFullband      = 1105 // 20kHz
)

Bandwidth types

const (
	ChannelsMono   = 1
	ChannelsStereo = 2
)

Channel modes

const (
	ModeSILKOnly = 1000
	ModeHybrid   = 1001
	ModeCELTOnly = 1002
)

Opus modes (internal)

const (
	BitrateAuto   = -1000
	BitrateMax    = -1
	BitrateMin    = 500    // 500 bps
	BitrateMaxVal = 512000 // 512 kbps
)

Bitrate constants

const (
	SetBitrateRequest             = 4002
	GetBitrateRequest             = 4003
	SetForceChannelsRequest       = 4022
	GetForceChannelsRequest       = 4023
	SetMaxBandwidthRequest        = 4004
	GetMaxBandwidthRequest        = 4005
	SetBandwidthRequest           = 4008
	GetBandwidthRequest           = 4009
	SetComplexityRequest          = 4010
	GetComplexityRequest          = 4011
	SetInbandFECRequest           = 4012
	GetInbandFECRequest           = 4013
	SetPacketLossPercRequest      = 4014
	GetPacketLossPercRequest      = 4015
	SetDTXRequest                 = 4016
	GetDTXRequest                 = 4017
	SetVBRRequest                 = 4006
	GetVBRRequest                 = 4007
	SetVBRConstraintRequest       = 4020
	GetVBRConstraintRequest       = 4021
	SetSignalRequest              = 4024
	GetSignalRequest              = 4025
	SetApplicationRequest         = 4000
	GetApplicationRequest         = 4001
	GetLookaheadRequest           = 4027
	SetExpertFrameDurationRequest = 4040
	GetExpertFrameDurationRequest = 4041
	SetPredictionDisabledRequest  = 4042
	GetPredictionDisabledRequest  = 4043
	ResetStateRequest             = 4028
)

Encoder/Decoder control codes (CTL)

const (
	SignalAuto  = -1000
	SignalVoice = 3001
	SignalMusic = 3002
)

Signal types

const (
	ComplexityMin     = 0
	ComplexityMax     = 10
	ComplexityDefault = 9
)

Complexity (0-10)

const (
	PacketLossPercMin = 0
	PacketLossPercMax = 100
)

Packet loss percentage (0-100)

const (
	MaxPacketSize = 1500 // bytes
	MaxFrameSize  = 2880 // samples at 48kHz for 60ms
)

Maximum packet size

Variables

var (
	// ErrBadArg indicates that one or more arguments are invalid
	ErrBadArg = errors.New("opus: bad argument")

	// ErrBufferTooSmall indicates that the provided buffer is too small
	ErrBufferTooSmall = errors.New("opus: buffer too small")

	// ErrInternalError indicates an internal error occurred
	ErrInternalError = errors.New("opus: internal error")

	// ErrInvalidPacket indicates the packet is invalid or corrupted
	ErrInvalidPacket = errors.New("opus: invalid packet")

	// ErrUnimplemented indicates a feature is not yet implemented
	ErrUnimplemented = errors.New("opus: unimplemented")

	// ErrInvalidState indicates the encoder/decoder is in an invalid state
	ErrInvalidState = errors.New("opus: invalid state")

	// ErrAllocFail indicates memory allocation failed
	ErrAllocFail = errors.New("opus: allocation failed")

	// ErrUnsupportedSampleRate indicates the sample rate is not supported
	ErrUnsupportedSampleRate = errors.New("opus: unsupported sample rate")

	// ErrUnsupportedChannels indicates the channel count is not supported
	ErrUnsupportedChannels = errors.New("opus: unsupported number of channels")

	// ErrUnsupportedFrameSize indicates the frame size is not supported
	ErrUnsupportedFrameSize = errors.New("opus: unsupported frame size")

	// ErrUnsupportedBandwidth indicates the bandwidth is not supported
	ErrUnsupportedBandwidth = errors.New("opus: unsupported bandwidth")
)

Common Opus errors

Types

type Application

type Application = int

Application specifies the encoding mode (use constants from package)

type Decoder

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

Decoder represents an Opus decoder instance

func NewDecoder

func NewDecoder(sampleRate, channels int) (*Decoder, error)

NewDecoder creates a new Opus decoder

sampleRate must be one of: 8000, 12000, 16000, 24000, 48000 Hz channels must be 1 (mono) or 2 (stereo)

func (*Decoder) Decode

func (d *Decoder) Decode(data []byte, pcm []int16) (int, error)

Decode decodes an Opus packet to PCM samples

data is the compressed Opus packet pcm is the output buffer for 16-bit PCM samples Returns the number of samples per channel decoded (clamped to buffer size)

func (*Decoder) DecodeFEC

func (d *Decoder) DecodeFEC(data []byte, pcm []int16) (int, error)

DecodeFEC decodes forward error correction data This is used for packet loss concealment

func (*Decoder) DecodeFloat

func (d *Decoder) DecodeFloat(data []byte) ([]float64, error)

DecodeFloat decodes an Opus packet to floating-point PCM samples

data is the compressed Opus packet Returns float64 samples in range [-1.0, 1.0]

func (*Decoder) GetLastPacketDuration

func (d *Decoder) GetLastPacketDuration() int

GetLastPacketDuration returns the duration of the last decoded packet in samples

func (*Decoder) Reset

func (d *Decoder) Reset() error

Reset resets the decoder state

type Encoder

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

Encoder represents an Opus encoder instance

func NewEncoder

func NewEncoder(sampleRate, channels int, application Application) (*Encoder, error)

NewEncoder creates a new Opus encoder

sampleRate must be one of: 8000, 12000, 16000, 24000, 48000 Hz channels must be 1 (mono) or 2 (stereo) application specifies the encoding mode

func (*Encoder) Encode

func (e *Encoder) Encode(pcm []int16, frameSize int) ([]byte, error)

Encode encodes PCM audio samples

pcm contains interleaved 16-bit PCM samples (left, right, left, right, ...) frameSize is the number of samples per channel (at the encoder's sample rate) Returns compressed Opus packet

func (*Encoder) EncodeFloat

func (e *Encoder) EncodeFloat(pcm []float64, frameSize int) ([]byte, error)

EncodeFloat encodes floating-point PCM samples

pcm contains interleaved float64 samples in range [-1.0, 1.0] frameSize is the number of samples per channel (at the encoder's sample rate)

func (*Encoder) Reset

func (e *Encoder) Reset() error

Reset resets the encoder state

func (*Encoder) SetApplication

func (e *Encoder) SetApplication(application Application)

SetApplication changes the application mode

func (*Encoder) SetBitrate

func (e *Encoder) SetBitrate(bitrate int) error

SetBitrate sets the target bitrate in bits per second

func (*Encoder) SetComplexity

func (e *Encoder) SetComplexity(complexity int) error

SetComplexity sets the computational complexity (0-10) Higher values use more CPU but may provide better quality

func (*Encoder) SetVBR

func (e *Encoder) SetVBR(vbr bool)

SetVBR enables or disables variable bitrate mode