@khalido/home 0.2.1 → 0.2.2

package/dist/connectors/spotify/index.js

@@ -183,12 +183,31 @@ export function spotify(config = {}) {
      * Soloist accepted the command that carried it (a merged write's may be another's: a pause merged into a later play never
      * confirms). A drop ends the wait early, unconfirmed.
      */
-    const change = async (slot, body) => {
+    const change = async (slot, body, options = {}) => {
+        if (options.dryRun)
+            return dry(body);
         const sent = await write(slot, body);
         const took = () => body.took?.(state, sent.before, sent.at) ?? true;
         await waitFor(() => took() || !isOpen(), CONFIRM_MS);
         return { state, confirmed: took() };
     };
+    /** A dry run: `command`'s own checks (connected, signed in), then the commands `send` would send, in order. */
+    const dry = (body) => {
+        if (!socket || !isOpen() || socket.readyState !== OPEN)
+            throw offline();
+        if (state.loggedIn === false)
+            throw new ConnectorError(WAITING, { code: "waiting" });
+        const one = (command, fields) => fields ? { command, fields } : { command };
+        return {
+            state,
+            confirmed: false,
+            wouldSend: [
+                ...(body.activeFirst && inactive() ? [one("activate")] : []),
+                one(body.command, body.fields),
+                ...(body.then ? [one(body.then.command, body.then.fields)] : []),
+            ],
+        };
+    };
     /** The track restarted: a new anchor near 0 when it had been 5 s or more in (a prev past the first seconds, a next on repeat-track). */
     const restarted = (s, b, at) => s.position !== b.position &&
         (s.position?.ms ?? Infinity) < 5000 &&
@@ -196,11 +215,11 @@ export function spotify(config = {}) {
     const newTrack = (s, b) => !!s.track && s.track.uri !== b.track?.uri;
     const invalid = (message) => new ConnectorError(message, { code: "invalid" });
     const near = (volume, v) => volume !== undefined && Math.abs(volume - v) <= VOLUME_SLACK;
-    const volumeTo = (v) => change("volume", {
+    const volumeTo = (v, options) => change("volume", {
         command: "set_volume",
         fields: { volume: v },
         took: (s) => near(s.volume, v),
-    });
+    }, options);
     /** Soloist accepts a `set_volume` while it isn't the active device and drops it (three times live, 2026-11-09). */
     const inactive = () => isOpen() && state.loggedIn !== false && state.active === false;
     /** Ask Soloist for something, through the lane; the same query twice merges. A refusal is an anomaly, a drop is the status's to say. */
@@ -473,6 +492,27 @@ export function spotify(config = {}) {
         asides = p.catch(() => { });
         return p;
     };
+    /** Why `interrupt` would leave the music alone, if it would. */
+    const interruptSkip = () => notPlaying() ??
+        // "playing" while inactive is the account playing on another speaker (live, 2026-11-10): a pause would stop that one.
+        (inactive()
+            ? "it is not the active device, so the music playing is on another speaker"
+            : undefined);
+    /** Why `duck` would leave the volume alone, if it would. */
+    const duckSkip = (to) => notPlaying() ??
+        (inactive()
+            ? "it is not the active device, so its volume can't be changed"
+            : state.volume === undefined
+                ? "its volume is not known"
+                : state.volume <= to
+                    ? `it was already at ${state.volume}`
+                    : undefined);
+    /** A dry `interrupt` or `duck`: `fn` runs, the music is not touched, and `why` says what would have happened to it. */
+    const dryAside = async (fn, skip, would) => ({
+        value: await fn(),
+        music: "untouched",
+        why: `dry run: ${skip ? `${skip}, so the music would be left alone` : `would ${would}`}`,
+    });
     const putBack = (r, what) => r.confirmed
         ? { music: "restored" }
         : {
@@ -480,22 +520,23 @@ export function spotify(config = {}) {
             why: failed(`sent the ${what}; Soloist has not reported it`),
         };
     const actions = {
-        async activate() {
+        async activate(options) {
             if (isOpen() && state.loggedIn !== false && state.active === true)
-                return { state, confirmed: true }; // a second activate might make a new stream
-            return change("activate", {
-                command: "activate",
-                took: (s) => s.active === true,
-            });
+                return {
+                    state,
+                    confirmed: true,
+                    ...(options?.dryRun ? { wouldSend: [] } : {}),
+                }; // a second activate might make a new stream
+            return change("activate", { command: "activate", took: (s) => s.active === true }, options);
         },
         // A `play` while inactive didn't take live; going active first is untested for this. `resume` worked inactive, so it doesn't.
-        async play(linkOrUri) {
+        async play(linkOrUri, options) {
             if (linkOrUri === undefined)
                 return change("transport", {
                     command: "play",
                     activeFirst: true,
                     took: (s) => s.status === "playing",
-                });
+                }, options);
             const uri = toSpotifyUri(linkOrUri);
             if (!uri)
                 throw invalid(`not a Spotify link or URI: ${linkOrUri}`);
@@ -505,28 +546,22 @@ export function spotify(config = {}) {
                 activeFirst: true,
                 took: (s) => s.status === "playing" &&
                     (s.track?.uri === uri || s.context?.uri === uri),
-            });
+            }, options);
         },
-        pause: () => change("transport", {
-            command: "pause",
-            took: (s) => s.status === "paused",
-        }),
-        resume: () => change("transport", {
-            command: "play",
-            took: (s) => s.status === "playing",
-        }),
+        pause: (options) => change("transport", { command: "pause", took: (s) => s.status === "paused" }, options),
+        resume: (options) => change("transport", { command: "play", took: (s) => s.status === "playing" }, options),
         // The end of the queue goes idle; repeat-track restarts it.
-        next: () => change(`once-${++once}`, {
+        next: (options) => change(`once-${++once}`, {
             command: "skip_next",
             took: (s, b, at) => newTrack(s, b) ||
                 (s.status === "idle" && b.status !== "idle") ||
                 restarted(s, b, at),
-        }),
-        prev: () => change(`once-${++once}`, {
+        }, options),
+        prev: (options) => change(`once-${++once}`, {
             command: "skip_prev",
             took: (s, b, at) => newTrack(s, b) || restarted(s, b, at),
-        }),
-        async seek(ms) {
+        }, options),
+        async seek(ms, options) {
             if (!Number.isFinite(ms) || ms < 0)
                 throw invalid(`a position in ms, 0 or more, not ${ms}`);
             return change("seek", {
@@ -534,16 +569,16 @@ export function spotify(config = {}) {
                 fields: { position_ms: ms },
                 took: (s, b) => s.position !== b.position &&
                     Math.abs((s.position?.ms ?? -Infinity) - ms) < 2000,
-            });
+            }, options);
         },
-        async setVolume(volume) {
+        async setVolume(volume, options) {
             if (!Number.isFinite(volume) || volume < 0 || volume > 100)
                 throw invalid(`volume is 0–100, not ${volume}`);
             if (inactive())
                 throw new ConnectorError("the speaker is not the active Spotify device, so Soloist would drop this; activate it first (`home spotify activate`; its volume may jump to the level last saved)", { code: "inactive" });
-            return volumeTo(Math.round(cap === undefined ? volume : Math.min(volume, cap)));
+            return volumeTo(Math.round(cap === undefined ? volume : Math.min(volume, cap)), options);
         },
-        async queue(track) {
+        async queue(track, options) {
             const uri = toSpotifyUri(track);
             if (!uri?.startsWith("spotify:track:"))
                 throw invalid(`only a Spotify track can be queued, not ${track}`);
@@ -551,14 +586,14 @@ export function spotify(config = {}) {
                 command: "add_to_queue",
                 fields: { uri },
                 took: (s) => !!s.upNext?.some((t) => t.uri === uri),
-            });
+            }, options);
         },
-        setShuffle: (on) => change("shuffle", {
+        setShuffle: (on, options) => change("shuffle", {
             command: "set_shuffle",
             fields: { enabled: on },
             took: (s) => s.shuffle === on,
-        }),
-        async setRepeat(mode) {
+        }, options),
+        async setRepeat(mode, options) {
             // developer.spotify.com/documentation/soloist/reference/websocket-api: clear the other mode first, then set this one.
             if (!Object.hasOwn(REPEAT_ORDER, mode))
                 throw invalid(`repeat is off, context or track, not ${mode}`);
@@ -568,18 +603,17 @@ export function spotify(config = {}) {
                 fields: { enabled: first[1] },
                 then: { command: second[0], fields: { enabled: second[1] } },
                 took: (s) => s.repeat === mode,
-            });
+            }, options);
         },
