@groovenet/player 0.1.2 → 0.1.4

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

@@ -33,10 +33,39 @@ Tracks without downloaded audio are skipped with a typed `NO_AUDIO` error.
 `insecureTls` is forwarded as mpv's `--tls-verify=no` setting for installations
 using a self-signed server certificate.
 
+By default mpv is started with `--vid=no`, so embedded cover art does not open
+a window (the player has no artwork view, and the daemon may have no display).
+Pass `artwork: true` to `MpvBackend` to keep mpv's cover-art window. The
+Groovenet CLI exposes this as the `player_artwork` config key and the
+`--artwork` flag; a running daemon must be restarted to pick up a change.
+
+`PlayLogger` is an opt-in subscriber that turns a `PlayerCore`'s events into
+play records without the core knowing about it. `playThreshold`, `advanceProgress`
+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`).
+
 `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
 owned process. The `TestPlaybackBackend` from `@groovenet/player/testing` is a small in-memory
 implementation for consumers that need to exercise the core without audio.
 
+`defaultPlayerPaths()` returns the daemon's socket and pidfile paths (`~/.groovenet/player/`), shared by the CLI and the MCP server.
+
 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,215 @@
+# 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.
+
+## 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 three fields
+to that 1Password item: `PLAYER_API_KEY`, `PLAYER_ENGINE_A_PASSWORD`, and
+`PLAYER_ENGINE_B_PASSWORD`. 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` and
+`PLAYER_ENGINES_JSON`. 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 revisioned 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 include `expected_revision` from the most recent snapshot. A stale
+revision returns `REVISION_CONFLICT`; fetch fresh state before deciding whether
+to retry. Position ticks do not change the edit revision. For example:
+
+```json
+{"type":"queue.add","expected_revision":0,"tracks":[{"track_id":"TRACK_ID","friend_id":1}]}
+```
+
+After each command, use its returned player revision for the next command:
+
+```json
+{"type":"output.select","expected_revision":1,"output_id":"OUTPUT_ID"}
+```
+
+```json
+{"type":"play","expected_revision":2,"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`.
+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.
+
+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
+
+Optionally configure `PLAYER_HA_URL`, `PLAYER_HA_TOKEN` and an output-to-entity
+map such as `PLAYER_HA_ENTITIES_JSON={"OUTPUT_ID":"media_player.lounge"}`.
+The observer only reads HA state, with a 2-second timeout and 5-second cache.
+`idle`, `off`, `standby` mean observed idle; active/paused states mean occupied;
+unavailable, missing configuration and failed observations mean unknown.
+HA does not prove which app is sending audio. Observations can race another app.
+
+Connecting to unknown activity requires explicit `allow_unknown: true`.
+Occupied activity requires `takeover: true`. A paused engine may release its
+AirPlay transport, so resuming may require another availability decision.
+Neither acknowledgement can steal another Groovenet player's assignment.
+For that, send `output.transfer` to the destination player:
+
+```json
+{"type":"output.transfer","expected_revision":7,"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.
+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.
+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;IAoBX,OAAO,CAAC,QAAQ,CAAC,OAAO;IAnBpC,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,CAAiF;IAEpH,YAA6B,OAAO,EAAE,mBAAmB,EAMxD;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAiB3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB1B;YAEa,iBAAiB;YAejB,cAAc;IAiB5B,OAAO,CAAC,MAAM;YAeA,UAAU;YAyBV,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

@@ -24,7 +24,10 @@ export class PlayerDaemon {
     };
     broadcastTrackStart = (entry) => this.broadcast("track-change", entry);
     broadcastTrackEnd = (entry) => this.broadcast("track-ended", entry);
-    broadcastTrackSkip = (entry, error) => this.broadcast("error", { entry, error });
+    broadcastTrackSkip = (entry, error) => {
+        const playerError = error;
+        this.broadcast("error", { entry, error: { code: playerError.code, message: playerError.message } });
+    };
     constructor(options) {
         this.options = options;
         this.createServer = options.createServer ?? createServer;
@@ -72,11 +75,15 @@ export class PlayerDaemon {
             await new Promise((resolve) => this.server.close(() => resolve()));
         }
         this.server = null;
-        await this.options.player.close();
-        await Promise.all([
-            unlink(this.options.paths.socketPath).catch(() => undefined),
-            unlink(this.options.paths.pidPath).catch(() => undefined),
-        ]);
+        try {
+            await this.options.player.close();
+        }
+        finally {
+            await Promise.all([
+                unlink(this.options.paths.socketPath).catch(() => undefined),
+                unlink(this.options.paths.pidPath).catch(() => undefined),
+            ]);
+        }
     }
     async recoverStaleFiles() {
         let pid = null;
@@ -86,8 +93,11 @@ export class PlayerDaemon {
                 pid = parsed;
         }
         catch { /* no pidfile */ }
-        if (pid !== null && this.isProcessAlive(pid) && await this.socketIsActive()) {
-            throw new Error(`Player daemon already appears to be running (pid ${pid}).`);
+        // The socket is authoritative. A missing, malformed, or stale pidfile must
+        // never cause us to unlink a live daemon's socket.
+        if (await this.socketIsActive()) {
+            const owner = pid !== null && this.isProcessAlive(pid) ? ` (pid ${pid})` : "";
+            throw new Error(`Player daemon already appears to be running${owner}.`);
         }
         await Promise.all([
             unlink(this.options.paths.pidPath).catch(() => undefined),
@@ -126,32 +136,45 @@ export class PlayerDaemon {
         socket.on("close", () => this.clients.delete(socket));
     }
     async handleLine(socket, line) {
-        let request;
+        let value;
         try {
-            request = JSON.parse(line);
+            value = JSON.parse(line);
         }
         catch {
             socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id: 0, error: { code: "INVALID_REQUEST", message: "Request must be a JSON object." } }));
             return;
         }
-        if (!Number.isInteger(request.id))
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id: 0, error: { code: "INVALID_REQUEST", message: "Request must be a JSON object." } }));
             return;
+        }
+        const request = value;
+        const id = Number.isInteger(request.id) ? request.id : 0;
         if (request.jsonrpc !== "2.0") {
-            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id: request.id, error: { code: "INVALID_REQUEST", message: "Expected JSON-RPC version 2.0." } }));
+            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id, error: { code: "INVALID_REQUEST", message: "Expected JSON-RPC version 2.0." } }));
             return;
         }
         if (request.version !== PLAYER_PROTOCOL_VERSION) {
-            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id: request.id, error: { code: "VERSION_MISMATCH", message: `Unsupported player protocol version ${request.version}; this daemon supports version ${PLAYER_PROTOCOL_VERSION}.` } }));
+            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id, error: { code: "VERSION_MISMATCH", message: `Unsupported player protocol version ${request.version}; this daemon supports version ${PLAYER_PROTOCOL_VERSION}.` } }));
+            return;
+        }
+        if (!Number.isInteger(request.id) || typeof request.method !== "string" || !request.method) {
+            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id, error: { code: "INVALID_REQUEST", message: "Request requires an integer id and a non-empty method." } }));
+            return;
+        }
+        const params = request.params === undefined ? {} : request.params;
+        if (typeof params !== "object" || params === null || Array.isArray(params)) {
+            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id, error: { code: "INVALID_REQUEST", message: "Request params must be a JSON object." } }));
             return;
         }
         try {
-            const result = await this.dispatch(request.method, request.params ?? {});
-            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id: request.id, result }));
+            const result = await this.dispatch(request.method, params);
+            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id, result }));
         }
         catch (error) {
             const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "PLAYER_ERROR";
             const message = error instanceof Error ? error.message : String(error);
-            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id: request.id, error: { code, message } }));
+            socket.write(encodeRpcResponse({ version: PLAYER_PROTOCOL_VERSION, id, error: { code, message } }));
         }
     }
     async dispatch(method, params) {
@@ -170,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;