@khalido/home 0.2.0 → 0.2.2

package/src/connector.ts

@@ -51,6 +51,11 @@ export class ConnectorError extends Error {
   }
 }
 
+/** A 401 or 403 from a device or service: the key or token is wrong or revoked. Every connector reads it as `reason: "auth"`. */
+export const isRejectedKey = (error: unknown) =>
+  error instanceof ConnectorError &&
+  (error.status === 401 || error.status === 403);
+
 /** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
 export function fetchTimeout(
   fetcher: typeof fetch,

package/src/connectors/amber/README.md

@@ -9,7 +9,7 @@ Amber Electric's live wholesale-linked prices, read through Amber's public API.
 - `forecast`: the current interval, then each forecast one, both channels on one row (`PriceInterval`). `next=96` asks for more than Amber has, so the reply runs as far as Amber forecasts: on 2026-10-28 at 3 pm, 12 five-minute intervals then 14 half-hours, to 11 pm. Amber's `startTime` is a second past the interval's start, so `start` is taken to the minute.
 - `estimate: true` means the current interval's price can still move; it is shown as "(estimate)", never as an anomaly.
 - The Amber line in `home status` shows the descriptor, "(estimate)", a spike other than `none`, and a negative price. `energyNow` combines the prices with Enphase; see Energy below.
-- A 401 marks Amber unavailable and stops polling.
+- A 401 or 403 marks Amber unavailable and stops polling.
 
 ## Energy
 

package/src/connectors/amber/client.ts

@@ -4,7 +4,7 @@ import { ConnectorError, getJson } from "../../connector.ts";
 // Amber Electric's public API v1 (https://app.amber.com.au/developers; the published spec is 1.0, there is no v2). Shapes checked against live replies,
 // 2026-10-13; every field optional so a change degrades a reading rather than throwing.
 
-/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+/** A failed Amber call. `status` 401 or 403 (`isRejectedKey`) means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
 export class AmberError extends ConnectorError {}
 
 /** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */

package/src/connectors/amber/index.ts

@@ -1,5 +1,5 @@
 import { asOf, type Clock, realClock } from "../../clock.ts";
-import { errorText } from "../../connector.ts";
+import { errorText, isRejectedKey } from "../../connector.ts";
 import { z } from "zod";
 import { envName, type Integration } from "../../home.ts";
 import { energyNow } from "../../energy.ts";
