@khalido/home 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-11-12
+
+### Added
+
+- **cast:** WAV speech. `announce` rewrites a clip of WAV bytes as 48 kHz, 16-bit, stereo PCM before serving it, in plain TypeScript, so a bot's TTS WAV needs no ffmpeg; a dry run says so. A 24 kHz mono WAV failed on audio-only Nest speakers (2026-11-09); rewritten, it played on a Nest Audio, a Nest Mini, a Google Home speaker, a Nest Hub and a Nest Hub Max (2026-11-12). `castWav`, `CAST_WAV` and the `WavFormat` type are exported for a clip served by URL; a clip given as a URL is sent as it is.
+- **cast, spotify:** dry run. Every Cast and Spotify write takes `{ dryRun: true }`: it checks as a real write does, sends nothing, and says what it would send (`wouldSend`). Cast's `setVolume`, `setMuted` and `stop` now resolve `{ wouldSend }` under a dry run and `undefined` otherwise; a dry `announce` also names in `notRestored` the app it would interrupt, and serves nothing. Spotify's `duck` and `interrupt` run `fn` and say in `why` what they would have done. `home cast …` and `home spotify …` take `--dry-run`. New types: `CastRequest`, `CastDryRun`, `CastWriteOptions`, `SpotifyRequest`, `SpotifyWriteOptions`.
+
+## [0.2.1] - 2026-11-12
+
+### Added
+
+- **printers:** printing. `identifyPrinter`, `validateJob`, `printJob` and `cancelJob` over IPP, and `pwgRaster` for a printer that takes no PDF (8-bit grey PWG Raster). The snapshot's `Printer` gains `port` and `rp`, so a write can reach it. `home printers print <file.pdf> [printer]`, `identify` and `cancel`; `print --dry-run` has the printer validate the job and sends no job; a printer with no PDF needs poppler's `pdftoppm`. Live on a Brother HL-L2350DW.
+
+### Fixed
+
+- **cli, enphase:** a stale `IQ_GATEWAY_HOST` no longer leaves `home enphase` refused for good: with the gateway's serial from the address cache, a failed read is followed by mDNS discovery, and the line says where the gateway moved. Without `IQ_GATEWAY_HOST` the address comes from the cache, then from mDNS.
+- **amber, enphase, up:** a 403 is a rejected key (`unavailable`, `reason: "auth"`), as a 401 already was and as Hue and Google weather already read both. It was `disconnected` and retried forever. One check, `isRejectedKey` in `src/connector.ts`, now serves every connector and the CLI.
+- **spotify:** after the first-play lowering ([spotify/soloist#23](https://github.com/spotify/soloist/issues/23)), `anomaly` no longer says only "lowered it" when the volume is back above `maxVolume`: it adds `it is back at <n>`. Soloist puts its own level back about 90 ms after `playing` when it goes active (live, 2026-11-11), and the cap leaves that level alone.
+
 ## [0.2.0] - 2026-11-12
 
 ### Breaking
@@ -34,7 +53,7 @@ All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](h
 - **cast: `castFreeSpeakers(state)`**: every free speaker and display in one call, a whole group where all of it is free, never a TV; `free` goes straight to `announceAll`.
 - **cast: `castFree(state, targets, { forms })`**: with `forms: ["speaker", "display"]` a TV is left out (`why: "form"`, only when `forms` is given), and a group holding one becomes its other free members.
 - **`home.add(integration)` and `home.remove(name)`** on the home `createHome` returns: add one while the rest keep running (a bridge paired just now), replace one by name (the old run has ended before the new one starts; how an `unavailable` part comes back after a re-key), or stop one and drop its part. `start` now also waits for those added.
-- **spotify: `playingElsewhere(state)`**, and **`spotifyElsewhere(snapshot)`** from `@khalido/home`: the names of the Cast devices and groups playing that track in Spotify, matched by the track's name since Soloist doesn't say where the music is. Empty for a phone or a laptop. `homeDevices` and `home devices` put it in the speaker's line (`silent · "Song" is playing on Front room speaker`), and `spotifyText(state, on)` takes it. Tested on built snapshots only.
+- **spotify: `playingElsewhere(state)`**, and **`spotifyElsewhere(snapshot)`** from `@khalido/home`: the names of the Cast devices and groups playing that track in Spotify, matched by the track's name since Soloist doesn't say where the music is. Empty for a phone or a laptop. `homeDevices` and `home devices` put it in the speaker's line (`silent · "Song" is playing on Den speaker`), and `spotifyText(state, on)` takes it. Tested on built snapshots only.
 - **hue: lights, rooms and scenes by name.** `client.light(name, change)`, `client.room(name, change)` and `client.scene(name, room?)`, each resolving `{ state, confirmed }` (`HueApplied`). `change` (`LightChange`) is `{ on?, brightness?, color?, kelvin?, transitionMs? }`: a colour as hex or `{ r, g, b }`, sent as `xy` inside the light's own gamut; a white temperature in kelvin, checked against the light's range. An unknown name or a value the light can't take throws `HueError` with `code: "invalid"` before anything is sent, and a light the bridge has lost throws with `code: "offline"`.
 - **hue: colour in the state.** Each light's `kelvin` and `kelvinRange`, and on a colour light its `xy`, `hex` and `gamut`. `colorToXy`, `xyToHex`, `kelvinToMirek`, `mirekToKelvin` and `hueText` are exported.
 - **`home light <name> …`**, and `home room` and `home scene` now take a brightness, a temperature (`2700k`) and a colour (`ff8800`) together, name a scene's room (`in <room>`), and print what the bridge then reported.
@@ -139,7 +158,10 @@ First release. Nine connectors: Hue, Daikin, Enphase, Google Cast, AirPrint prin
 - **Agent skills** in `skills/`: `use-home` (reading safely, connecting, the rules for writes) and `draw-home` (an SVG plan of a home and its rooms). `llms.txt` points agents at the docs.
 - **Node.** Hue and Enphase take the fetches in `@khalido/home/node`. The library runs on Bun 1.4+ and Node 24+; the `home` command needs Bun.
 
-[Unreleased]: https://github.com/khalido/home.ts/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/khalido/home.ts/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/khalido/home.ts/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/khalido/home.ts/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/khalido/home.ts/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/khalido/home.ts/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/khalido/home.ts/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/khalido/home.ts/compare/v0.1.0...v0.1.1

package/dist/connector.d.ts

@@ -23,6 +23,8 @@ export declare class ConnectorError extends Error {
         cause?: unknown;
     });
 }
