roon-internal-api

Latest release: v0.1.1

The latest release fixes protocol framing, stable struct schemas, nullable values, repeated search, and web session recovery. It also adds read-only history export. Release notes and validation limits →

Why bother

Roon users have been asking for a more capable API for years. The official node-roon-api is deliberately limited — no metadata editing, no real library management, just a sandboxed slice of what the app can do.

So this is the brute-force route: watch what the desktop client itself sends to the Core, figure out the wire format, and see how much of it you can replay from your own code. It’s an experiment, not a product, and definitely not blessed by Roon.

The one interesting finding

On the local network, the protocol doesn’t seem to use any authentication. The thing I expected to be the wall — “mutations need a cloud auth token” — turned out (in my testing) to be wrong. A correctly-formed call against a live object reference just works. The actual hard part was the wire format and the fact that object references are ephemeral. How I got there →

Stability & safety — read before you run it

This is an internal protocol meant for Roon’s own trusted code, not a public API. It will break: Roon versions client and Core in lockstep and changes it freely, so any update can break this client. Misuse can degrade your own Core: the protocol isn’t hardened for third parties, and there are resource-management obligations across the connection (releasing handles, tearing down subscriptions, completing callbacks) that a reverse-engineered client may not get right — getting them wrong can leak memory or compute inside your own Roon Core. Only point it at a Core you own and can restart. Roon’s CTO made these same points on the forum.

What seems to work

This is one person tinkering against a single Core, confirmed by hand — not a test matrix across setups. Treat everything as “worked for me,” not “guaranteed.”

Protocol

Framing, varints, primitives, method calls, by-val structs, and the object graph are mapped well enough to talk to a Core. Cross-checked against my own packet captures.

A TypeScript port

~14k LOC. Typed wrappers are code-generated for all ~1550 methods, but the vast majority are untested — generated from metadata, not exercised live.

Tried by hand

Reading the object graph, favoriting, playing an album, pause, standby, and a reversible metadata edit each worked once or twice against my setup.

Lots still open

Most generated methods and broader version/provider compatibility still need validation. UnifiedSearch and bounded history reads were checked against Roon 2.73 build 1696. Pitch in →

Built with Claude

Most of this — the protocol decoding, the TypeScript port, the codegen, and these docs — was done by pair-programming with Claude (Anthropic’s Claude Code). It’s as much an experiment in “how far can an AGI agent push a gnarly reverse-engineering task” as it is a Roon experiment.

The v0.1.1 maintenance, adversarial reviews, and read-only Core validation were carried out with Codex. Contributor attribution is preserved in the releases.

Pages

How this went The actual path: a wrong theory about auth, reading the decompiled client, and confirming there's no local auth.

Protocol notes Wire format as I understand it: framing, varints, primitives, calls, structs, object graph.

Using the client Point it at your own Core and try the bits that work. You supply your own connection details.

Contributing Capture traffic, find your own Core's details, run the checks, and help with the open bits.

---

Use at your own risk

Independent reverse-engineering for interoperability and learning. Not affiliated with, endorsed by, or supported by Roon Labs. The protocol is private and unversioned — it can break on any Roon update. Only point this at a Core you own. See the license & ethics note.