-        interrupt(fn) {
+        interrupt(fn, options) {
+            if (options?.dryRun)
+                return dryAside(fn, interruptSkip(), "pause the music, then resume it");
             let track;
             let shown = false; // the pause showed
             return aside("interrupt", fn, async () => {
-                const no = notPlaying();
+                const no = interruptSkip();
                 if (no)
                     return no;
-                // "playing" while inactive is the account playing on another speaker (live, 2026-11-10): a pause would stop that one.
-                if (inactive())
-                    return "it is not the active device, so the music playing is on another speaker";
                 track = state.track?.uri;
                 try {
                     shown = (await actions.pause()).confirmed; // a pause that never shows still runs fn: what interrupts matters more
@@ -608,21 +642,17 @@ export function spotify(config = {}) {
                 }
             });
         },
-        duck(fn, { to }) {
+        duck(fn, { to, dryRun }) {
             if (!Number.isFinite(to) || to < 0 || to > 100)
                 return Promise.reject(invalid(`duck's volume is 0–100, not ${to}`));
+            if (dryRun)
+                return dryAside(fn, duckSkip(to), `lower the volume from ${state.volume} to ${Math.round(to)}, then put it back`);
             let earlier = 0;
             let shown = false; // the lowered volume showed
             return aside("duck", fn, async () => {
-                const no = notPlaying();
+                const no = duckSkip(to);
                 if (no)
                     return no;
-                if (inactive())
-                    return "it is not the active device, so its volume can't be changed";
-                if (state.volume === undefined)
-                    return "its volume is not known";
-                if (state.volume <= to)
-                    return `it was already at ${state.volume}`;
                 earlier = state.volume;
                 try {
                     shown = (await volumeTo(Math.round(to))).confirmed;

package/docs/cast.md

@@ -109,7 +109,7 @@ No host: a group's host changes with its leader. All entries fold into one `cast
 - `announce(target, clip, { volume?, timeoutMs? })`, target a device or group, `clip` a URL or bytes with their type (KO's own dictation as recorded, or TTS output; the library never synthesises) served by `serveClip`. The result names each member it could not restore. Read status, set volume, launch Default Media Receiver (`CC1AD845`), `LOAD` the clip, wait for `IDLE`/`FINISHED` (with a timeout), then restore: a prior Default Media Receiver `contentId` is re-loaded at its `currentTime`, an idle device gets `STOP`, then the volume. Spotify, YouTube and other apps cannot be resumed generically (our launch ends their session); the result says so.
 - `castUrl(name, url)` launches DashCast (`84912283`, pychromecast's list) with the URL. HA casts its dashboard with its own registered receiver (`A078F6B0`), a hint at DashCast's limits. KO's own receiver costs a one-off Cast SDK fee and must be published (unpublished ones run only on serial-registered devices). Try DashCast first.
 
-**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3 or AAC; not AIFF; a 24 kHz mono WAV failed on audio-only Nest speakers, live 2026-11-09): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
+**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3 or AAC; not AIFF; a 24 kHz mono WAV failed on audio-only Nest speakers, live 2026-11-09; `announce` now rewrites WAV bytes as 48 kHz 16-bit stereo, which played on every audio-only speaker and display here, 2026-11-12): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
 
 **CLI.** `home status`: `cast  7 · Display A idle 47% · TV B standby · Whole house (3, led by Display A) idle`. `home probe`: this probe.
 

package/docs/cli.md

@@ -12,7 +12,7 @@ home scene <name> [in <room>]  # a scene; name the room when several have one by
 home pair                     # waits 60 s for the bridge's button, counting down; prints the env lines to set
 home daikin on | off           # power only: the AC comes back as it was last left
 home daikin cool | heat | auto [°C] | dry | fan  # mode, on, and the setpoint: the one given, else cool 25 and heat 27; prints what the unit then reports. Live on KO's unit: on, and dry to cool at 25 (2026-11-11); the rest untried
-                              # --dry-run on a hue or daikin write (lights, light, room, scene, daikin …): check it and print what would be sent; nothing is sent. Refused on every other command
+                              # --dry-run on a write (lights, light, room, scene, daikin, cast, spotify, printers print): check it and print what would be sent; nothing is sent. Refused on every other command
 home enphase login            # once a year: mints the Enphase owner token into ~/.config/home/ (0600)
 home discover [--json] [--passes n]  # which smart-home devices answer here (mDNS + Daikin UDP), which this package supports, then with a config how they match it; two passes 5 s apart
 home cache [clear]            # the addresses kept between runs, or delete them so the next run discovers afresh

package/docs/using.md

@@ -74,7 +74,7 @@ A write changes someone's house: make one only when a person asked for it. Write
 | hue       | `.client.put(kind, id, body)`, `.client.recallScene(id)`                                                           | the bridge's answer, for what the typed writes don't cover                                       |
 
 - **`confirmed`** is true once the device reported what was asked. False is a result, not an error: the write was sent and the device hasn't shown it yet, and `state` is how it stood.
-- **Dry run.** `opts` is `{ dryRun: true }` on Hue's and the Daikin's writes: every check made before sending runs (the name, the range, a lost light; a colour off the gamut shows moved in the body) and nothing is sent. The device can still refuse a real write that a dry run passed. The result has `wouldSend`, the request it would make (Hue: `{ method, path, body }`; Daikin adds `sets`, `{ on?, mode?, targetC? }`), `state` as things stand now, and `confirmed: false`, so check `wouldSend` first. A wrong name still throws with the names that exist. For testing a bot end to end with people home; `home … --dry-run` does the same from the terminal.
+- **Dry run.** `opts` is `{ dryRun: true }` on Hue's, the Daikin's, Cast's and Spotify's writes: every check made before sending runs (the name, the range, a lost light; a colour off the gamut shows moved in the body) and nothing is sent. The device can still refuse a real write that a dry run passed. The result has `wouldSend`, the request it would make (Hue: `{ method, path, body }`; Daikin adds `sets`, `{ on?, mode?, targetC? }`; Spotify: the WebSocket commands in order), `state` as things stand now, and `confirmed: false`, so check `wouldSend` first. Cast's `setVolume`, `setMuted` and `stop` resolve `{ wouldSend }` (each `{ device, channel, payload }`), and `announce` its usual result with `played: false`, `why: "dry run"`, `wouldSend` and, in `notRestored`, what the real one could not put back (an app it would interrupt); nothing is served. Spotify's `duck` and `interrupt` run `fn`, touch nothing, and say in `why` what they would have done, so `duck(() => cast.announce(…, { dryRun: true }), { to: 20, dryRun: true })` tests an announcement end to end without a sound. A wrong name still throws with the names that exist. For testing a bot end to end with people home; `home … --dry-run` does the same from the terminal.
 - **Use the returned state.** The Daikin's part in the snapshot is from its last poll and can be 120 s behind, unless you call `home.refresh("daikin")`.
 - **Daikin defaults.** `mode("cool")` is 25 °C and `mode("heat")` 27 (`DEFAULT_TARGET_C`); `mode("cool", 23)` for another. `power(true)` brings the unit back as it was last left.
 - **A target** for Cast is a device's or group's name or id. A clip is `{ url, type? }` or `{ bytes, type }`; bytes need `castServe`.

package/llms.txt

@@ -11,8 +11,8 @@ The library never reads the environment or a file: callers pass addresses, keys
 - **Why a part is down:** `part.status` (`connected`, `disconnected`, `unavailable`) and, when `unavailable`, `part.reason` (`auth`, `config`, `crashed`). Errors are `ConnectorError` with a typed `code`.
 - **Hue** (`@khalido/home/hue`): `pairWhenPressed` waits for the bridge's button and returns `{ key }`; Signify's root certificates are in the package, so `hue({ host, bridgeId, key })` needs no file. Writes by name: `client.light(name, change)`, `client.room(name, change)`, `client.scene(name, room?)`, `client.allOff()`, with `change` `{ on?, brightness?, color?, kelvin?, transitionMs? }`, each resolving `{ state, confirmed }`. `{ dryRun: true }` as the last argument checks and returns `wouldSend` without sending.
 - **Daikin** (`@khalido/home/daikin`): `client.power(on)` and `client.mode(mode, targetC?)` resolve `{ state, confirmed }`, and take `{ dryRun: true }` last; cool defaults to 25 °C and heat to 27.
-- **Cast** (`@khalido/home/cast`): `castStatus(state)` and `castFree(state, targets, { forms? })`, on the Cast part's state, say what is playing and where an announcement would disturb nothing; `castFreeSpeakers(state)` is the one call for every free speaker and display; `announce`, `announceAll`, `setVolume`, `setMuted`, `stop`.
-- **Spotify Soloist** (`@khalido/home/spotify`): `play`, `pause`, `setVolume` and the rest resolve `{ state, confirmed }`; `duck` and `interrupt` wrap an announcement. `speakerState(part)` is `elsewhere` when the music is on another Spotify device.
+- **Cast** (`@khalido/home/cast`): `castStatus(state)` and `castFree(state, targets, { forms? })`, on the Cast part's state, say what is playing and where an announcement would disturb nothing; `castFreeSpeakers(state)` is the one call for every free speaker and display; `announce`, `announceAll`, `setVolume`, `setMuted`, `stop`. Its writes take `{ dryRun: true }`.
+- **Spotify Soloist** (`@khalido/home/spotify`): `play`, `pause`, `setVolume` and the rest resolve `{ state, confirmed }`; `duck` and `interrupt` wrap an announcement. Every write takes `{ dryRun: true }`. `speakerState(part)` is `elsewhere` when the music is on another Spotify device.
 - **Discovery** (`@khalido/home/finders`, Node-side): `FINDERS`, one finder per connector, and `fileCache`. **Node** needs the fetches in `@khalido/home/node`.
 - **The command:** `home`, `home devices`, `home <connector>`, and writes such as `home daikin cool`, `home room <name> on`, `home cast announce`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khalido/home",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "home.ts: small, typed home automation for TypeScript: 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.",
   "license": "MIT",
   "author": "Khalid Omar",

package/skills/use-home/SKILL.md

@@ -10,7 +10,7 @@ description: Use the `home` command and the @khalido/home library to see and run
 ## Rules
 
 - **Reads are free.** `home`, `home <connector>` with no verb, `home devices`, `home discover`, `home probe`, `home up spend` and every `--json` read touch nothing.
-- **Writes only on request.** Lights, AC, speakers, printing, Up categories and tags, webhooks: run one only when the person asked for that change, then read back and report the state it left. Never write to "test" something: `--dry-run` on a Hue or Daikin write (`home room …`, `home scene …`, `home lights off`, `home daikin …`, `home printers print …`) checks it and prints what it would send, sending nothing (a print's dry run also asks the printer to validate the job, which prints nothing); other commands refuse the flag.
+- **Writes only on request.** Lights, AC, speakers, printing, Up categories and tags, webhooks: run one only when the person asked for that change, then read back and report the state it left. Never write to "test" something: `--dry-run` on a write (`home room …`, `home scene …`, `home lights off`, `home daikin …`, `home cast …`, `home spotify …`, `home printers print …`) checks it and prints what it would send, sending nothing (a print's dry run also asks the printer to validate the job, which prints nothing); other commands refuse the flag.
 - **Never print a key, token or password**, not even part of one. Say "set" or "unset". Env names are fine; values are not.
 - **Nothing private into a public repo**: no IPs, MACs, serials, device or room names, Up transactions or balances. A real `home.jsonc`, `home.svg` and floor plan live in a private folder.
 - **Show values as read.** A missing field is unknown, not zero. An `anomaly` is something odd the device said: report it, never smooth it.

package/src/cli/cast.ts

@@ -13,6 +13,7 @@ import {
   resolvedFrom,
 } from "../connectors/cast/index.ts";
 import { findCast } from "../connectors/cast/state.ts";
+import type { CastDryRun, CastRequest } from "../connectors/cast/writes.ts";
 import { serveClip } from "../connectors/cast/serve.ts";
 import { tlsConnect } from "../connectors/cast/tls.ts";
 import { addressBook } from "../discover.ts";
@@ -114,14 +115,32 @@ export const CAST_OPTIONS: [string, string, { type: unknown[] }?][] = [
 /** How long a write waits for the device to report the change before saying it was only sent. */
 const SHOWN_MS = 2000;
 
-/** One write, then the device's line once it reports what was asked, or that it has not yet. */
+/** A dry run's messages, one line each: `would send <device> <channel> <payload>`. */
+const dryLines = (sends: CastRequest[], who = "") =>
+  sends.length
+    ? sends.forEach((r) =>
+        console.log(
+          `${who}would send ${r.device} ${r.channel} ${JSON.stringify(r.payload)}`,
+        ),
+      )
+    : console.log(`${who}nothing to send`);
+
+/** One write, then the device's line once it reports what was asked, or that it has not yet. Dry: what would be sent. */
 const wrote = (
   name: string,
-  write: (c: ReturnType<typeof castNow>) => Promise<void>,
+  write: (
+    c: ReturnType<typeof castNow>,
+    options: { dryRun: boolean },
+  ) => Promise<CastDryRun | undefined>,
   shown: (d: CastDevice) => boolean,
+  dryRun: boolean,
 ) =>
   withCast(async (c, state) => {
-    await write(c);
+    const dry = await write(c, { dryRun });
+    if (dry) {
+      console.log("dry run, nothing sent:");
+      return dryLines(dry.wouldSend);
+    }
     const now = () => {
       const s = state();
       const d = s && findCast(s.devices, name);
@@ -140,29 +159,32 @@ const wrote = (
   });
 
 export const castVerbs: Verbs = {
-  async volume([name, value]) {
+  async volume([name, value], o) {
     if (!name) usage(CAST_USAGE);
     const level = percentLevel(value);
     await wrote(
       name!,
-      (c) => c.setVolume(name!, level),
+      (c, dry) => c.setVolume(name!, level, dry),
       (d) => d.volume !== undefined && Math.abs(d.volume - level) < 0.006,
+      !!o.dryRun,
     );
   },
-  async mute([name, value]) {
+  async mute([name, value], o) {
     if (!name || (value !== "on" && value !== "off")) usage(CAST_USAGE);
     await wrote(
       name!,
-      (c) => c.setMuted(name!, value === "on"),
+      (c, dry) => c.setMuted(name!, value === "on", dry),
       (d) => d.muted === (value === "on"),
+      !!o.dryRun,
     );
   },
-  async stop([name]) {
+  async stop([name], o) {
     if (!name) usage(CAST_USAGE);
     await wrote(
       name!,
-      (c) => c.stop(name!),
+      (c, dry) => c.stop(name!, dry),
       (d) => d.idle === true,
+      !!o.dryRun,
     );
   },
   async announce(_, o) {
@@ -209,13 +231,21 @@ export const castVerbs: Verbs = {
       type = "audio/mp4";
     }
     const results = await withCast((c) =>
-      c.announceAll(to, { bytes, type }, { volume }),
+      c.announceAll(to, { bytes, type }, { volume, dryRun: !!o.dryRun }),
     );
-    if (results.some((r) => !r.played)) process.exitCode = 1; // docs/cli.md: 1 is a failure, so a script can tell
+    const failed = results.some((r) => (o.dryRun ? !r.wouldSend : !r.played));
+    if (failed) process.exitCode = 1; // docs/cli.md: 1 is a failure, so a script can tell
     if (o.json) return printJson(to.length === 1 ? results[0] : results);
     const named = results.length > 1;
+    if (o.dryRun) console.log("dry run, nothing sent:");
     for (const r of results) {
       const who = named ? `${r.target}: ` : "";
+      if (r.wouldSend) {
+        dryLines(r.wouldSend, who);
+        for (const n of r.notRestored)
+          console.log(`${who}would not restore: ${n.name}: ${n.why}`);
+        continue;
+      }
       console.log(`${who}${r.played ? "played" : `not played: ${r.why}`}`);
       if (r.restored.length)
         console.log(`${who}restored: ${r.restored.join(", ")}`);

package/src/cli/context.ts

@@ -38,7 +38,7 @@ export const usage = (message: string): never => fail(message, "usage");
 /** The options cac parses: the global ones, and each command's own. */
 export type Options = {
   json?: boolean;
-  /** `--dry-run`: Hue and Daikin writes check and say what they would send, and send nothing. */
+  /** `--dry-run`: Hue, Daikin, Cast, Spotify and printer writes check and say what they would send, and send nothing. */
   dryRun?: boolean;
   config?: string;
   write?: string | true;

package/src/cli/main.ts

@@ -57,9 +57,13 @@ const VERBS: Record<
   },
   daikin: { verbs: daikinVerbs, usage: DAIKIN_USAGE, options: [DRY_RUN] },
   enphase: { verbs: enphaseVerbs, usage: "usage: home enphase login" },
-  cast: { verbs: castVerbs, usage: CAST_USAGE, options: CAST_OPTIONS },
+  cast: {
+    verbs: castVerbs,
+    usage: CAST_USAGE,
+    options: [...CAST_OPTIONS, DRY_RUN],
+  },
   up: { verbs: upVerbs, usage: UP_USAGE, options: UP_OPTIONS },
-  spotify: { verbs: spotifyVerbs, usage: SPOTIFY_USAGE },
+  spotify: { verbs: spotifyVerbs, usage: SPOTIFY_USAGE, options: [DRY_RUN] },
   printers: {
     verbs: printersVerbs,
     usage: PRINTERS_USAGE,

package/src/cli/spotify.ts

@@ -7,7 +7,7 @@ import {
   type SpotifyState,
   spotifyText,
 } from "../connectors/spotify/index.ts";
-import { env, fail, usage, type Verbs } from "./context.ts";
+import { env, fail, type Options, usage, type Verbs } from "./context.ts";
 
 /** SOLOIST_MAX_VOLUME as a number 0–100, or undefined when unset. */
 function maxVolume(): number | undefined {
@@ -55,23 +55,27 @@ async function withSpotify<T>(
   }
 }
 
-/** What a write left, in a line: the speaker as Soloist then reported it, or that it has not reported the change yet. */
-const said = ({ state, confirmed }: Applied) =>
+/** What a write left, in a line: the speaker as Soloist then reported it, that it has not reported the change yet, or what a dry run would send. */
+const said = ({ state, confirmed, wouldSend }: Applied) =>
   console.log(
-    confirmed
-      ? spotifyText(state)
-      : `sent; Soloist has not reported it yet (${spotifyText(state)})`,
+    wouldSend
+      ? `dry run, nothing sent: ${wouldSend.length ? `would send ${wouldSend.map((r) => JSON.stringify(r)).join(", then ")}` : "nothing to send"} (now ${spotifyText(state)})`
+      : confirmed
+        ? spotifyText(state)
+        : `sent; Soloist has not reported it yet (${spotifyText(state)})`,
   );
 
+const dry = (o: Options) => ({ dryRun: !!o.dryRun });
+
 export const spotifyVerbs: Verbs = {
-  activate: () => withSpotify((s) => s.activate()).then(said),
-  pause: () => withSpotify((s) => s.pause()).then(said),
-  next: () => withSpotify((s) => s.next()).then(said),
-  play: ([link]) => withSpotify((s) => s.play(link)).then(said),
-  async volume([value]) {
+  activate: (_, o) => withSpotify((s) => s.activate(dry(o))).then(said),
+  pause: (_, o) => withSpotify((s) => s.pause(dry(o))).then(said),
+  next: (_, o) => withSpotify((s) => s.next(dry(o))).then(said),
+  play: ([link], o) => withSpotify((s) => s.play(link, dry(o))).then(said),
+  async volume([value], o) {
     const n = Number(value);
     if (value === undefined || value.trim() === "" || !(n >= 0 && n <= 100))
       usage(SPOTIFY_USAGE);
-    said(await withSpotify((s) => s.setVolume(n)));
+    said(await withSpotify((s) => s.setVolume(n, dry(o))));
   },
 };

package/src/connectors/cast/README.md

@@ -15,6 +15,8 @@ Nest speakers, Nest Hubs, Chromecasts, Google TV and speaker groups, read over C
 - Writes, on the object `cast()` returns (`CastActions`), over the sockets it already holds, never a second connection. A target is a name (any case) or a castId; volume is 0 to 1, as the snapshot's. `setVolume`, `setMuted` (receiver `SET_VOLUME`; a group's goes to the group's socket; per device, levels and mutes each at most 30 a minute, the newest waiting one winning; one device's lane never waits on another's) and `stop` (receiver `STOP` of the running app; nothing when idle). Each request waits 10 s for its reply and a refusal (`LAUNCH_ERROR`, `LOAD_FAILED`, …) rejects, naming it.
 - `castFreeSpeakers(state)`: the one call for "where can I announce now": `castFree` over every device and group, with `forms: ["speaker", "display"]`. Read live 2026-11-11 (Bun 1.4.4, reads only): 8 devices and groups gave one free group of four, with two TVs and a device whose model was not known skipped as `form`.
 - `announce(target, clip, { volume?, timeoutMs? })`: `clip` is `{ url, type? }` or `{ bytes, type }`, bytes served through `serve` (`serveClip` from `@khalido/home/cast/serve`, passed to `cast()`). It reads the receiver status (and a Default Media Receiver's media status), for a group re-runs discovery first and reconnects if the leader moved, sets the volume if given and unmutes a muted target (as two requests: a `SET_VOLUME` takes a level or a mute, not both), launches the Default Media Receiver (`CC1AD845`), `LOAD`s the clip and waits for its media session to go `IDLE` with `FINISHED` (60 s plus the clip's length when the device reports it, or `timeoutMs`). Then, always: what the Default Media Receiver was playing is loaded again at its `currentTime`, an idle device gets `STOP`, then the volume and mute (a group's its own level first, then member by member, through each member's own socket, from the group's multizone status). Another app (Spotify, YouTube) is interrupted, as Google's own announcements do, and the result names it in `notRestored`. It returns `{ played, why?, restored, notRestored }` and throws only before anything changed (an unknown target, a socket down). A clip gets 15 s to reach `PLAYING`, then the name of its type goes in the failure, since a device that can't play it took 35-44 s to say so; a receiver error sooner carries its reason and code. `timeoutMs` replaces both waits. `announceAll(targets, clip, options)` does several at once, one result per device, an unreachable target its own `played: false`; a group and one of its members would clash, untried.
+- **WAV.** A clip of WAV bytes (`audio/wav` and its other names) is rewritten as 48 kHz, 16-bit, stereo PCM before it is served (`castWav`, in `wav.ts`, plain TypeScript, linear interpolation): a 24 kHz mono WAV failed on audio-only speakers (below) and Google lists WAV for them without rates. Integer PCM of 8 to 32 bits and 32-bit float are read; anything else throws before anything is sent. A clip already in that form is sent unchanged. `castWav(bytes)` is exported for a clip served by URL. Live 2026-11-12 (Bun 1.4.4, from the Mac, KO's OK): a 24 kHz mono 16-bit WAV from macOS `say`, converted, played to the end on a Nest Audio at volume 30 in 3.9 s, idle and volume restored. Then at volume 50, one at a time, KO home: a Nest Mini (the oldest here), a Google Home speaker, a Nest Hub and a Nest Hub Max all played it, 3.7 to 7.5 s each, each put back to idle and its volume (the Hub Max, muted, unmuted for the clip and muted again). KO heard each, and the Nest Audio again at volume 100 from the next room. So every Cast model here plays the converted WAV, and none needs MP3. After it, `home cast volume <name> 50` printed the speaker's line once it reported the level (`…: idle · 50%`), the first live run of that line.
+- **Dry run.** Each write takes `{ dryRun: true }` last: the target is found and checked as for a real write, the reads it needs run (an announce reads the receiver status, a Default Media Receiver's media and a group's members, and re-runs discovery for a group), and no write is sent and nothing served. `setVolume`, `setMuted` and `stop` resolve `{ wouldSend }`; `announce` resolves `played: false`, `why: "dry run"`, `wouldSend` in order (volume, LAUNCH, LOAD, then the restores), and in `notRestored` what the real one could not put back. Its `STOP` has no `sessionId`: that is the launched app's, which only the real run knows. Live 2026-11-12 (Bun 1.4.4) on a Nest Hub: `home cast volume … --dry-run` and `home cast announce … --dry-run`, nothing played.
 - `serveClip(bytes, type, { host?, signal? })` (`node:http`, Node-only like `tls.ts`): an address of this machine on the target's network (else the first non-internal IPv4), a random port and an unguessable path, `Content-Type` and `Content-Length`; the whole body to every GET and HEAD (a `Range` probe gets a full 200, which HTTP allows), so a player that probes before it fetches still gets the clip. It closes on `close()`, which `announce` calls once the clip has played, when `signal` aborts, or after 60 s. Not yet seen live: how the Default Media Receiver fetches, and the macOS local-network prompt the first serve may raise.
 - CLI: `home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100]`, `home cast volume <name> <0-100>`, `home cast mute <name> on|off`, `home cast stop <name>`. `--say` runs `say -o <tmp>.m4a --file-format=m4af --data-format=aac` (without the data format, m4af holds uncompressed PCM), serves it as `audio/mp4` and deletes the file. The library never runs `say`.
 - Config: one entry per device or group, `{ "connector": "cast", "name": "…", "castId": "…" }`, all folded into one `cast` integration; `home discover --write` fills them and refreshes a renamed entry's `name` (the same `castId` with a new `fn`), printed as `renamed`. No host: discovery gives every address.

package/src/connectors/cast/index.ts

@@ -52,10 +52,14 @@ export type {
   CastStatus,
   Resolved,
 } from "./state.ts";
+export { CAST_WAV, castWav, type WavFormat } from "./wav.ts";
 export type {
   AnnounceResult,
   CastActions,
   CastClip,
+  CastDryRun,
+  CastRequest,
+  CastWriteOptions,
   ServeClip,
 } from "./writes.ts";