+/** 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 declare const isRejectedKey: (error: unknown) => boolean;
 /** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
 export declare function fetchTimeout(fetcher: typeof fetch, url: string | URL, init?: Omit<RequestInit, "signal">, options?: {
     timeoutMs?: number;

package/dist/connector.js

@@ -24,6 +24,9 @@ export class ConnectorError extends Error {
         this.code = options.code;
     }
 }
+/** 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) => 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, url, init = {}, options = {}) {
     const timeout = AbortSignal.timeout(options.timeoutMs ?? TIMEOUT_MS);

package/dist/connectors/amber/client.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { ConnectorError } from "../../connector.ts";
-/** 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 declare 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/dist/connectors/amber/client.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { ConnectorError, getJson } from "../../connector.js";
 // 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/dist/connectors/amber/index.js

@@ -1,5 +1,5 @@
 import { asOf, realClock } from "../../clock.js";
-import { errorText } from "../../connector.js";
+import { errorText, isRejectedKey } from "../../connector.js";
 import { z } from "zod";
 import { envName } from "../../home.js";
 import { energyNow } from "../../energy.js";
@@ -41,7 +41,7 @@ export function amber(config) {
                 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/dist/connectors/cast/index.d.ts

@@ -9,7 +9,8 @@ import { type CastActions, type ServeClip } from "./writes.ts";
 export type { CastConnect } from "./codec.ts";
 export { castDevices, castForm, castFree, castFreeSpeakers, castStatus, } from "./state.ts";
 export type { CastDevice, CastForm, CastSkipped, CastSnapshot, CastStatus, Resolved, } from "./state.ts";
-export type { AnnounceResult, CastActions, CastClip, ServeClip, } from "./writes.ts";
+export { CAST_WAV, castWav, type WavFormat } from "./wav.ts";
+export type { AnnounceResult, CastActions, CastClip, CastDryRun, CastRequest, CastWriteOptions, ServeClip, } from "./writes.ts";
 /** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */
 export declare const configSchema: z.ZodObject<{
     connector: z.ZodLiteral<"cast">;

package/dist/connectors/cast/index.js

@@ -9,6 +9,7 @@ import { CastPayload, KNOWN_TYPES } from "./schemas.js";
 import { castKey, connection, found, mediaApp, reduce, castDevices, castStatus, } from "./state.js";
 import { castActions, } from "./writes.js";
 export { castDevices, castForm, castFree, castFreeSpeakers, castStatus, } from "./state.js";
+export { CAST_WAV, castWav } from "./wav.js";
 /** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */
 export const configSchema = z.looseObject({
     connector: z.literal("cast"),

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

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

package/dist/connectors/cast/wav.js

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

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

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