@khalido/home 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-11-09
+
+From chota-bot's live writes on a Raspberry Pi. `setVolume` on an inactive speaker now rejects, and `track` events can come later than before.
+
+### Added
+
+- **spotify:** `activate()`, and `home spotify activate`.
+- **cast:** `announceAll(targets, clip, options)`, one result per device, and repeated `--to` on `home cast announce` (`--json` is an array with several).
+- **cast:** `form` on a device whose model it knows (`speaker`, `display`, `tv`, from `castForm(model)`), so "all speakers" can skip TVs. The address cache keeps the model; a cached device without one goes through discovery once.
+- **up:** the integration has `client`, for a consumer's writes.
+
+### Changed
+
+- **spotify:** `setVolume` while the speaker isn't the active device rejects with code `inactive`, instead of `confirmed: false`: Soloist accepts it and drops it. `duck` then runs `fn` with `music: "untouched"`.
+- **spotify:** `play` while inactive goes active first.
+- **spotify:** the `track` event waits for the track's name.
+- **cast:** a clip that doesn't start playing fails after 15 s (or `timeoutMs`), naming its type. An error the receiver reports sooner gives its reason, and its code if it has one.
+
+### Fixed
+
+- **spotify:** `maxVolume` waits until the speaker is active, retries until Soloist reports the lower volume, and says "lowered it" only then; if it never shows, `detail` says so. It said "lowered it" at 56 with a cap of 40. The window also opens when the speaker goes active.
+- **spotify:** `setRepeat("off")` from `track` stayed on `track`: the two commands now go 600 ms apart.
+- **spotify:** a volume within 1 of the request confirms, since Soloist rounds it.
+- **spotify:** a stall repair can run again when a track comes back after another.
+- **`home cast announce`** exits 1 when a clip didn't play.
+
 ## [0.1.1] - 2026-11-09
 
 Fixes from chota-bot's first live reads, on a Raspberry Pi and a Mac. No breaking changes.
@@ -42,6 +68,7 @@ First release. Nine connectors: Hue, Daikin, Enphase, Google Cast, AirPrint prin
 - **Agent skills** in `skills/`: `use-home` (reading safely, connecting, the rules for writes) and `draw-home` (an SVG plan of a home and its rooms). `llms.txt` points agents at the docs.
 - **Node.** Hue and Enphase take the fetches in `@khalido/home/node`. The library runs on Bun 1.4+ and Node 24+; the `home` command needs Bun.
 
-[Unreleased]: https://github.com/khalido/home.ts/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/khalido/home.ts/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/khalido/home.ts/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/khalido/home.ts/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/khalido/home.ts/releases/tag/v0.1.0

package/README.md

@@ -50,17 +50,17 @@ The library never reads your environment or a file: you pass addresses, keys and
 
 ## Connectors
 