@@ -62,7 +62,7 @@ export function amber(
           update({ status: "connected", anomaly: last.anomaly, state: last });
         } catch (error) {
           if (signal.aborted) return; // stopped mid-read: not a failure
-          if (error instanceof AmberError && error.status === 401)
+          if (isRejectedKey(error))
             return update({
               status: "unavailable",
               reason: "auth",

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

package/src/connectors/cast/wav.ts

@@ -0,0 +1,181 @@
+// 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.
+
+/** 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 const CAST_WAV: Omit<WavFormat, "encoding"> = {
+  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: string | undefined) =>
+  !!type && WAV_TYPES.has(type.split(";")[0]!.trim().toLowerCase());
+
+const ascii = (b: Uint8Array, at: number) =>
+  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: Uint8Array): {
+  format: WavFormat;
+  channels: Float32Array[];
+} {
+  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: WavFormat | undefined;
+  let blockAlign = 0;
+  let data: Uint8Array | undefined;
+  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: Uint8Array): {
+  bytes: Uint8Array;
+  from: WavFormat;
+  converted: boolean;
+} {
+  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: number, s: string) =>
+    [...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: Omit<WavFormat, "encoding"> & { encoding?: string },
+) =>
+  `${f.sampleRate} Hz ${f.channels === 1 ? "mono" : f.channels === 2 ? "stereo" : `${f.channels}-channel`} ${f.bitsPerSample}-bit${f.encoding === "float" ? " float" : ""}`;

package/src/connectors/cast/writes.ts

@@ -1,6 +1,7 @@
 import type { Clock } from "../../clock.ts";
 import { errorText } from "../../connector.ts";
 import { type WriteLane, writeLane } from "../../lane.ts";
+import { CAST_WAV, castWav, isWav, type WavFormat, wavText } from "./wav.ts";
 import { NS } from "./codec.ts";
 import {
   type Application,
@@ -43,12 +44,27 @@ const REFUSALS = new Set([
 export type CastClip =
   { url: string; type?: string } | { 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;
   restored: string[];
   notRestored: { 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. */
@@ -60,20 +76,32 @@ export type ServeClip = (
 
 /** 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 },
+    options?: { volume?: number; timeoutMs?: number } & 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 },
+    options?: { volume?: number; timeoutMs?: number } & CastWriteOptions,
   ): Promise<(AnnounceResult & { target: string })[]>;
 };
 
@@ -407,22 +435,55 @@ export function castActions(ctx: WriteContext): CastActions {
       );
   };
 
+  const toReceiver = (
+    d: CastDevice,
+    payload: Record<string, unknown>,
+  ): CastRequest => ({ device: d.name, channel: "receiver", payload });
+  /** A dry SET_VOLUME: the target found and connected, nothing sent. */
+  const dryVolume = (
+    target: string,
+    volume: { level: number } | { muted: boolean },
+  ): CastDryRun => {
+    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<Uint8Array, WavFormat>();
+  /** WAV bytes as 48 kHz 16-bit stereo, which audio-only speakers play (`wav.ts`); any other clip as it is. */
+  const playable = (clip: CastClip): CastClip => {
+    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: CastActions = {
-    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);
     },
 
     /**
@@ -431,12 +492,14 @@ export function castActions(ctx: WriteContext): CastActions {
      * 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
@@ -456,6 +519,7 @@ export function castActions(ctx: WriteContext): CastActions {
         restored: [],
         notRestored: [],
       };
+      if (options.dryRun) return dryAnnounce();
       const serving = new AbortController();
       let served: { close(): void } | undefined;
       let volumeSet = false;
@@ -501,6 +565,59 @@ export function castActions(ctx: WriteContext): CastActions {
       }
       return result;
 
+      /** What the announce would send, from the reads above; what it could not put back goes in `notRestored`. */
+      function dryAnnounce(): AnnounceResult {
+        const to = (
+          device: { name: string },
+          payload: Record<string, unknown>,
+        ): CastRequest => ({
+          device: device.name,
+          channel: "receiver",
+          payload,
+        });
+        const media = (payload: Record<string, unknown>): CastRequest => ({
+          device: d.name,
+          channel: "media",
+          payload,
+        });
+        const sends: CastRequest[] = [];
+        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.
@@ -538,81 +655,104 @@ export function castActions(ctx: WriteContext): CastActions {
         }
       }
 
-      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(): (
+        | {
+            name: string;
+            socket: CastSession;
+            payloads: Record<string, unknown>[];
+            label: string;
+          }
+        | { name: string; gap: string }
+      )[] {
+        const steps: ReturnType<typeof volumeSteps> = [];
         if (d.kind === "group" && options.volume !== undefined) {
           const level = before.volume?.level;
-          if (level === undefined)
-            result.notRestored.push({
-              name: d.name,
-              why: "its volume before was not reported",
-            });
-          else
-            try {
-              await receiver(s, { type: "SET_VOLUME", volume: { level } });
-              result.restored.push(`${d.name}: volume`);
-            } catch (error) {
-              result.notRestored.push({
-                name: d.name,
-                why: `volume not restored: ${errorText(error)}`,
-              });
-            }
+          steps.push(
+            level === undefined
+              ? { name: d.name, gap: "its volume before was not reported" }
+              : {
+                  name: d.name,
+                  socket: s,
+                  payloads: [{ type: "SET_VOLUME", volume: { level } }],
+                  label: `${d.name}: volume`,
+                },
+          );
         }
+        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 as { type: string });
+            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: string) => {
         try {
           return find(t).id;

package/src/connectors/enphase/README.md

@@ -10,9 +10,11 @@ Reads an IQ Gateway (Envoy) on the LAN: production, consumption and grid flow. `
 - `host` may be pasted with a scheme or a trailing slash (`https://…/`); `gatewayHost` reduces it to the bare host for requests, discovery and the address cache.
 - In the home config the device may carry `marker` (the plan's marker where the array is drawn, on the roof outside any room) and `capacityW` (the array's rated watts from the installer's paperwork, never guessed from the gateway). Neither reaches the gateway; they are for drawing.
 - A meter counts only when `/ivp/meters` says `enabled` **and** its reading has `activeCount > 0`; otherwise production comes from the inverters and Wh today is left out, since pyenphase found the inverter daily total unreliable.
-- The token's days left ride in the snapshot; under 30 the status says to run `home enphase login`. A 401 marks Enphase unavailable and stops polling.
+- The token's days left ride in the snapshot; under 30 the status says to run `home enphase login`. A 401 or 403 marks Enphase unavailable and stops polling.
 - `home enphase login` mints the token (below) and writes `~/.config/home/enphase-token.json` (0600, directory 0700), printing only the days left. `home status` shows solar now, consumption and the token's days left.
 
+**Live, 2026-11-12 (Bun 1.4.4).** From late October `home enphase` said ECONNREFUSED. The gateway had not changed: DHCP had given it a new address, mDNS and the address cache had the new one, and an `IQ_GATEWAY_HOST` in the shell still named the old one, which the CLI trusted without a fallback. The CLI now takes the serial from the address cache and runs discovery after one failed read, so the status line reads and says "moved from a to b". The owner token was fine throughout (338 days left).
+
 **Live, KO's gateway, 2026-10-13 (D8.3.5528, owner token).** `/info` answers without a token; everything else answers 401 without one. With the token, one GET each:
 
 - `/ivp/meters`: `production` and `net-consumption` **enabled**, `meteringStatus normal`; `storage`, `backfeed`, `load`, `evse`, `pv3p` disabled. So both CTs are fitted.