@khalido/home 0.1.0 → 0.1.2

package/src/connectors/cast/writes.ts

@@ -19,6 +19,8 @@ export const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
 export const ANSWER_MS = 10_000;
 /** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */
 export const PLAY_MS = 60_000;
+/** How long a clip gets to start playing. A clip a speaker can't play took 35–44 s to say so (live, 2026-11-09); good ones start within a few seconds. A stated guess. */
+export const START_MS = 15_000;
 
 const RECEIVER = "receiver-0";
 /** Level writes, and mute writes, per device or group in any minute; more wait their turn, the newest winning. A guess: Cast publishes no limit. */
@@ -64,6 +66,12 @@ export type CastActions = {
     clip: CastClip,
     options?: { volume?: number; timeoutMs?: number },
   ): Promise<AnnounceResult>;
+  /** `announce` to several targets at once, one result per device, in the order given. A target that can't be reached is its own `played: false`. A group and one of its own members are not told apart. */
+  announceAll(
+    targets: string[],
+    clip: CastClip,
+    options?: { volume?: number; timeoutMs?: number },
+  ): Promise<(AnnounceResult & { target: string })[]>;
 };
 
 /** A payload as it came, before any schema. */
@@ -115,10 +123,11 @@ function waitFor<T>(
   clock: Clock,
   s: CastSession,
   ms: number | (() => number),
-  what: string,
+  what: string | (() => string),
   pick: (raw: RawPayload) => T | undefined,
   signal?: AbortSignal,
 ): Promise<T> {
+  const name = () => (typeof what === "string" ? what : what());
   return new Promise<T>((resolve, reject) => {
     const done = new AbortController();
     const finish = (settle: () => void) =>
@@ -128,11 +137,11 @@ function waitFor<T>(
       done.abort(),
       settle());
     const cancel = () =>
-      finish(() => reject(new Error(`stopped waiting for ${what}`)));
+      finish(() => reject(new Error(`stopped waiting for ${name()}`)));
     const off = s.listen((raw) => {
       if (raw === undefined)
         return finish(() =>
-          reject(new Error(`the socket closed waiting for ${what}`)),
+          reject(new Error(`the socket closed waiting for ${name()}`)),
         );
       try {
         const value = pick(raw);
@@ -152,7 +161,7 @@ function waitFor<T>(
       )
         await clock.sleep(left, done.signal);
       finish(() =>
-        reject(new Error(`no ${what} in ${Math.round(limit() / 1000)} s`)),
+        reject(new Error(`no ${name()} in ${Math.round(limit() / 1000)} s`)),
       );
     })();
   });
@@ -318,18 +327,22 @@ export function castActions(ctx: WriteContext): CastActions {
   const play = async (
     s: CastSession,
     transport: string,
-    media: object,
+    media: { contentId: string; contentType: string; streamType: string },
     timeoutMs?: number,
   ): Promise<boolean> => {
     const loadId = s.nextId();
     let session: number | "any" | undefined;
     let durationS = 0;
+    let started = false; // it has reached PLAYING: BUFFERING is where a clip it can't play sits
     const cancel = new AbortController();
     const finished = waitFor(
       clock,
       s,
-      () => timeoutMs ?? PLAY_MS + durationS * 1000,
-      "end of the clip",
+      () => timeoutMs ?? (started ? PLAY_MS + durationS * 1000 : START_MS),
+      () =>
+        started
+          ? "end of the clip"
+          : `start of the clip (${media.contentType}, which this device may not play)`,
       (raw) => {
         const r = MediaStatus.safeParse(raw);
         if (!r.success) return undefined;
@@ -345,9 +358,12 @@ export function castActions(ctx: WriteContext): CastActions {
             continue;
           if (typeof m.media?.duration === "number")
             durationS = m.media.duration;
+          if (m.playerState === "PLAYING") started = true;
           if (m.playerState !== "IDLE" || !m.idleReason) continue;
           if (m.idleReason === "FINISHED") return true;
-          throw new Error(`the clip stopped: ${m.idleReason}`);
+          throw new Error(
+            `the clip stopped: ${m.idleReason}${m.detailedErrorCode === undefined ? "" : ` (detailed error ${m.detailedErrorCode})`}${m.idleReason === "ERROR" ? `; this device may not play ${media.contentType}` : ""}`,
+          );
         }
         return undefined;
       },
@@ -390,7 +406,7 @@ export function castActions(ctx: WriteContext): CastActions {
       );
   };
 
-  return {
+  const actions: CastActions = {
     async setVolume(target, level) {
       checkLevel(level);
       await setVolume(target, { level });
@@ -568,5 +584,38 @@ export function castActions(ctx: WriteContext): CastActions {
         }
       }
     },
+
+    async announceAll(targets, clip, options = {}) {
+      // A caller's mistake is one error, not a failure per speaker.
+      if (options.volume !== undefined) checkLevel(options.volume);
+      if (!("url" in clip) && !ctx.serve)
+        throw new Error(
+          "a clip of bytes needs serve: serveClip from @khalido/home/cast/serve",
+        );
+      const id = (t: string) => {
+        try {
+          return find(t).id;
+        } catch {
+          return t; // unknown: announce says so, as this target's own failure
+        }
+      };
+      const once = targets.filter(
+        (t, i) => targets.findIndex((o) => id(o) === id(t)) === i,
+      ); // one device twice would save the first's volume as the one to restore
+      return Promise.all(
+        once.map(async (target) => ({
+          target,
+          ...(await actions
+            .announce(target, clip, options)
+            .catch((error): AnnounceResult => ({
+              played: false,
+              why: errorText(error),
+              restored: [],
+              notRestored: [],
+            }))),
+        })),
+      );
+    },
   };
+  return actions;
 }

package/src/connectors/daikin/README.md

@@ -4,7 +4,7 @@ Reads one Daikin AC over its local JSON `dsiot` API. `iot_class`: **local_pollin
 
 - `client.ts`: `daikinClient({ host, fetch }).read()` returns `DaikinState` (power, mode, the selected mode's setpoint and fan speed, room °C, humidity, outside °C, `anomaly`). `setPower`, `setMode`, `setTarget`, `setFan` build write requests; `client.write(request)` sends one, through a write lane: 1 s apart and at most 20 a minute (guesses), a waiting write merging the next one field by field (`mergeWrites`). Every request times out at 10 s.
 - `index.ts`: `daikin({ host, fetch, clock })` reads now, then every **120 s** (Home Assistant's `update_interval`). A failed poll is `disconnected` and keeps the last reading with `asOf`; a 404 on `/dsiot/multireq` is a failed read too, saying "not a dsiot Daikin": the address may now be another device's, so discovery looks for the unit. There is no key, so nothing is terminal. Writes go through `daikin().client.write(…)`: one client for the integration's life, at the unit's current address.
-- `home status` reads `DAIKIN_HOST`, else the first unit that answers the UDP broadcast. There is no CLI command that writes.
+- `home status` reads `DAIKIN_HOST`, or a home config's address, with discovery by `mac` if the unit moves. There is no CLI command that writes.
 
 ## The protocol
 

package/src/connectors/spotify/README.md

@@ -1,6 +1,6 @@
 # Spotify (Soloist)
 
-What a [Spotify Soloist](https://developer.spotify.com/documentation/soloist) speaker is playing (start with its [basic integration](https://developer.spotify.com/documentation/soloist/howtos/basic-integration)), and control over it, over Soloist's local WebSocket. `iot_class`: **local_push**. Tested against a fake socket only: no real Soloist has answered this connector yet.
+What a [Spotify Soloist](https://developer.spotify.com/documentation/soloist) speaker is playing (start with its [basic integration](https://developer.spotify.com/documentation/soloist/howtos/basic-integration)), and control over it, over Soloist's local WebSocket. `iot_class`: **local_push**. Reads and most writes seen live on a real Soloist (0.1.1, 2026-11-09); what 0.1.2 changed since is tested against a fake socket only.
 
 Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x86_64, Apple Silicon, Windows x86_64). The machine running it is a speaker in every Spotify app on the network; this connector is how a program on the same machine sees and steers it. It doesn't search Spotify or read a library: Soloist plays URIs and reports its own session. Search belongs to the consumer (KO, 2026-11-08; `docs/ideas.md`).
 
@@ -14,15 +14,17 @@ Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x8
 
 **State.** Each frame passes a zod schema, every field optional, and folds into `SpotifyState`: `loggedIn`, `deviceName`, `active`, `status`, `track` (`uri`, `type`, `name`, `artists`, `album`, cover, `durationMs`), `context`, `position` (Soloist's anchor `ms`, `atMs`, `speed`; `positionMs(state, now)` moves it on, not clamped), `volume`, `shuffle`, `repeat`, `upNext` (from `queue_changed`, plus one `get_queue` with `limit: 10` per socket; an unanswered one is quiet, as an empty queue may send nothing). An empty item `uri` is nothing loaded: no `track`. Unknown frame types are skipped. The library adds `aside` while its own `duck`, `interrupt` or stall repair runs, and `stalled`. Odd readings pass through into `anomaly`: an unknown status or repeat, a volume outside 0–100, a negative speed, a position past the track's end, a frame the schema rejects (which leaves the state as it was).
 
-**Writes**, on the integration: `play(linkOrUri?)`, `pause`, `resume`, `next`, `prev`, `seek(ms)`, `setVolume(0–100)`, `queue(track)`, `setShuffle(on)`, `setRepeat("off" | "context" | "track")`. A link is an `open.spotify.com` URL or a `spotify:` URI; `spotify.link` short links are refused.
+**Writes**, on the integration: `activate()`, `play(linkOrUri?)`, `pause`, `resume`, `next`, `prev`, `seek(ms)`, `setVolume(0–100)`, `queue(track)`, `setShuffle(on)`, `setRepeat("off" | "context" | "track")`. A link is an `open.spotify.com` URL or a `spotify:` URI; `spotify.link` short links are refused.
 
 - Each resolves `{ state, confirmed }`: after Soloist accepts (`command_result`), it waits up to 2 s for the event that shows _this caller's_ change (the volume sent, `paused` or `playing`, a new track URI, the context or track played, a position near the seek, the shuffle or repeat set, the track in `upNext`), then gives the state. No such event: `confirmed: false`, the state as it stands. A write merged into a later one confirms only if its own change shows; a write of what is already so confirms at once; a drop ends the wait. `next` also confirms on idle (end of queue) or a restart, `prev` on a restart from 5 s or more in.
-- Errors are `ConnectorError` with `code`: `offline`, `waiting`, `refused` (Soloist's `error`), `timeout` (3 s), `invalid` (bad input, nothing sent).
+- A volume reported within 1 of the request confirms, since Soloist rounds it (phone steps are sixteenths).
+- **While inactive** (`state.active: false`), Soloist accepts `set_volume` and drops it, three times live. `setVolume` is refused unsent with code `inactive`; `duck` runs `fn` over the music with `music: "untouched"`. `activate()` fixes it, but makes a new audio stream, so the volume can jump to the level last saved (62 to 40, live). `play` while inactive goes active first (a `play` alone didn't take live; going active first is untested). `resume` doesn't: it worked inactive, and `interrupt` relies on that.
+- Errors are `ConnectorError` with `code`: `offline`, `waiting`, `inactive`, `refused` (Soloist's `error`), `timeout` (3 s), `invalid` (bad input, nothing sent).
 - One write lane, 100 ms apart (a guess). `volume`, `seek`, `shuffle`, `repeat` merge to the last; `play`, `pause`, `resume` share a slot, so the last wins; each `next`, `prev`, `queue` is its own. Queries go through the lane too, at most 1 s each, since Soloist's `error` names no command.
-- `setRepeat` is two commands in the docs' order (clear the other mode, then set this one); if the second is refused, repeat may be left off.
+- `setRepeat` is two commands in the docs' order (clear the other mode, then set this one), 600 ms apart: back to back, `off` from `track` stayed on `track` live, and 600 ms apart worked. If the second is refused, repeat may be left off.
 - A failed write the library made itself stays in `detail` until a write works or the socket reconnects.
 
-**`maxVolume`** holds requests (rounded to a whole percent). Within 10 s of idle → playing, a reported volume above it is lowered once and `anomaly` says so until the speaker goes idle: [#23](https://github.com/spotify/soloist/issues/23), the first play on PipeWire starts at 100%. `--initial-volume` is ignored there. Not on resuming from pause, not on connecting to a song already playing, and a person turning it up again keeps it.
+**`maxVolume`** holds requests (rounded to a whole percent). For 10 s after a start signal, a reported volume above it is lowered: a start from idle (to playing or buffering), the first such status after a sign-in, `playing` after a start through buffering, or the speaker going active. Event order differs between runs, so no one pattern is relied on. It waits until the speaker is active, retries until Soloist reports the lower volume, and only then says so in `anomaly`, until the speaker goes idle; if it never shows or Soloist refuses it, `detail` says so. A reported volume within 1 of the cap is left alone. Not on resuming from pause while active, not on connecting to a song already playing, and a person turning it up after the lowering keeps it (before Soloist has reported the lowering, a person's raise looks like the start's own jump and is lowered too). `--initial-volume` is ignored on PipeWire ([#23](https://github.com/spotify/soloist/issues/23)).
 
 **`duck(fn, { to })` and `interrupt(fn)`** turn the music down, or pause it, around `fn`, then put it back. Both resolve `{ value, music, why? }`, `music` one of:
 
@@ -33,7 +35,7 @@ Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x8
 
 The restore runs even if `fn` throws: the error is `fn`'s, and a failed restore goes to `detail`. `duck` restores the earlier volume even above `maxVolume`. One aside at a time: never call one inside another's `fn` (it waits forever), and put two announcements in one `fn`. With Cast: `speaker.duck(() => cast.announce("Kitchen", clip), { to: 20 })`. Cast's own `announce` restores what a Cast device was playing; these are for Soloist's output.
 
-**Reading it.** `speakerState(part)`: `offline`, `connecting`, `waiting`, then Soloist's status (`idle`, `playing`, `paused`, `buffering`, or its own string); signed in with no status yet is `idle`. `spotifyChanges(before, after)`, for `onChange`, gives events in this order: `offline`, `online`, `waiting`, `picked`, `started` (from idle), `resumed` (from paused), `paused`, `stopped`, `track`, `stalled`, `recovered`. Buffering counts as playing. Nothing on the first report, so a restart announces nothing; no volume or queue events. Playback events during an aside carry `own: true`; connection, sign-in and stall events never do.
+**Reading it.** `speakerState` takes the Part; `spotifyText` and `positionMs` take its `state`. `speakerState(part)`: `offline`, `connecting`, `waiting`, then Soloist's status (`idle`, `playing`, `paused`, `buffering`, or its own string); signed in with no status yet is `idle`. `spotifyChanges(before, after)`, for `onChange`, gives events in this order: `offline`, `online`, `waiting`, `picked`, `started` (from idle), `resumed` (from paused), `paused`, `stopped`, `track`, `stalled`, `recovered`. Buffering counts as playing. Nothing on the first report, so a restart announces nothing; no volume or queue events. Playback events during an aside carry `own: true`; connection, sign-in and stall events never do. `track` waits for the track's name, which Soloist can send a few seconds after the track (seen live); one that never gets a name never fires. One press on a phone can fire track, resumed, stopped, started and track over 3 s, sometimes with a 0.8 s `waiting`, and the order varies: anything announcing these should wait a few seconds. `state.volume` isn't the level that will play until `active` (it reads `--initial-volume`).
 
 **Stalls** ([#5](https://github.com/spotify/soloist/issues/5): playback stops mid-track, often the first after idle, while Soloist still says `playing`). While playing, one `get_state` every 20 s (`stallCheckMs`, code only; 0 turns it off).
 
@@ -52,18 +54,31 @@ JSON text frames on a plain WebSocket: no path, subprotocol, auth, TLS or origin
 - On connect: `auth_state`, then `playback_state` only if signed in. A later sign-in is promised only `auth_state`, so the connector asks `get_state`.
 - If `--ws` can't bind, Soloist runs without it and only logs a warning: `disconnected` while the daemon looks healthy. `--ws ADDR:0` writes the port to the data dir; this connector takes a fixed `url`.
 
-Not built: `activate`/`deactivate`, `available_actions`. An ad (`entity_type: "ad"`) shows as a `track`.
+Not built: `deactivate`, `available_actions`. An ad (`entity_type: "ad"`) shows as a `track`.
 
 ## Unverified
 
-Everything through this connector; only `soloist ctl` has talked to a real Soloist. In particular:
+Writes through this connector, and what a live read hasn't shown. In particular:
 
 - **Stalls:** whether the reported position freezes in one (if not, only an overrun is caught), whether `get_state` re-anchors the position, and whether a seek or a pause and play restarts it.
 - **Writes:** that each confirming event arrives within 2 s; which events a `play` of an album or playlist sends; `play` of a new URI with no phone around; seek on playback a phone started.
+- **The cap in 0.1.2:** on a real start, and whether a real burst is audible before it lands.
+- **`activate`:** whether `play(uri)` with no phone around works after it.
 - **The rest:** `get_queue` answered by `queue_changed`; `play` with nothing loaded; whole-number volumes; the order of `auth_state` and `playback_state`; the 100% first play and its lowering; Family-plan members picking the speaker; whether the session survives a Soloist restart; a USB speaker's standby dropping it mid-play.
 
 ## Live findings
 
+**2026-11-09, Raspberry Pi 5, Bun 1.4.4, Soloist 1.3.10.51, PipeWire and WirePlumber 0.5.8, on 0.1.1** (chota-bot's session; writes with KO's OK).
+
+- Confirmed: pause, resume, next, prev, seek, shuffle, repeat to context and track, queue, all under 900 ms. `interrupt` restored the music.
+- `set_volume` while inactive: `command_result`, no `volume_changed`, every time. After `activate`, at once. The docs say `command_result` only means accepted.
+- **Why the first volume is what it is:** WirePlumber saves each stream's level by role and restores it, and Soloist adopts it (100 and 56 in two runs, each the last level). Config can't force a fixed start: with `restore-props` off, the default volume is skipped too (`state-stream.lua`). So the cap is the way.
+- A Music-role stream played at a set level (`pw-play --volume 0.38`) leaves that level saved for Spotify's next stream. `pw-play -P '{ state.restore-props = false }'` avoids it.
+- A session survives a Soloist restart: same track, paused, signed in. `deactivate` while already inactive changed nothing visible.
+- Setup that works: speaker knob and sink at 100, Spotify's level only through Soloist, other sounds at their own unsaved levels.
+
+**2026-11-09, Raspberry Pi 5, Bun 1.4.4, through this connector** (chota-bot's session, reads only). `home spotify` took 140 ms. In code: connected at 11 ms, second report at 55 ms, 51 MB RSS, a clean exit after abort. Track, volume and `paused` read correctly, with no anomaly. `spotifyChanges` gave nothing on the first report.
+
 **2026-11-08, Raspberry Pi 5, Pi OS Lite Trixie arm64, via `soloist ctl`** (chota-bot's session). `soloist 1.3.10.51 build 1793988108 (20261106)` as a systemd user unit with `-w 127.0.0.1:9091`. It logs the days left on the build (88), the WebSocket listening, then "waiting for login". Builds expire 90 days after they're made (exit code 10); chota-bot's units refresh weekly.
 
 - Not logged in until a phone picked the speaker: the normal waiting state. After: logged in, active device.

package/src/connectors/spotify/changes.ts

@@ -62,7 +62,7 @@ const PLAYING = new Set(["playing", "buffering"]);
 /**
  * The events between two reports, for `onChange`'s `before` and `after`: `offline` and `online`; `waiting` (signed out) and
  * `picked` (someone picked the speaker); `started` (from idle), `resumed` (from paused), `paused`, `stopped` (to idle), then
- * `track` for a new track, so "started" and the track come as a pair, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
+ * `track` for a new track, once it has a name, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
  * with no state (createHome's placeholder before the first report, as at a restart): nothing, since nothing was seen to change. No volume or queue events: read the state.
  */
 export function spotifyChanges(
@@ -96,7 +96,9 @@ export function spotifyChanges(
   if (to === "paused" && from !== "paused") add({ type: "paused" });
   if (to === "idle" && from !== undefined && from !== "idle")
     add({ type: "stopped" });
-  if (a?.track && a.track.uri !== b?.track?.uri)
+  // Soloist's first report of a new track can have no name yet (seen live): the event waits for it.
+  const named = (p?: SpotifyState) => !!p?.track?.name;
+  if (a?.track && named(a) && (a.track.uri !== b?.track?.uri || !named(b)))
     add({ type: "track", track: a.track });
   if (a?.stalled && !b?.stalled)
     events.push({ type: "stalled", stall: a.stalled });

package/src/connectors/spotify/client.ts

@@ -185,7 +185,7 @@ export type SpotifyState = {
   /** The playlist, album or show playing from. */
   context?: { uri: string; type?: string; name?: string };
   position?: PositionAnchor;
-  /** 0–100, as Soloist reports it. */
+  /** 0–100, as Soloist reports it, rounded. Until `active` it isn't the level that will play (it reads `--initial-volume`, seen live). */
   volume?: number;
   shuffle?: boolean;
   /** off, context or track. */