Skip to content
Back to search

frankensonos

Memory-safe Rust controller for your own Sonos speakers on your own LAN — reliable SSDP/UPnP-SOAP/GENA interoperability (S1 + S2), a Spotify-library classical DJ, and a CLI + HTTP API + MCP server so AI agents can run the house, including off-LAN over Tailscale.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Dicklesworthstone/frankensonos with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Dicklesworthstone/frankensonos'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dicklesworthstone--frankensonos/badge.svg)](/listings/dicklesworthstone--frankensonos)

HTML

<a href="/listings/dicklesworthstone--frankensonos"><img src="/api/listings/dicklesworthstone--frankensonos/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

No prebuilt binaries yet (pre-release). Build from source:

git clone https://github.com/Dicklesworthstone/frankensonos
cd frankensonos
cargo build --release      # the toolchain is pinned in rust-toolchain.toml
cargo test --workspace     # unit, golden and end-to-end tests (no speakers needed)

The binary is `target/release/fsonos`. Run it on a machine on the same LAN as your speakers; for access from anywhere, that machine also joins your tailnet. `fsonos setup` takes it from there. To run the daemon at boot, see [`docs/DEPLOY.md`](docs/DEPLOY.md) (launchd plus Tailscale).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 960 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # FrankenSonos
  3. <img src="frankensonos_illustration.webp" alt="FrankenSonos illustration" width="900">
  4. **Your Sonos, your way. Command your speakers from anywhere in the world, as
  5. long as you're on your Tailscale tailnet.** A memory-safe Rust controller and
  6. daemon for the Sonos speakers you already own: one binary that runs the whole
  7. house from the terminal, an HTTP API, or any AI agent that speaks MCP.
  8. ![status: pre-release](https://img.shields.io/badge/status-pre--release-orange)
  9. ![language: Rust 2024](https://img.shields.io/badge/Rust-2024%20(nightly)-dea584)
  10. ![license: MIT + rider](https://img.shields.io/badge/license-MIT%20%2B%20OpenAI%2FAnthropic%20rider-blue)
  11. ![interfaces: CLI · HTTP · MCP](https://img.shields.io/badge/interfaces-CLI%20%C2%B7%20HTTP%20%C2%B7%20MCP-7b4bff)
  12. ![networks: S1 + S2](https://img.shields.io/badge/Sonos-S1%20%2B%20S2-111)
  13. </div>
  14. > **Status: pre-release (before `0.1.0`).** Features have protocol, unit and
  15. > end-to-end regression tests using `fsonos-sim`, a virtual
  16. > Sonos house (an S1 and an S2 household speaking SOAP and GENA on loopback,
  17. > checked against scrubbed captures of real players). The daemon also runs a
  18. > real two-household house, S1 and S2, where discovery, grouping, volume,
  19. > favorites, Spotify rendering and announcements have run on real players,
  20. > and `fsonos selftest` checks yours without changing anything you can hear.
  21. > There is no real-hardware CI yet, and interfaces may still change before
  22. > `0.1.0`.
  23. ---
  24. ## Why FrankenSonos
  25. Sonos hardware is excellent and lasts for years; the software around it is
  26. where it falls short. The app loses speakers, grouping fights you, automation
  27. is out of reach, the legacy S1 line is frozen while S2 moves on without it, and
  28. the Spotify Web API cannot start playback on a Sonos at all.
  29. FrankenSonos talks to your speakers directly, over the local protocols they
  30. already speak (SSDP discovery, UPnP/SOAP on port 1400, GENA events), and turns
  31. the whole house, both generations at once, into something you and your agents
  32. can drive:
  33. - **From anywhere on your tailnet.** `fsonos serve` serves its HTTP API on
  34. loopback and your Tailscale addresses for both HTTP and MCP, and `fsonos tailscale
  35. setup` puts HTTPS in front of both with Tailscale Serve. Your phone in another city, an agent on a cloud VM,
  36. a laptop at work: if it is on your tailnet, it runs your house (the CLI
  37. there too: `FSONOS_DAEMON_URL=https://<mac>.<tailnet>.ts.net fsonos pause
  38. Kitchen`). Nothing is
  39. exposed to the public internet, Funnel is never used, and the speakers never
  40. leave your LAN.
  41. - **Built for agents, with guardrails.** Every surface (CLI, HTTP, MCP) goes
  42. through one control path: the house policy (per-room volume caps, quiet
  43. hours, per-client tool allowlists), an action log of who did what, and undo.
  44. The volume caps and quiet hours bind the agent surfaces; the local CLI is
  45. trusted and runs uncapped by default (set `[clients.cli] capped = true` to
  46. cap it too). The caps hold for music an agent starts as well as for the
  47. volumes it sets: a play, a resume, a DJ start or skip, or an unmute first
  48. brings a room left loud down to its cap, and one whose level can't be read
  49. is not started. The DJ restarting a group on its own is held to them too,
  50. as client `dj` (`[clients.dj]`) and as whoever started it. Hand the house to an agent without it playing volume
  51. 80 at 2 a.m.
  52. - **A DJ that plays what you like.** It plays from your own Spotify likes and
  53. saves, in whatever genres they span (pop, jazz, hip-hop, soundtracks,
  54. classical), puts your own steering ahead of anything it infers, follows mood
  55. and time of day, spreads a set across artists, explains every pick, and
  56. keeps learning from your likes, dislikes, early skips and full listens.
  57. Classical works play whole, every movement in order. Standing preferences of
  58. your own — favored and avoided genres, artists and eras, a default energy,
  59. explicit tracks, pins and bans — override what it infers, on the CLI, HTTP
  60. and MCP.
  61. - **One memory-safe binary.** Pure Rust 2024 with `#![forbid(unsafe_code)]`,
  62. on an owned async stack (no Tokio, no reqwest). Nothing is installed on the
  63. speakers and nothing about them is changed.
  64. ## What it does
  65. | Area | What you get |
  66. |---|---|
  67. | **Discovery & topology** | Every player of both S1 and S2 households, its zone group and coordinator. Rooms resolve by name, `Room@S1` / `Room@S2`, your own aliases (`fsonos rooms alias add downstairs Kitchen "Living Room"`), `here` (your default room, `[defaults] room` in `aliases.toml`), or `all` / `everywhere`. [Manage saved aliases and defaults](docs/ROOM_CONFIGURATION.md) on the selected daemon from the phone, dashboard, CLI, HTTP or MCP |
  68. | **Play and queue across rooms** | Start a source link, favorite or saved Sonos playlist in every existing group selected by an alias, `all` or `everywhere`; `all@S1` / `all@S2` selects one household. `--next` and `--queue` add it without changing playback and return each group's confirmed insertion range. Grouped rooms act once, each household supplies its own source metadata, and an artist/show selection is resolved once for the whole request. Groups remain independent. Phone and desktop source players review the complete target and every returned result. CLI, HTTP, MCP and browser requests share one action log and undo boundary; see [Multi-room playback](docs/MULTI_ROOM_PLAYBACK.md) for partial receipts and source-specific limits |
  69. | **Control** | Play a Spotify link (a track, album, playlist, artist, episode or show), a source URI, a Sonos favorite or a library search (your tracks, saved albums and playlists), or add a Spotify link to the queue instead, next or at the end (`fsonos play Kitchen <link> --next`); seek within a track (`fsonos seek Kitchen +30`, `0` starts it over); play a track already on the queue where it is (`fsonos queue-play Kitchen 5`); set the queue's shuffle/repeat mode (`fsonos play-mode Kitchen SHUFFLE_NOREPEAT --expected-mode NORMAL`, or the web remote's Shuffle & repeat panel); pause, resume, next, previous; room or group volume (set or ±N); mute; ungroup — these on one room, an alias or `everywhere` at once (`fsonos pause everywhere`; `fsonos ungroup everywhere` breaks every group up), logged and undone as one action; fades on demand (`fsonos volume Kitchen 20 --fade 10s` ramps, `--fade auto` lets each speaker ramp itself at its own pace, `fsonos pause Den --fade 30s` fades out first); group; a room's tone, bass, treble and loudness (`fsonos eq Kitchen --bass 2`); **move** the music to another room (handing the group over, or `--copy` across households); **party** mode for a whole household. Group commands always go to the group's coordinator |
  70. | **Live state** | GENA subscriptions keep a live model of every zone (transport, track, volume, shuffle and repeat), so reads need no polling, and `GET /events` streams the changes as server-sent events (`fsonos events` prints them as they happen); `fsonos queue Kitchen` lists what is queued and what plays; `fsonos queue-search Kitchen "artist title"` finds exact queued occurrences across pages (also HTTP/MCP, with revision-checked continuation); `fsonos history` shows what played |
  71. | **Library** | Browse cached tracks, albums and playlists from the web remote, CLI or MCP, even with Spotify or speakers offline. Open a playlist's cached tracks in their original order, including duplicate occurrences, filter by title/artist/album, then play or queue an exact track. Both web remotes select up to ten entries from a cached page and [play or queue the ordered selection](docs/QUEUE_TRACK_SELECTIONS.md), retaining repeated occurrences. **Play selected now** replaces the queue and starts the first track; next/append preserve playback. CLI `play-tracks` / `queue-tracks` and MCP `play_tracks` / `add_tracks_to_queue` share the same guarded operations and verified undo boundaries. [Playlist contents](docs/PLAYLIST_CONTENTS.md) show the cache's age and whether the bounded sync read is complete, partial or not yet available |
  72. | **Spotify catalog search** | Find tracks, albums, artists, playlists, shows and episodes beyond the local cache with `fsonos spotify-search "artist or title" --kind track`, HTTP `GET /spotify/search`, or MCP `search_spotify`. Choose a returned source URI for the existing play or queue commands. Uses your signed-in Spotify account and leaves playback unchanged while searching. See [Catalog search](docs/SPOTIFY_SEARCH.md) |
  73. | **Native line-in** | Discover a household's physical inputs with `fsonos line-in Study`, then play a connected source on another group with `fsonos play Study --line-in "Music Room"`. Exact player ids preserve individual stereo-pair inputs. CLI, HTTP, MCP, browser remotes and the native Apple app share household checks, playback caps, the retained queue and undo. Discovery reports input capability; cable and signal state remain unknown. See [Line-in](docs/LINE_IN.md) |
  74. | **Saved Sonos playlists** | List, inspect, play, create, rename, edit and remove native playlists on either Sonos household without Spotify Web API sign-in. `fsonos playlists Kitchen` lists native ids; `fsonos playlist-contents Kitchen SQ:7` previews ordered tracks without interrupting music; `playlist-track Kitchen SQ:7 3 --expected-revision <revision>` plays one exact occurrence; `playlist-tracks Kitchen SQ:7 3 1 3 --revision <revision> --mode play` replaces the queue with an ordered selection of up to ten occurrences. Both offer `--mode next` or `--mode append` for silent queue additions; `fsonos playlist-save Kitchen 'Evening Mix'` saves the current group queue as a new playlist without interrupting playback. Equal titles create distinct ids. `playlist-rename` and `playlist-remove` require the exact `SQ:` id and a freshly read contents revision; they leave playback unchanged. `playlist-remove-tracks` removes an exact saved range, and `playlist-move-tracks` reorders it before an original position or at the end, preserving duplicate occurrences and current playback. `fsonos play Kitchen --playlist 'Evening Mix'` recalls one; `--next` or `--queue` inserts its saved tracks. The CLI, HTTP and MCP share the [native playlist contract](docs/SONOS_PLAYLISTS.md); the phone remote and desktop dashboard offer revision-checked track previews, individual and ordered multi-track Play now / Play next / Add to queue actions, whole-playlist recall, reviewed **Save queue as playlist** from both queue views, and **Manage saved playlist** with explicit rename/deletion and saved-track editing reviews, plus recovery in the original household. The [native Apple app](docs/NATIVE_SONOS_PLAYLIST_MANAGEMENT.md) also saves retained queues and reviews exact playlist rename/deletion, keeping uncertain results through navigation and suspension |
  75. | **My Sonos favorites** | [Save the selected native track or station, rename a favorite, or remove an exact entry](docs/FAVORITES_MANAGEMENT.md) through CLI, HTTP, MCP and both web remotes. The phone's **Music → Sonos favorites → Manage favorites** and the dashboard's source controls review the exact target, preserve pending or uncertain results, and recover through the original household. `favorite-current` previews the actual source; `favorite-save` retains its native playback metadata. `favorite-inspect`, `favorite-rename` and `favorite-remove` use the household-local `FV:2/` identity and observed revision. The current queue, playback and DJ continue unchanged |
  76. | **Self-healing** | A player that moved to a new address, or a group whose coordinator changed under a command, is found again and the command retried once (the answer notes `HEALED`); the live model resurveys and resubscribes on its own |
  77. | **DJ** | [Start, steer, skip or stop across rooms](docs/MULTI_ROOM_DJ.md) with a saved alias, `all` / `everywhere`, or `all@S1` / `all@S2`; each existing group acts once and keeps its own feed. The phone and dashboard’s **DJ across rooms** panel reviews every affected group, current source and exact session before one command, retains partial results, and follows the original players for recovery. `dj start` takes optional mood, artists, genres, decades or other steering constraints in one request; picks from your Spotify liked tracks and saved albums, in any genre; a song plays on its own, and a classical work plays whole, every movement in order; varied by artist (or composer), era and time-of-day energy; duplicate recordings share one work’s weighted chance, with artist balance based on distinct permitted works and explicit pins and favorites preserved; `dj steer` by mood, artists, genre, decade, keywords (which also match genres), work length or energy, and for classical music by composers and periods, any of them left out too (`--not-decade 80s`, `--not-genre pop`), for a while or until cleared; `dj prefs` sets your standing favorites, avoids, default energy and pins or bans; `dj status` and `dj why` explain the pick factor by factor; `dj rehearse` plans the set it would play from any hour, with each pick's reasons and how varied each hour is, without playing anything; `dj moods` lists presets; [`dj configuration`](docs/DJ_CONFIGURATION.md) and the phone/dashboard editor save custom moods and automatic daily programs; `dj like` / `dislike`, early skips and full listens shape later picks |
  78. | **Scenes** | `scene save dinner` captures grouping, volumes, mutes and what each group plays, or `--from dinner.toml` writes one out (a favorite, a [saved Sonos playlist](docs/SONOS_PLAYLIST_SCENES.md), a stream, a Spotify link or the DJ with a mood and full direction per group). Native playlist scenes pin their household and SQ: id, load current saved contents, support silent loading, and can run as scheduled Apply scene routines. A captured DJ retains its added filters and remaining lifetime; [reusable directions](docs/DJ_DIRECTIONS.md) restart that lifetime on recall. A captured normal queue remembers its selected occurrence, position and known shuffle/repeat mode; [recall requires that original queue to remain unchanged](docs/SCENE_QUEUES.md). `scene apply dinner` sends only the steps the house needs, `--fade 20s` ramps the volumes there, and `fsonos undo` attempts to restore the prior state |
  79. | **Sleep & schedules** | `sleep Bedroom 45m` fades the group out over the last two minutes (with the speaker's own timer as a backstop); `schedule add "weekdays 07:30" dj start all --mood bright` starts independent DJs across a room alias, the whole house or `all@S2`, with every group checked before the occurrence is claimed. The phone and dashboard routine forms offer the same targets and review all affected groups before saving. The mood lasts until the time-of-day program changes, then the program takes over; use the full DJ direction flags, such as `--genre jazz --artist 'Miles Davis' --for 2h`, to reapply those settings on each run; `--automatic` clears prior steering. Also schedule a pause, a volume, a scene (ramped over the policy's fade), or a [spoken reminder or chime](docs/SCHEDULED_ANNOUNCEMENTS.md), at times or after delays; runs with the rights of whoever added it. [Edit an existing routine](docs/ROUTINE_EDITING.md) from the phone, dashboard, CLI (`schedule edit`), HTTP or MCP, retaining its id, creator and paused state; a restarted daemon picks its sleep timers up again |
  80. | **Announcements** | `say "Dinner is ready" --rooms Kitchen,Office` with offline Linux speech (FrankenTTS, espeak-ng or Piper) or macOS `say`; `chime bell`; `announce --file clip.wav`. Policy-capped playback restores the previous music and speaker state. Add `--background` to inspect or cancel an [announcement job](docs/ANNOUNCEMENT_JOBS.md) from the CLI, HTTP, MCP, phone remote, or dashboard |
  81. | **Safety** | `policy.toml`: per-room caps, a per-step limit, quiet hours, per-client tool allowlists; over-limit volumes are clamped and say so (the local CLI runs uncapped by default); `fsonos log` / `undo`, `fsonos policy show` / `check` |
  82. | **Setup & diagnosis** | `fsonos setup` walks a first run (including your Spotify app and sign-in); `fsonos doctor` checks speakers, Spotify linkage, listeners, the daemon, the store's free disk space and the Tailscale chain, and names the fix for each problem |
  83. | **Three surfaces** | The `fsonos` CLI (`--json` everywhere), an HTTP API with an OpenAPI document, and an MCP server (tools plus `sonos://zones` and `sonos://dj` resources) over streamable HTTP or stdio, all answering alike, with the same stable error codes ([`docs/ERRORS.md`](docs/ERRORS.md)); room alias/default edits follow the selected daemon too; `fsonos policy check` validates a local policy file |
  84. | **A house without speakers** | `fsonos sim` starts virtual S1 and S2 households on loopback, so you can try every command, or develop an agent, with no hardware |
  85. The [native iPhone, iPad and Mac remote](docs/APPLE_REMOTE.md) can build an
  86. ordered selection of up to ten saved Sonos playlist occurrences across pages.
  87. Reorder, remove or repeat selected entries, then review Play now, Queue next or
  88. Add to end. Confirmation rechecks the saved contents and destination queue
  89. before one request. It also preserves the native playlist save, rename and
  90. removal workflow.
  91. Scenes saved with `--backup-queues` can reconstruct their saved queues after
  92. the originals change. A complete, verified recall on unchanged groups now
  93. retains [bounded queue undo](docs/QUEUE_UNDO.md), restoring the intervening
  94. queue's duplicate occurrences, bookmark, shuffle/repeat mode, capped room
  95. levels, mutes and previous playback intent.
  96. ### Changes made in other Sonos controllers
  97. The daemon subscribes to native queue, favorite and saved-playlist changes.
  98. Editing a paused queue in another controller can refresh an open queue view
  99. even when its length and selected track stay the same. Both browser remotes
  100. retire obsolete queue and catalog reviews; late replies cannot restore stale
  101. selections. Reads are coalesced by the affected group or household, with no
  102. periodic queue polling.
  103. The DJ also rechecks an invalidated queue before automatic maintenance,
  104. preserving manually inserted music and relinquishing a completely replaced
  105. queue. Its own queue additions retain listening-feedback continuity and bounded
  106. retry backoff. HTTP, CLI and MCP event consumers receive `queue_changed`
  107. in `zone.state` and household-scoped `catalog.changed` notifications.
  108. See [Event delivery](docs/EVENT_DELIVERY.md) for the contract.
  109. Hosts connected to multiple speaker networks serve events on each required
  110. local address. Each player receives a callback URL on its own route, and a
  111. listener failure on one network leaves the others running. Health and doctor
  112. report partial failures while the daemon retries the unavailable listener.
  113. See [Callback routing and recovery](docs/CALLBACK_RECOVERY.md).
  114. Before starting a source or queue, resuming, or silently loading music, the
  115. controller verifies that the addressed speaker is the intended group coordinator.
  116. An old address reassigned to another room cannot pass merely because the intended
  117. player still appears elsewhere in the house topology. A stale initial target can
  118. use the existing bounded recovery to the originally requested room; a later
  119. mismatch never restarts completed playback changes. See
  120. [Command recovery](docs/COMMAND_RECOVERY.md).
  121. ### Playback errors and DJ recovery
  122. `fsonos status ROOM`, API state, MCP and live events expose the speaker's
  123. reported transport status. `ERROR_OCCURRED` is distinct from an ordinary
  124. stop; an absent status means unknown. Phone and dashboard views display the
  125. same playback-error state.
  126. A copied move also checks the destination’s renderer status before stopping
  127. the source. If the destination reports `ERROR_OCCURRED`, the original music
  128. keeps playing even if the destination still reports `PLAYING` or `TRANSITIONING`.
  129. Later confirmation reads keep the same check. Paused moves stay silent, and
  130. an already failed destination can still be replaced with a healthy source.
  131. See [Moving playback](docs/MOVE_QUEUES.md) for the transfer and failure contract.
  132. An active DJ can move past a confirmed failed work to the first movement of
  133. the next intact DJ work already waiting on its queue. Recovery keeps the
  134. listener's inserted tracks intact, obeys current volume caps and quiet hours,
  135. and is limited to three attempts in any rolling five minutes, including across
  136. daemon restarts. A failed or ambiguous command stops automatic management;
  137. the DJ does not replay it or clear the queue. Renderer failures do not teach
  138. the DJ that the listener disliked the music. The action log distinguishes an
  139. observed successful recovery from a continuation that has only been requested.
  140. Before sending a recovery command, the daemon durably saves the attempt with
  141. the feed's initiating callers and group identity. A failed save defers recovery
  142. without touching the speaker. Playback, queue, group and shuffle/repeat mode
  143. are checked again after that save. A saved attempt without a saved completion
  144. is left unmanaged on the next startup, preserving the speaker's queue and
  145. playback. Inspect the room and explicitly start the DJ again to resume
  146. automatic management.
  147. An ordinary exhausted queue also retains its pending continuation across daemon
  148. restarts. If refilling succeeded but the speaker explicitly refused playback,
  149. the DJ can retry from the first movement after the old end without adding the
  150. same music twice. Every retry checks the current queue, source, selected
  151. occurrence, group and coordinator boot; a user pause or replacement queue is
  152. left alone. Before retrying, the daemon durably consumes the saved continuation.
  153. A failed checkpoint postpones playback, and an unconfirmed command stops
  154. automatic management without replaying it after another restart.
  155. This addition includes simulator regression cases. Its Rust build and test
  156. execution remain unverified: the restored local environment still kills the
  157. existing `asupersync` dependency build before project code is checked. Browser
  158. regressions run successfully under Node; that does not substitute for Rust or
  159. physical-speaker acceptance.
  160. ## Quick tour
  161. ```bash
  162. fsonos discover # every player on the LAN, S1 and S2
  163. fsonos zones # the groups and what each is doing
  164. fsonos play "Living Room" --favorite "Morning" # a Sonos favorite (or a URI, or --search "bwv 988")
  165. fsonos play all@S2 --favorite "Morning" # the favorite on every existing S2 group
  166. fsonos playlists Kitchen # playlists saved on this Sonos household
  167. fsonos playlist-contents Kitchen SQ:7 # inspect saved tracks without changing playback
  168. fsonos playlist-save Kitchen 'Evening Mix' # save the current queue as a new native playlist
  169. fsonos playlist-rename Kitchen SQ:7 'Evening Mix' --expected-revision '<contents revision>'
  170. fsonos playlist-remove Kitchen SQ:7 --expected-revision '<fresh contents revision>'
  171. fsonos playlist-move-tracks Kitchen SQ:7 4 --count 2 --before 1 --expected-revision '<revision>'
  172. fsonos playlist-remove-tracks Kitchen SQ:7 3 --expected-revision '<fresh revision>'
  173. fsonos play Kitchen --playlist 'Evening Mix' # recall one; --next or --queue adds its tracks
  174. fsonos play Kitchen spotify:album:<id> --next # after the track playing; --queue for the end
  175. fsonos play-tracks Kitchen spotify:track:<id1> spotify:track:<id2> # replace queue and start this ordered selection
  176. fsonos queue-tracks Kitchen spotify:track:<id1> spotify:track:<id2> --next # quietly add an ordered selection
  177. fsonos play-mode Kitchen SHUFFLE_NOREPEAT --expected-mode NORMAL # whole mode, guarded
  178. fsonos volume "Living Room" +5 # set, or change by ±N; --group for the whole group
  179. fsonos eq Kitchen --bass 2 --loudness off # tone: bass and treble -10..10, loudness on/off
  180. fsonos group Office Kitchen # Office joins Kitchen's group
  181. fsonos move "Living Room" Bedroom # the music follows you
  182. fsonos dj start "Living Room" --mood calm # the DJ, from your own Spotify taste
  183. fsonos dj start Kitchen --genre jazz --decade 60s --for 2h # choose and start a set together
  184. fsonos dj start all --mood calm # independent DJs across every existing group
  185. fsonos dj why "Living Room" # why it chose this pick
  186. fsonos queue-search Kitchen "dvorak prelude" # find music already queued, with exact positions
  187. fsonos spotify-search "Nina Simone" --kind artist # find an uncached source, then choose one to play
  188. fsonos line-in Kitchen # discover native inputs in Kitchen's household
  189. fsonos play Kitchen --line-in Office # listen to Office's input on Kitchen's group
  190. fsonos dj browse tracks --playlist-uri 'spotify:playlist:<id>' # inspect cached playlist order and coverage
  191. fsonos dj rehearse "Living Room" --at 23:00 # what it would play at 23:00, and why
  192. fsonos scene save dinner && fsonos scene apply dinner
  193. fsonos sleep Bedroom 45m # fade out, then pause
  194. fsonos schedule add "weekdays 07:30" dj start Kitchen --mood bright
  195. fsonos schedule add "weekdays 08:15" say "Time to leave" --rooms Kitchen,Office --volume 25
  196. fsonos schedule add "daily 12:00" chime bell --rooms Office
  197. fsonos --json schedule list
  198. fsonos schedule edit 7 --expected-revision '<revision>' "weekdays 08:00" dj start Kitchen --mood bright
  199. fsonos say "Dinner is ready" --rooms Kitchen,Office
  200. fsonos announce --file clip.wav --rooms Kitchen # an existing 16-bit PCM WAV
  201. fsonos stream Kitchen --input alsa_output.example.monitor # Linux desktop audio (Ctrl-C stops)
  202. fsonos undo # put the newest action back
  203. fsonos serve # the daemon: HTTP API and MCP on loopback + tailnet
  204. fsonos tailscale setup # HTTPS for the tailnet via Tailscale Serve (never Funnel)
  205. fsonos service install --tailscale-serve --load # serve as a login service that survives restarts
  206. fsonos doctor # what is wrong, and how to fix it
  207. fsonos selftest # live checks on your players; nothing you can hear changes
  208. fsonos selftest --audible --room Kitchen --room Office # with you listening: play, fade, group, hand over; all put back
  209. ```
  210. No speakers handy? Run `fsonos sim` in one terminal; it prints the `--seeds` and
  211. `--routes` flags that point every other command (and `fsonos mcp`) at the
  212. virtual house.
  213. ### Reusable DJ moods and daily programs
  214. Open **Moods & daily programs** in the phone remote’s **Music** workspace
  215. or on the dashboard to create reusable selection rules and choose their automatic weekday/time windows.
  216. Edit a built-in mood, restore its factory definition, or create a custom name;
  217. preview the program at a day and time before saving. Settings apply to future
  218. DJ picks across the daemon's groups and keep queued music and temporary
  219. steering intact.
  220. `fsonos dj configuration show` returns the editable document, its exact
  221. revision, and the effective/factory definitions. Apply an edited JSON document
  222. with `fsonos dj configuration apply moods.json --expected-revision <revision>`.
  223. HTTP `GET`/`POST /dj/configuration` and MCP `dj_configuration`/`dj_configure`
  224. share the same contract. Stale saves are rejected, and removing a mood checks
  225. standing preferences, active steering, saved scenes, and schedules first.
  226. See [DJ configuration](docs/DJ_CONFIGURATION.md) for examples, program ordering,
  227. concurrent edits, and defaults.
  228. Standing preference edits from separate CLI processes and the daemon preserve
  229. one another's accepted changes. A field edit reads the latest file while holding
  230. the shared writer lock and publishes a complete replacement atomically. No-op
  231. edits preserve comments and formatting; invalid existing content is reported
  232. without replacing it. If publication succeeds but durability cannot be confirmed,
  233. the caller receives an uncertain outcome and must read the preferences before
  234. another edit.
  235. ### Live computer audio (experimental)
  236. On the computer connected to the speaker LAN, install FFmpeg with the
  237. `libmp3lame` encoder and a PipeWire/PulseAudio-compatible audio server.
  238. Use `pactl list short sources` to find your output device's **monitor**
  239. source, then:
  240. ```bash
  241. fsonos stream Kitchen --input <output-source>.monitor
  242. # The default is --format pulse --input @DEFAULT_MONITOR@.
  243. # Use a dedicated PipeWire/PulseAudio virtual sink to stream only selected apps.
  244. # Ctrl-C ends the capture and restores the previous music if the room still plays this stream.
  245. ```
  246. For macOS with a configured loopback/virtual audio device, choose
  247. `--format avfoundation --input :<device-index>` (check
  248. `ffmpeg -f avfoundation -list_devices true -i ""`). The encoder starts locally;
  249. the Sonos player fetches MP3 from a randomly named, read-only endpoint bound
  250. only on the LAN interface used to reach that player. There is no public
  251. audio service or cloud relay. `--daemon-url` is not supported for live capture:
  252. the computer running `stream` must reach the players and be reachable by them.
  253. **Video lip-sync is experimental:** Sonos buffers HTTP-radio playback by
  254. seconds, and the delay drifts. `--latency-wav` measures the delay from a
  255. time-aligned reference/microphone recording, and
  256. `--sync-mpv <socket> --sync-input <source>` keeps an existing mpv player's
  257. `audio-delay` corrected while streaming. On Linux, launch mpv into a temporary
  258. output and use a room microphone for startup calibration and continuing
  259. correction in one command:
  260. ```bash
  261. fsonos stream Kitchen --virtual-output movie --sync-launched-mpv \
  262. --sync-microphone room_mic --sync-probe movie -- mpv movie.mkv
  263. ```
  264. Replace `room_mic` with your Pulse microphone source. `--sync-probe movie`
  265. opts into audible calibration noise on that output; omit it to measure from
  266. the movie's own audio. Managed launch supplies a private IPC socket and Pulse
  267. routing, waits for that exact child to become ready, and uses the existing
  268. ownership-checked delay correction and cleanup. User configuration and automatically loaded user
  269. scripts are disabled. See [Application streaming](docs/STREAM_APPLICATION.md)
  270. for the launch contract and [Acoustic calibration](docs/AUDIO_CALIBRATION.md)
  271. for the capture setup. Physical Sonos routing and video timing still require
  272. installation-specific acceptance; simulator and process tests do not establish
  273. audible synchronization.
  274. ### Offline speech and WAV announcements
  275. Linux discovers [FrankenTTS](https://github.com/Dicklesworthstone/franken_tts)
  276. (`ftts`) first, then `espeak-ng`. Install the engine and its local models before
  277. announcing; FrankenTTS's `ftts pull` prepares its models. An explicit Piper
  278. model takes priority in automatic Linux selection: set `piper_model` or
  279. `FSONOS_PIPER_MODEL` to a local `.onnx` file with its `.onnx.json` sidecar, or
  280. pass that model as `--voice`. macOS keeps using `/usr/bin/say` by default.
  281. `fsonos say "Dinner is ready" --voice <voice>` selects the backend's voice,
  282. and `fsonos doctor --only speech` identifies the executable.
  283. Configure the data directory's `speech.toml` on the machine generating speech:
  284. the daemon host with `--daemon`, or the CLI host with `--direct`. For native
  285. FrankenTTS:
  286. ```toml
  287. backend = "frankentts"
  288. timeout_secs = 180
  289. ```
  290. Alternatively, this custom adapter runs espeak-ng with a default voice:
  291. ```toml
  292. backend = "command"
  293. command = ["espeak-ng", "--stdin", "-w", "{output}", "-v", "{voice}"]
  294. voice = "en"
  295. ```
  296. The adapter sends text on stdin and substitutes exactly one `{output}` and
  297. optional `{voice}` inside individual arguments, without shell interpolation.
  298. `FSONOS_TTS_BACKEND`, `FSONOS_TTS_VOICE`, `FSONOS_PIPER_MODEL`, and
  299. `FSONOS_TTS_TIMEOUT_SECS` override their file settings. `FSONOS_TTS_COMMAND`
  300. is a JSON argument array (the same shape as `command` above) and selects the
  301. command adapter even when another backend is configured. A request's `--voice`
  302. overrides the configured voice. Synthesis defaults to 180 seconds; allowed
  303. `timeout_secs` values are 1–600.
  304. `announce --file` uploads the client's WAV bytes to the daemon. `POST /announce`
  305. and the daemon's MCP `announce` tool accept exactly one of `text`, `chime`, or
  306. `wav_base64` (standard padded base64), plus `rooms` and `volume`. Uploaded WAVs
  307. must be 16-bit PCM, at most 16 MiB and five minutes; all clips use the same
  308. validated media listener, volume caps and restoration. Announcement playback
  309. over MCP requires `fsonos serve`; standalone `fsonos mcp` has no media listener.
  310. Announcements across separate speaker networks use the media address reachable
  311. from each household's actual announcement leader. The daemon shares its routed
  312. event listeners; direct CLI announcements open and retain their own listeners
  313. on the required interfaces. If one household has no media route, its music and
  314. levels remain untouched while other households can complete. Synchronous,
  315. background and scheduled announcements share this behavior. See
  316. [Callback and media routing](docs/CALLBACK_RECOVERY.md).
  317. Add `--background` to return a daemon job ID immediately after admission:
  318. `fsonos say "Dinner is ready" --rooms Kitchen --background`. Use
  319. `fsonos announcements`, `fsonos announcements status <job-id>`, and
  320. `fsonos announcements cancel <job-id>` to follow or cancel it. The phone remote
  321. and dashboard use the same job controls. Queued cancellation avoids speaker
  322. writes; cancellation during local speech synthesis stops the engine and discards
  323. unpublished audio. Active cancellation checks ownership and finishes restoration before
  324. publishing its final receipt. Jobs retain per-household progress and partial
  325. restoration details. See [Announcement jobs](docs/ANNOUNCEMENT_JOBS.md) for the
  326. HTTP/MCP contract, permissions, and process-local retention.
  327. ## From anywhere on your tailnet
  328. The daemon is the only thing that leaves your LAN, and only onto your tailnet:
  329. ```bash
  330. fsonos serve # HTTP API + MCP on loopback and every tailnet address; prints the URLs
  331. fsonos tailscale setup # Serve: https://<mac>.<tailnet>.ts.net/ (API), :8443/mcp (MCP)
  332. FSONOS_DAEMON_URL=https://<mac>.<tailnet>.ts.net fsonos --json events # live changes anywhere on the tailnet
  333. FSONOS_DAEMON_URL=https://<mac>.<tailnet>.ts.net fsonos doctor --only lan # diagnose the daemon's LAN
  334. fsonos doctor --only tailscale # Tailscale up, the MagicDNS name, the daemon answering, Serve in front
  335. ```
  336. `fsonos doctor --daemon` and `fsonos --daemon-url <url> doctor` run the checks
  337. on the selected daemon, including its LAN, Spotify account, store and listener
  338. settings. `--only <prefix>` filters the report and its exit status: 0 for passes,
  339. 6 for warnings, 7 for failures. Text and `--json` have the same shape as local
  340. diagnosis. An unavailable or refusing daemon returns an error; an ordinary
  341. `fsonos doctor` or an explicit `--direct` diagnoses the local host.
  342. `fsonos events` follows a daemon URL over HTTP or certificate-validated HTTPS,
  343. using the same bounded event-journal reader as the local follower. `--since <id>` resumes after
  344. a previously printed event; `--count N` stops after N lines. Temporary read
  345. failures retry three times with backoff and retain the cursor. When the daemon
  346. reports lost journal history, an `events.reset` line comes before the available
  347. events, so consumers know to reread current state. Local followers also recover
  348. from brief disconnects and reload the daemon address and caller token after a
  349. restart, retaining simulator route confinement. Both paths validate the cursor,
  350. preserve `--count`, and stop promptly on Ctrl-C, including during a waiting read
  351. or retry backoff.
  352. - `fsonos tailscale setup` maps HTTPS on 443 (API) and 8443 (MCP) to the
  353. daemon's loopback ports, refuses to run while Funnel is on for either port,
  354. and never touches Serve config it didn't make (`status`, `teardown`,
  355. `--dry-run`).
  356. - Run the daemon with `--tailscale-serve` (or `FSONOS_TAILSCALE_SERVE=1`)
  357. behind Serve: it sets Serve up at startup and trusts the login Serve passes
  358. along, so each HTTP and MCP caller is named by their Tailscale login, a
  359. `[clients."alice@example.com"]` table in `policy.toml` sets what that
  360. person's devices may do, and the action log records who did what. Without the
  361. flag, HTTP and MCP callers arriving through Serve get the daemon's own
  362. loopback rights (`loopback-http`), and `fsonos doctor --only tailscale` warns
  363. about it. Direct tailnet listeners identify the actual socket peer with
  364. Tailscale WhoIs. Each MCP request, session and resource subscription retains
  365. its admitted caller, so concurrent agents have their own policy, action
  366. history and undo ownership. Multiple MCP listeners share the same live
  367. house. Native MCP never accepts the HTTP API's local CLI token as an
  368. uncapped CLI or stdio identity.
  369. - Both default listeners follow Tailscale after startup: HTTP on port 8099 and
  370. MCP at `/mcp` on port 8098. A late login, reconnect, address change or logout
  371. adds or retires the corresponding listeners without a daemon restart.
  372. Loopback remains available, and a failed automatic MCP bind retries without
  373. interrupting HTTP. Explicit `--http` / `--mcp-http` binds stay fixed;
  374. `--tailscale off` keeps the unconfigured listeners on loopback.
  375. - The daemon follows its host's owner login after startup too. A late Tailscale
  376. login gains owner rights without a restart; logout, account changes and
  377. tagged nodes retire the old owner. This works with explicit loopback binds
  378. behind Serve and with IPv6-only hosts. Brief lookup failures retain the last
  379. verified identity for at most four checks, while policy edits remain in force.
  380. - Point an agent at it from any tailnet machine:
  381. ```bash
  382. claude mcp add --transport http fsonos https://<mac>.<tailnet>.ts.net:8443/mcp
  383. curl https://<mac>.<tailnet>.ts.net/zones
  384. ```
  385. The full walkthrough (launchd, the firewall, tailnet policy grants, the
  386. Spotify sign-in) is in [`docs/DEPLOY.md`](docs/DEPLOY.md).
  387. ## For agents
  388. `fsonos serve` exposes the house as MCP tools (also `fsonos mcp` over stdio for
  389. a local agent, which hands the DJ, scenes, sleep timers and announcements to a
  390. running `serve`):
  391. ```text
  392. reads list_zones · list_rooms · list_players · get_zone · get_zone_state · list_favorites
  393. list_sonos_playlists · search_library · search_spotify · browse_library · playlist_contents · get_queue · search_queue
  394. get_play_mode · recent_plays · recent_actions · get_policy · doctor
  395. dj_status · dj_moods · dj_rehearse · events · echo
  396. list_scenes · get_scene · list_sleep_timers · list_schedules · get_eq
  397. list_announcements · get_announcement
  398. control play · play_favorite · play_sonos_playlist · add_to_queue · play_queue · remove_from_queue · move_in_queue
  399. set_play_mode · pause · resume · next · previous
  400. seek · set_volume · mute · group · ungroup · move_playback · group_all · set_eq
  401. announce · announce_start · cancel_announcement
  402. undo_last · undo_checked · preview_undo · search_and_play
  403. fade_volume · fade_and_pause
  404. dj dj_start · dj_skip · dj_stop · dj_steer · dj_feedback · dj_preferences · dj_prefer
  405. dj_sync · dj_sync_status
  406. house room_configuration · configure_rooms
  407. save_sonos_playlist · rename_sonos_playlist · remove_sonos_playlist
  408. remove_sonos_playlist_tracks · move_sonos_playlist_tracks
  409. save_scene · apply_scene · delete_scene
  410. set_sleep_timer · add_schedule · update_schedule · pause_schedule · resume_schedule · remove_schedule
  411. resources sonos://zones · sonos://zones/{room} · sonos://dj
  412. ```
  413. An agent that needs only the everyday tools can ask for fewer:
  414. `fsonos mcp --profile essentials` (or `FSONOS_MCP_PROFILE=essentials`) offers the
  415. 15 most tasks use (`list_zones`, `get_zone_state`, `list_favorites`, `play`,
  416. `play_favorite`, `search_library`, `pause`, `resume`, `next`, `set_volume`,
  417. `dj_start`, `dj_steer`, `dj_skip`, `undo_last`, `events`). The full profile adds
  418. the rest of the tools listed above, including native Sonos playlists. The
  419. house policy applies the same either way.
  420. Over `fsonos serve`, give an agent the short list per caller with
  421. `[clients."<login-or-tag>"] mcp_profile = "essentials"` in `policy.toml`; its
  422. `tools/list` is then trimmed to the essentials while every other caller still
  423. sees all the tools. The profile shapes only what is listed, never what the
  424. policy allows.
  425. `events` is how an agent keeps up with the house: call it once for the newest
  426. event id, then again with `since` and `wait_secs` to hear what changes (a
  427. track, a volume, a regroup, a player going offline, a logged action, the
  428. DJ's picks) as it happens.
  429. Every HTTP route that an MCP tool mirrors has that tool's name as its operation
  430. id, so an agent gets the same answer, and the same error code, either way. The API
  431. documents itself at `GET /openapi.json`.
  432. ## Safety for a house run by agents
  433. Undoing a volume, mute or volume fade restores the affected room settings while
  434. music continues from its current track and position. Group-volume undo restores
  435. each targeted room's earlier level. Later source changes, pauses, and settings
  436. in other rooms remain intact; changed or unreadable settings in the actual undo
  437. scope require another review. Current volume caps still apply. Actions recorded
  438. by older versions keep their original full-zone undo behavior.
  439. Tone undo also keeps its original scope: undoing a bass adjustment restores
  440. only bass, preserving later treble, loudness and playback changes. Normal undo
  441. requires the touched settings to remain as the action left them. Even a forced
  442. undo restores only fields the action reached; a refused or unsent later setting
  443. is left alone. See [Reviewed undo](docs/REVIEWED_UNDO.md).
  444. ```toml
  445. # policy.toml in the data directory. A missing file falls back to the
  446. # [defaults] below only (no quiet hours, room caps or client tables until you
  447. # add them); the other sections here are examples.
  448. [defaults]
  449. max_volume = 70 # per room
  450. max_step = 20 # largest single increase
  451. [quiet_hours] # local time; may wrap midnight
  452. start = "22:00"
  453. end = "07:00"
  454. max_volume = 25
  455. [rooms."Bedroom"]
  456. max_volume = 40
  457. [clients."alice@example.com"] # a person behind Tailscale Serve
  458. allow = ["list_zones", "get_zone_state", "play", "set_volume"]
  459. [clients."tag:agent"] # an agent that may do anything but change volume
  460. deny = ["volume"]
  461. ```
  462. - One choke point: every mutating call on every surface is authorized,
  463. snapshotted, carried out under the policy, and logged with who asked, the
  464. verdict (allow, clamp or deny) and what happened. That includes the DJ's
  465. own top-ups (client `dj`), a sleep timer's fade-out (client `sleep`), each
  466. audible self-test run (client `selftest`), `fsonos setup --test-play`'s
  467. short test play, the restore at the end of `fsonos stream`, and each step
  468. of a Spotify sign-in (never its code); none of these is undoable.
  469. - Starting a Spotify sign-in is the owner's: the CLI on the daemon's host
  470. (`fsonos setup`) and the owner's own devices (the tailnet login the
  471. daemon's host is logged in as, as the Apple and web remotes are through
  472. Tailscale) may; anyone else only when `policy.toml` grants it
  473. (`grant = ["auth"]` under the caller's `[clients."<login>"]`), since whoever
  474. signs in chooses whose library and taste the DJ follows. With
  475. `FSONOS_TAILSCALE_SERVE` set the login can come from Serve's header, which
  476. any process on the daemon's host could also send, so there this guard is
  477. only as strong as local access (see [`docs/DEPLOY.md`](docs/DEPLOY.md)).
  478. - `allow`, `deny` and `grant` name tools or whole classes of them: `volume`,
  479. `playback`, `grouping`, `queue`, `sound`, `house-config`, `announce`, `dj`,
  480. `auth`, `undo`, and `read` for every read; a `grant` adds to what an `allow`
  481. list names, and a `deny` beats both. Composite calls are held to each
  482. step they would take: a client denied `set_volume` cannot fade a volume,
  483. applies a scene with its volumes left as they are (and told so), and its
  484. scheduled volume changes are refused when they fire. `fsonos policy check`
  485. names a denial another tool of the same class still gets around.
  486. - A scene or a schedule is its saver's: saving over, deleting, pausing,
  487. resuming or removing one another client saved needs the owner (the CLI, or
  488. the owner's own tailnet login) or `manage_others = true` under the caller's
  489. `[clients."<key>"]`, so an agent cannot drop your wake-up alarm. One saved
  490. before fsonos kept who saved it is the owner's.
  491. - Edit `policy.toml` while the daemon runs and its next call obeys the new
  492. rules, no restart needed. An edit that does not parse is logged and the last
  493. good policy stays in force (`fsonos policy check` says what is wrong).
  494. - `fsonos undo` restores the volumes, grouping and what was playing in the
  495. zones the newest action changed (`--mine`: your own newest), and says what it
  496. could not. A scene deleted or saved over, and a schedule paused, resumed or
  497. removed, come back the same way (a schedule runs next at its next time). The `undo_last` tool and `POST /undo` undo the caller's own newest.
  498. Undo goes back at most an hour: past that, the house has moved on. It also
  499. refuses an action whose speakers someone changed since (in the Sonos app,
  500. say), naming what changed and putting nothing back; `fsonos undo --force`
  501. puts it back anyway. And it stops at a newer change it cannot put back (a
  502. queue edit, a sleep timer, a fade-out) rather than reach past it and roll
  503. back an older action instead.
  504. Eligible native queue removals, moves and successful playback replacements
  505. retain complete queue contents for recovery. Playing an album, playlist,
  506. resolved artist/show selection or container favorite can therefore be undone
  507. after a daemon restart, restoring duplicate occurrences, the selected track,
  508. elapsed time, shuffle/repeat mode and quiet playback intent. Queue ownership
  509. checks still apply with `--force`, and undo preserves policy volume reductions.
  510. Completed scenes can retain this recovery for playing and silent replacements
  511. on unchanged groups, including native saved playlists. Their undo rebuilds the
  512. original queue silently, restores the scene's volume and mute fields under
  513. current caps, then resumes only the original playback intent. Regrouping,
  514. DJ changes, queue-backup recalls, failed steps and superseded fades remain
  515. barriers to queue recovery.
  516. See [Queue undo](docs/QUEUE_UNDO.md) for the bounds and eligibility rules.
  517. - Callers the daemon cannot identify get read-only tools; the API and MCP
  518. listeners refuse wildcard and public binds (unless you pass
  519. `--allow-unsafe-bind`); the HTTP API checks Host and Origin and accepts POST
  520. bodies only as JSON.
  521. ## Design
  522. - **Pure where it can be.** SSDP, SOAP, GENA and DIDL encoding, planning, the
  523. policy, scene diffs, schedules and the DJ's picks are pure functions, unit
  524. tested without a network; I/O sits behind narrow traits.
  525. - **Events, not polling.** The live model follows GENA, renews subscriptions,
  526. and resurveys when the house changes; group-wide commands are addressed to
  527. the coordinator automatically.
  528. - **S1 and S2 together.** Each player's generation is recorded, and the code
  529. branches only where the protocols differ; S1 and S2 rooms never share a
  530. group, and the commands say so instead of failing quietly.
  531. - **End to end against a simulator.** `fsonos-sim` serves the real protocols
  532. on loopback (queues, favorites, GENA, sleep timers, media fetches, a clock
  533. tests can move), and the e2e suite drives the real `fsonos` binary against
  534. it, logging every step as JSON lines.
  535. - **No site data.** Your rooms, addresses and tokens are learned at runtime and
  536. stored locally; the repository holds none of them.
  537. ## Architecture
  538. ```
  539. SSDP / UPnP-SOAP / GENA (your LAN, port 1400)
  540. │
  541. ┌───────────────────▼───────────────────┐
  542. │ fsonos-proto discovery · SOAP · │
  543. │ events · DIDL/URIs │
  544. └───────────────────┬───────────────────┘
  545. │
  546. ┌───────────────────▼───────────────────┐ ┌────────────────┐
  547. │ fsonos-core inventory · live model │ │ fsonos-spotify │
  548. │ policy · scenes · schedules · store │◄──┤ library + DJ │
  549. └───────────────────┬───────────────────┘ └───────┬────────┘
  550. │ │
  551. ┌──────────────┬───────────┼───────────────┐ Spotify Web API
  552. ▼ ▼ ▼ ▼ (read-only, your account)
  553. fsonos-api fsonos-mcp fsonos-cli fsonos-tailscale
  554. (HTTP API) (MCP tools) (`fsonos`) (tailnet presence)
  555. ```
  556. | Crate | Responsibility |
  557. |---|---|
  558. | `fsonos-types` | Shared domain vocabulary (players, groups, tracks) |
  559. | `fsonos-proto` | SSDP, UPnP/SOAP, GENA events, DIDL-Lite and URIs |
  560. | `fsonos-core` | Inventory, the live model, grouping, moving, policy, snapshots and undo, scenes, schedules, sleep timers, announcements, the doctor, the local store |
  561. | `fsonos-spotify` | Read-only Spotify library sync and the DJ: works, picks, steering, feedback |
  562. | `fsonos-api` | The shared surface (requests, planning, policy, logging) and the HTTP API (`fastapi_rust`) |
  563. | `fsonos-mcp` | The MCP server and its tools and resources (`fastmcp_rust`) |
  564. | `fsonos-cli` | The `fsonos` binary: the CLI, `serve`, `setup`, `doctor`, `sim` |
  565. | `fsonos-tailscale` | Is this host on a tailnet, at which addresses and name; connect URLs; who a tailnet caller is |
  566. | `fsonos-sim` | The virtual Sonos house the tests (and `fsonos sim`) run against |
  567. Built on the author's Rust stack: [`asupersync`](https://github.com/Dicklesworthstone/asupersync)
  568. (async runtime), [`fsqlite`](https://github.com/Dicklesworthstone/frankensqlite)
  569. (local store), [`fastmcp_rust`](https://github.com/Dicklesworthstone/fastmcp_rust),
  570. and [`fastapi_rust`](https://github.com/Dicklesworthstone/fastapi_rust). The full
  571. design is in [`COMPREHENSIVE_PLAN_FOR_FRANKENSONOS.md`](COMPREHENSIVE_PLAN_FOR_FRANKENSONOS.md).
  572. ## Installation
  573. No published release binaries yet (pre-release). CI builds Apple Silicon and
  574. x86_64 Linux binaries for every push to `main`, but those artifacts expire with
  575. the run; a release download starts with `0.1.0`. Until then, build from source
  576. (the toolchain is pinned):
  577. ```bash
  578. git clone https://github.com/Dicklesworthstone/frankensonos
  579. cd frankensonos
  580. cargo build --release # the toolchain is pinned in rust-toolchain.toml
  581. cargo test --workspace # unit, golden and end-to-end tests (no speakers needed)
  582. ```
  583. The binary is `target/release/fsonos`. Run it on a machine on the same LAN as
  584. your speakers; for access from anywhere, that machine also joins your tailnet.
  585. `fsonos setup` takes it from there. To run the daemon at boot, see
  586. [`docs/DEPLOY.md`](docs/DEPLOY.md) (launchd plus Tailscale).
  587. ## Roadmap
  588. Shipped: discovery and topology across S1 and S2, coordinator-addressed control
  589. and grouping, the GENA live model and self-healing, the DJ (drawing on
  590. everything you save or like on Spotify, plus your top tracks, recent plays and
  591. own playlists, in any genre) with your standing preferences, steering,
  592. explanations and feedback, scenes, sleep timers and schedules, announcements,
  593. the house policy with quiet hours, the action log and undo, `doctor` and
  594. `setup`, the simulator, and the CLI, HTTP API and MCP server, on loopback and
  595. your tailnet. The CLI goes through a running daemon when there is one, with
  596. room-name completions for zsh, bash and fish, and the daemon serves a web
  597. remote (rooms, now playing with album art, volume and mute, pause everywhere,
  598. the DJ and scenes) to any
  599. device on your tailnet. The daemon keeps the DJ's library fresh on its own,
  600. and `fsonos dj sync` refreshes it on demand.
  601. The graphical [Listening Studio](docs/DASHBOARD.md) at `/dashboard` also offers
  602. **Standing taste** for persistent DJ preferences across every group, including
  603. favored and avoided music, default energy, explicit content, pins and bans.
  604. **Rehearse a set** uses the real planner to preview whole works, reasons and
  605. hourly energy and variety for a chosen group and start time. Its temporary mood
  606. and filters affect only that preview; rehearsing never starts music, edits a
  607. queue, saves steering or records hypothetical listening history.
  608. The phone remote’s **Queue → Save queue as playlist** reviews the retained
  609. queue and creates a native playlist without interrupting playback. **Music & DJ
  610. → Save queues as Sonos playlists** keeps the last save result available after a
  611. room disappears or changes groups. If a reply is lost, it offers an explicit
  612. catalog check for the original household before another save; nothing is
  613. resubmitted automatically. **Browse saved playlists** opens the native catalog
  614. without starting music or replacing an existing source draft. See
  615. [Web queue controls](docs/WEB_QUEUE.md).
  616. Both web remotes also edit saved Sonos playlists directly. **Edit saved track**
  617. selects an occurrence, and **Manage saved playlist → Edit saved tracks** reviews
  618. a contiguous range for removal or a move. Review shows every affected track
  619. and the original destination. The native operation checks the complete saved
  620. order and its revision, retains duplicate occurrences, and leaves current
  621. playback untouched. The same operations are available through CLI, HTTP and
  622. MCP; see [Saved playlist editing](docs/SONOS_PLAYLISTS.md#remove-or-reorder-saved-tracks).
  623. Saved albums, liked tracks, and missing album-track pages now resume from
  624. private checkpoints after an interrupted read or Spotify cooldown. Each pass
  625. uses at most 512 page requests; the daemon continues unfinished work at its
  626. next check. The last complete library remains playable while the scan is
  627. incomplete. Resumed pages are checked again before publication, and an account
  628. switch or a competing refresh cannot publish an older prepared result.
  629. The DJ also checks the accepted account and catalog revision before selecting
  630. new music. An account switch or a library update from another process retires
  631. its stale selection pool, including when a refresh fails after changing the
  632. store. A failed or inconsistent rebuild cannot select from that old pool;
  633. already queued music stays in place. An unchanged catalog reuses the cached
  634. pool, so listening-history updates do not trigger a full library scan.
  635. New Spotify reads also exclude tracks the provider marks restricted, even
  636. when its optional playback flag is absent or says playable. Restrictions on
  637. returned album metadata apply to that album's tracks too. This applies to saved
  638. music, taste reads, catalog search, artist selections and whole-work expansion
  639. wherever the response supplies that restriction. A failed or malformed refresh
  640. retains the last accepted library; changing your explicit content preference
  641. does not override a provider restriction.
  642. The sync panel and CLI/HTTP/MCP status distinguish reading, verification, and
  643. prepared music waiting for publication. Retained page and track counts, retry
  644. deadlines, and actual failures survive daemon restart, including before the
  645. first completed library. A normal bounded pause returns pending status, and
  646. the web panel keeps observing it. `fsonos setup` shares the daemon's refresh
  647. worker when available and explains unfinished intake without asking you to
  648. repeat a successful Spotify sign-in.
  649. The daemon also checks [recent Spotify listening](docs/RECENT_LISTENING.md)
  650. before its normal background pass, so the next DJ selection can avoid music
  651. you just heard on another device without waiting for the daily library sync.
  652. Each check reads only the latest 50 plays, shares Spotify cooldowns, and merges
  653. accepted evidence under the exact account identity. Delayed full refreshes
  654. cannot erase newer listening. The sync panel and CLI/HTTP/MCP show this
  655. observation's freshness separately from the last full-library refresh.
  656. Whole-work album completion also retains private page proofs across interruptions.
  657. Each pass still uses at most eight catalog requests, including root checks and
  658. verification. A resumed album is published only after its retained pages are
  659. rechecked; changed metadata or coverage discards the partial scan and gives later
  660. albums a turn. Verification progress survives restarts, and checkpoints older
  661. than seven days start again. Small albums read in one uninterrupted pass do not
  662. need an extra scan.
  663. Large libraries continue artist genre enrichment in background passes of up to
  664. 50 artists. Progress survives restarts, failed artists yield to later ones,
  665. and newly learned tags reach the DJ's next selection without rereading saved
  666. music. `fsonos dj sync --status`, the HTTP and MCP status tools, and the web
  667. sync panel show current progress and Spotify cooldowns separately from the last
  668. full refresh. New genre evidence that reveals a classical work also feeds the
  669. existing whole-work album completion queue.
  670. Catalog cache reads are batched, so rebuilding a large DJ pool avoids one
  671. database call per artist. Failed metadata rows preserve the tracks' stored
  672. tags while healthy entries remain usable.
  673. Playlist background passes add proved snapshot music in one transaction while
  674. preserving current saved-track metadata and stronger taste weights. Overlapping
  675. full and background refreshes cannot replace newer accepted candidates or
  676. playlist observations. A full refresh that loses this race keeps its prepared
  677. saved-library read for retry and does not advance the last successful refresh.
  678. Followed-artist directories also continue past the first 1,000 artists. Each
  679. pass reads at most 20 directory pages, including verification; private cursor
  680. and artist evidence survives restart. Resumed scans recheck their boundaries
  681. and retained pages before a full refresh reconciles membership and taste
  682. weights. Background passes retain directory progress and genre evidence without
  683. rewriting playable music. The sync panel and CLI/HTTP/MCP distinguish reading,
  684. verification, and a verified directory awaiting full reconciliation. This reader
  685. takes turns with playlist, album, and genre completion and shares Spotify's
  686. cooldown. Private evidence is bounded to 100,000 artists, 16 MiB, and seven days;
  687. a reached cache bound is reported as incomplete and stops automatic intake.
  688. Followed and top artists without music in the fresh library get a fair turn
  689. through [background artist sampling](docs/ARTIST_SAMPLING.md). A full refresh
  690. samples at most 50 artists and up to three tracks each, then saves a finite
  691. backlog for the daemon to finish in similarly bounded passes. Progress survives
  692. restarts and shares cooldowns and fair scheduling with playlist, album, genre
  693. and followed-directory work. Once the cohort is complete, its background reads
  694. stop until a new full refresh establishes another cohort.
  695. Artist IDs distinguish namesakes, and captured artist signals preserve taste
  696. weights without rereading saved music or the artist directories. Publication
  697. adds playable samples while preserving current saved-track metadata and stronger
  698. weights; the account generation, exact prior progress and new music commit
  699. together. Failed or superseded passes cannot skip a batch or overwrite a newer
  700. account. Cached samples for deferred or unavailable artists remain playable.
  701. CLI, HTTP, MCP and the web sync panel show artist-sampling progress separately
  702. from the last full refresh. This remains a bounded sample of each artist's
  703. catalog, with the existing catalog fallback when top tracks are unavailable.
  704. DJ starts, live steering and rehearsals accept `--strict` to keep all requested
  705. steering filters, including exclusions, even when matching music is scarce.
  706. A small matching set stays playable; if no permitted work matches, new
  707. selections wait with an explanation instead of relaxing the filters. Existing
  708. queued music stays in place. The web remote, HTTP API and MCP tools expose the
  709. same option, and saved scenes, routines and moods retain it. Existing saved
  710. directions keep their adaptive behavior unless strictness is requested.
  711. For example, `fsonos dj steer Kitchen --not-genre opera --strict --for 2h` keeps
  712. that exclusion for new selections during the two-hour session. Clearing the
  713. steer returns to the time-of-day program. A missing mood or unreadable active
  714. session now defers refills visibly instead of losing its constraints; an
  715. expired override no longer blocks the normal program.
  716. Scheduled DJ starts and DJ scenes check their prospective direction, playable
  717. music, required household Spotify rendering, and current queue prerequisites
  718. before the occurrence is marked as run. Queue checks cover ownership, readable
  719. contents and capacity; a scene's future coordinator is checked after regrouping.
  720. Temporary readiness failures retry after 30 seconds within the existing
  721. grace period. Once dispatch begins, failures are not replayed. Direct scene
  722. application checks every permitted DJ before regrouping, volume cap changes,
  723. fades, queues, or stored steering change. These checks preserve the current
  724. feed and selection state; a complete retained DJ queue can resume without new
  725. library picks.
  726. Scenes also check their Sonos favorites and Spotify renderer prerequisites
  727. before changing any group or volume. A deleted or ambiguous favorite, an
  728. unplayable shortcut, or missing Spotify linkage leaves the current music
  729. untouched. Scheduled scenes retry temporary catalog failures within the same
  730. ten-minute grace period, then skip the missed occurrence. Each source is read
  731. again when executed; a later playback failure is reported without replaying
  732. the scene. Album and playlist sources can use their household's own container
  733. favorite without requiring an unrelated track favorite.
  734. A favorite or URI scene with `playing = false` loads its selected music without
  735. starting it, including when different music was playing or the earlier
  736. playback snapshot was unavailable. Both the caller's and the saved author's
  737. pause permissions apply to that silent load, along with permission to play
  738. the selected source.
  739. Next:
  740. - Real-hardware CI (a nightly `fsonos selftest` against a real house), then
  741. `0.1.0` with prebuilt binaries; CI already builds them for Apple Silicon and
  742. x86_64 Linux on every push to `main`.
  743. ## Scope & privacy
  744. FrankenSonos controls hardware you own, on your own network, and reads your own
  745. Spotify library with your own credentials (read-only, PKCE). It never writes
  746. to device firmware or changes anything on the speakers, and it handles no
  747. secrets beyond your own local OAuth cache. This repository is public and
  748. contains no site data (addresses, serials, tokens, room lists); all of that is
  749. learned at runtime and kept locally. The full boundary is in
  750. [`docs/SCOPE.md`](docs/SCOPE.md).
  751. ## Limitations
  752. - It is pre-release: simulator-verified end to end and run on one real
  753. two-household house, with a live self-test (`fsonos selftest`) but no
  754. real-hardware CI yet. Expect interfaces to change until `0.1.0`.
  755. - Sonos plays Spotify through its own music-service integration; the Spotify
  756. Web API is only used to read your library. Spotify must be linked once in
  757. each household's Sonos app, and the per-household render parameters are
  758. learned from your own Sonos favorites. Rendering was verified on real S1 and
  759. S2 players ([`docs/PROTOCOL.md`](docs/PROTOCOL.md) §4).
  760. - The DJ reads your library through a Spotify app of your own (create one at
  761. developer.spotify.com/dashboard); `fsonos setup` asks for its client id and
  762. keeps it in the data directory for the daemon.
  763. - The DJ's taste comes from your liked tracks and saved albums, plus your top
  764. tracks, recent plays and own playlists, leaning toward the artists you follow
  765. and play most (read-only scopes you grant at sign-in; without them it uses
  766. your library alone, and `doctor` says so). `dj steer`, standing preferences
  767. and `moods.toml` are your overrides. Spotify gives new apps no audio
  768. features, so a song's energy comes from its artists' genre tags, and a
  769. classical movement's from its tempo marking. New saves and likes reach the
  770. DJ at the daemon's next daily read of your library, or at once with
  771. `fsonos dj sync`.
  772. - You run the daemon on a machine on your speaker LAN (a Mac mini, a Pi, a
  773. NAS). The deploy docs describe macOS launchd; Linux speech uses a locally
  774. installed engine and models.
  775. - A sleep timer fades only through the daemon: the CLI's when one is running,
  776. HTTP and MCP. `fsonos sleep --direct`, or `fsonos sleep` with no daemon,
  777. sets the speaker's own timer, which pauses without a fade.
  778. - Spotify artist links resolve to up to ten actual tracks through the owner's
  779. Spotify sign-in: top tracks, or a bounded album sample when that endpoint is
  780. unavailable. `fsonos play Kitchen <artist-link>` replaces the queue and plays
  781. in order; `--next` and `--queue` add the selection without starting music.
  782. The phone, dashboard, HTTP and MCP use the same path. The sample is not artist
  783. radio or a complete discography. Show links use the same actions with up to
  784. ten available episodes from the show's first episode page, in Spotify's
  785. returned order. Episodes also play directly. See
  786. [Artist and show playback](docs/ARTIST_PLAYBACK.md).
  787. Artist/show containers are expanded into concrete tracks or episodes before
  788. playback; the speakers use their own linked Spotify account. Authored scenes
  789. and scheduled scene recalls also accept these links. Each recall prepares its
  790. selections before changing rooms or volumes, and paused scenes load silently.
  791. - The API and MCP server take their remote caller identity from Tailscale:
  792. WhoIs on a direct tailnet listener, or the login header behind Serve when
  793. the daemon runs with `FSONOS_TAILSCALE_SERVE`. Both apply the house policy's
  794. `[clients]` tables to that caller. A peer Tailscale cannot name uses
  795. `unknown` and is read-only by default. MCP resource subscriptions require
  796. `events` plus the permissions needed to read the selected document; resource
  797. reads apply the caller's current policy.
  798. ## FAQ
  799. **Does this replace the Sonos app?** For day-to-day control, grouping, the DJ,
  800. scenes, schedules and announcements, yes. You still link Spotify once in the
  801. official app so Sonos can render it.
  802. **Does it modify my speakers or their firmware?** No. It sends them the same
  803. local control requests a controller always has. Nothing is flashed or changed
  804. on the devices.
  805. **Why can't it just use the Spotify API to play music?** The Spotify Web API
  806. cannot target a Sonos renderer. Sonos plays Spotify through its own
  807. integration, so FrankenSonos builds the right `x-sonos-spotify:` request for
  808. *your* household, from parameters learned from your own favorites.
  809. **S1 and S2 at once?** Yes. Both households appear together, every command
  810. addresses the right one, and `Room@S1` / `Room@S2` picks between rooms with the
  811. same name.
  812. **Can my AI agent control it from another city?** Yes, over your Tailscale
  813. tailnet: the agent reaches the daemon, and the daemon reaches the speakers on
  814. the LAN. The house policy bounds what it may do, and `undo` puts it back.
  815. **Can I try it without Sonos speakers?** Yes: `fsonos sim` runs a virtual S1
  816. and S2 house on loopback, and every command and the MCP server work against it.
  817. **What streaming services work?** Spotify first, plus anything you have saved
  818. as a Sonos favorite (stations, playlists, other services). The control layer
  819. is source-agnostic.
  820. ## About Contributions
  821. Please don't take this the wrong way, but I do not accept outside contributions
  822. for any of my projects. I simply don't have the mental bandwidth to review
  823. anything, and it's my name on the thing, so I'm responsible for any problems it
  824. causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also
  825. have to worry about other "stakeholders," which seems unwise for tools I mostly
  826. make for myself for free. Feel free to submit issues, and even PRs if you want to
  827. illustrate a proposed fix, but know I won't merge them directly. Instead, I'll
  828. have Claude or Codex review submissions via `gh` and independently decide whether
  829. and how to address them. Bug reports in particular are welcome. Sorry if this
  830. offends, but I want to avoid wasted time and hurt feelings. I understand this
  831. isn't in sync with the prevailing open-source ethos that seeks community
  832. contributions, but it's the only way I can move at this velocity and keep my
  833. sanity.
  834. ## License
  835. MIT License with an OpenAI/Anthropic rider; see [`LICENSE`](LICENSE).
  836. (`LicenseRef-MIT-OpenAI-Anthropic-Rider`; not plain MIT.)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.