iobroker.assistant 1.4.4 → 1.4.5

package/build/lib/voice/replyFormat.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_FORMAT = exports.CONTENT_TYPES = void 0;
+exports.chooseReplyFormat = chooseReplyFormat;
+exports.resamplePcm = resamplePcm;
+exports.monoToStereo = monoToStereo;
+exports.encodeReply = encodeReply;
+/**
+ * Which audio format an ESPHome satellite gets its spoken replies in.
+ *
+ * A media player announces the formats it takes (`ListEntitiesMediaPlayerResponse.supported_formats`, one per
+ * purpose: default playback and announcements). Home Assistant transcodes every reply to the announcement format,
+ * so that is the only one a firmware is tested with — and since ESPHome 2026.10 often the only one it can decode at
+ * all: the player is built with just the codecs its pipelines use. We do the same: the announcement format first,
+ * at its sample rate and channel count. A device that lists nothing (linux-voice-assistant, older firmware) keeps
+ * getting WAV as before.
+ */
+const flac_1 = require("./flac");
+const stt_1 = require("./stt");
+/** Codecs written here, without any tool. */
+const NATIVE = ['flac', 'wav'];
+const EXTERNAL = ['mp3', 'opus'];
+exports.CONTENT_TYPES = {
+    wav: 'audio/wav',
+    flac: 'audio/flac',
+    mp3: 'audio/mpeg',
+    // ESPHome takes Opus only as `audio/ogg` with an opus codecs parameter.
+    opus: 'audio/ogg; codecs=opus',
+};
+/** The format replies have always had: WAV at the rate of the TTS engine. */
+exports.LEGACY_FORMAT = { codec: 'wav', sampleRate: 0, channels: 1, source: '' };
+function describe(f) {
+    return `${f.format}${f.sampleRate ? ` ${f.sampleRate} Hz` : ''}${f.channels ? ` ×${f.channels}` : ''} (${f.purpose})`;
+}
+/**
+ * Pick the reply format from what the device's media players announced.
+ *
+ * @param formats every `supported_formats` entry of the device
+ * @param external whether MP3/Opus can be produced (ffmpeg)
+ */
+function chooseReplyFormat(formats, external) {
+    if (!formats.length) {
+        return exports.LEGACY_FORMAT;
+    }
+    const usable = (f) => {
+        const codec = f.format.trim().toLowerCase();
+        return NATIVE.includes(codec) || (external && EXTERNAL.includes(codec)) ? codec : null;
+    };
+    // Announcements first (that is how a reply is played), our own codecs before ffmpeg ones.
+    const ordered = [
+        ...formats.filter(f => f.purpose === 'announcement'),
+        ...formats.filter(f => f.purpose !== 'announcement'),
+    ];
+    const pick = ordered.find(f => {
+        const codec = usable(f);
+        return codec !== null && NATIVE.includes(codec);
+    }) ?? ordered.find(f => usable(f) !== null);
+    if (!pick) {
+        // Nothing we can write (or `none` = the device takes anything): WAV, as before.
+        return { ...exports.LEGACY_FORMAT, source: ordered.map(describe).join(', ') };
+    }
+    return {
+        codec: usable(pick),
+        sampleRate: pick.sampleRate || 0,
+        channels: pick.channels === 2 ? 2 : 1,
+        source: describe(pick),
+    };
+}
+/** Filter taps per side at the lower of the two rates, and the number of precomputed sub-sample positions. */
+const ZERO_CROSSINGS = 8;
+const PHASES = 128;
+/**
+ * Resample mono s16le PCM with a Hann-windowed sinc. Cheap enough for the voice path (a table per sub-sample
+ * position, ~20 taps when upsampling), and — unlike linear interpolation — it filters before it decimates, so a
+ * 24 kHz voice taken down to 16 kHz does not fold its sibilants back into the speech band.
+ */
+function resamplePcm(pcm, from, to) {
+    const n = pcm.length >> 1;
+    if (from === to || !n || from <= 0 || to <= 0) {
+        return pcm;
+    }
+    const input = new Float32Array(n);
+    for (let i = 0; i < n; i++) {
+        input[i] = pcm.readInt16LE(i * 2);
+    }
+    const ratio = to / from;
+    // A little below the Nyquist frequency of the lower rate.
+    const cutoff = Math.min(1, ratio) * 0.95;
+    const half = Math.ceil(ZERO_CROSSINGS / cutoff);
+    const taps = 2 * half;
+    const table = new Float32Array((PHASES + 1) * taps);
+    for (let p = 0; p <= PHASES; p++) {
+        const frac = p / PHASES;
+        let sum = 0;
+        for (let k = 0; k < taps; k++) {
+            const d = k - half + 1 - frac; // distance of the input sample from the output position
+            const x = d * cutoff;
+            const sinc = x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x);
+            const w = Math.abs(d) >= half ? 0 : 0.5 + 0.5 * Math.cos((Math.PI * d) / half);
+            table[p * taps + k] = sinc * w;
+            sum += sinc * w;
+        }
+        for (let k = 0; k < taps; k++) {
+            table[p * taps + k] /= sum; // unity gain at every position: no ripple on a constant level
+        }
+    }
+    const outLen = Math.max(1, Math.round(n * ratio));
+    const out = Buffer.alloc(outLen * 2);
+    for (let i = 0; i < outLen; i++) {
+        const center = i / ratio;
+        const base = Math.floor(center);
+        const row = Math.round((center - base) * PHASES) * taps;
+        const first = base - half + 1;
+        let acc = 0;
+        for (let k = 0; k < taps; k++) {
+            const j = first + k;
+            if (j >= 0 && j < n) {
+                acc += input[j] * table[row + k];
+            }
+        }
+        out.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round(acc))), i * 2);
+    }
+    return out;
+}
+/** Duplicate mono s16le PCM into interleaved stereo. */
+function monoToStereo(pcm) {
+    const n = pcm.length >> 1;
+    const out = Buffer.alloc(n * 4);
+    for (let i = 0; i < n; i++) {
+        const v = pcm.readInt16LE(i * 2);
+        out.writeInt16LE(v, i * 4);
+        out.writeInt16LE(v, i * 4 + 2);
+    }
+    return out;
+}
+/**
+ * Encode a mono reply in `format`. MP3/Opus go through `external`; everything else is written here.
+ * Throws when `external` is needed but missing or fails — the caller falls back to a native format.
+ */
+async function encodeReply(pcm, sampleRate, format, external) {
+    const rate = format.sampleRate || sampleRate;
+    if (format.codec === 'mp3' || format.codec === 'opus') {
+        if (!external) {
+            throw new Error(`no encoder for ${format.codec}`);
+        }
+        const body = await external(pcm, sampleRate, {
+            codec: format.codec,
+            sampleRate: rate,
+            channels: format.channels,
+        });
+        return { body, contentType: exports.CONTENT_TYPES[format.codec] };
+    }
+    const resampled = resamplePcm(pcm, sampleRate, rate);
+    const samples = format.channels === 2 ? monoToStereo(resampled) : resampled;
+    const body = format.codec === 'flac' ? (0, flac_1.encodeFlac)(samples, rate, format.channels) : (0, stt_1.pcmToWav)(samples, rate, format.channels);
+    return { body, contentType: exports.CONTENT_TYPES[format.codec] };
+}
+//# sourceMappingURL=replyFormat.js.map

