Reference
The feed.
One HTTP server on port 8765, the same on a Mac and on Track Fly Server. Plain GET, JSON, open CORS, no token.
The fields.
Stable keys, sensible types, nothing nested. Values you can trust a display with.
| Key | Type | Meaning |
|---|---|---|
| state | string | playing, paused, stopped or not_running |
| source | string | music, spotify, roon or plex |
| title · artist · album | string | The track, as the player names it |
| duration · position | seconds | Track length and playhead, one decimal |
| progress | 0 – 1 | Position divided by duration, for progress bars |
| text | string | “Artist - Title (Album)”, ready to show |
| text_ascii | string | The same line in plain ASCII |
| zone | string | Roon zone or Plex player, when there is one |
| track_number · track_count | number | Place on the album, 0 when unknown |
| playlist · queue_index · queue_count | string · number | The playlist playing and the place in it (Apple Music) |
| queue_remaining | number | Tracks left in the queue (Roon), null when unknown |
| volume | 0 – 100 | Player or Roon zone volume, null when it can't be set |
| id | string | Changes when the track changes |
| artwork_url | string · null | The album cover as a JPEG, served by Track Fly |
Endpoints · port 8765
/nowThe current track as JSON./textOne line of text, empty when nothing plays./sourcesEvery enabled source at once./zonesWhat a display can follow: every source and Roon zone./control?action=playpause,next,prev,volume&value=40,seek&value=90(to a second) orseekby&value=-10. Roon, Apple Music and Spotify; Plex can't be controlled yet./artworkThe cover of the current track (JPEG, up to 640 px)./historyRecently played, newest first:?limit=20,&zone=or&source=. A track counts once it has played 20 s./displayA full-screen now-playing page for any browser on your network, in the display’s look, or as a turntable or a cassette./displaysThe Track Fly displays that read this feed./healthIs it up: version, sources, Roon and Plex status./settingsTrack Fly Server only: its settings page.
?ascii=1 on any endpoint turns Sigur Rós into Sigur Ros. &source=plex pins one source, &zone=Kitchen follows one Roon zone. Track Fly announces itself on the network as _trackfly._tcp, so a display can find it even after its address changes.
Mac or server.
Same port, same JSON, same displays. What differs is what each can reach.
| Track Fly for Mac | Track Fly Server | |
|---|---|---|
| Runs on | macOS 15 or later, menu bar | Windows (tray icon), Linux, Docker |
| Sources | Apple Music, Spotify, Roon, Plex | Roon, Plex |
| Controls | Roon, Apple Music, Spotify | Roon |
| Settings | Settings window | /settings in a browser, config.json, environment variables |
| Updates | Itself and your displays | Download a new version; Docker: docker pull |