Client SDKs

Six first-party SDKs. All wrap the GraphQL transport, surface real-time events, and ship a tiny plugin system.

Every SDK targets the GraphQL endpoint on port 6062 and exposes the same domain-namespaced API:

client.playback     # transport, current/next track, play helpers
client.library      # albums, artists, tracks, search, likes, scan
client.playlist     # the active queue
client.savedPlaylists
client.smartPlaylists
client.sound        # volume
client.settings     # global EQ / replaygain / crossfade / shuffle
client.system       # version, runtime info
client.browse       # filesystem browser
client.devices      # output devices (Cast, AirPlay, Snapcast)
client.bluetooth    # Linux only

Pick a language

TypeScript

bun add @rockbox-zig/sdk

Python

uv add rockbox-sdk — async-first

Ruby

gem install rockbox

Elixir

{:rockbox_ex, "~> 0.1"}

Clojure

org.clojars.tsiry/rockbox-clj

Gleam

gleam add rockbox

Why not just use the GraphQL transport directly?

You can — client.query() on every SDK is an escape hatch, and the GraphiQL explorer at http://localhost:6062/graphiql lets you test queries without writing any client code. The SDKs add value when you want:

• Typed responses — Pydantic models in Python, Structs in Ruby, TypeScript types, Gleam tagged unions.
• Real-time events — track:changed / status:changed / playlist:changed over WebSocket with auto-reconnect and exponential backoff.
• A plugin system — Jellyfin-style install/uninstall lifecycle for cross-cutting features (scrobbling, notifications, sleep timer).
• Smart-playlist rule builders — type-safe rule DSLs (Gleam, Elixir, Clojure).
• Idiomatic ergonomics — pipe-friendly in functional languages, builder DSLs in OOP languages.

Common patterns

TypeScript

import { RockboxClient } from '@rockbox-zig/sdk';

const client = new RockboxClient();
client.connect();

client.on('track:changed', (t) => console.log(`▶ ${t.title} — ${t.artist}`));

const { albums } = await client.library.search('dark side');
await client.playback.playAlbum(albums[0].id, { shuffle: true });