@khalido/home 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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.
+
+### Added
+
+- **`discover`:** a `stopOn` option, for an error no later pass could get past.
+
+### Changed
+
+- **cast:** `tlsConnect` gives up after 3 s, down from 10 s, so one offline device holds up a one-shot read for less. A device whose cached address fails and that discovery can't find no longer gets a second try before it shows as disconnected. `home cast` with one device down: 13.3 s to 2.3 s (Bun 1.4.4, macOS, 2026-11-09).
+
+### Fixed
+
+- **spotify:** `maxVolume`'s first-play window now opens on a start through `buffering` too: idle → buffering → playing escaped it.
+- **weather:** the text's chance of rain for today is the highest of the hours still to come, once that's lower than the day's figure and from the same source, and it says "the rest of the day". `forecast.today.rainChance` stays as the source gave it.
+- **`home discover`:** without `avahi-browse` or `dns-sd` it fails at once, naming the package, instead of after both passes.
+- **spotify:** a frame or open event from a socket that had already ended (dropped, or closed after 10 s with no message) no longer changes the state or the next socket's status.
+- **cast:** `@khalido/home/cast/serve`'s types no longer name `NodeJS.Dict`, so they compile without `@types/node`.
+- **Docs:** corrected the config parser, the printers exception to one device per connector, Daikin's `home status` address, and the weather user agent. `skills/draw-home` no longer points at private paths.
+
 ## [0.1.0] - 2026-11-08
 
 First release. Nine connectors: Hue, Daikin, Enphase, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber prices, Up Bank spending and the weather from the cloud. Each connector's README says what has run against a real device.
@@ -21,5 +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.0...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 () => {
@@ -297,7 +299,9 @@ export function cast(config) {
                     // A cached address that fails is only stale: discover now and try where it answers, still "connecting".
                     cached = false;
                     await discover();
-                    continue;
+                    // Unless discovery can't find it: then the address is the one that just failed, and a second try only waits out the timeout. The backoff still retries.
+                    if (!lastFound || lastFound.has(id))
+                        continue;
                 }
                 const why = errorText(error);
                 // A cached address the last discovery did not find says so, as a polling connector's does.
@@ -357,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/serve.d.ts

@@ -1,11 +1,18 @@
 import type { ServeClip } from "./writes.ts";
 /** How long a clip stays served when nothing fetches it. */
 export declare const SERVE_MS = 60000;
+type NetworkAddress = {
+    family: string;
+    address: string;
+    netmask: string;
+    internal: boolean;
+};
 /** This machine's IPv4 on the subnet that holds `host`, or with no host, its first non-internal IPv4. */
-export declare function lanAddress(host?: string, interfaces?: NodeJS.Dict<import("node:os").NetworkInterfaceInfo[]>): string;
+export declare function lanAddress(host?: string, interfaces?: Record<string, NetworkAddress[] | undefined>): string;
 /**
  * Serve `bytes`: a random port, an unguessable path, the given `Content-Type` and its `Content-Length`, the whole body
  * to every GET (a player may probe before it fetches). It closes on `close()` (`announce` calls it when the clip has
  * played), when `signal` aborts, or after `SERVE_MS`. `host` is the device that will fetch it, so the address is on its network.
  */
 export declare const serveClip: ServeClip;
+export {};

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/tls.js

@@ -6,7 +6,7 @@ import { encode, framer, } from "./codec.js";
 // Verification is off: every Cast device presents a self-signed certificate that rotates every 48 hours, so there is
 // nothing to pin. The integration instead checks the certificate's name (`peer`, the device's id) against discovery.
 /** Open a Cast socket: TLS to host:port within `timeoutMs`, framed CastMessages in and out. */
-export const tlsConnect = ({ host, port, signal, timeoutMs = 10_000, }) => new Promise((resolve, reject) => {
+export const tlsConnect = ({ host, port, signal, timeoutMs = 3000, }) => new Promise((resolve, reject) => {
     const socket = connect({ host, port, rejectUnauthorized: false });
     let timer;
     const fail = (error) => (clearTimeout(timer),

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