-| Connector                                     | Reads                                                                                                 | Writes                                                                                                                                                                                                                    |
-| --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [hue](src/connectors/hue/README.md)           | lights, rooms, scenes, over the bridge's event stream                                                 | lights, rooms, scenes                                                                                                                                                                                                     |
-| [daikin](src/connectors/daikin/README.md)     | the AC, over its local API                                                                            | power, mode, setpoint, fan                                                                                                                                                                                                |
-| [enphase](src/connectors/enphase/README.md)   | solar production and consumption from the IQ Gateway                                                  | none                                                                                                                                                                                                                      |
-| [cast](src/connectors/cast/README.md)         | every Cast device and speaker group                                                                   | volume, mute, stop, announcements                                                                                                                                                                                         |
-| [printers](src/connectors/printers/README.md) | AirPrint printers over IPP: state, toner, paper                                                       | none                                                                                                                                                                                                                      |
-| [spotify](src/connectors/spotify/README.md)   | a Spotify Soloist speaker: what is playing, volume, shuffle, over its local WebSocket                 | play a link, pause, resume, skip, seek, volume (capped), queue, shuffle, repeat, each confirmed by what the speaker reports; turn down or pause around an announcement; a stalled stream noticed and, if asked, restarted |
-| [amber](src/connectors/amber/README.md)       | live import and feed-in prices                                                                        | none                                                                                                                                                                                                                      |
-| [up](src/connectors/up/README.md)             | household spending by category, what still needs one                                                  | a category or tag on a transaction                                                                                                                                                                                        |
-| [weather](src/connectors/weather/README.md)   | now, forecast by the hour and by part of the day, rain soon, the sun, from BOM, Open-Meteo and Google | none                                                                                                                                                                                                                      |
+| Connector                                     | Reads                                                                                                 | Writes                                                                                                                                                                                                                              |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [hue](src/connectors/hue/README.md)           | lights, rooms, scenes, over the bridge's event stream                                                 | lights, rooms, scenes                                                                                                                                                                                                               |
+| [daikin](src/connectors/daikin/README.md)     | the AC, over its local API                                                                            | power, mode, setpoint, fan                                                                                                                                                                                                          |
+| [enphase](src/connectors/enphase/README.md)   | solar production and consumption from the IQ Gateway                                                  | none                                                                                                                                                                                                                                |
+| [cast](src/connectors/cast/README.md)         | every Cast device and speaker group                                                                   | volume, mute, stop, announcements                                                                                                                                                                                                   |
+| [printers](src/connectors/printers/README.md) | AirPrint printers over IPP: state, toner, paper                                                       | none                                                                                                                                                                                                                                |
+| [spotify](src/connectors/spotify/README.md)   | a Spotify Soloist speaker: what is playing, volume, shuffle, over its local WebSocket                 | activate, play a link, pause, resume, skip, seek, volume (capped), queue, shuffle, repeat, each confirmed by what the speaker reports; turn down or pause around an announcement; a stalled stream noticed and, if asked, restarted |
+| [amber](src/connectors/amber/README.md)       | live import and feed-in prices                                                                        | none                                                                                                                                                                                                                                |
+| [up](src/connectors/up/README.md)             | household spending by category, what still needs one                                                  | a category or tag on a transaction                                                                                                                                                                                                  |
+| [weather](src/connectors/weather/README.md)   | now, forecast by the hour and by part of the day, rain soon, the sun, from BOM, Open-Meteo and Google | none                                                                                                                                                                                                                                |
 
 Each connector's README says what has run against a real device and what has not. This covers only the devices I own; [Home Assistant](https://www.home-assistant.io/) is the inspiration and the reference for every protocol.
 

package/dist/config.js

@@ -331,7 +331,9 @@ export function loadHome(input, options) {
                 {
                     castId: x.castId,
                     name: x.name,
-                    ...(c?.port === undefined ? {} : { host: c.host, port: c.port }),
+                    ...(c?.port === undefined
+                        ? {}
+                        : { host: c.host, port: c.port, model: c.model }),
                 },
             ];
         });

package/dist/connectors/cast/index.d.ts

@@ -7,7 +7,8 @@ import { type CastConnect } from "./codec.ts";
 import { type CastDevice, type CastSnapshot, type Resolved } from "./state.ts";
 import { type CastActions, type ServeClip } from "./writes.ts";
 export type { CastConnect } from "./codec.ts";