package/build/lib/voice/replyFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replyFormat.js","sourceRoot":"","sources":["../../../src/lib/voice/replyFormat.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which audio format an ESPHome satellite gets its spoken replies in.\n *\n * A media player announces the formats it takes (`ListEntitiesMediaPlayerResponse.supported_formats`, one per\n * purpose: default playback and announcements). Home Assistant transcodes every reply to the announcement format,\n * so that is the only one a firmware is tested with — and since ESPHome 2026.10 often the only one it can decode at\n * all: the player is built with just the codecs its pipelines use. We do the same: the announcement format first,\n * at its sample rate and channel count. A device that lists nothing (linux-voice-assistant, older firmware) keeps\n * getting WAV as before.\n */\nimport { encodeFlac } from './flac';\nimport { pcmToWav } from './stt';\n\n/** One entry of `supported_formats`. */\nexport interface MediaFormat {\n    /** `flac`, `mp3`, `wav`, `opus`, `none` … as the device names it. */\n    format: string;\n    /** 0 = no preference. */\n    sampleRate: number;\n    /** 0 = no preference. */\n    channels: number;\n    purpose: 'default' | 'announcement';\n    sampleBytes: number;\n}\n\nexport type ReplyCodec = 'wav' | 'flac' | 'mp3' | 'opus';\n\nexport interface ReplyFormat {\n    codec: ReplyCodec;\n    /** Target rate; 0 keeps the rate of the TTS engine. */\n    sampleRate: number;\n    channels: 1 | 2;\n    /** What the device asked for, for the log. */\n    source: string;\n}\n\n/** Turns PCM into a codec we cannot write ourselves (MP3, Opus) — ffmpeg in the adapter. */\nexport type ExternalEncoder = (\n    pcm: Buffer,\n    sampleRate: number,\n    target: { codec: 'mp3' | 'opus'; sampleRate: number; channels: number },\n) => Promise<Buffer>;\n\n/** Codecs written here, without any tool. */\nconst NATIVE: ReplyCodec[] = ['flac', 'wav'];\nconst EXTERNAL: ReplyCodec[] = ['mp3', 'opus'];\n\nexport const CONTENT_TYPES: Record<ReplyCodec, string> = {\n    wav: 'audio/wav',\n    flac: 'audio/flac',\n    mp3: 'audio/mpeg',\n    // ESPHome takes Opus only as `audio/ogg` with an opus codecs parameter.\n    opus: 'audio/ogg; codecs=opus',\n};\n\n/** The format replies have always had: WAV at the rate of the TTS engine. */\nexport const LEGACY_FORMAT: ReplyFormat = { codec: 'wav', sampleRate: 0, channels: 1, source: '' };\n\nfunction describe(f: MediaFormat): string {\n    return `${f.format}${f.sampleRate ? ` ${f.sampleRate} Hz` : ''}${f.channels ? ` ×${f.channels}` : ''} (${f.purpose})`;\n}\n\n/**\n * Pick the reply format from what the device's media players announced.\n *\n * @param formats every `supported_formats` entry of the device\n * @param external whether MP3/Opus can be produced (ffmpeg)\n */\nexport function chooseReplyFormat(formats: MediaFormat[], external: boolean): ReplyFormat {\n    if (!formats.length) {\n        return LEGACY_FORMAT;\n    }\n    const usable = (f: MediaFormat): ReplyCodec | null => {\n        const codec = f.format.trim().toLowerCase() as ReplyCodec;\n        return NATIVE.includes(codec) || (external && EXTERNAL.includes(codec)) ? codec : null;\n    };\n    // Announcements first (that is how a reply is played), our own codecs before ffmpeg ones.\n    const ordered = [\n        ...formats.filter(f => f.purpose === 'announcement'),\n        ...formats.filter(f => f.purpose !== 'announcement'),\n    ];\n    const pick =\n        ordered.find(f => {\n            const codec = usable(f);\n            return codec !== null && NATIVE.includes(codec);\n        }) ?? ordered.find(f => usable(f) !== null);\n    if (!pick) {\n        // Nothing we can write (or `none` = the device takes anything): WAV, as before.\n        return { ...LEGACY_FORMAT, source: ordered.map(describe).join(', ') };\n    }\n    return {\n        codec: usable(pick) as ReplyCodec,\n        sampleRate: pick.sampleRate || 0,\n        channels: pick.channels === 2 ? 2 : 1,\n        source: describe(pick),\n    };\n}\n\n/** Filter taps per side at the lower of the two rates, and the number of precomputed sub-sample positions. */\nconst ZERO_CROSSINGS = 8;\nconst PHASES = 128;\n\n/**\n * Resample mono s16le PCM with a Hann-windowed sinc. Cheap enough for the voice path (a table per sub-sample\n * position, ~20 taps when upsampling), and — unlike linear interpolation — it filters before it decimates, so a\n * 24 kHz voice taken down to 16 kHz does not fold its sibilants back into the speech band.\n */\nexport function resamplePcm(pcm: Buffer, from: number, to: number): Buffer {\n    const n = pcm.length >> 1;\n    if (from === to || !n || from <= 0 || to <= 0) {\n        return pcm;\n    }\n    const input = new Float32Array(n);\n    for (let i = 0; i < n; i++) {\n        input[i] = pcm.readInt16LE(i * 2);\n    }\n    const ratio = to / from;\n    // A little below the Nyquist frequency of the lower rate.\n    const cutoff = Math.min(1, ratio) * 0.95;\n    const half = Math.ceil(ZERO_CROSSINGS / cutoff);\n    const taps = 2 * half;\n    const table = new Float32Array((PHASES + 1) * taps);\n    for (let p = 0; p <= PHASES; p++) {\n        const frac = p / PHASES;\n        let sum = 0;\n        for (let k = 0; k < taps; k++) {\n            const d = k - half + 1 - frac; // distance of the input sample from the output position\n            const x = d * cutoff;\n            const sinc = x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x);\n            const w = Math.abs(d) >= half ? 0 : 0.5 + 0.5 * Math.cos((Math.PI * d) / half);\n            table[p * taps + k] = sinc * w;\n            sum += sinc * w;\n        }\n        for (let k = 0; k < taps; k++) {\n            table[p * taps + k] /= sum; // unity gain at every position: no ripple on a constant level\n        }\n    }\n    const outLen = Math.max(1, Math.round(n * ratio));\n    const out = Buffer.alloc(outLen * 2);\n    for (let i = 0; i < outLen; i++) {\n        const center = i / ratio;\n        const base = Math.floor(center);\n        const row = Math.round((center - base) * PHASES) * taps;\n        const first = base - half + 1;\n        let acc = 0;\n        for (let k = 0; k < taps; k++) {\n            const j = first + k;\n            if (j >= 0 && j < n) {\n                acc += input[j] * table[row + k];\n            }\n        }\n        out.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round(acc))), i * 2);\n    }\n    return out;\n}\n\n/** Duplicate mono s16le PCM into interleaved stereo. */\nexport function monoToStereo(pcm: Buffer): Buffer {\n    const n = pcm.length >> 1;\n    const out = Buffer.alloc(n * 4);\n    for (let i = 0; i < n; i++) {\n        const v = pcm.readInt16LE(i * 2);\n        out.writeInt16LE(v, i * 4);\n        out.writeInt16LE(v, i * 4 + 2);\n    }\n    return out;\n}\n\n/**\n * Encode a mono reply in `format`. MP3/Opus go through `external`; everything else is written here.\n * Throws when `external` is needed but missing or fails — the caller falls back to a native format.\n */\nexport async function encodeReply(\n    pcm: Buffer,\n    sampleRate: number,\n    format: ReplyFormat,\n    external?: ExternalEncoder,\n): Promise<{ body: Buffer; contentType: string }> {\n    const rate = format.sampleRate || sampleRate;\n    if (format.codec === 'mp3' || format.codec === 'opus') {\n        if (!external) {\n            throw new Error(`no encoder for ${format.codec}`);\n        }\n        const body = await external(pcm, sampleRate, {\n            codec: format.codec,\n            sampleRate: rate,\n            channels: format.channels,\n        });\n        return { body, contentType: CONTENT_TYPES[format.codec] };\n    }\n    const resampled = resamplePcm(pcm, sampleRate, rate);\n    const samples = format.channels === 2 ? monoToStereo(resampled) : resampled;\n    const body =\n        format.codec === 'flac' ? encodeFlac(samples, rate, format.channels) : pcmToWav(samples, rate, format.channels);\n    return { body, contentType: CONTENT_TYPES[format.codec] };\n}\n"]}

package/build/lib/voice/stt.js

@@ -67,9 +67,8 @@ function hintsToPrompt(hints, maxChars = 800) {
     }
     return parts.join(', ');
 }
