Go - Rockbox Daemon

go get github.com/tsirysndr/rockboxd/bindings/go

Requires Go 1.22+. Calls the native engine through purego — no cgo and no C toolchain; the package dlopens a prebuilt librockbox_ffi at process start. From a repo checkout the loader walks up to target/release/; override with ROCKBOX_FFI_LIB.

Quick start

package main

import (
	"fmt"

	rockbox "github.com/tsirysndr/rockboxd/bindings/go"
)

func main() {
	// --- metadata -----------------------------------------------------
	meta, _ := rockbox.Metadata.Read("song.flac")
	fmt.Println(meta.Artist, "—", meta.Title, meta.DurationMs, "ms")
	label, _ := rockbox.Metadata.Probe("track.opus") // "Opus" (no I/O, extension guess)
	fmt.Println(label)

	// --- DSP: process interleaved stereo int16 ------------------------
	dsp, _ := rockbox.NewDsp(44_100)
	defer dsp.Close()
	dsp.EqEnable(true)
	dsp.SetEqBand(0, 60, 0.7, 3.0)
	dsp.SetReplaygain(rockbox.DspReplayGainTrack, true, 0.0)
	dsp.SetReplaygainGains(rockbox.Opt(-6.02), nil, nil, nil) // −6 dB ≈ half amplitude
	processed, _ := dsp.Process(samples)                      // []int16
	_ = processed

	// --- playback (needs an output device) ----------------------------
	// Functional-options constructor (or use NewPlayer(Config) directly):
	player, _ := rockbox.New(
		rockbox.WithVolume(0.8),
		rockbox.WithReplayGain(rockbox.ReplayGainTrack, 0.0, true),
		rockbox.WithCrossfade(rockbox.CrossfadeAlways, 0, 2000, 0, 2000, rockbox.MixCrossfade),
		rockbox.WithResumeFile("state.m3u8"),
	)
	defer player.Close()

	// DSP chain — EQ presets, tone, crossfeed, compressor, … (setters return nothing)
	player.SetEqEnabled(true)
	player.SetEqPreset(rockbox.EqPresetBassBoost)

	// Shuffle & repeat
	player.SetShuffle(true)
	player.SetRepeat(rockbox.RepeatAll)

	// Queue entries may be local paths, http(s):// URLs, or live-radio / streaming URLs.
	player.SetQueue([]string{"a.flac", "https://example.com/b.mp3", "https://stream.example/radio"})
	player.Play()
	st, _ := player.Status() // &Status{State: "playing", Index: 0, Shuffle: true, Repeat: "all", ...}
	fmt.Println(st.State, st.Shuffle, st.Repeat)
}

Decode a file to PCM

OpenDecoder runs a file through the Rockbox codec engine and hands back interleaved-stereo S16LE PCM one chunk at a time — decode without an output device.

dec, err := rockbox.OpenDecoder("song.flac")
if err != nil {
	log.Fatal(err)
}
defer dec.Close() // safe to call twice

meta, _ := dec.Metadata() // map[string]any, same shape as Metadata.Read
fmt.Println(meta["title"])

for {
	samples, rate, ok := dec.NextChunk() // []int16, sample rate, ok=false at EOF
	if !ok {
		break
	}
	_ = samples
	_ = rate
	// dec.SeekMs(30_000); dec.ElapsedMs()
}

if done, code := dec.Finished(); done && code < 0 {
	log.Printf("codec error: %d", code) // 0 = clean end, negative = codec error
}

The codec engine is process-wide: only one Decoder may decode at a time, and always from a single goroutine. A second OpenDecoder blocks until the first is closed.

API

Symbol	Contents
`rockbox.Metadata`	`Read(path) (*Meta, error)`, `Probe(name) (string, bool)`
`rockbox.NewDsp` → `*Dsp`	EQ / tone / surround / compressor / ReplayGain, `Process([]int16)`
`rockbox.New` / `rockbox.NewPlayer` → `*Player`	Construct: `New(WithVolume, WithReplayGain, WithCrossfade, WithResumeFile, …)` (functional options) or `NewPlayer(Config)`. Transport: `Play` / `Pause` / `Toggle` / `Stop` / `Next` / `Previous` / `SkipTo` / `SeekMs`. Queue: `SetQueue` / `Enqueue` / `Insert` / `Queue` (local paths, `http(s)://`, live-radio / streaming URLs). Shuffle & repeat: `SetShuffle` / `IsShuffleEnabled`, `SetRepeat` / `Repeat`. DSP chain: `SetEqEnabled` / `IsEqEnabled` / `SetEqPreset` / `SetEqBand` / `SetEqPrecut`, `SetTone` / `SetBass` / `SetTreble` / `SetBassCutoff` / `SetTrebleCutoff`, `SetCrossfeed`, `SetSurround`, `SetChannelMode` / `SetStereoWidth`, `SetBassEnhancement`, `SetFatigueReduction`, `SetCompressor`, `SetDither`, `SetPitch`, `DSPSettings()`. Volume/balance/ReplayGain/crossfade: `SetVolume` / `Volume`, `SetBalance` / `Balance`, `SetReplaygain`, `SetCrossfade`. Resume / m3u: `Resume` / `SaveResume` / `ClearResume`, `LoadM3u` / `ImportM3u` / `ExportM3u`. State: `Status()`.
`rockbox.OpenDecoder` → `*Decoder`	Stream-decode a file to interleaved-stereo S16LE PCM via the Rockbox codec engine: `Metadata()`, `NextChunk() ([]int16, uint32, bool)`, `SeekMs` / `ElapsedMs`, `Finished() (bool, int32)`. Codec state is process-wide — only one Decoder decodes at a time, from one goroutine.
`rockbox.*` consts	`DspReplayGainMode`, `ReplayGainMode`, `RepeatMode` (Off/One/All), `EqPreset` (21 presets), `CrossfeedMode`, `ChannelMode`, `CrossfadeMode`, `MixMode`, `InsertPosition`, `ChannelConfig`

Handles own native resources — defer dsp.Close() / defer player.Close() frees them.
Rich values (metadata, status) decode into typed structs (Meta, Status); optional tags are nil-able pointer fields.
Sample buffers are []int16 of interleaved-stereo signed 16-bit samples.
DSP semantics (EQ bands, tone, crossfeed, compressor, …) mirror Rockbox’s own settings — see the official Rockbox manual for what each control does.

Dsp.SetReplaygain and Player.SetReplaygain take different mode integers. Always pass the named constants — DspReplayGain* for the DSP, ReplayGain* for the player. See the overview.

Smoke test

cd bindings/go
go run ./examples/smoke   # metadata + DSP + player checks
go test ./...