@khalido/home 0.1.1 → 0.1.3

package/src/connectors/cast/writes.ts

@@ -8,17 +8,22 @@ import {
   MultizoneStatus,
   ReceiverStatus,
 } from "./schemas.ts";
-import { type CastDevice, castKey } from "./state.ts";
+import {
+  type CastDevice,
+  castKey,
+  DEFAULT_MEDIA_RECEIVER,
+  findCast,
+} from "./state.ts";
 
 // Writes over the sockets `cast()` already holds: volume, mute, stop, and an announcement that plays a clip and puts
-// the device back as it was. Never called by the integration itself; tried on a scripted fake socket, not yet live.
+// the device back as it was. Never called by the integration itself; announce, volume and mute have run on real devices (the README has the dates).
 
-/** Google's own player for a URL of audio or video. */
-export const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
 /** Each request (a status, a volume, LAUNCH, LOAD, STOP) gets this long to answer. */
 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 +69,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 +126,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 +140,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 +164,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`)),
       );
     })();
   });
@@ -191,9 +203,7 @@ export function castActions(ctx: WriteContext): CastActions {
 
   const find = (target: string): CastDevice => {
     const all = Object.values(ctx.devices());
-    const d =
-      all.find((x) => x.id === castKey(target)) ??
-      all.find((x) => x.name.toLowerCase() === target.toLowerCase());
+    const d = findCast(ctx.devices(), target);
     if (!d)
       throw new Error(
         `no Cast device or group "${target}"; have: ${
@@ -318,18 +328,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 +359,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 +407,7 @@ export function castActions(ctx: WriteContext): CastActions {
       );
   };
 
