Roon Music Controller

Your Roon system is controlled via a REST API running in LCX container on Proxmox server.

API Base

http://roonext2.home:3001/api

CRITICAL: How to make API calls

GET:

curl -s 'http://roonext2.home:3001/api/status'

POST:

curl -X POST http://roonext2.home:3001/api/find-and-play \
  -H "Content-Type: application/json" \
  -d '{
    "zone_id": "YOUR_ZONE_ID",
    "query": "stool pigeon",
    "type": "Tracks",
    "action": "Play Now"
  }'

Zones

Replace this table with your own zones. Get them by calling /api/zones.

How to find your zone IDs:

curl -s 'http://roonext2.home:3001/api/zones'

Endpoints

play-album (album playback)

Use this endpoint when the user asks to play an album. Do NOT use find-and-play for albums — it only plays the first track.

{ "zone_id": "...", "query": "Artist Album", "action": "Play Now" }

Searches for the album, navigates Roon's full browse hierarchy (Search → Albums → Album page → Play Album → action), and triggers album-level playback. All tracks are queued natively in the correct album order.

Supports the same action strings: Play Now, Queue, Add Next, Start Radio.

curl -X POST http://roonext2.home:3001/api/play-album \
  -H "Content-Type: application/json" \
  -d '{
    "zone_id": "YOUR_ZONE_ID",
    "query": "white city a novel",
    "action": "Play Now"
  }'

find-and-play (single track playback)

{ "zone_id": "...", "query": "...", "type": "Tracks", "action": "Play Now" }

CRITICAL — Roon's exact action labels

These are the real strings Roon uses internally. Wrong names silently fall back to Play Now.

transport

{ "zone_id": "...", "action": "next" }

Valid actions: play, pause, stop, next, previous, toggle_play_pause

shuffle

{ "zone_id": "...", "shuffle": true }

Set shuffle to true to enable, false to disable.

curl -s -X POST http://roonext2.home3001/api/shuffle \
  -H 'Content-Type: application/json' \
  -d '{"zone_id": "1601dcef8115529daf4cd6807753971fae3e", "shuffle": true}'

volume

{ "zone_id": "...", "how": "absolute", "value": 40 }

Range 0–100. how: absolute, relative, relative_step

Playlist pattern

Option A — /api/playlist (recommended for multi-track lists)

Queues all tracks in one API call. First track plays immediately, rest are queued. To save as a permanent Roon playlist: Queue → ⋮ → Save Queue as Playlist.

Note: Roon's Extension API does not expose "Add to Playlist" to third-party extensions — only playback actions are available. The queue-then-save workflow is the supported path.

POST /api/playlist
{
  "name": "My 1988 Mix",
  "zone_id": "YOUR_ZONE_ID",
  "tracks": [
    { "query": "Song One Artist One" },
    { "query": "Song Two Artist Two" },
    { "query": "Song Three Artist Three" }
  ]
}

curl -s -X POST http://roonext2.home:3001/api/playlist \
  -H 'Content-Type: application/json' \
  -d '{"name":"My Playlist","zone_id":"YOUR_ZONE_ID","tracks":[{"query":"Song One Artist"},{"query":"Song Two Artist"}]}'

Option B — individual find-and-play calls (for short lists or fine control)

First track → Play Now (starts playback, clears existing queue). All subsequent tracks → Queue. Use delay 2 between calls.

ZONE="YOUR_ZONE_ID"
API="http://roonext2.home:3001/api/find-and-play"

tracks=(
  "Song One Artist One|Play Now"
  "Song Two Artist Two|Queue"
  "Song Three Artist Three|Queue"
)

for track in "${tracks[@]}"; do
  query="${track%%|*}"
  action="${track##*|}"
  curl -s -X POST "$API" \
    -H 'Content-Type: application/json' \
    -d "{\"zone_id\":\"$ZONE\",\"query\":\"$query\",\"type\":\"Tracks\",\"action\":\"$action\"}"
  sleep 2
done

Your library and taste profile

Edit this section to describe your own library and musical taste. Cowork uses this to make smart recommendations and playlist choices on your behalf.

YOUR_STREAMING_SERVICE is connected — any track can be played.

Local library includes:
- Artist — albums

Taste profile: describe your taste here so Cowork can recommend music you'll enjoy.

Roon authorisation

If the API returns "Not connected to Roon Core", you need to re-authorise:

Roon → Settings → Extensions → Enable "Cowork Controller"

Learnings

• verify.artist_match – check that the artist of a track or album matches the requested artist before adding to the queue. This prevents mismatches like Bobbi Humphrey for a Commodores request.
• Embedding future learnings here ensures they are only loaded when the roon‑controller skill is used.