@groovenet/player 0.1.3 → 0.1.5

package/MPRIS.md

@@ -0,0 +1,97 @@
+# Desktop controls — issue #650 design and smoke tests
+
+## Linux design
+
+`groovenet-mpris` is an opt-in foreground companion to an already running
+`groovenet player start --detach` daemon. Install `@groovenet/player` with optional
+dependencies enabled (the CLI also depends on this package). From a checkout,
+build contracts → client → player, then run:
+
+```sh
+node packages/groovenet-player/build/mprisBin.js
+```
+
+The bridge uses `dbus-next` 0.10.2 directly, with native JavaScript BigInt for
+MPRIS's signed 64-bit microsecond values. The dependency is optional and dynamically
+loaded only on Linux with `DBUS_SESSION_BUS_ADDRESS`. No display is needed for
+MPRIS; a user session bus is sufficient. The library's optional native Unix FD
+addon is unnecessary for these interfaces; no audio, file descriptors or credentials
+are sent over D-Bus. A missing dependency or unavailable bus reports a bridge error
+and never changes daemon lifetime. Installing with `--omit=optional` leaves the
+headless daemon usable. Nothing starts this bridge automatically.
+
+The service owns `org.mpris.MediaPlayer2.groovenet` and exports the root and
+Player interfaces at `/org/mpris/MediaPlayer2`. A second bridge refuses to take
+over that name. It takes an initial `status` snapshot over the existing private
+Unix socket, then subscribes to `state` events. Those already contain both
+track-change and position information, so consuming their separate notifications
+would duplicate updates. Metadata uses the queue-entry ID (hex encoded into a
+valid object path), title, artist, album and known duration. It never publishes
+authenticated stream URLs. Normal position updates do not emit PropertiesChanged.
+
+Play, pause, toggle, next, previous and seeks forward to daemon RPCs. Absolute
+seeks reject stale track IDs; relative seeks clamp to zero or skip beyond the
+known duration. The additive `stop` RPC pauses the backend, clears current playback
+state and retains the queue and daemon. It differs from `shutdown` and the CLI's
+`player stop`, which still shuts down the daemon. A later play reloads the stopped
+queue entry. Transport errors return through D-Bus rather than becoming unhandled
+promise rejections. SIGINT/SIGTERM close the bridge connection and bus. Loss of the
+daemon or bus closes the bridge; restart it after restarting the daemon.
+
+References: [dbus-next](https://github.com/dbusjs/node-dbus-next),
+[MPRIS Player specification](https://specifications.freedesktop.org/mpris/latest/Player_Interface.html).
+
+## macOS decision and scope
+
+macOS is deferred. Apple's
+[MPNowPlayingInfoCenter](https://developer.apple.com/documentation/mediaplayer/mpnowplayinginfocenter)
+and [MPRemoteCommandCenter](https://developer.apple.com/documentation/mediaplayer/mpremotecommandcenter)
+are native MediaPlayer framework APIs. Node's standard library does not expose
+them. Supporting them here would require a native binding or a separately built
+Swift/Objective-C helper with its own run loop, packaging and lifecycle. That
+exceeds the issue's lightweight integration constraint. The socket-subscriber
+boundary allows such a helper later without changing the playback core. Running
+this bridge on macOS prints that it is disabled and exits successfully.
+
+Also out of scope: artwork fetching, graphical UI raising, URI loading, queue
+editing over D-Bus, shuffle/repeat, volume control, playback rate changes,
+automatic bridge startup/reconnection, and desktop hotkey binding installation.
+Desktop environments usually route media keys to MPRIS; minimal window managers
+can bind them to the `playerctl` commands below.
+
+## Manual acceptance smoke test
+
+In a Linux desktop session, with mpv, dbus and playerctl installed:
+
+1. Start `groovenet player start --detach`, add two downloaded tracks with
+   `groovenet player queue add '<query>'`, and run `groovenet-mpris` in another
+   terminal (or the checkout command above).
+2. `playerctl --player=groovenet play`; `playerctl --player=groovenet status`
+   should print `Playing`.
+3. `playerctl --player=groovenet metadata` should show `xesam:title`,
+   `xesam:artist`, `xesam:album` and a valid `mpris:trackid`.
+4. `playerctl --player=groovenet play-pause` should pause, then resume on a
+   second call. Verify the desktop's play/pause media key does the same.
+5. `playerctl --player=groovenet next` and `previous` should update metadata
+   and audible playback. Verify the desktop's next/previous media keys.
+6. `playerctl --player=groovenet position` reports seconds;
+   `position 12.5` seeks absolutely and `position 2+` seeks relatively.
+7. `playerctl --player=groovenet stop` reports Stopped; `play` restarts the
+   retained entry. Ctrl-C the bridge; the daemon should keep playing.
+8. Stop the daemon while the bridge is running: the bridge should exit and
+   release its bus name. Start two bridges: the second should fail cleanly.
+9. `env -u DBUS_SESSION_BUS_ADDRESS groovenet-mpris` should exit successfully
+   with a disabled message. Repeat daemon startup without a desktop/session bus
+   and with optional npm dependencies omitted: playback must still work.
+
+An automated Linux wire smoke test uses an in-memory audio backend and the real
+D-Bus daemon/playerctl, requiring no server or audio device:
+
+```sh
+dbus-run-session -- node packages/groovenet-player/scripts/mpris-smoke.mjs
+```
+
+This checks status, play/pause, metadata, next/previous, absolute/relative position,
+stop, and that closing the bridge leaves playback usable. Unit tests cover mapping,
+property notifications, stale/invalid seeks, failures and cleanup; use
+`npm run test:coverage --workspace @groovenet/player`.

package/OWNTONE.md

@@ -0,0 +1,145 @@
+# OwnTone backend (single output)
+
+`OwnToneBackend` controls a **dedicated** OwnTone engine. Groovenet owns the
+queue; OwnTone holds one indexed track at a time. mpv remains the default.
+Persistent named players, server APIs and independent listening sessions are
+#693; remote TUI control is #694. Synchronized speaker groups are deferred.
+
+## Engine requirements
+
+Stock OwnTone 29.3 does not expose a completion reason through its JSON API.
+The backend requires the additive `groovenet_terminal` v1 extension in
+[`owntone/terminal-v1.patch`](owntone/terminal-v1.patch). It refuses an unpatched
+engine with `ENGINE_INCOMPATIBLE` before changing outputs or playback.
+
+This introduces a maintained engine patch, rather than depending only on the
+upstream container. The Dockerfile pins upstream 29.3 commit
+`d6fb3edf5831de38134ebd92fcf09a730ddd37aa` and verifies its source archive hash.
+The upstream license is GPL-2.0. The image includes the corresponding source,
+license and patch at `/usr/src/owntone`; retain these when distributing it.
+Alpine packages are resolved at build time; this is not a bit-reproducible image.
+
+```sh
+# From the repository root:
+docker build -t groovenet-owntone:692-test packages/groovenet-player/owntone
+npm run build --workspace @groovenet/contracts
+npm run build --workspace @groovenet/client
+npm run build --workspace @groovenet/player
+node packages/groovenet-player/owntone/smoke.mjs
+```
+
+The smoke test creates and removes a network-isolated container with generated
+files and a dummy output. It publishes no ports and never uses real speakers.
+The engine image does not start Avahi/D-Bus itself: a deployment must supply
+those services. The smoke script shows an isolated startup sequence, **not** a
+production Compose service. Production worker/Compose integration is #693.
+
+For AirPlay discovery on Debian, use the LAN network/interface with Avahi and
+D-Bus available. `bind_address = "127.0.0.1"` also restricts discovery to
+loopback, so it is suitable only for the isolated test. Restrict engine access
+with firewall/trusted networks and an admin password when it binds to the LAN;
+do not expose an unauthenticated control API. The CLI's `insecure_tls` setting
+applies to the Groovenet client/mpv, not the OwnTone connection.
+
+Configure `speaker_autoselect = no`. The patch disables automatic speaker
+resurrection after a failed streaming connection; only an explicit play or
+output-selection request can select a receiver again. This does not prevent
+another application from taking over an AirPlay receiver. Busy/auth status is
+best-effort engine information, not a cross-application speaker reservation.
+
+## Shared audio delivery
+
+Mount Groovenet's audio volume **read-only** into OwnTone and configure that
+path in its `library.directories`. Set `owntone_library` to the absolute Linux
+path **inside the engine**, for example `/srv/media`. The CLI does not read
+that local path. It maps each track's `local_audio_url` to an engine-side file
+URL, then looks up the exact indexed path using `/api/library/files`.
+Directory contents are read afresh on each load; no stale track-ID cache or
+whole-library scan is required by the adapter.
+
+OwnTone must finish indexing before a file can play; a missing/unindexed or
+ambiguous file is refused. The backend does not force a library rescan. It
+accepts finite indexed files with a known positive duration, not Internet radio
+or HTTP streams. Standard relative names, `/audio/` and `/app/audio/` prefixes,
+and legacy app audio URLs are supported. Traversal, backslashes, NULs and
+ambiguous path segments are refused. There is no basename fallback.
+
+Groovenet credentials remain on Groovenet API requests. Indexed file delivery
+needs no bearer token; sources containing HTTP headers or non-file URLs are
+explicitly rejected, never forwarded with authentication silently removed.
+
+## CLI setup
+
+Run the daemon on the host that should control OwnTone. These settings apply
+when a daemon starts; stop an existing daemon before changing backends.
+
+```sh
+groovenet config set owntone_url http://127.0.0.1:3689/api
+groovenet config set owntone_library /srv/media
+groovenet config set player_backend owntone
+groovenet player start --detach
+groovenet player devices list
+groovenet player devices select <output-id>
+groovenet player queue add "miles davis"
+groovenet player play
+```
+
+Alternatively keep `player_backend` unset and pass `--backend owntone` to
+`player` or `player start`. Set `owntone_output` to remember one stable engine
+output ID for subsequent starts. `owntone_password` supplies HTTP Basic admin
+authentication; keep the CLI config private. Human config output masks it;
+`config show --json`, like the existing API-key behavior, includes credentials.
+`--backend mpv` overrides the persisted choice. Artwork is an mpv-only setting.
+
+The Unix socket and its v1 protocol are unchanged. A TUI connects to an existing
+daemon regardless of the requested backend; restart it to change engines.
+This is still a local daemon, not the remote server-player API from #693.
+
+## Events, interruption and cleanup
+
+The patch snapshots a random per-process instance ID, sequence, queue item ID
+and terminal reason on the engine player thread. EOF is recorded only at the
+playback boundary; input failures and failed/lost output callbacks mark the
+source as failed, suppressing successful EOF. Stop and skip are not inferred
+from elapsed time, play counts or an empty engine queue. The adapter emits
+`ended` only for a new EOF of its owned item in the same engine instance, with
+no foreign replacement queue. Duplicate/stale events cannot advance twice.
+
+All adapter commands and polls are serialized. API outages trigger read-only
+reconciliation: no load, resume or output selection is retried. A still-owned
+active item can be controlled explicitly after recovery. The core retains its
+error state until an explicit playback command. A completion observed across
+a connection gap is treated as uncertain and **does not advance**. A restarted
+engine, replaced queue or terminal interruption drops ownership and requires
+an explicit new play. This favors preserving the queue over guessing EOF.
+
+`close()` stops/clears/releases only a still-owned or completed session (or an
+idle explicit output selection), and leaves a foreign session/output alone.
+After ownership is lost or the API remains unreachable, cleanup cannot promise
+to stop the engine; use the engine controls if necessary. The engine must not
+be shared with another queue controller. Separate engines are needed for
+independent player queues; concurrent instances remain unvalidated.
+
+Typed errors include `ENGINE_UNAVAILABLE`, `ENGINE_AUTH`, `ENGINE_TIMEOUT`,
+`ENGINE_API`, `ENGINE_INCOMPATIBLE`, `DEVICE_UNAVAILABLE`, `DEVICE_BUSY`,
+`DEVICE_AUTH`, `NO_AUDIO`, `STREAM_FAILED` and `PLAYBACK_INTERRUPTED`.
+Authentication of AirPlay receivers is managed in OwnTone, outside Groovenet.
+
+## Volume and verification limits
+
+`setVolume` sends 0–100 to the selected engine output. It cannot guarantee an
+acoustic level. Lounge Room Audio uses Shairport's
+`ignore_volume_control = "yes"`, so sender volume does **not** attenuate its
+USB output. The snapshot volume is the last requested Groovenet value, not a
+measured receiver level; OwnTone may report -1 when no output is selected.
+Generate attenuated audio for hardware tests, rather than relying on volume 5.
+
+The #691 prototype confirmed audible single-speaker AirPlay on Lounge Room
+Audio, plus engine pause/seek/resume and USB PCM activity. That used the stock
+29.3 image, not this patched build. The new adapter/patch has isolated dummy
+output validation for natural EOF, external stop and queue replacement,
+pause/resume/seek/volume API acceptance, and engine restart handling. Fake API
+tests cover transport/auth/timeouts, ownership, stale events and reconciliation.
+Patched-engine AirPlay takeover, receiver disconnect, effective volume and
+audible seek accuracy still need hardware verification. No synchronized or
+concurrent-engine playback is claimed.

package/README.md

@@ -45,6 +45,9 @@ and `isPlay` are the pure rules: a track of 30 seconds or more counts after
 `min(50% of its duration, 240 s)` of accumulated play time, where only forward
 progress while playing is counted. The CLI wires it to `POST /api/spins` with
 `medium: "digital"` (`player_log_plays` / `--log-plays`).
+Persistent server players apply the same threshold per queue entry and deliver
+owner-library plays through the app's `/api/spins` endpoint. Pending deliveries
+are stored in Postgres for retries across worker restarts.
 
 `MpvBackend` does not install mpv. Install it separately and make it available
 on `PATH`, or pass an executable path in the constructor. `close()` stops the
@@ -55,3 +58,17 @@ implementation for consumers that need to exercise the core without audio.
 
 Build with `npm run build --workspace=@groovenet/player` after building
 `@groovenet/client`.
+
+Linux desktop media controls are available through the optional `groovenet-mpris`
+companion process. It subscribes to an existing daemon over its socket and exposes
+MPRIS for `playerctl` and desktop media keys. It is off unless explicitly started,
+and exits disabled without a Linux session bus. See [MPRIS.md](MPRIS.md) for setup,
+the platform design (including the macOS deferral), and smoke tests.
+
+Persistent Debian server players with independent queues and a shared control
+API are documented in [SERVER_PLAYERS.md](SERVER_PLAYERS.md).
+
+An opt-in `OwnToneBackend` supports one selected AirPlay output through a
+dedicated patched OwnTone engine. See [OWNTONE.md](OWNTONE.md) for the pinned
+engine build, shared read-only audio mapping, CLI setup, completion semantics
+and verification limits. mpv remains the default.

package/SERVER_PLAYERS.md

@@ -0,0 +1,348 @@
+# Persistent server players
+
+Server players run on the Debian Docker host. Closing a laptop, TUI or event
+subscription leaves playback running. Each named player has its own persistent
+queue and one dedicated OwnTone engine. Different players can use different
+speakers concurrently; synchronized groups are deferred. This is the backend
+for #693; remote TUI controls are tracked in #694. The web UI can control these sessions through an optional household browser
+session; see [web controls](../../my-collection-search/docs/server-player-web.md).
+There is no iOS UI yet. Web authorization can be provisioned from 1Password with
+`just player-web-setup`; existing hosts remain opted out until that explicit setup.
+
+## Deployment
+
+Use the repository's existing Debian Compose stack and apply migrations first
+(`just migrate-up` with the stack's normal environment). Do not start a second
+stack against the production database volume. Add `docker-compose.players.yml`
+after your usual Compose files and enable profile `players`. This extension is
+optional; the ordinary stack does not start any player engines.
+
+For production, put the following player settings in a private root `.env.players`
+(`chmod 600 .env.players`), using `.env.example` as the reference. Its presence
+opts the production deploy script into the player Compose overlay/profile and
+builds the two local images before starting services. It survives the normal
+`.env` rendering step. Keep the existing database/collection secrets in `.env`.
+Player secrets and private worktree files are excluded from Docker build contexts.
+
+The optional `.env.players.tpl` uses the existing `GROOVENET_OP_VAULT` /
+`GROOVENET_OP_ITEM` selection (defaults `Homelab` / `groovenet`). Add four fields
+to that 1Password item: `PLAYER_API_KEY`, `PLAYER_LIBRARY_FRIEND_ID`,
+`PLAYER_ENGINE_A_PASSWORD`, and `PLAYER_ENGINE_B_PASSWORD`. The friend ID is the
+positive `friends.id` of the library owner. API keys must be at least 32
+characters on one line; engine passwords must be distinct hex/base64url values.
+To render locally:
+
+```sh
+mkdir -p .worktree
+op run --env-file .env.players.tpl -- node my-collection-search/scripts/render-player-env.mjs .worktree/players.env
+# Copy to the production checkout as .env.players with mode 0600.
+```
+
+The renderer validates credentials before replacing any existing file, writes
+atomically with private permissions, and constructs the engine JSON from the same
+passwords. It quotes literal dollar signs/backslashes so Compose preserves secret
+values. Never commit the rendered file. `just deploy` refreshes `.env.players`
+from 1Password only on a host that already has that file; other hosts stay opted
+out. The ordinary collection credential template is unchanged.
+
+For the laptop CLI, load only the API key (never the engine passwords):
+
+```sh
+PLAYER_API_KEY='op://Homelab/groovenet/PLAYER_API_KEY' op run -- groovenet player list
+PLAYER_API_KEY='op://Homelab/groovenet/PLAYER_API_KEY' op run --no-masking -- groovenet player --remote lounge
+```
+
+Use the installed executable or the built Node entrypoint inside `op run`; shell
+functions such as `gn` are not executables that `op run` can invoke directly.
+Existing CLI collection credentials remain independent. For the interactive TUI,
+`op run` needs `--no-masking`: its default output-masking pipe makes stdout cease
+to be a TTY. This option passes terminal output through directly; the player UI
+does not print credentials. Keep default masking for noninteractive commands.
+
+Configure player settings:
+
+* Generate `PLAYER_API_KEY` with `openssl rand -hex 32`. It is a **shared
+  household/admin credential**, with access to every player and friend’s queued
+  track references. All reads, commands and SSE require it. Existing browser
+  cookies and the ordinary app API key do not grant player access. The opt-in
+  web bridge issues a separate player-only session after web-passphrase
+  authorization; it never shares this worker key with browsers. Give it only
+  to trusted controllers and use HTTPS when reaching the app across a network.
+* Generate distinct hex/base64url `PLAYER_ENGINE_A_PASSWORD` and
+  `PLAYER_ENGINE_B_PASSWORD` values (`openssl rand -hex 24`).
+* Set `PLAYER_LAN_INTERFACE` to the Debian host's actual speaker-facing interface.
+  Engines and the shared clock use host networking for discovery/AirPlay.
+  Reserve API ports 13689/13690, WebSocket ports 13688/13691 and PTP UDP 319/320.
+  Restrict engine APIs to trusted host/network access; never expose them publicly.
+* Set `PLAYER_AUDIO_MOUNT=music_data` with the production overlay: this logical
+  Compose volume maps to the existing `PROD_MUSIC_DATA_VOLUME`. Alternatively use
+  an absolute directory visible to Docker. Do not supply an undeclared Docker
+  volume name. The mount is read-only. OwnTone must finish indexing before play.
+* Set `PLAYER_ENGINES_JSON` to the following single-line JSON, replacing passwords
+  to match the engine environment variables. These credentials stay server-side.
+
+```json
+{"primary":{"apiUrl":"http://host.docker.internal:13689/api","password":"A_PASSWORD","libraryRoot":"/srv/media"},"secondary":{"apiUrl":"http://host.docker.internal:13690/api","password":"B_PASSWORD","libraryRoot":"/srv/media"}}
+```
+
+For example, with the existing production environment loaded:
+
+```sh
+docker compose --env-file .env --env-file .env.players -p dj-playlist -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.players.yml --profile players build player-clock player-worker
+docker compose --env-file .env --env-file .env.players -p dj-playlist -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.players.yml --profile players up -d app player-clock player-engine-a player-engine-b player-worker
+```
+
+The worker has no published port: the app proxies to `http://player-worker:13700`.
+The two engine cache databases use separate persistent volumes. Both engines
+must share the clock's IPC namespace (`ipc: service:player-clock`): AirPlay 2
+requires `/dev/shm/airptp_shm`, as well as network access to the clock. The engine
+entrypoint refuses startup without it. Run only one such shared clock per host.
+
+Outside Compose, build packages with `just build-packages`, then run
+`groovenet-player-server` with `DATABASE_URL`, `PLAYER_API_KEY`,
+`PLAYER_LIBRARY_FRIEND_ID`, `PLAYER_ENGINES_JSON` and `PLAYER_APP_URL` (the app
+origin, default `http://app:3000`). Set the app's `PLAYER_WORKER_URL` to that
+private worker.
+The standalone worker binds `0.0.0.0:13700` (override `PLAYER_WORKER_PORT`), so
+restrict access at the host/network boundary.
+
+## Control API
+
+All public paths start with `/api/players`. Supply
+`Authorization: Bearer <PLAYER_API_KEY>` on every request.
+
+| Method and path | Purpose |
+| --- | --- |
+| `GET /api/players` | List persistent players |
+| `GET /api/players/engines` | List configured engine IDs |
+| `POST /api/players` | Create `{ "id": "lounge", "name": "Lounge", "engine_id": "primary" }` |
+| `GET /api/players/lounge` | Get full state and revision |
+| `GET /api/players/lounge/devices` | Discovered outputs, assignments and observations |
+| `POST /api/players/lounge/commands` | Apply a command |
+| `GET /api/players/lounge/events` | SSE snapshots and lightweight position updates |
+
+Each engine can belong to only one named player. Names can be changed; player
+IDs and engine assignments are fixed. Engine configuration is an operator
+allowlist, never a client-provided URL. Player deletion is not implemented.
+
+Commands use last-write-wins behavior by default. Optionally include
+`expected_revision` from a snapshot to require optimistic concurrency: a stale
+value returns `REVISION_CONFLICT`. Position ticks do not change the revision.
+Each player has a persisted `availability_policy`, initially `ask`. Set it with
+the bearer credential:
+
+```sh
+groovenet player set lounge --availability allow_unknown
+groovenet player set lounge --availability always
+groovenet player set lounge --availability ask
+```
+
+The equivalent command is
+`{"type":"availability.set","availability_policy":"allow_unknown","expected_revision":3}`.
+`ask` requires the existing per-command acknowledgements. `allow_unknown`
+connects when HA activity is unknown without `allow_unknown: true`, but still
+requires `takeover: true` for observed occupied activity. `always` also permits
+observed occupied activity without a takeover flag. Both policies apply to fresh
+connection and reconnection checks; neither bypasses another Groovenet player's
+assignment. Use `output.transfer` explicitly to move that assignment. Browser
+sessions cannot change this policy.
+For example:
+
+```json
+{"type":"queue.add","tracks":[{"track_id":"TRACK_ID","friend_id":1}]}
+```
+
+Scripts that need optimistic concurrency can use the returned player revision
+for their next command:
+
+```json
+{"type":"output.select","expected_revision":1,"output_id":"OUTPUT_ID"}
+```
+
+```json
+{"type":"play","allow_unknown":true}
+```
+
+Selecting an output remembers intent; it does not connect or reserve the
+speaker. Playback requires indexed local audio, resolved afresh from Postgres.
+Queue entries get stable UUIDs, including repeated copies of the same track.
+Use those entry IDs for `queue.remove`, `queue.move` and an explicit `play`.
+If an entry has disappeared, these commands return `ENTRY_NOT_FOUND`.
+Other commands are `rename`, `queue.clear`, `pause`, `resume`, `stop`, `next`,
+`previous`, `seek` (seconds) and `volume` (0–100). Stop clears the current entry
+and position while preserving the queue. Natural EOF advances only that player's
+queue; interruption/error preserves the current entry and requires a command.
+
+### Atomic queue replacement
+
+`queue.replace` resolves every track before changing the queue or playback. An
+unresolved track rejects the whole command. Entries accept optional UUIDs;
+provided IDs are preserved and new entries receive generated IDs. Duplicate IDs
+and reusing a current queue ID for another track/friend are rejected. Titles and
+artists are resolved on the server, never accepted from the caller.
+
+```json
+{"type":"queue.replace","expected_revision":3,"entries":[{"id":"11111111-1111-4111-8111-111111111111","track_id":"TRACK_ID","friend_id":1}],"current_entry_id":"11111111-1111-4111-8111-111111111111","position":42,"play":false}
+```
+
+Omitting `current_entry_id` retains the current entry if present; otherwise it
+selects the first replacement entry only when `play: true`. Explicit `null`
+clears the current entry. A non-null ID must belong to the replacement queue.
+Omitting `position` preserves the retained entry's position, or starts a new
+entry at zero. An explicit position seeks a retained live entry, or saves a
+checkpoint for a later play. Removing/changing the current entry stops playback
+unless `play: true`. Retaining it keeps its existing backend and playing/paused
+state; `play: true` resumes it. An empty replacement clears the queue and cannot
+be played. Playback is opt-in and uses the usual output availability/assignment
+checks; rejected preflight checks leave the old queue intact. Engine failures
+after playback effects begin are reported as playback errors, not a rollback of
+already-performed audio operations.
+
+The typed client's `commandServerPlayer` accepts this command. From the CLI:
+
+```sh
+groovenet player --remote lounge queue replace '{"entries":[{"track_id":"TRACK_ID","friend_id":1}],"play":true}' --json
+```
+
+Use `--allow-unknown` or `--takeover` only when deliberately authorizing the
+corresponding speaker policy. A replacement with retained UUIDs can restore an
+Undo snapshot, including its current entry and position. Revisions still guard
+against overwriting changes made after that snapshot.
+
+SSE begins with a complete `snapshot`. `position` events include player ID,
+revision, current entry ID and observation time; apply them only to a matching
+snapshot revision/entry. Each event also carries worker instance and sequence.
+Reconnect for a fresh snapshot; there is no event replay. Slow clients are
+disconnected, and client disconnection never stops audio. The SDK exposes the
+list/create/get/command/devices/engines requests; SSE can be consumed directly.
+
+## Speaker activity and transfers
+
+Configure `PLAYER_HA_URL`, `PLAYER_HA_TOKEN` and `PLAYER_HA_ENTITIES_JSON`
+with exact OwnTone output IDs or names as keys. ID mappings take precedence.
+Names are case-sensitive. A name mapping is used only when that name is unique
+among the engine's discovered outputs; duplicate names remain unmapped unless
+each output has an ID mapping. ID mappings always take precedence. Name mapping
+still appears in device diagnostics when HA credentials are missing, so the
+mapping can be checked separately from HA connectivity.
+For example:
+
+```json
+{"aswitch":"media_player.aswitch_streamer","Lounge Room Audio":"media_player.lounge_streamer","132116595608304":"media_player.bedroom_sonos"}
+```
+
+Read-only inspection on beelink on 2026-10-25 confirmed both engines discover:
+
+| OwnTone output ID | Name | HA entity from the installed registry (#691) |
+| --- | --- | --- |
+| `202481599519404` | aswitch | `media_player.aswitch_streamer` |
+| `202481586338774` | Lounge Room Audio | `media_player.lounge_streamer` |
+| `132116595608304` | Bedroom | `media_player.bedroom_sonos` |
+
+The running worker had an empty HA URL/token and `{}` mappings. HA live states
+could not be queried through that worker. These settings must be supplied to
+`.env.players` and retained in the environment used to render it on deployment.
+The optional `.env.players.tpl` does not supply HA credentials by default.
+
+`groovenet player devices --remote lounge` (or the devices API) shows
+`observed.entity_id`, availability, source, observation time and sender identity.
+`entity=unmapped` exposes missing mappings; an entity with `source=unconfigured`
+means the URL/token is missing. A configured but inaccessible entity reports
+`source=home_assistant`, unknown activity and no observation timestamp.
+
+The observer reads HA with a 2-second timeout. Device listings cache observations
+for 5 seconds; connection/reconnection decisions always fetch fresh state.
+`idle`, `off`, `standby` mean observed idle; active/paused states mean occupied;
+unavailable, missing configuration and failed observations mean unknown.
+Observations can race another app.
+
+To recognise an engine, HA must expose receiver **session sender attributes**.
+Configure exact attribute/value matches keyed by engine ID, for example:
+
+```sh
+PLAYER_HA_SENDERS_JSON='{"primary":{"client_name":"Groovenet-primary","client_ip":"192.168.2.151"},"secondary":{"client_name":"Groovenet-secondary","client_ip":"192.168.2.151"}}'
+```
+
+These attribute names/values are illustrative: inspect the actual HA entity
+attributes before configuring them. All attributes for an engine must match;
+exactly one engine must match. Matching only the beelink IP cannot distinguish
+its two engines or another app on that host. Use a unique sender identifier,
+never track metadata, a room source label or a shared host IP. Duplicate matches
+remain unknown identity and occupied activity. Sender attributes must describe
+the current session and be cleared/replaced on takeover. Idle/unavailable states
+never identify a sender, even if attributes linger.
+
+The installed `shairport_sync` 1.4.0 integration was inspected read-only: it
+subscribes to playback and track metadata but exposes no client name/IP. It needs
+an HA integration/receiver metadata update before this sender configuration can
+work. Shairport's D-Bus client address is available on the Lounge receiver, but
+its client name was empty in #691 and the address persists after disconnect.
+Do not assume an engine library name appears as `client_name`. No receiver or HA
+configuration was changed as part of the inspection.
+
+An active matching sender reports `sender_identity=groovenet` and
+`sender_engine_id`. Its own player may connect/resume without takeover; other
+engines still need takeover. Nonmatching sender attributes report `foreign`;
+missing/ambiguous attributes report `unknown`. Both retain occupancy protection.
+
+Connecting to unknown activity requires explicit `allow_unknown: true`.
+Occupied activity requires `takeover: true` unless its sender identifies this
+player's dedicated engine. A paused engine may release its AirPlay transport;
+reconnection checks apply the same sender rules.
+Neither acknowledgement can steal another Groovenet player's assignment.
+For that, send `output.transfer` to the destination player:
+
+```json
+{"type":"output.transfer","from_player_id":"lounge","from_revision":12,"output_id":"OUTPUT_ID","play":true,"allow_unknown":true}
+```
+
+Transfer detaches the source first and keeps each player's own queue and
+checkpoint. `play: false` only changes the destination's desired output.
+`from_revision` is required even when `expected_revision` is omitted; it fences
+the source player whose output is being transferred.
+Inspect `transfer.detached`, `attached` and `error` even when HTTP status is 200:
+the source can be detached while destination playback fails. It is never
+automatically reconnected to hide that partial result.
+
+## Restarts and recovery
+
+Postgres holds names, independent queues, current entry, volume, desired output
+and position checkpoints (at most once per five seconds, plus command/shutdown
+writes). Only one worker holds the database lifecycle lease. Commands and engine
+events share a serial lane; a slow engine can delay commands to other players.
+
+A worker restart restores **stopped checkpoints**, clears transient assignments
+and creates no engine connections. It never resumes or reclaims a speaker
+automatically. `checkpoint: true` means saved position, not observed live audio.
+
+Server players log digital plays after the shared `playThreshold` listen time.
+Only tracks belonging to `PLAYER_LIBRARY_FRIEND_ID` are eligible. Each queue
+entry has its own durable delivery record; failed app API requests are retried
+every 30 seconds and after a worker restart. An API conflict for an already
+logged digital play completes the delivery. The worker must be able to reach
+`POST /api/spins` at `PLAYER_APP_URL`.
+
+An abrupt crash can leave an old engine playing; stop that engine explicitly
+before issuing new playback if its ownership cannot be established. Do not use
+the dedicated engines from other controller apps.
+
+When a receiver or input fails, the worker stops, clears and releases only a
+verified failed engine session. It rechecks the engine instance, queue version,
+item and terminal failure sequence, and refuses to clean up a resumed/replaced
+session or another selected output. The named player's queue/current entry and
+checkpoint remain intact; it never automatically resumes or advances after a
+failure. Once the receiver is ready, explicitly play again (with any required
+availability acknowledgement). Queue and settings edits preserve the playback
+error until a successful transport action leaves the error state.
+
+If engine cleanup fails, an uncertain assignment remains reserved and commands
+return `RELEASE_UNCERTAIN`. Stop/restart the affected engine, then restart the
+worker to restore stopped checkpoints and clear the claim. Investigate DB/engine
+connectivity before retrying. Do not run a second worker to bypass a lease error.
+
+Some receivers ignore AirPlay volume. The saved volume is the requested sender
+value, not a measured loudness guarantee. The implementation does not promise
+synchronization, automatic recovery after receiver outages, or Sonos validation.
+
+Validation and the successful two-room hardware results are recorded in
+[evaluations/693](../../../evaluations/693/README.md).

package/build/daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAe,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAGpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IACnC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3C;AAED,6EAA6E;AAC7E,qBAAa,YAAY;IAuBX,OAAO,CAAC,QAAQ,CAAC,OAAO;IAtBpC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2B;IAC1D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAO9B;IACF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6D;IACjG,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4D;IAC9F,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAGjC;IAEF,YAA6B,OAAO,EAAE,mBAAmB,EAMxD;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAiB3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAqB1B;YAEa,iBAAiB;YAkBjB,cAAc;IAiB5B,OAAO,CAAC,MAAM;YAeA,UAAU;YAuCV,QAAQ;IAgDtB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,SAAS;CAIlB"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAe,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAGpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IACnC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3C;AAED,6EAA6E;AAC7E,qBAAa,YAAY;IAuBX,OAAO,CAAC,QAAQ,CAAC,OAAO;IAtBpC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2B;IAC1D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAO9B;IACF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6D;IACjG,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4D;IAC9F,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAGjC;IAEF,YAA6B,OAAO,EAAE,mBAAmB,EAMxD;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAiB3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAqB1B;YAEa,iBAAiB;YAkBjB,cAAc;IAiB5B,OAAO,CAAC,MAAM;YAeA,UAAU;YAuCV,QAAQ;IAiDtB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,SAAS;CAIlB"}

package/build/daemon.js

@@ -193,6 +193,9 @@ export class PlayerDaemon {
             case "pause":
                 await player.pause();
                 return player.snapshot;
+            case "stop":
+                await player.stop();
+                return player.snapshot;
             case "resume":
                 await player.resume();
                 return player.snapshot;