-/** Wrap raw mono 16-bit-signed-LE PCM into a minimal 44-byte WAV container. */
-function pcmToWav(pcm, sampleRate) {
-    const numChannels = 1;
+/** Wrap raw 16-bit-signed-LE PCM (mono, or interleaved stereo) into a minimal 44-byte WAV container. */
+function pcmToWav(pcm, sampleRate, numChannels = 1) {
     const bitsPerSample = 16;
     const blockAlign = (numChannels * bitsPerSample) / 8;
     const byteRate = sampleRate * blockAlign;

package/build/lib/voice/stt.js.map

@@ -1 +1 @@
-{"version":3,"file":"stt.js","sourceRoot":"","sources":["../../../src/lib/voice/stt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Speech-to-text engines. V1 ships the cloud engine (OpenAI Whisper); local engines\n * (Vosk / whisper.cpp / Wyoming) plug in behind the same `SttEngine` interface later.\n */\nimport OpenAI, { toFile } from 'openai';\n\nexport interface SttEngine {\n    /**\n     * Transcribe raw mono 16-bit PCM. `lang` is an ISO-639-1 hint ('' = auto-detect).\n     *\n     * `hints` is an optional domain vocabulary (device / room / scene names …) to bias recognition toward,\n     * so the engine better transcribes those proper nouns. Only engines that support *soft* biasing use it\n     * (OpenAI Whisper `prompt`, Azure phrase list); engines where a word list would be a hard constraint or\n     * needs pre-registration (Vosk grammar, AWS custom vocabulary) ignore it.\n     */\n    transcribe(pcm: Buffer, sampleRate: number, lang: string, hints?: string[]): Promise<string>;\n    /** Optional warm-up (install/download engine + model for `lang`) so the first request isn't slow. */\n    prepare?(lang: string): Promise<void>;\n}\n\n/**\n * Join vocabulary hints into a Whisper `prompt` string (a soft bias toward these terms), de-duplicated and\n * length-bounded to stay within the model's ~224-token prompt budget. Returns '' when there are no hints.\n */\nexport function hintsToPrompt(hints: string[] | undefined, maxChars = 800): string {\n    if (!hints?.length) {\n        return '';\n    }\n    const seen = new Set<string>();\n    const parts: string[] = [];\n    let len = 0;\n    for (const h of hints) {\n        const term = (h || '').trim();\n        const key = term.toLowerCase();\n        if (!term || seen.has(key)) {\n            continue;\n        }\n        if (len + term.length + 2 > maxChars) {\n            break;\n        }\n        seen.add(key);\n        parts.push(term);\n        len += term.length + 2;\n    }\n    return parts.join(', ');\n}\n\n/** Wrap raw mono 16-bit-signed-LE PCM into a minimal 44-byte WAV container. */\nexport function pcmToWav(pcm: Buffer, sampleRate: number): Buffer {\n    const numChannels = 1;\n    const bitsPerSample = 16;\n    const blockAlign = (numChannels * bitsPerSample) / 8;\n    const byteRate = sampleRate * blockAlign;\n    const header = Buffer.alloc(44);\n    header.write('RIFF', 0);\n    header.writeUInt32LE(36 + pcm.length, 4);\n    header.write('WAVE', 8);\n    header.write('fmt ', 12);\n    header.writeUInt32LE(16, 16); // PCM fmt chunk size\n    header.writeUInt16LE(1, 20); // audio format = PCM\n    header.writeUInt16LE(numChannels, 22);\n    header.writeUInt32LE(sampleRate, 24);\n    header.writeUInt32LE(byteRate, 28);\n    header.writeUInt16LE(blockAlign, 32);\n    header.writeUInt16LE(bitsPerSample, 34);\n    header.write('data', 36);\n    header.writeUInt32LE(pcm.length, 40);\n    return Buffer.concat([header, pcm]);\n}\n\n/** Cloud STT via the OpenAI transcription API (Whisper). */\nexport class OpenAiStt implements SttEngine {\n    private readonly client: OpenAI;\n    private readonly model: string;\n\n    constructor(apiKey: string, model = 'whisper-1') {\n        this.client = new OpenAI({ apiKey });\n        this.model = model;\n    }\n\n    async transcribe(pcm: Buffer, sampleRate: number, lang: string, hints?: string[]): Promise<string> {\n        const file = await toFile(pcmToWav(pcm, sampleRate), 'audio.wav', { type: 'audio/wav' });\n        // A prompt biases Whisper toward the given domain vocabulary (device/room names) without excluding\n        // other words — improves recognition of proper nouns the NLU then needs to match.\n        const prompt = hintsToPrompt(hints);\n        const res = await this.client.audio.transcriptions.create({\n            file,\n            model: this.model,\n            // Whisper wants the bare ISO-639-1 code; strip any region (de-DE → de). '' → auto-detect.\n            language: (lang || '').split('-')[0] || undefined,\n            ...(prompt ? { prompt } : {}),\n        });\n        return (res.text || '').trim();\n    }\n}\n"]}
+{"version":3,"file":"stt.js","sourceRoot":"","sources":["../../../src/lib/voice/stt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Speech-to-text engines. V1 ships the cloud engine (OpenAI Whisper); local engines\n * (Vosk / whisper.cpp / Wyoming) plug in behind the same `SttEngine` interface later.\n */\nimport OpenAI, { toFile } from 'openai';\n\nexport interface SttEngine {\n    /**\n     * Transcribe raw mono 16-bit PCM. `lang` is an ISO-639-1 hint ('' = auto-detect).\n     *\n     * `hints` is an optional domain vocabulary (device / room / scene names …) to bias recognition toward,\n     * so the engine better transcribes those proper nouns. Only engines that support *soft* biasing use it\n     * (OpenAI Whisper `prompt`, Azure phrase list); engines where a word list would be a hard constraint or\n     * needs pre-registration (Vosk grammar, AWS custom vocabulary) ignore it.\n     */\n    transcribe(pcm: Buffer, sampleRate: number, lang: string, hints?: string[]): Promise<string>;\n    /** Optional warm-up (install/download engine + model for `lang`) so the first request isn't slow. */\n    prepare?(lang: string): Promise<void>;\n}\n\n/**\n * Join vocabulary hints into a Whisper `prompt` string (a soft bias toward these terms), de-duplicated and\n * length-bounded to stay within the model's ~224-token prompt budget. Returns '' when there are no hints.\n */\nexport function hintsToPrompt(hints: string[] | undefined, maxChars = 800): string {\n    if (!hints?.length) {\n        return '';\n    }\n    const seen = new Set<string>();\n    const parts: string[] = [];\n    let len = 0;\n    for (const h of hints) {\n        const term = (h || '').trim();\n        const key = term.toLowerCase();\n        if (!term || seen.has(key)) {\n            continue;\n        }\n        if (len + term.length + 2 > maxChars) {\n            break;\n        }\n        seen.add(key);\n        parts.push(term);\n        len += term.length + 2;\n    }\n    return parts.join(', ');\n}\n\n/** Wrap raw 16-bit-signed-LE PCM (mono, or interleaved stereo) into a minimal 44-byte WAV container. */\nexport function pcmToWav(pcm: Buffer, sampleRate: number, numChannels = 1): Buffer {\n    const bitsPerSample = 16;\n    const blockAlign = (numChannels * bitsPerSample) / 8;\n    const byteRate = sampleRate * blockAlign;\n    const header = Buffer.alloc(44);\n    header.write('RIFF', 0);\n    header.writeUInt32LE(36 + pcm.length, 4);\n    header.write('WAVE', 8);\n    header.write('fmt ', 12);\n    header.writeUInt32LE(16, 16); // PCM fmt chunk size\n    header.writeUInt16LE(1, 20); // audio format = PCM\n    header.writeUInt16LE(numChannels, 22);\n    header.writeUInt32LE(sampleRate, 24);\n    header.writeUInt32LE(byteRate, 28);\n    header.writeUInt16LE(blockAlign, 32);\n    header.writeUInt16LE(bitsPerSample, 34);\n    header.write('data', 36);\n    header.writeUInt32LE(pcm.length, 40);\n    return Buffer.concat([header, pcm]);\n}\n\n/** Cloud STT via the OpenAI transcription API (Whisper). */\nexport class OpenAiStt implements SttEngine {\n    private readonly client: OpenAI;\n    private readonly model: string;\n\n    constructor(apiKey: string, model = 'whisper-1') {\n        this.client = new OpenAI({ apiKey });\n        this.model = model;\n    }\n\n    async transcribe(pcm: Buffer, sampleRate: number, lang: string, hints?: string[]): Promise<string> {\n        const file = await toFile(pcmToWav(pcm, sampleRate), 'audio.wav', { type: 'audio/wav' });\n        // A prompt biases Whisper toward the given domain vocabulary (device/room names) without excluding\n        // other words — improves recognition of proper nouns the NLU then needs to match.\n        const prompt = hintsToPrompt(hints);\n        const res = await this.client.audio.transcriptions.create({\n            file,\n            model: this.model,\n            // Whisper wants the bare ISO-639-1 code; strip any region (de-DE → de). '' → auto-detect.\n            language: (lang || '').split('-')[0] || undefined,\n            ...(prompt ? { prompt } : {}),\n        });\n        return (res.text || '').trim();\n    }\n}\n"]}

package/build/main.js

@@ -162,6 +162,10 @@ function valuesMatch(actual, expected) {
     }
     return String(actual).trim().toLowerCase() === String(expected).trim().toLowerCase();
 }
+/** Whether an ESPHome entity id can be the last part of an ioBroker id (empty ones came from ESPHome 2026). */
+function isControlId(objectId) {
+    return !!objectId && !/[^\p{Ll}\p{Lu}\p{Nd}_-]/u.test(objectId);
+}
 /**
  * ioBroker role for a measurement, derived from its unit — a `value.temperature` shows up with the right
  * icon and in the right place in vis, where a bare `value` is just a number.
@@ -334,6 +338,8 @@ class Assistant extends adapter_core_1.Adapter {
     satControlsReady = new Map();
     /** Satellites whose `volume` state exists and is subscribed (see updateSatelliteVolume). */
     satVolumeEnsured = new Set();
+    /** ESPHome satellite id → the table address already written to its object (see markEsphomeSatellite). */
+    satEsphomeMarked = new Map();
     /** Native (ioBroker) satellite state-id → sender instance id, so we can push announcements back to it. */
     nativeSatFrom = new Map();
     /** Countdown timers / reminders (roadmap #2); mirrored into `timers.*` states. Null until onReady. */
@@ -588,6 +594,8 @@ class Assistant extends adapter_core_1.Adapter {
     async startEsphome(llmKey) {
         const cfg = this.config;
         const devices = (cfg.esphomeDevices || []).filter(d => d?.ip?.trim());
+        // Rows deleted from the table leave their satellite objects behind otherwise — forever offline in the list.
+        await this.removeStaleEsphomeSatellites(devices).catch(e => this.log.warn(`Could not clean up removed ESPHome satellites: ${e.message}`));
         if (!devices.length) {
             this.log.warn('ESPHome satellites are enabled, but no device is configured.');
             return;
@@ -643,9 +651,12 @@ class Assistant extends adapter_core_1.Adapter {
             mediaHost: (cfg.esphomeMediaHost || '').trim(),
             silenceMs: cfg.esphomeSilenceMs || 0,
             log: this.log,
-            onStatus: (device, room, state) => {
-                this.updateSatelliteState(device, room, state).catch(e => this.log.debug(`satellite state update failed: ${e.message}`));
+            onStatus: (device, room, state, address) => {
+                this.updateSatelliteState(device, room, state)
+                    .then(() => this.markEsphomeSatellite(device, room, address))
+                    .catch(e => this.log.debug(`satellite state update failed: ${e.message}`));
             },
+            encodeAudio: (pcm, sampleRate, target) => this.runFfmpegEncode(pcm, sampleRate, target),
             onWakeWords: (device, room, config) => {
                 this.updateSatelliteWakeWords(device, room, config).catch(e => this.log.debug(`satellite wake word update failed: ${e.message}`));
             },
@@ -1100,6 +1111,93 @@ class Assistant extends adapter_core_1.Adapter {
         this.satDeviceById.set(id, device);
         return id;
     }
+    /**
+     * Note which table row an ESPHome satellite belongs to (`native.esphome` on `satellites.<id>`) and show its
+     * address in the host column. That is what lets {@link removeStaleEsphomeSatellites} remove it once the row is
+     * deleted — the id alone is the room or the device name and says nothing about the configuration.
+     */
+    async markEsphomeSatellite(device, room, address) {
+        const id = await this.ensureSatelliteObjects(device, room);
+        if (this.satEsphomeMarked.get(id) === address) {
+            return;
+        }
+        this.satEsphomeMarked.set(id, address);
+        const obj = await this.getObjectAsync(`satellites.${id}`);
+        if (obj?.native?.esphome !== address) {
+            await this.extendObjectAsync(`satellites.${id}`, { native: { esphome: address } });
+        }
+        await this.setStateAsync(`satellites.${id}.host`, { val: address, ack: true });
+    }
+    /**
+     * Remove the objects of ESPHome satellites whose row was deleted from the table (or whose room changed, which
+     * changes the id). Runs before the devices connect, so nothing is re-created meanwhile.
+     *
+     * A satellite marked by {@link markEsphomeSatellite} is matched by its address. One from an older version
+     * carries no mark; it is recognised by `wakeWords` (only ESPHome satellites have it) and removed only when
+     * every row has a room — otherwise a row without one could be it, under its device name.
+     */
+    async removeStaleEsphomeSatellites(devices) {
+        const expected = new Map(devices.map(d => [(0, esphome_1.esphomeAddress)(d), d.room?.trim() ? this.satelliteStateId('', d.room) : null]));
+        const allHaveRooms = [...expected.values()].every(id => id !== null);
+        const roomIds = new Set([...expected.values()].filter((id) => !!id));
+        const prefix = `${this.namespace}.satellites.`;
+        const view = await this.getObjectViewAsync('system', 'device', {
+            startkey: prefix,
+            endkey: `${prefix}香`,
+        });
+        for (const row of view.rows) {
+            const id = row.id.slice(prefix.length);
+            if (!id || id.includes('.')) {
+                continue;
+            }
+            const address = row.value?.native?.esphome;
+            let reason = '';
+            if (address) {
+                if (!expected.has(address)) {
+                    reason = `${address} is no longer in the ESPHome satellites table`;
+                }
+                else {
+                    const want = expected.get(address);
+                    if (want && want !== id) {
+                        reason = `${address} is now in room ${want}`;
+                    }
+                }
+            }
+            else if (allHaveRooms && !roomIds.has(id) && (await this.getObjectAsync(`satellites.${id}.wakeWords`))) {
+                reason = 'no row of the ESPHome satellites table has this room any more';
+            }
+            if (reason) {
+                this.log.info(`Satellite ${id} removed: ${reason}`);
+                await this.forgetSatellite(id);
+            }
+        }
+    }
+    /** Delete a satellite's objects (Satellites tab). Refused while it is online: it would be re-created at once. */
+    async deleteSatellite(id) {
+        if (!id || /[^\w-]/.test(id)) {
+            throw new Error(`invalid satellite id "${id}"`);
+        }
+        if (!(await this.getObjectAsync(`satellites.${id}`))) {
+            throw new Error(`no satellite ${id}`);
+        }
+        const alive = await this.getStateAsync(`satellites.${id}.alive`);
+        if (alive?.val === true) {
+            throw new Error(`satellite ${id} is online`);
+        }
+        await this.forgetSatellite(id);
+        this.log.info(`Satellite ${id} deleted`);
+    }
+    /** Drop the object tree of one satellite and everything cached about it. */
+    async forgetSatellite(id) {
+        await this.delObjectAsync(`satellites.${id}`, { recursive: true });
+        this.satStatesEnsured.delete(id);
+        this.satWakeWordStatesEnsured.delete(id);
+        this.satVolumeEnsured.delete(id);
+        this.satControlsReady.delete(id);
+        this.satEsphomeMarked.delete(id);
+        this.satDeviceById.delete(id);
+        this.dndById.delete(id);
+    }
     /**
      * Publish a satellite's wake-word configuration and let it be changed from ioBroker.
      *
@@ -1303,6 +1401,10 @@ class Assistant extends adapter_core_1.Adapter {
             native: {},
         });
         for (const entity of entities) {
+            if (!isControlId(entity.objectId)) {
+                this.log.debug(`Satellite ${device}: no usable id for "${entity.name}" (${entity.kind}) — skipped`);
+                continue;
+            }
             const id = `${base}.${entity.objectId}`;
             const name = entity.name || entity.objectId;
             if (entity.kind === 'mediaPlayer') {
@@ -1439,6 +1541,9 @@ class Assistant extends adapter_core_1.Adapter {
     }
     /** Write one entity's current value into its state(s). Always acked — this is the device talking. */
     async writeSatelliteControl(satId, entity) {
+        if (!isControlId(entity.objectId)) {
+            return; // never created (see buildSatelliteControls)
+        }
         const base = `satellites.${satId}.controls.${entity.objectId}`;
         if (entity.kind === 'mediaPlayer') {
             const v = entity.value;
@@ -1904,7 +2009,35 @@ class Assistant extends adapter_core_1.Adapter {
             }
         });
     }
-    /** Invalidate the cached device/room/function listings when a room/function enum changes. */
+    /**
+     * Encode mono 16-bit PCM as MP3 or Opus (Ogg) via ffmpeg — for an ESPHome media player that was built with
+     * nothing but that decoder. FLAC and WAV need no tool and are written in `replyFormat.ts`.
+     */
+    runFfmpegEncode(pcm, sampleRate, target) {
+        return new Promise((resolve, reject) => {
+            // prettier-ignore
+            const input = ['-hide_banner', '-loglevel', 'error', '-f', 's16le', '-ar', String(sampleRate), '-ac', '1', '-i', 'pipe:0'];
+            // prettier-ignore
+            const output = target.codec === 'mp3'
+                ? ['-c:a', 'libmp3lame', '-b:a', '128k', '-f', 'mp3']
+                : ['-c:a', 'libopus', '-b:a', '64k', '-f', 'ogg'];
+            // Opus runs at 48/24/16/12/8 kHz only; anything else would make libopus refuse.
+            const rate = target.codec === 'opus' && ![48000, 24000, 16000, 12000, 8000].includes(target.sampleRate)
+                ? 48000
+                : target.sampleRate;
+            const args = [...input, '-ar', String(rate), '-ac', String(target.channels), ...output, '-'];
+            const proc = (0, node_child_process_1.spawn)('ffmpeg', args);
+            const chunks = [];
+            proc.stdout.on('data', (d) => chunks.push(d));
+            proc.stderr.on('data', (d) => this.log.debug(`ffmpeg: ${String(d).trim()}`));
+            proc.on('error', e => reject(new Error(`ffmpeg failed: ${e.message}`)));
+            proc.on('close', code => code === 0 && chunks.length
+                ? resolve(Buffer.concat(chunks))
+                : reject(new Error(`ffmpeg exited with code ${code}`)));
+            proc.stdin.on('error', () => { }); // ignore EPIPE if ffmpeg exits early
+            proc.stdin.end(pcm);
+        });
+    }
     /** Vendor and key of the cloud LLM: speech of the same vendor (OpenAI, OpenRouter) reuses the key. */
     async speechLlmKey() {
         const provider = this.config.provider || 'openai';
@@ -2509,6 +2642,23 @@ class Assistant extends adapter_core_1.Adapter {
             }
             return;
         }
+        // Satellites tab: forget a satellite that is gone. message = { id } (the state id under `satellites.`).
+        if (obj.command === 'deleteSatellite') {
+            const raw = obj.message?.id;
+            const id = typeof raw === 'string' ? raw : '';
+            let payload;
+            try {
+                await this.deleteSatellite(id);
+                payload = { ok: true };
+            }
+            catch (e) {
+                payload = { error: e.message };
+            }
+            if (obj.callback) {
+                this.sendTo(obj.from, obj.command, payload, obj.callback);
+            }
+            return;
+        }
         // Scripts: silence a ringing timer/alarm.
         if (obj.command === 'stopRinging') {
             const n = this.stopRinging();