-  return {
+  const actions: CastActions = {
     async setVolume(target, level) {
       checkLevel(level);
       await setVolume(target, { level });
@@ -411,7 +428,7 @@ export function castActions(ctx: WriteContext): CastActions {
     /**
      * Read the target's state, set the volume if asked and unmute a muted target, launch the Default Media Receiver, play the clip to its end, then
      * put back what it can, always: what the Default Media Receiver was playing is loaded again where it was, an idle
-     * device gets STOP, then the volume (a group's, member by member through each member's own socket). Another app
+     * device gets STOP, then the volume (a group's own first, then member by member through each member's own socket). Another app
      * (Spotify, YouTube) is interrupted and cannot be resumed from here; the result says so. Throws only before anything changed.
      */
     async announce(target, clip, options = {}) {
@@ -533,6 +550,26 @@ export function castActions(ctx: WriteContext): CastActions {
                   muted: before.volume?.muted,
                 },
               ];
+        // A group keeps a level of its own, which its members' levels don't bring back (live, 2026-11-10: it stayed at the
+        // announcement's 30 with every member restored). First, so whatever it does to the members, their own levels land last.
+        if (d.kind === "group" && options.volume !== undefined) {
+          const level = before.volume?.level;
+          if (level === undefined)
+            result.notRestored.push({
+              name: d.name,
+              why: "its volume before was not reported",
+            });
+          else
+            try {
+              await receiver(s, { type: "SET_VOLUME", volume: { level } });
+              result.restored.push(`${d.name}: volume`);
+            } catch (error) {
+              result.notRestored.push({
+                name: d.name,
+                why: `volume not restored: ${errorText(error)}`,
+              });
+            }
+        }
         for (const m of each) {
           const ms = m.id === d.id ? s : ctx.session(m.id);
           if (m.level === undefined)
@@ -568,5 +605,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

@@ -63,6 +63,10 @@ All setpoint and fan fields, read from `e_3001` with `md` (setpoint is one byte,
 
 Unmapped and unread: `p_27` (`0A00`, like auto), `p_34` (one signed byte, `00`, `mi FA`, `mx 00`), and the `p_05`–`p_08`, `p_20`–`p_25` fields (3- and 4-byte values, mostly `0F…`, likely schedules or limits). Meaning unknown.
 
+## Read from a Pi (2026-11-10)
+
+`home daikin` on 0.1.2 (Bun 1.4.4; chota-bot's session): "connected · off · dry · room 26 °C · outdoor unit 28 °C". `home discover` found the unit by UDP. No write was sent.
+
 ## Sources
 
 Both Daikin protocol sources are GPL-3.0, so they are read for facts only (endpoints, field paths, value maps) and no code is copied; that keeps this package MIT.

package/src/connectors/daikin/index.ts

@@ -1,10 +1,20 @@
 import { asOf, type Clock, realClock } from "../../clock.ts";
 import { z } from "zod";
-import type { Integration } from "../../home.ts";
+import {
+  type DeviceRecord,
+  deviceRecords,
+  type Integration,
+  type Part,
+} from "../../home.ts";
 import { type Finder, lostDetail, relocator } from "../../discover.ts";
 import type { Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
-import { daikinClient, DaikinError, type DaikinState } from "./client.ts";
+import {
+  daikinClient,
+  DaikinError,
+  type DaikinState,
+  type Mode,
+} from "./client.ts";
 
 export {
   DaikinError,
@@ -143,3 +153,32 @@ export const manifest: Manifest<DaikinSnapshot> = {
   ],
   lines: ({ state }) => (state ? [acText(state)] : []),
 };
+
+/** The AC as a home device: `state` is `off`, its mode while on, or `on` when it hasn't said which; `detail` its snapshot. */
+export type DaikinHomeDevice = DeviceRecord<
+  "daikin",
+  "ac",
+  "off" | "on" | Mode,
+  DaikinSnapshot
+>;
+
+/** The one unit, once it has been read. It reports no name or id of its own: a home config's entry names and places it. */
+export function daikinHomeDevices(
+  part: Part<DaikinSnapshot> | undefined,
+): DaikinHomeDevice[] {
+  const s = part?.state;
+  if (!s) return [];
+  return deviceRecords<DaikinHomeDevice>(part, [
+    {
+      connector: "daikin",
+      id: "daikin",
+      name: manifest.title,
+      kind: "ac",
+      available: true,
+      ...(s.on === undefined ? {} : { state: s.on ? (s.mode ?? "on") : "off" }),
+      asOf: s.asOf,
+      text: `${manifest.title}: ${acText(s)}`,
+      detail: s,
+    },
+  ]);
+}

package/src/connectors/enphase/index.ts

@@ -1,6 +1,12 @@
 import { type Clock, localDay, realClock } from "../../clock.ts";
 import { z } from "zod";
-import { filePath, type Integration } from "../../home.ts";
+import {
+  type DeviceRecord,
+  deviceRecords,
+  filePath,
+  type Integration,
+  type Part,
+} from "../../home.ts";
 import { type Finder, lostDetail, relocator } from "../../discover.ts";
 import { kw, type Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
@@ -102,7 +108,16 @@ export function enphase(
     name: "enphase",
     refresh: () => (where.reset(), poll.nudge()),
     async run(signal, update) {
-      const expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+      let expiresAt: Date;
+      try {
+        expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+      } catch {
+        return update({
+          status: "unavailable",
+          reason: "auth",
+          detail: "the token is unreadable; run `home enphase login`",
+        });
+      }
       let last: EnphaseSnapshot | undefined;
       let day:
         | {
@@ -168,6 +183,7 @@ export function enphase(
           if (error instanceof EnphaseError && error.status === 401)
             return update({
               status: "unavailable",
+              reason: "auth",
               detail:
                 "the gateway rejected the token; run `home enphase login`",
               state: last,
@@ -239,3 +255,34 @@ export const manifest: Manifest<EnphaseSnapshot> = {
   files: ["token"],
   lines: ({ state }) => (state ? [enphaseText(state)] : []),
 };
+
+/** The gateway as a home device: `state` is `producing` while the solar makes power, else `idle`; `detail` its snapshot. */
+export type EnphaseHomeDevice = DeviceRecord<
+  "enphase",
+  "solar",
+  "producing" | "idle",
+  EnphaseSnapshot
+>;
+
+/** The one gateway, once it has been read. */
+export function enphaseHomeDevices(
+  part: Part<EnphaseSnapshot> | undefined,
+): EnphaseHomeDevice[] {
+  const s = part?.state;
+  if (!s) return [];
+  return deviceRecords<EnphaseHomeDevice>(part, [
+    {
+      connector: "enphase",
+      id: "enphase",
+      name: manifest.title,
+      kind: "solar",
+      available: true,
+      ...(s.productionW === undefined
+        ? {}
+        : { state: s.productionW > 0 ? "producing" : "idle" }),
+      asOf: s.asOf,
+      text: `${manifest.title}: ${enphaseText(s)}`,
+      detail: s,
+    },
+  ]);
+}

package/src/connectors/hue/index.ts

@@ -5,6 +5,8 @@ import { type Finder, lostDetail, relocator } from "../../discover.ts";
 import {
   envName,
   filePath,
+  type DeviceRecord,
+  deviceRecords,
   type Integration,
   type Part,
   type Status,
@@ -14,8 +16,10 @@ import { bunPinnedFetch, type HueClient, hueClient } from "./client.ts";
 import { hueEvents, isRejectedKey } from "./events.ts";
 import type { HueEvent } from "./schemas.ts";
 import {
+  type GroupView,
   groups,
   type HueSnapshot,
+  type LightView,
   lights,
   reduce,
   snapshotFrom,
@@ -189,6 +193,7 @@ export function hue(
           if (isRejectedKey(error))
             return update({
               status: "unavailable",
+              reason: "auth",
               detail: "the bridge rejected the key; pair again",
               state: snapshot,
             });
@@ -215,6 +220,56 @@ const view = (s: HueSnapshot) => ({
   })),
 });
 
+/** "Kitchen: on · 40%", "Kitchen: off", or the name alone when the bridge hasn't said. */
+const onText = (v: {
+  name?: string;
+  id: string;
+  on?: boolean;
+  brightness?: number;
+}) =>
+  `${v.name ?? v.id}${v.on === undefined ? "" : `: ${v.on ? `on${v.brightness === undefined ? "" : ` · ${Math.round(v.brightness)}%`}` : "off"}`}`;
+
+/** A Hue light, or a room or zone, as a home device: `detail` is its `LightView` or `GroupView`. */
+export type HueHomeDevice =
+  | DeviceRecord<"hue", "light", "on" | "off", LightView>
+  | DeviceRecord<"hue", "group", "on" | "off", GroupView>;
+
+/** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */
+export function hueHomeDevices(
+  part: Part<HueSnapshot> | undefined,
+): HueHomeDevice[] {
+  const s = part?.state;
+  if (!s) return [];
+  const on = (v: { on?: boolean }) =>
+    v.on === undefined
+      ? {}
+      : { state: v.on ? ("on" as const) : ("off" as const) };
+  return deviceRecords<HueHomeDevice>(part, [
+    ...lights(s).map((l): HueHomeDevice => ({
+      connector: "hue",
+      id: l.id,
+      name: l.name ?? l.id,
+      kind: "light",
+      ...(l.reachable === undefined ? {} : { available: l.reachable }),
+      ...on(l),
+      asOf: s.asOf,
+      text: onText(l),
+      detail: l,
+    })),
+    ...groups(s).map((g): HueHomeDevice => ({
+      connector: "hue",
+      id: g.id,
+      name: g.name ?? g.id,
+      kind: "group",
+      ...on(g),
+      asOf: s.asOf,
+      text: onText(g),
+      members: g.lightIds,
+      detail: g,
+    })),
+  ]);
+}
+
 export const manifest: Manifest<HueSnapshot> = {
   name: "hue",
   title: "Philips Hue",
@@ -248,14 +303,8 @@ export const manifest: Manifest<HueSnapshot> = {
   /** "3 lights on", then "Kitchen: on · 40%" per room and zone. */
   lines({ state }) {
     if (!state) return [];
-    const { lightsOn, rooms } = view(state);
-    return [
-      `${lightsOn} lights on`,
-      ...rooms.map(
-        (r) =>
-          `${r.name}: ${r.on ? `on${r.brightness === undefined ? "" : ` · ${Math.round(r.brightness)}%`}` : "off"}`,
-      ),
-    ];
+    const { lightsOn } = view(state);
+    return [`${lightsOn} lights on`, ...groups(state).map(onText)];
   },
   record: ({ state }) => (state ? view(state) : {}),
 };

package/src/connectors/printers/README.md

@@ -1,6 +1,6 @@
 # Printers
 
-AirPrint printers, found by mDNS and read over IPP on the local network. `iot_class`: **local_polling** (one Get-Printer-Attributes per printer every 120 s). Built read-only; **untried on a live printer** (the Brother KO has did not answer mDNS on 2026-10-14, see Live findings).
+AirPrint printers, found by mDNS and read over IPP on the local network. `iot_class`: **local_polling** (one Get-Printer-Attributes per printer every 120 s). Built read-only; first read of a live printer 2026-11-10 (see Live findings).
 
 Try it: `home printers`
 
@@ -34,7 +34,9 @@ Everything, until a real printer answers: the request bytes (the codec is checke
 
 ## Live findings
 
-None yet. 2026-10-14 (Bun 1.4.3): `home discover` (two passes) and `home printers` found no `_ipp._tcp` or `_ipps._tcp` instance on the network, so the Brother was not advertising (off, asleep, or on another network).
+**2026-11-10, from a Pi (Bun 1.4.4, 0.1.2; chota-bot's session).** `home discover` found the Brother by mDNS and `home printers` read it: "Brother HL-L2350DW series: idle · BK 80% · A4 ready". So discovery, the request, the default path, a real `marker-levels` and `media-ready` work on this model. Still unverified from the list above: `printer-uuid` against TXT `UUID`, a sleeping printer waking, `printer-alert`, and the macOS local-network prompt.
+
+2026-10-14 (Bun 1.4.3): `home discover` (two passes) and `home printers` found no `_ipp._tcp` or `_ipps._tcp` instance on the network, so the Brother was not advertising (off, asleep, or on another network).
 
 ## Sources
 

package/src/connectors/printers/index.ts

@@ -11,7 +11,13 @@ import {
   lostDetail,
   rescanDelay,
 } from "../../discover.ts";
-import type { Integration, Part, Status } from "../../home.ts";
+import {
+  type DeviceRecord,
+  deviceRecords,
+  type Integration,
+  type Part,
+  type Status,
+} from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
 import { getPrinterAttributes, printerUrl } from "./client.ts";
@@ -19,6 +25,7 @@ import { attributesOf } from "./codec.ts";
 import {
   type Printer,
   printerKey,
+  type PrinterStatus,
   printerText,
   type PrintersState,
   type Reading,
@@ -383,3 +390,38 @@ export const manifest: Manifest<PrintersState> = {
     ];
   },
 };
+
+/** A printer as a home device: `state` is the printer's own (`idle`, `printing`, `stopped`, `offline`); `detail` its `Printer`. */
+export type PrinterHomeDevice = DeviceRecord<
+  "printers",
+  "printer",
+  PrinterStatus,
+  Printer
+>;
+
+/** Every printer, by name. One that has stopped answering is not `available`, and keeps its last values. */
+export function printersHomeDevices(
+  part: Part<PrintersState> | undefined,
+): PrinterHomeDevice[] {
+  if (!part?.state) return [];
+  return deviceRecords(
+    part,
+    printerList(part.state).map((p): PrinterHomeDevice => ({
+      connector: "printers",
+      id: p.uuid,
+      name: p.name,
+      kind: "printer",
+      ...(p.state === undefined ? {} : { available: p.state !== "offline" }),
+      ...(p.state === undefined ? {} : { state: p.state }),
+      // An offline printer's values are from when it last answered, not from this check.
+      ...(p.state === "offline"
+        ? p.lastSeen === undefined
+          ? {}
+          : { asOf: p.lastSeen }
+        : { asOf: p.asOf }),
+      text: printerText(p),
+      ...(p.room ? { room: p.room } : {}),
+      detail: p,
+    })),
+  );
+}

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**. Reads seen live on a real Soloist (2026-11-09); writes tested against a fake socket only.
+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,26 +14,28 @@ 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` and `interrupt` run `fn` over the music with `music: "untouched"`: "playing" while inactive is the account playing on another speaker, which a pause would stop. `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 a start from idle (to playing or buffering, or the first such status after a sign-in; a start through buffering opens the window again at `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:
 
-- `untouched`: not playing or buffering, not connected, (duck) the volume unknown or already at `to` or below, or the lowering or pause failed, so `fn` ran over it.
+- `untouched`: not playing or buffering, not connected, not the active device, (duck) the volume unknown or already at `to` or below, or the lowering or pause failed, so `fn` ran over it.
 - `restored`: put back as it was.
 - `kept`: someone changed it meanwhile (resumed, skipped, set the volume), or the pause or lower volume never showed. Theirs stays.
 - `failed`: the restore failed or was never reported; it may be left quiet or paused.
 
 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` 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.
+**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,7 +54,7 @@ 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
 
@@ -60,11 +62,33 @@ 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:** the order of statuses at a start. Soloist's docs list `buffering` but not when it comes; #23 reports the 100% about 100 ms after `playing`, on the first play after the process starts.
+- **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-10, Raspberry Pi 5, Bun 1.4.4, on 0.1.2, through this connector** (chota-bot's session, KO listening).
+
+- Confirmed with `maxVolume: 60`, the speaker active and playing: `activate`, `setVolume(50)`, `setVolume(90)` (came back 60), `seek`, `setShuffle`, `setRepeat("context")` and `("off")` (about 2.1 s each), `queue` (first in `upNext`), `play` of a playlist URI. `duck(fn, { to: 20 })` around a Cast announce: 20 inside, `music: "restored"`, 60 after, 5.2 s in all.
+- **The level can jump above the cap on a pause, not only on a start.** One-shot CLI, cap 60: `volume 45` read 45, `play` 45, then `pause` read 62 and the next `play` 62 (62 was the level before the test). Nothing lowered it: a pause is not a start signal, and each CLI command is a new process.
+- **That jump did not repeat, and it is not WirePlumber.** A second pass the same day, the speaker already active: 60, `volume 45`, `pause`, `play`, `volume 60`. Soloist's number and the stream's live level (`wpctl get-volume`) matched at every step (0.60, 0.45, 0.45, 0.45, 0.60), WirePlumber 0.5.8 never wrote a saved entry for the stream in `stream-properties`, and the stream kept its id across pause and play. The run that jumped had just been made active with `activate`, minutes after the account was casting from a phone, which points at the account side. One case each way.
+- **`active: false` with `status: "playing"`:** the account playing on another speaker. `speakerState` says `playing`, `spotifyText` prints it as this speaker's, and `spotifyChanges` fired `resumed`, with the box silent.
+- Through chota-bot's wrapper, later the same day: `play` of a playlist confirmed in 241 ms, `next` in 134 ms, `pause` in 17 ms; `duck` to 15 and `interrupt`, 2.5 s each, both `restored`. `play()` with the music paused on a Cast speaker: confirmed in 1.3 s, playing on the box at the same position.
+- **`interrupt` paused music that was on another speaker** (found in chota's switch): it checked `playing` and not `active`. Fixed after 0.1.2.
+- `positionMs` around a duck and an interrupt read 2 s, 2 s, 3 s, 5 s, then 4 s after a pause: it can step back a second.
+- A consumer's test with a fake socket: a write goes out behind the connector's own queries (`get_state`, `get_queue`), up to about 1 s on a fresh socket, so "the command was sent" can't be checked straight after the call.
+- Not run: the first-play cap from idle (the box never went active), stall events.
+
+**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.

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 });