@khalido/home 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-11-12
+
+### Added
+
+- **cast:** WAV speech. `announce` rewrites a clip of WAV bytes as 48 kHz, 16-bit, stereo PCM before serving it, in plain TypeScript, so a bot's TTS WAV needs no ffmpeg; a dry run says so. A 24 kHz mono WAV failed on audio-only Nest speakers (2026-11-09); rewritten, it played on a Nest Audio, a Nest Mini, a Google Home speaker, a Nest Hub and a Nest Hub Max (2026-11-12). `castWav`, `CAST_WAV` and the `WavFormat` type are exported for a clip served by URL; a clip given as a URL is sent as it is.
+- **cast, spotify:** dry run. Every Cast and Spotify write takes `{ dryRun: true }`: it checks as a real write does, sends nothing, and says what it would send (`wouldSend`). Cast's `setVolume`, `setMuted` and `stop` now resolve `{ wouldSend }` under a dry run and `undefined` otherwise; a dry `announce` also names in `notRestored` the app it would interrupt, and serves nothing. Spotify's `duck` and `interrupt` run `fn` and say in `why` what they would have done. `home cast …` and `home spotify …` take `--dry-run`. New types: `CastRequest`, `CastDryRun`, `CastWriteOptions`, `SpotifyRequest`, `SpotifyWriteOptions`.
+
 ## [0.2.1] - 2026-11-12
 
 ### Added
@@ -151,7 +158,8 @@ 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.2.1...HEAD
+[Unreleased]: https://github.com/khalido/home.ts/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/khalido/home.ts/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/khalido/home.ts/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/khalido/home.ts/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/khalido/home.ts/compare/v0.1.2...v0.1.3

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

@@ -9,7 +9,8 @@ import { type CastActions, type ServeClip } from "./writes.ts";
 export type { CastConnect } from "./codec.ts";
 export { castDevices, castForm, castFree, castFreeSpeakers, castStatus, } from "./state.ts";
 export type { CastDevice, CastForm, CastSkipped, CastSnapshot, CastStatus, Resolved, } from "./state.ts";
