Python

Rockbox DSP, metadata, and playback in Python via cffi over the librockbox_ffi C ABI.

pip install rockbox-ffi
# or
uv add rockbox-ffi

Requires Python 3.9+. The wheel bundles a prebuilt librockbox_ffi for your platform — no Rust toolchain needed. From a repo checkout, the loader walks up to target/release/; override with ROCKBOX_FFI_LIB.

Quick start

import rockbox_ffi as rb
from rockbox_ffi import Dsp, Player, metadata
from rockbox_ffi.enums import (
    DspReplayGainMode, ReplayGainMode, CrossfadeMode,
    EqPreset, RepeatMode, CrossfeedMode,
)

# --- metadata ---------------------------------------------------------
meta = metadata.read("song.flac")
print(meta["artist"], "—", meta["title"], meta["duration_ms"], "ms")
print(metadata.probe("track.opus"))          # -> "Opus"  (no I/O, extension guess)

# --- DSP: process interleaved stereo int16 ----------------------------
with Dsp(44_100) as dsp:
    dsp.eq_enable(True)
    dsp.set_eq_band(0, cutoff_hz=60, q=0.7, gain_db=3.0)
    dsp.set_replaygain(DspReplayGainMode.TRACK, noclip=True, preamp_db=0.0)
    dsp.set_replaygain_gains(track_gain_db=-6.02)   # −6 dB ≈ half amplitude
    processed = dsp.process(samples)                # array('h')

# --- playback (needs an output device) --------------------------------
# Setters return None — call them plainly, one per line (no chaining).
with Player(volume=0.8) as player:
    player.set_replaygain(ReplayGainMode.TRACK, preamp_db=0.0, prevent_clipping=True)
    player.set_crossfade(CrossfadeMode.ALWAYS)

    # --- live DSP chain (mirrored back by player.dsp_settings()) ------
    player.set_eq_enabled(True)
    player.set_eq_preset(EqPreset.BASS_BOOST)        # 21 presets: Flat, Rock, Jazz, …
    player.set_bass(4)                                # tone: bass/treble in dB
    player.set_treble(2)
    player.set_crossfeed(CrossfeedMode.MEIER, 0, -60, -80, 700)
    player.set_bass_enhancement(strength=30, precut=-30)   # PBE
    print(player.dsp_settings())                     # -> dict of the whole chain

    # --- shuffle & repeat --------------------------------------------
    player.set_shuffle(True)
    player.set_repeat(RepeatMode.ALL)

    # --- sources: local paths, http(s):// files, live-radio URLs ------
    player.set_queue([
        "a.flac",
        "https://example.com/b.mp3",
        "https://stream.example.com/radio",          # live stream
    ])
    player.play()
    print(player.status())     # {'state': 'playing', 'index': 0, ...}

Decode a file to PCM

Decoder streams an audio file to interleaved-stereo S16LE PCM one chunk at a time through the Rockbox codec engine — the same decoders that power playback, without an output device.

from rockbox_ffi import Decoder

with Decoder("song.flac") as dec:
    print(dec.metadata()["title"])               # same shape as metadata.read
    for samples, rate in dec.chunks():            # array('h'), Hz
        ...                                        # feed samples somewhere
    print(dec.finished())                          # (True, 0) — clean end
    # dec.seek_ms(30_000); dec.elapsed_ms()       # seek / query position

chunks() (or next_chunk()) yields (samples, sample_rate) and stops at None on end of track; finished() returns (done, code) where code is 0 for a clean end and negative for a codec error.

One decoder at a time. The codec state is process-wide (global) — only one Decoder can decode at once. Constructing a second one blocks until the first is closed. Always use with Decoder(...) (or call close()) so the native resource is freed; a GC finalizer is the backstop.

API

Module	Contents
rockbox_ffi.metadata	read(path) -> dict, probe(filename) -> str | None
rockbox_ffi.Dsp	EQ / tone / surround / compressor / ReplayGain, process(samples)
rockbox_ffi.Decoder	streaming file → S16LE PCM via the codec engine: metadata(), next_chunk() / chunks(), seek_ms(ms), elapsed_ms(), finished() -> (done, code) (one decoder at a time — codec state is global)
rockbox_ffi.Player	queue + transport + crossfade + ReplayGain + shuffle/repeat + full live DSP chain (10-band EQ, tone, crossfeed, surround, PBE/AFR, compressor, dither, pitch), dsp_settings() -> dict, status() -> dict
rockbox_ffi.enums	DspReplayGainMode, ReplayGainMode, CrossfadeMode, MixMode, RepeatMode, EqPreset, ChannelMode, CrossfeedMode, InsertPosition, …

• Handles are context managers — with Dsp(...) as dsp: frees the native resource on exit. A GC finalizer is the backstop.
• Rich values (metadata, status) come back as plain dicts.
• Sample buffers are array('h') of interleaved-stereo signed 16-bit samples.

Player DSP chain. Every setter applies live and is reflected back by player.dsp_settings(). The full surface: EQ — set_eq_enabled / is_eq_enabled, set_eq_preset(EqPreset) (21 presets: FLAT, ROCK, JAZZ, BASS_BOOST, …), set_eq_band, set_eq_precut. Tone — set_tone, set_bass, set_treble, set_bass_cutoff, set_treble_cutoff. Spatial — set_crossfeed(CrossfeedMode), set_surround, set_channel_mode(ChannelMode), set_stereo_width, set_balance(balance) / balance() (stereo balance, -100 full left … +100 full right, 0 = centre). Enhancers — set_bass_enhancement (PBE), set_fatigue_reduction (AFR), set_compressor, set_dither, set_pitch. Shuffle / repeat — set_shuffle / is_shuffle_enabled, set_repeat(RepeatMode) / repeat().

For what each parameter does (and sensible ranges), see the official Rockbox manual: Sound Settings.

Dsp.set_replaygain and Player.set_replaygain take different mode integers. Always pass the named enums — DspReplayGainMode for the DSP, ReplayGainMode for the player. See the overview.

Interactive console

uv pip install -e '.[dev]'      # installs IPython
uv run python console.py

Drops into IPython with rb, metadata, Dsp, Player, the enums, and a FIXTURE sample track preloaded:

metadata.read(str(FIXTURE))["title"]        # 'Speak'
p = Player(volume=0.6)
p.set_queue([str(FIXTURE)]); p.play()
p.status()["state"]                          # 'playing'