@khalido/home 0.2.1 → 0.2.2

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/spotify/README.md

@@ -26,6 +26,8 @@ Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x8
 
 **`maxVolume`** holds requests (rounded to a whole percent). For 10 s after a start signal, a reported volume above it is lowered: a start from idle (to playing or buffering), the first such status after a sign-in, `playing` after a start through buffering, or the speaker going active. Event order differs between runs, so no one pattern is relied on. It waits until the speaker is active, retries until Soloist reports the lower volume, and only then says so in `anomaly`, until the speaker goes idle; if it never shows or Soloist refuses it, `detail` says so. A reported volume within 1 of the cap is left alone. Not on resuming from pause while active, not on connecting to a song already playing, and a person turning it up after the lowering keeps it (before Soloist has reported the lowering, a person's raise looks like the start's own jump and is lowered too). `--initial-volume` is ignored on PipeWire ([#23](https://github.com/spotify/soloist/issues/23)).
 
+**Dry run.** Every write takes `{ dryRun: true }` last: the checks run (connected, signed in, the input, `inactive` for `setVolume`, `maxVolume`), nothing is sent, and it resolves `confirmed: false` with `wouldSend`, the commands in order (an inactive speaker's `play` lists `activate` first). `duck` and `interrupt` with `dryRun` run `fn`, touch nothing, and say in `why` what they would have done; they don't wait behind a real `duck` or `interrupt`. Tested on a fake socket only.
+
 **`duck(fn, { to })` and `interrupt(fn)`** turn the music down, or pause it, around `fn`, then put it back. Both resolve `{ value, music, why? }`, `music` one of:
 
 - `untouched`: not playing or buffering, not connected, not the active device, (duck) the volume unknown or already at `to` or below, or the lowering or pause failed, so `fn` ran over it.