-export type { AnnounceResult, CastActions, CastClip, ServeClip, } from "./writes.ts";
+export { CAST_WAV, castWav, type WavFormat } from "./wav.ts";
+export type { AnnounceResult, CastActions, CastClip, CastDryRun, CastRequest, CastWriteOptions, 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<{
     connector: z.ZodLiteral<"cast">;

package/dist/connectors/cast/index.js

@@ -9,6 +9,7 @@ import { CastPayload, KNOWN_TYPES } from "./schemas.js";
 import { castKey, connection, found, mediaApp, reduce, castDevices, castStatus, } from "./state.js";
 import { castActions, } from "./writes.js";
 export { castDevices, castForm, castFree, castFreeSpeakers, castStatus, } from "./state.js";
+export { CAST_WAV, castWav } from "./wav.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"),

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

@@ -0,0 +1,31 @@
+/** What a WAV file says about its audio. */
+export type WavFormat = {
+    sampleRate: number;
+    channels: number;
+    bitsPerSample: number;
+    /** 1 integer PCM, 3 IEEE float; WAVE_FORMAT_EXTENSIBLE is read as its sub-format. */
+    encoding: "pcm" | "float";
+};
+/** The rate, depth and channels every WAV clip is rewritten to. */
+export declare const CAST_WAV: Omit<WavFormat, "encoding">;
+/** Whether a clip's MIME type is WAV. */
+export declare const isWav: (type: string | undefined) => boolean;
+/** A WAV file's format and its samples, each channel as floats −1 to 1. Throws on anything but integer or float PCM. */
+export declare function readWav(bytes: Uint8Array): {
+    format: WavFormat;
+    channels: Float32Array[];
+};
+/**
+ * A WAV clip as one a Cast speaker plays: 48 kHz, 16-bit, stereo (`CAST_WAV`). A clip already in that form comes back as
+ * it is. Mono is copied to both channels; more than two channels keep the first two. A float sample past ±1 is limited to
+ * full scale, as any 16-bit output must.
+ */
+export declare function castWav(bytes: Uint8Array): {
+    bytes: Uint8Array;
+    from: WavFormat;
+    converted: boolean;
+};
+/** A format in a few words: `24000 Hz mono 16-bit`. */
+export declare const wavText: (f: Omit<WavFormat, "encoding"> & {
+    encoding?: string;
+}) => string;

package/dist/connectors/cast/wav.js

@@ -0,0 +1,149 @@
+// WAV for Cast speakers. Google lists WAV (LPCM) for Google Home speakers without saying which rates
+// (developers.google.com/cast/docs/media), and a 24 kHz mono WAV failed on two audio-only Nest speakers while the displays
+// played it (live, 2026-11-09). So a WAV clip is rewritten as 48 kHz, 16-bit, stereo, the most common LPCM there is, in
+// plain TypeScript: no encoder, nothing to install. Linear interpolation with no low-pass: enough for speech (TTS is 16 to
+// 24 kHz); a source above 48 kHz would alias.
+/** The rate, depth and channels every WAV clip is rewritten to. */
+export const CAST_WAV = {
+    sampleRate: 48_000,
+    channels: 2,
+    bitsPerSample: 16,
+};
+const WAV_TYPES = new Set([
+    "audio/wav",
+    "audio/wave",
+    "audio/x-wav",
+    "audio/vnd.wave",
+]);
+/** Whether a clip's MIME type is WAV. */
+export const isWav = (type) => !!type && WAV_TYPES.has(type.split(";")[0].trim().toLowerCase());
+const ascii = (b, at) => String.fromCharCode(b[at], b[at + 1], b[at + 2], b[at + 3]);
+/** A WAV file's format and its samples, each channel as floats −1 to 1. Throws on anything but integer or float PCM. */
+export function readWav(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
+    if (bytes.length < 12 ||
+        ascii(bytes, 0) !== "RIFF" ||
+        ascii(bytes, 8) !== "WAVE")
+        throw new Error("wav: not a RIFF WAVE file");
+    let format;
+    let blockAlign = 0;
+    let data;
+    for (let at = 12; at + 8 <= bytes.length;) {
+        const id = ascii(bytes, at);
+        const size = view.getUint32(at + 4, true);
+        // 0xFFFFFFFF is a streaming writer's "unknown length" (ffmpeg on a pipe): to the end. Otherwise a chunk cut short is
+        // a file cut short, and a cut-off announcement must not play as if it were whole.
+        const end = size === 0xffffffff ? bytes.length : at + 8 + size;
+        if (end > bytes.length && (id === "fmt " || id === "data"))
+            throw new Error(`wav: the ${id.trim()} chunk says ${size} bytes, the file has ${bytes.length - at - 8}`);
+        const body = bytes.subarray(at + 8, Math.min(end, bytes.length));
+        if (id === "fmt ") {
+            if (body.length < 16)
+                throw new Error("wav: a fmt chunk under 16 bytes");
+            const f = new DataView(body.buffer, body.byteOffset, body.length);
+            let tag = f.getUint16(0, true);
+            if (tag === 0xfffe && body.length >= 26)
+                tag = f.getUint16(24, true); // extensible: the sub-format GUID's first two bytes
+            if (tag !== 1 && tag !== 3)
+                throw new Error(`wav: format ${tag} is not PCM or float`);
+            format = {
+                channels: f.getUint16(2, true),
+                sampleRate: f.getUint32(4, true),
+                bitsPerSample: f.getUint16(14, true),
+                encoding: tag === 3 ? "float" : "pcm",
+            };
+            blockAlign = f.getUint16(12, true);
+        }
+        else if (id === "data")
+            data = body;
+        if (size === 0xffffffff)
+            break;
+        at += 8 + size + (size % 2); // chunks are padded to an even length
+    }
+    if (!format)
+        throw new Error("wav: no fmt chunk");
+    if (!data)
+        throw new Error("wav: no data chunk");
+    const { channels: n, bitsPerSample: bits, encoding } = format;
+    const width = bits / 8;
+    if (!n ||
+        !format.sampleRate ||
+        !(encoding === "float" ? bits === 32 : [8, 16, 24, 32].includes(bits)))
+        throw new Error(`wav: ${bits}-bit ${encoding}, ${n} channels at ${format.sampleRate} Hz is not read`);
+    if (blockAlign !== width * n)
+        throw new Error(`wav: ${blockAlign} bytes a frame, not ${width * n} for ${n} × ${bits}-bit`);
+    const frames = Math.floor(data.length / (width * n));
+    if (!frames)
+        throw new Error("wav: no samples");
+    const d = new DataView(data.buffer, data.byteOffset, data.length);
+    const out = Array.from({ length: n }, () => new Float32Array(frames));
+    for (let i = 0; i < frames; i++)
+        for (let c = 0; c < n; c++) {
+            const at = (i * n + c) * width;
+            out[c][i] =
+                encoding === "float"
+                    ? d.getFloat32(at, true)
+                    : bits === 8
+                        ? (d.getUint8(at) - 128) / 128
+                        : bits === 16
+                            ? d.getInt16(at, true) / 32768
+                            : bits === 24
+                                ? ((d.getUint8(at + 2) << 24) |
+                                    (d.getUint8(at + 1) << 16) |
+                                    (d.getUint8(at) << 8)) /
+                                    2147483648
+                                : d.getInt32(at, true) / 2147483648;
+        }
+    return { format, channels: out };
+}
+/**
+ * A WAV clip as one a Cast speaker plays: 48 kHz, 16-bit, stereo (`CAST_WAV`). A clip already in that form comes back as
+ * it is. Mono is copied to both channels; more than two channels keep the first two. A float sample past ±1 is limited to
+ * full scale, as any 16-bit output must.
+ */
+export function castWav(bytes) {
+    const { format, channels } = readWav(bytes);
+    const { sampleRate: rate, channels: n, bitsPerSample } = CAST_WAV;
+    if (format.encoding === "pcm" &&
+        format.sampleRate === rate &&
+        format.channels === n &&
+        format.bitsPerSample === bitsPerSample)
+        return { bytes, from: format, converted: false };
+    const src = [channels[0], channels[1] ?? channels[0]];
+    const frames = Math.round((src[0].length * rate) / format.sampleRate);
+    const step = format.sampleRate / rate;
+    const out = new Uint8Array(44 + frames * n * 2);
+    const v = new DataView(out.buffer);
+    const text = (at, s) => [...s].forEach((ch, i) => v.setUint8(at + i, ch.charCodeAt(0)));
+    text(0, "RIFF");
+    v.setUint32(4, out.length - 8, true);
+    text(8, "WAVE");
+    text(12, "fmt ");
+    v.setUint32(16, 16, true);
+    v.setUint16(20, 1, true); // PCM
+    v.setUint16(22, n, true);
+    v.setUint32(24, rate, true);
+    v.setUint32(28, rate * n * 2, true); // bytes per second
+    v.setUint16(32, n * 2, true); // bytes per frame
+    v.setUint16(34, 16, true);
+    text(36, "data");
+    v.setUint32(40, frames * n * 2, true);
+    for (let i = 0; i < frames; i++) {
+        const x = i * step;
+        const j = Math.floor(x);
+        const t = x - j;
+        for (let c = 0; c < n; c++) {
+            const s = src[c];
+            const a = s[j] ?? 0;
+            const b = s[j + 1] ?? a;
+            const raw = a + (b - a) * t;
+            if (Number.isNaN(raw))
+                throw new Error(`wav: sample ${j} is not a number`);
+            const y = Math.max(-1, Math.min(1, raw));
+            v.setInt16(44 + (i * n + c) * 2, Math.round(y * 32767), true);
+        }
+    }
+    return { bytes: out, from: format, converted: true };
+}
+/** A format in a few words: `24000 Hz mono 16-bit`. */
+export const wavText = (f) => `${f.sampleRate} Hz ${f.channels === 1 ? "mono" : f.channels === 2 ? "stereo" : `${f.channels}-channel`} ${f.bitsPerSample}-bit${f.encoding === "float" ? " float" : ""}`;

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

@@ -16,7 +16,24 @@ export type CastClip = {
     bytes: Uint8Array;
     type: string;
 };
-/** What `announce` did: whether the clip played to its end, why not, and what it put back or could not. */
+/** One Cast message, as a dry run reports it: the device it goes to, the channel (`receiver` or the app's `media`) and the payload. */
+export type CastRequest = {
+    device: string;
+    channel: "receiver" | "media";
+    payload: Record<string, unknown>;
+};
+/** `dryRun`: run every check a real write runs (the target, its connection, the input) and the reads it makes first, send no write, and say what would go. */
+export type CastWriteOptions = {
+    dryRun?: boolean;
+};
+/** A dry run's answer: the messages in order; empty when there is nothing to send. */
+export type CastDryRun = {
+    wouldSend: CastRequest[];
+};
+/**
+ * What `announce` did: whether the clip played to its end, why not, and what it put back or could not. A dry run has
+ * `played: false`, `why: "dry run"`, `wouldSend`, and in `notRestored` what the real one could not put back.
+ */
 export type AnnounceResult = {
     played: boolean;
     why?: string;
@@ -25,6 +42,7 @@ export type AnnounceResult = {
         name: string;
         why: string;
     }[];
+    wouldSend?: CastRequest[];
 };
 /** Serves bytes once over HTTP on the LAN: `serveClip` from `@khalido/home/cast/serve`. `host` is the device that will fetch it. */
 export type ServeClip = (bytes: Uint8Array, type: string, options?: {
@@ -36,19 +54,20 @@ export type ServeClip = (bytes: Uint8Array, type: string, options?: {
 }>;
 /** The writes on `cast()`'s object. A target is a device's or group's name (any case) or its castId; volume is 0 to 1, as the snapshot's. */
 export type CastActions = {
-    setVolume(target: string, level: number): Promise<void>;
-    setMuted(target: string, muted: boolean): Promise<void>;
+    /** Resolves `undefined` once sent, or a `CastDryRun` under `dryRun`. */
+    setVolume(target: string, level: number, options?: CastWriteOptions): Promise<CastDryRun | undefined>;
+    setMuted(target: string, muted: boolean, options?: CastWriteOptions): Promise<CastDryRun | undefined>;
     /** Ends the running app (receiver STOP), which returns the device to its idle screen. Nothing running: nothing sent. */
-    stop(target: string): Promise<void>;
+    stop(target: string, options?: CastWriteOptions): Promise<CastDryRun | undefined>;
     announce(target: string, clip: CastClip, options?: {
         volume?: number;
         timeoutMs?: number;
-    }): Promise<AnnounceResult>;
+    } & CastWriteOptions): 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 & {
+    } & CastWriteOptions): Promise<(AnnounceResult & {
         target: string;
     })[]>;
 };

package/dist/connectors/cast/writes.js

@@ -1,5 +1,6 @@
 import { errorText } from "../../connector.js";
 import { writeLane } from "../../lane.js";
+import { CAST_WAV, castWav, isWav, wavText } from "./wav.js";
 import { NS } from "./codec.js";
 import { MediaStatus, MultizoneStatus, ReceiverStatus, } from "./schemas.js";
 import { castKey, DEFAULT_MEDIA_RECEIVER, findCast, } from "./state.js";
@@ -221,22 +222,51 @@ export function castActions(ctx) {
             .get(id)
             .send("level" in volume ? "level" : "muted", volume, (v) => receiver(live(find(target)), { type: "SET_VOLUME", volume: v }));
     };
+    const toReceiver = (d, payload) => ({ device: d.name, channel: "receiver", payload });
+    /** A dry SET_VOLUME: the target found and connected, nothing sent. */
+    const dryVolume = (target, volume) => {
+        const d = find(target);
+        live(d);
+        return {
+            wouldSend: [toReceiver(d, { type: "SET_VOLUME", volume })],
+        };
+    };
+    /** Each WAV clip made here, and the format it came from, so a dry run can say what was converted. */
+    const fromWav = new WeakMap();
+    /** WAV bytes as 48 kHz 16-bit stereo, which audio-only speakers play (`wav.ts`); any other clip as it is. */
+    const playable = (clip) => {
+        if ("url" in clip || !isWav(clip.type) || fromWav.has(clip.bytes))
+            return clip;
+        const r = castWav(clip.bytes);
+        if (r.converted)
+            fromWav.set(r.bytes, r.from);
+        return { bytes: r.bytes, type: "audio/wav" };
+    };
     const actions = {
-        async setVolume(target, level) {
+        async setVolume(target, level, options) {
             checkLevel(level);
+            if (options?.dryRun)
+                return dryVolume(target, { level });
             await setVolume(target, { level });
         },
-        async setMuted(target, muted) {
+        async setMuted(target, muted, options) {
+            if (options?.dryRun)
+                return dryVolume(target, { muted });
             await setVolume(target, { muted });
         },
-        async stop(target) {
-            const s = live(find(target));
+        async stop(target, options) {
+            const d = find(target);
+            const s = live(d);
             const app = (await receiver(s)).applications?.[0];
-            if (app && !app.isIdleScreen)
-                await receiver(s, {
-                    type: "STOP",
-                    ...(app.sessionId ? { sessionId: app.sessionId } : {}),
-                });
+            const stop = {
+                type: "STOP",
+                ...(app?.sessionId ? { sessionId: app.sessionId } : {}),
+            };
+            const running = app && !app.isIdleScreen;
+            if (options?.dryRun)
+                return { wouldSend: running ? [toReceiver(d, stop)] : [] };
+            if (running)
+                await receiver(s, stop);
         },
         /**
          * 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
@@ -244,11 +274,13 @@ export function castActions(ctx) {
          * 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 = {}) {
+        async announce(target, given, options = {}) {
             if (options.volume !== undefined)
                 checkLevel(options.volume);
-            if (!("url" in clip) && !ctx.serve)
+            if (!("url" in given) && !ctx.serve)
                 throw new Error("a clip of bytes needs serve: serveClip from @khalido/home/cast/serve");
+            const clip = playable(given); // a bad WAV throws here, before anything changed
+            const wavFrom = "url" in clip ? undefined : fromWav.get(clip.bytes);
             let d = find(target);
             const s = d.kind === "group" ? await regroup(d) : live(d);
             d = ctx.devices()[d.id] ?? d; // a group's host as discovery gives it now, for serving the clip on its network
@@ -266,6 +298,8 @@ export function castActions(ctx) {
                 restored: [],
                 notRestored: [],
             };
+            if (options.dryRun)
+                return dryAnnounce();
             const serving = new AbortController();
             let served;
             let volumeSet = false;
@@ -311,6 +345,52 @@ export function castActions(ctx) {
                     await restoreVolume();
             }
             return result;
+            /** What the announce would send, from the reads above; what it could not put back goes in `notRestored`. */
+            function dryAnnounce() {
+                const to = (device, payload) => ({
+                    device: device.name,
+                    channel: "receiver",
+                    payload,
+                });
+                const media = (payload) => ({
+                    device: d.name,
+                    channel: "media",
+                    payload,
+                });
+                const sends = [];
+                if (options.volume !== undefined)
+                    sends.push(to(d, { type: "SET_VOLUME", volume: { level: options.volume } }));
+                if (unmute)
+                    sends.push(to(d, { type: "SET_VOLUME", volume: { muted: false } }));
+                sends.push(to(d, { type: "LAUNCH", appId: DEFAULT_MEDIA_RECEIVER }), media({
+                    type: "LOAD",
+                    media: {
+                        contentId: "url" in clip
+                            ? clip.url
+                            : `(${clip.bytes.length} bytes of ${clip.type}${wavFrom ? `, converted from ${wavText(wavFrom)} to ${wavText(CAST_WAV)}` : ""}, served on the LAN)`,
+                        contentType: clip.type ?? "audio/mpeg",
+                        streamType: "BUFFERED",
+                    },
+                    autoplay: true,
+                }));
+                if (priorMedia)
+                    sends.push(media({ type: "LOAD", ...priorMedia }));
+                else {
+                    sends.push(to(d, { type: "STOP" }));
+                    if (!idleApp(prior) && prior?.appId !== DEFAULT_MEDIA_RECEIVER)
+                        result.notRestored.push({
+                            name: d.name,
+                            why: `${prior?.displayName ?? prior?.appId ?? "an app"} would be interrupted and cannot be resumed from here`,
+                        });
+                }
+                for (const step of volumeSteps())
+                    if ("gap" in step)
+                        result.notRestored.push({ name: step.name, why: step.gap });
+                    else
+                        for (const p of step.payloads)
+                            sends.push(to(step, p));
+                return { ...result, why: "dry run", wouldSend: sends };
+            }
             async function restoreApp() {
                 try {
                     // A LAUNCH that timed out may still have started: look before deciding nothing of ours runs.
@@ -346,78 +426,91 @@ export function castActions(ctx) {
                     });
                 }
             }
-            async function restoreVolume() {
-                const each = d.kind === "group"
-                    ? members
-                    : [
-                        {
-                            id: d.id,
-                            name: d.name,
-                            level: before.volume?.level,
-                            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.
+            /**
+             * The volume put back after the clip, as steps: a group's own level first (it keeps one 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), so
+             * whatever it does to the members, their own levels land last; then each member's, or the target's, through its own
+             * socket. A step it can't take is a gap with the reason. `restoreVolume` takes them; a dry run reports them.
+             */
+            function volumeSteps() {
+                const steps = [];
                 if (d.kind === "group" && options.volume !== undefined) {
                     const level = before.volume?.level;
-                    if (level === undefined)
-                        result.notRestored.push({
+                    steps.push(level === undefined
+                        ? { name: d.name, gap: "its volume before was not reported" }
+                        : {
                             name: d.name,
-                            why: "its volume before was not reported",
+                            socket: s,
+                            payloads: [{ type: "SET_VOLUME", volume: { level } }],
+                            label: `${d.name}: volume`,
                         });
-                    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)}`,
-                            });
-                        }
                 }
+                const each = d.kind === "group"
+                    ? members
+                    : options.volume !== undefined || unmute
+                        ? [
+                            {
+                                id: d.id,
+                                name: d.name,
+                                level: before.volume?.level,
+                                muted: before.volume?.muted,
+                            },
+                        ]
+                        : [];
                 for (const m of each) {
                     const ms = m.id === d.id ? s : ctx.session(m.id);
                     if (m.level === undefined)
-                        result.notRestored.push({
+                        steps.push({
                             name: m.name,
-                            why: "its volume before was not reported",
+                            gap: "its volume before was not reported",
                         });
                     else if (!ms)
-                        result.notRestored.push({
+                        steps.push({
                             name: m.name,
-                            why: "not connected, so its volume stays as the announcement set it",
+                            gap: "not connected, so its volume stays as the announcement set it",
                         });
                     else
-                        try {
-                            await receiver(ms, {
-                                type: "SET_VOLUME",
-                                volume: { level: m.level },
-                            });
-                            if (m.muted)
-                                await receiver(ms, {
-                                    type: "SET_VOLUME",
-                                    volume: { muted: true },
-                                });
-                            result.restored.push(`${m.name}: volume${m.muted ? ", muted" : ""}`);
-                        }
-                        catch (error) {
-                            result.notRestored.push({
-                                name: m.name,
-                                why: `volume not restored: ${errorText(error)}`,
-                            });
-                        }
+                        steps.push({
+                            name: m.name,
+                            socket: ms,
+                            payloads: [
+                                { type: "SET_VOLUME", volume: { level: m.level } },
+                                ...(m.muted
+                                    ? [{ type: "SET_VOLUME", volume: { muted: true } }]
+                                    : []),
+                            ],
+                            label: `${m.name}: volume${m.muted ? ", muted" : ""}`,
+                        });
+                }
+                return steps;
+            }
+            async function restoreVolume() {
+                for (const step of volumeSteps()) {
+                    if ("gap" in step) {
+                        result.notRestored.push({ name: step.name, why: step.gap });
+                        continue;
+                    }
+                    try {
+                        for (const p of step.payloads)
+                            await receiver(step.socket, p);
+                        result.restored.push(step.label);
+                    }
+                    catch (error) {
+                        result.notRestored.push({
+                            name: step.name,
+                            why: `volume not restored: ${errorText(error)}`,
+                        });
+                    }
                 }
             }
         },
-        async announceAll(targets, clip, options = {}) {
+        async announceAll(targets, given, 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)
+            if (!("url" in given) && !ctx.serve)
                 throw new Error("a clip of bytes needs serve: serveClip from @khalido/home/cast/serve");
+            const clip = playable(given); // converted once, for every target
             const id = (t) => {
                 try {
                     return find(t).id;

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

@@ -30,10 +30,23 @@ export type SpotifyConfig = {
 };
 /** Soloist's repeat modes. */
 export type Repeat = "off" | "context" | "track";
-/** What a write left: the state once Soloist reported the change (`confirmed`), or the state as it stood when `CONFIRM_MS` ran out without it. */
+/** One WebSocket command, as a dry run reports it: Soloist's command name and its fields. */
+export type SpotifyRequest = {
+    command: string;
+    fields?: Record<string, unknown>;
+};
+/** `dryRun`: run every check a real write runs (connected, signed in, the input), send nothing, and say what would go. */
+export type SpotifyWriteOptions = {
+    dryRun?: boolean;
+};
+/**
+ * What a write left: the state once Soloist reported the change (`confirmed`), or the state as it stood when `CONFIRM_MS`
+ * ran out without it. A dry run resolves `confirmed: false` with `wouldSend`, the commands in order; an `activate` already done resolves `confirmed: true` with `wouldSend: []`.
+ */
 export type Applied = {
     state: SpotifyState;
     confirmed: boolean;
+    wouldSend?: SpotifyRequest[];
 };
 /**
  * What happened to the music around `duck` or `interrupt`'s `fn`: `untouched` (it was not playing, not connected, already
@@ -54,36 +67,37 @@ export type Aside<T> = {
  */
 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>;
+    activate(options?: SpotifyWriteOptions): 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>;
-    resume(): Promise<Applied>;
-    next(): Promise<Applied>;
-    prev(): Promise<Applied>;
+    play(linkOrUri?: string, options?: SpotifyWriteOptions): Promise<Applied>;
+    pause(options?: SpotifyWriteOptions): Promise<Applied>;
+    resume(options?: SpotifyWriteOptions): Promise<Applied>;
+    next(options?: SpotifyWriteOptions): Promise<Applied>;
+    prev(options?: SpotifyWriteOptions): Promise<Applied>;
     /** Jump to a position in the current track, in ms. */
-    seek(ms: number): Promise<Applied>;
+    seek(ms: number, options?: SpotifyWriteOptions): Promise<Applied>;
     /** Set the volume 0–100, held to `maxVolume` and rounded to a whole percent: `state.volume` is what Soloist then reports. */
-    setVolume(volume: number): Promise<Applied>;
+    setVolume(volume: number, options?: SpotifyWriteOptions): Promise<Applied>;
     /** Add a track to the queue (Soloist queues tracks only); confirmed when it shows in `upNext`. */
-    queue(track: string): Promise<Applied>;
-    setShuffle(on: boolean): Promise<Applied>;
+    queue(track: string, options?: SpotifyWriteOptions): Promise<Applied>;
+    setShuffle(on: boolean, options?: SpotifyWriteOptions): Promise<Applied>;
     /** Repeat off, the context (playlist, album) or the track: two commands, in the order Soloist's docs give, as one write. */
-    setRepeat(mode: Repeat): Promise<Applied>;
+    setRepeat(mode: Repeat, options?: SpotifyWriteOptions): Promise<Applied>;
     /**
      * Pause if playing, run `fn`, then resume, unless someone changed it meanwhile (resumed, stopped or skipped it from a
      * phone): then it is theirs and stays. The resume runs even if `fn` throws. Not playing or not connected: just `fn`.
      * One `interrupt` or `duck` at a time; a second waits for the first, so never call either from inside `fn` (it would wait
      * forever). Two announcements back to back belong in one `fn`, or the music comes back between them.
      */
-    interrupt<T>(fn: () => Promise<T> | T): Promise<Aside<T>>;
+    interrupt<T>(fn: () => Promise<T> | T, options?: SpotifyWriteOptions): Promise<Aside<T>>;
     /**
      * Lower the volume to `to` while `fn` runs, then put the earlier volume back, unless someone set the volume meanwhile.
      * For a short announcement over the music. Not playing, not connected or already at `to` or below: just `fn`.
+     * With `dryRun`, `interrupt` and `duck` run `fn`, touch nothing, and say in `why` what they would have done.
      */
     duck<T>(fn: () => Promise<T> | T, options: {
         to: number;
-    }): Promise<Aside<T>>;
+    } & SpotifyWriteOptions): Promise<Aside<T>>;
 };
 /**
  * A Spotify Soloist speaker as one integration: one WebSocket to Soloist, its `auth_state` and `playback_state` on connect,