-export type { CastDevice, CastSnapshot, Resolved } from "./state.ts";
+export { castForm } from "./state.ts";
+export type { CastDevice, CastForm, CastSnapshot, Resolved } from "./state.ts";
 export type { AnnounceResult, CastActions, CastClip, ServeClip, } from "./writes.ts";
 /** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */
 export declare const configSchema: z.ZodObject<{
@@ -30,6 +31,7 @@ export type CastConfig = {
     expect?: {
         castId: string;
         name: string;
+        model?: string;
         host?: string;
         port?: number;
     }[];
@@ -38,6 +40,7 @@ export type CastConfig = {
         host: string;
         port: number;
         name?: string;
+        model?: string;
     }) => void;
     clock?: Clock;
     /** Heartbeat interval; a socket silent for three of them is dropped. */

package/dist/connectors/cast/index.js

@@ -7,6 +7,7 @@ import { NS } from "./codec.js";
 import { CastPayload, KNOWN_TYPES } from "./schemas.js";
 import { castKey, connection, found, mediaApp, reduce, } from "./state.js";
 import { castActions, } from "./writes.js";
+export { castForm } from "./state.js";
 /** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */
 export const configSchema = z.looseObject({
     connector: z.literal("cast"),
@@ -205,6 +206,7 @@ export function cast(config) {
                 host: d.host,
                 port: d.port,
                 name: named.has(id) ? d.name : undefined,
+                model: d.model,
             }); // a config's name never reaches the cache
             publish();
             void (async () => {
@@ -359,10 +361,14 @@ export function cast(config) {
             report = update;
             running = signal;
             const expect = config.expect ?? [];
-            const cached = expect.filter((e) => e.host !== undefined && e.port !== undefined);
+            // A device with no model (a cache from before 0.1.2) goes through discovery once, or it would never get a `form`.
+            const cached = expect.filter((e) => e.host !== undefined &&
+                e.port !== undefined &&
+                (e.port !== 8009 || e.model !== undefined));
             snapshot = found(snapshot, cached.map((e) => ({
                 id: e.castId,
                 name: e.name,
+                model: e.model,
                 host: e.host,
                 port: e.port,
                 group: e.port !== 8009,

package/dist/connectors/cast/schemas.d.ts

@@ -41,6 +41,7 @@ export declare const MediaStatus: z.ZodObject<{
         mediaSessionId: z.ZodOptional<z.ZodNumber>;
         playerState: z.ZodOptional<z.ZodString>;
         idleReason: z.ZodOptional<z.ZodString>;
+        detailedErrorCode: z.ZodOptional<z.ZodNumber>;
         currentTime: z.ZodOptional<z.ZodNumber>;
         media: z.ZodOptional<z.ZodObject<{
             contentId: z.ZodOptional<z.ZodString>;
@@ -118,6 +119,7 @@ export declare const CastPayload: z.ZodDiscriminatedUnion<[z.ZodObject<{
         mediaSessionId: z.ZodOptional<z.ZodNumber>;
         playerState: z.ZodOptional<z.ZodString>;
         idleReason: z.ZodOptional<z.ZodString>;
+        detailedErrorCode: z.ZodOptional<z.ZodNumber>;
         currentTime: z.ZodOptional<z.ZodNumber>;
         media: z.ZodOptional<z.ZodObject<{
             contentId: z.ZodOptional<z.ZodString>;

package/dist/connectors/cast/schemas.js

@@ -36,6 +36,7 @@ export const MediaStatus = z.looseObject({
         mediaSessionId: z.number().optional(),
         playerState: z.string().optional(), // "PLAYING" | "PAUSED" | "BUFFERING" | "IDLE"
         idleReason: z.string().optional(), // "FINISHED" | "CANCELLED" | "INTERRUPTED" | "ERROR"
+        detailedErrorCode: z.number().optional(),
         currentTime: z.number().optional(), // seconds into the media
         media: z
             .looseObject({

package/dist/connectors/cast/state.d.ts

@@ -1,4 +1,7 @@
 import type { CastPayload } from "./schemas.ts";
+/** What a device is for, read from its model name; a model it doesn't know has none. A group is `kind: "group"`. */
+export type CastForm = "speaker" | "display" | "tv";
+export declare function castForm(model?: string): CastForm | undefined;
 /** A Cast device or group as found by discovery: what `resolve` returns for each. */
 export type Resolved = {
     id: string;
@@ -16,6 +19,7 @@ export type CastDevice = {
     id: string;
     name: string;
     model?: string;
+    form?: CastForm;
     kind: "device" | "group";
     host?: string;
     port?: number;

package/dist/connectors/cast/state.js

@@ -1,3 +1,14 @@
+export function castForm(model) {
+    if (!model)
+        return undefined;
+    if (/hub|tablet|display/i.test(model))
+        return "display";
+    if (/audio|speaker|mini|google home/i.test(model))
+        return "speaker";
+    if (/chromecast|streamer|\btv\b/i.test(model))
+        return "tv";
+    return undefined;
+}
 /** An id as the snapshot keys it: the mDNS id (32 hex) and the certificate's and multizone's dashed UUID are one key. */
 export const castKey = (id) => id.toLowerCase().replace(/-/g, "");
 /** Add or update what discovery found; devices it did not find this time are kept as they were. */
@@ -11,6 +22,7 @@ export function found(s, entries, asOf) {
             id,
             name: e.name,
             model: e.model,
+            form: kind === "device" ? castForm(e.model) : undefined,
             kind,
             host: e.host,
             port: e.port,

package/dist/connectors/cast/writes.d.ts

@@ -6,6 +6,8 @@ export declare const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
 export declare const ANSWER_MS = 10000;
 /** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */
 export declare const PLAY_MS = 60000;
+/** 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 declare const START_MS = 15000;
 /** 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. */
 export declare const VOLUME_PER_MINUTE = 30;
 /** What to play: a URL the device can fetch (type defaults to audio/mpeg), or bytes for `serve` to put on the LAN. */
@@ -44,6 +46,13 @@ export type CastActions = {
         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. */
 export type RawPayload = {

package/dist/connectors/cast/writes.js

@@ -11,6 +11,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. */
 export const VOLUME_PER_MINUTE = 30;
@@ -33,6 +35,7 @@ function checkLevel(level) {
  * aborts, or after `ms` (a function is read again each time it would expire, so a deadline can grow).
  */
 function waitFor(clock, s, ms, what, pick, signal) {
+    const name = () => (typeof what === "string" ? what : what());
     return new Promise((resolve, reject) => {
         const done = new AbortController();
         const finish = (settle) => done.signal.aborted ||
@@ -40,10 +43,10 @@ function waitFor(clock, s, ms, what, pick, signal) {
                 signal?.removeEventListener("abort", cancel),
                 done.abort(),
                 settle());
-        const cancel = () => finish(() => reject(new Error(`stopped waiting for ${what}`)));
+        const cancel = () => 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}`)));
+                return finish(() => reject(new Error(`the socket closed waiting for ${name()}`)));
             try {
                 const value = pick(raw);
                 if (value !== undefined)
@@ -59,7 +62,7 @@ function waitFor(clock, s, ms, what, pick, signal) {
         void (async () => {
             for (let left = limit(); left > 0 && !done.signal.aborted; left = start + limit() - clock.now())
                 await clock.sleep(left, done.signal);
-            finish(() => reject(new Error(`no ${what} in ${Math.round(limit() / 1000)} s`)));
+            finish(() => reject(new Error(`no ${name()} in ${Math.round(limit() / 1000)} s`)));
         })();
     });
 }
@@ -171,8 +174,11 @@ export function castActions(ctx) {
         const loadId = s.nextId();
         let session;
         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", (raw) => {
+        const finished = waitFor(clock, s, () => 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;
@@ -187,11 +193,13 @@ export function castActions(ctx) {
                     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;
         }, cancel.signal);
@@ -216,7 +224,7 @@ export function castActions(ctx) {
             .get(id)
             .send("level" in volume ? "level" : "muted", volume, (v) => receiver(live(find(target)), { type: "SET_VOLUME", volume: v }));
     };
-    return {
+    const actions = {
         async setVolume(target, level) {
             checkLevel(level);
             await setVolume(target, { level });
@@ -386,5 +394,33 @@ export function castActions(ctx) {
                 }
             }
         },
+        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) => {
+                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) => ({
+                    played: false,
+                    why: errorText(error),
+                    restored: [],
+                    notRestored: [],
+                }))),
+            })));
+        },
     };
+    return actions;
 }

package/dist/connectors/spotify/changes.d.ts

@@ -24,7 +24,7 @@ export type SpotifyEvent = {
 /**
  * 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 declare function spotifyChanges(before: Part<SpotifyState> | undefined, after: Part<SpotifyState> | undefined): SpotifyEvent[];

package/dist/connectors/spotify/changes.js

@@ -22,7 +22,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(before, after) {
@@ -55,7 +55,9 @@ export function spotifyChanges(before, after) {
         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) => !!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/dist/connectors/spotify/client.d.ts

@@ -158,7 +158,7 @@ export type SpotifyState = {
         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. */

package/dist/connectors/spotify/index.d.ts

@@ -49,9 +49,11 @@ export type Aside<T> = {
 /**
  * The writes, on the object `spotify()` returns. Each resolves once Soloist reports the change it asked for, with the state
  * then (`confirmed: true`), or after `CONFIRM_MS` with the state as it stands (`confirmed: false`). Each rejects with a
- * `ConnectorError` whose `code` is `offline`, `waiting` (nobody has picked the speaker), `refused`, `timeout` or `invalid`.
+ * `ConnectorError` whose `code` is `offline`, `waiting` (nobody has picked the speaker), `inactive` (`setVolume` on a speaker that isn't the active device: `activate()` first), `refused`, `timeout` or `invalid`.
  */
 export type SpotifyActions = {
+    /** Make this the account's active Spotify device. Soloist drops volume changes until it is. It makes a new audio stream, so the volume can jump to the level last saved. */
+    activate(): Promise<Applied>;
     /** Play a Spotify link or URI (track, album, playlist, artist, episode, show), or resume what is loaded when none is given. */
     play(linkOrUri?: string): Promise<Applied>;
     pause(): Promise<Applied>;