iobroker.assistant 1.3.0 → 1.4.0

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

@@ -1 +1 @@
-{"version":3,"file":"vad.js","sourceRoot":"","sources":["../../../src/lib/voice/vad.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * End-of-speech detection for satellites that stream microphone audio until they are told to stop.\n *\n * The Hannah/UDP protocol has the satellite decide when an utterance ended (`audio_end`), and Wyoming\n * clients send `audio-stop` themselves. ESPHome voice satellites do neither: they keep streaming until\n * the server sends `STT_VAD_END`/`STT_END`, so the decision has to happen here.\n *\n * This is a plain energy gate, not a neural VAD — good enough to close an utterance, and it costs\n * nothing per frame. Speech must first rise above `startLevel`; after that, `silenceMs` worth of frames\n * below `endLevel` ends it. `maxMs` is the hard stop for rooms that are simply loud.\n *\n * Fixed thresholds only work when the microphone level is known, and on a real satellite it is not.\n * Measured on a ThirdReality Voice & Music Assistant: the device plays a wake-acknowledgement chirp\n * into its own microphone that peaks at full scale (RMS ~16000, clipped), while the speech that follows\n * arrives at RMS 358–469 — below the 700 default for `startLevel` and right on the 400 for `endLevel`.\n * That breaks the gate twice over: `sawSpeech` is satisfied by the chirp rather than by any voice, so\n * the \"nothing but speech-free audio\" guard never fires, and half the real speech frames count as\n * silence, so the utterance can be cut off mid-sentence.\n *\n * Hence two opt-in knobs, both enabled by the ESPHome transport:\n *\n * - `skipMs` drops the leading chirp from the *analysis* (never from the audio, which still goes to STT\n *   in full — a fast speaker may already be talking).\n * - `adaptive` derives the thresholds from a tracked noise floor instead of fixed levels. The floor\n *   follows the quietest frame seen (instant down, very slow up), so it settles on room noise even when\n *   someone starts talking immediately — which a mean or median over a calibration window would not.\n */\n\n/**\n * A buffer that may be a view onto any `ArrayBufferLike` — what `Buffer.subarray()` and\n * `Buffer.concat()` hand back. Plain `Buffer` (= `Buffer<ArrayBuffer>`) assigns to it, not the reverse.\n */\nexport type Bytes = Buffer<ArrayBufferLike>;\n\n/** Root-mean-square amplitude (0…32767) of a mono 16-bit signed LE PCM buffer. */\nexport function rms(pcm: Bytes): number {\n    const samples = Math.floor(pcm.length / 2);\n    if (!samples) {\n        return 0;\n    }\n    let sum = 0;\n    for (let i = 0; i < samples; i++) {\n        const value = pcm.readInt16LE(i * 2);\n        sum += value * value;\n    }\n    return Math.sqrt(sum / samples);\n}\n\nexport interface SpeechDetectorOptions {\n    /** Sample rate of the incoming PCM (ESPHome satellites always capture at 16 kHz). */\n    sampleRate?: number;\n    /** Analysis window; 30 ms is the usual compromise between latency and stability. */\n    frameMs?: number;\n    /** RMS above which we consider speech to have started. Ignored when `adaptive` is on. */\n    startLevel?: number;\n    /** RMS below which a frame counts as silence. Ignored when `adaptive` is on. */\n    endLevel?: number;\n    /** Silence after speech that ends the utterance. */\n    silenceMs?: number;\n    /** Hard cap on one utterance, in case the room never falls quiet. */\n    maxMs?: number;\n    /**\n     * Leading audio to leave out of the analysis — for devices that chirp into their own microphone\n     * when the wake word fires. The audio itself is untouched; this only stops the chirp from being\n     * mistaken for speech and from poisoning the noise floor.\n     */\n    skipMs?: number;\n    /** Derive the thresholds from the tracked noise floor instead of using fixed levels. */\n    adaptive?: boolean;\n    /** Adaptive mode: `startLevel` is at least this, however quiet the room is. */\n    minStartLevel?: number;\n    /** Adaptive mode: `endLevel` is at least this. */\n    minEndLevel?: number;\n    /** Adaptive mode: speech threshold as a multiple of the noise floor. */\n    startFactor?: number;\n    /** Adaptive mode: silence threshold as a multiple of the noise floor. */\n    endFactor?: number;\n    /** Adaptive mode: settle the noise floor this long before speech may be declared. */\n    warmupMs?: number;\n}\n\n/** Why an utterance ended: the speaker stopped, or we hit the hard cap. */\nexport type SpeechEnd = 'speech-end' | 'timeout';\n\n/**\n * How fast the tracked noise floor may follow a *rising* ambient level, per analysed frame (30 ms).\n * Fast enough that a genuinely noisy room is matched within about a second, slow enough that a voice\n * cannot pull the floor up to its own level before it has been recognised as speech.\n */\nconst NOISE_RISE = 0.02;\n\nexport class SpeechDetector {\n    private readonly frameBytes: number;\n    private readonly frameMs: number;\n    private readonly fixedStart: number;\n    private readonly fixedEnd: number;\n    private readonly silenceMs: number;\n    private readonly maxMs: number;\n    private readonly skipMs: number;\n    private readonly adaptive: boolean;\n    private readonly minStartLevel: number;\n    private readonly minEndLevel: number;\n    private readonly startFactor: number;\n    private readonly endFactor: number;\n    private readonly warmupMs: number;\n\n    private pending: Bytes = Buffer.alloc(0);\n    private speechSeen = false;\n    private silentMs = 0;\n    /** Tracked room level in adaptive mode; null until the first analysed frame. */\n    private floor: number | null = null;\n    /** Audio seen so far *including* the skipped lead-in, in milliseconds. */\n    private elapsedMs = 0;\n    /** Audio analysed so far, in milliseconds (exposed for logging). */\n    totalMs = 0;\n    /** Loudest frame seen so far (exposed for logging — the usual clue when a mic is mis-configured). */\n    peak = 0;\n\n    constructor({\n        sampleRate = 16000,\n        frameMs = 30,\n        startLevel = 700,\n        endLevel = 400,\n        silenceMs = 900,\n        maxMs = 12000,\n        skipMs = 0,\n        adaptive = false,\n        minStartLevel = 250,\n        minEndLevel = 150,\n        startFactor = 3.5,\n        endFactor = 2,\n        warmupMs = 150,\n    }: SpeechDetectorOptions = {}) {\n        this.frameBytes = Math.round((sampleRate * frameMs) / 1000) * 2;\n        this.frameMs = frameMs;\n        this.fixedStart = startLevel;\n        this.fixedEnd = endLevel;\n        this.silenceMs = silenceMs;\n        this.maxMs = maxMs;\n        this.skipMs = skipMs;\n        this.adaptive = adaptive;\n        this.minStartLevel = minStartLevel;\n        this.minEndLevel = minEndLevel;\n        this.startFactor = startFactor;\n        this.endFactor = endFactor;\n        this.warmupMs = warmupMs;\n    }\n\n    /** True once any frame crossed {@link startLevel} — an utterance that never did is room noise. */\n    get sawSpeech(): boolean {\n        return this.speechSeen;\n    }\n\n    /** Tracked room level (adaptive mode), for logging. 0 before the first analysed frame. */\n    get noiseFloor(): number {\n        return this.floor ?? 0;\n    }\n\n    /** Current speech threshold — fixed, or derived from the noise floor in adaptive mode. */\n    get startLevel(): number {\n        return this.adaptive ? Math.max(this.minStartLevel, (this.floor ?? 0) * this.startFactor) : this.fixedStart;\n    }\n\n    /** Current silence threshold. Never above {@link startLevel}, so the gate keeps its hysteresis. */\n    get endLevel(): number {\n        if (!this.adaptive) {\n            return this.fixedEnd;\n        }\n        return Math.min(this.startLevel, Math.max(this.minEndLevel, (this.floor ?? 0) * this.endFactor));\n    }\n\n    /** Feed one audio chunk (any size). Returns why the utterance ended, or null to keep listening. */\n    push(chunk: Bytes): SpeechEnd | null {\n        this.pending = this.pending.length ? Buffer.concat([this.pending, chunk]) : chunk;\n        let verdict: SpeechEnd | null = null;\n\n        while (this.pending.length >= this.frameBytes) {\n            const frame = this.pending.subarray(0, this.frameBytes);\n            this.pending = this.pending.subarray(this.frameBytes);\n            this.elapsedMs += this.frameMs;\n\n            const level = rms(frame);\n            if (level > this.peak) {\n                this.peak = level;\n            }\n\n            // The device's own wake chirp: loud, clipped, and not speech. Leaving it out of the\n            // analysis is what makes `sawSpeech` mean anything, and keeps the noise floor honest.\n            if (this.elapsedMs <= this.skipMs) {\n                continue;\n            }\n            this.totalMs += this.frameMs;\n\n            if (this.adaptive) {\n                // Three rules, each there to defeat a specific way of getting this wrong:\n                //  - start at zero, i.e. maximally sensitive. Seeding from the first frame instead\n                //    lets someone who talks straight after the wake word install their own voice as\n                //    the room's noise floor, which shuts the gate for good — the same trap an average\n                //    or median over a calibration window falls into.\n                //  - fall instantly, so a room that went quiet is believed at once.\n                //  - rise slowly, and not at all once speech has been recognised: otherwise a long\n                //    utterance drags the floor, and with it `endLevel`, up to its own level and cuts\n                //    itself off mid-sentence. Falling stays on, so the pauses between words still count.\n                this.floor =\n                    this.floor === null\n                        ? 0\n                        : level < this.floor\n                          ? level\n                          : this.speechSeen\n                            ? this.floor\n                            : this.floor + (level - this.floor) * NOISE_RISE;\n                if (this.totalMs < this.warmupMs) {\n                    continue; // let the floor settle before anything may count as speech\n                }\n            }\n\n            if (!this.speechSeen) {\n                if (level >= this.startLevel) {\n                    this.speechSeen = true;\n                    this.silentMs = 0;\n                }\n            } else if (level < this.endLevel) {\n                this.silentMs += this.frameMs;\n                if (this.silentMs >= this.silenceMs) {\n                    verdict ||= 'speech-end';\n                }\n            } else {\n                this.silentMs = 0;\n            }\n\n            if (this.totalMs >= this.maxMs) {\n                verdict ||= 'timeout';\n            }\n        }\n        return verdict;\n    }\n}\n"]}
+{"version":3,"file":"vad.js","sourceRoot":"","sources":["../../../src/lib/voice/vad.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * End-of-speech detection for satellites that stream microphone audio until they are told to stop.\n *\n * The Hannah/UDP protocol has the satellite decide when an utterance ended (`audio_end`), and Wyoming\n * clients send `audio-stop` themselves. ESPHome voice satellites do neither: they keep streaming until\n * the server sends `STT_VAD_END`/`STT_END`, so the decision has to happen here.\n *\n * This is a plain energy gate, not a neural VAD — good enough to close an utterance, and it costs\n * nothing per frame. Speech must first rise above `startLevel`; after that, `silenceMs` worth of frames\n * below `endLevel` ends it. `maxMs` is the hard stop for rooms that are simply loud.\n *\n * Fixed thresholds only work when the microphone level is known, and on a real satellite it is not.\n * Measured on a ThirdReality Voice & Music Assistant: the device plays a wake-acknowledgement chirp\n * into its own microphone that peaks at full scale (RMS ~16000, clipped), while the speech that follows\n * arrives at RMS 358–469 — below the 700 default for `startLevel` and right on the 400 for `endLevel`.\n * That breaks the gate twice over: `sawSpeech` is satisfied by the chirp rather than by any voice, so\n * the \"nothing but speech-free audio\" guard never fires, and half the real speech frames count as\n * silence, so the utterance can be cut off mid-sentence.\n *\n * Hence two opt-in knobs, both enabled by the ESPHome transport:\n *\n * - `skipMs` drops the leading chirp from the *analysis* (never from the audio, which still goes to STT\n *   in full — a fast speaker may already be talking).\n * - `adaptive` derives the thresholds from a tracked noise floor instead of fixed levels. The floor\n *   follows the quietest frame seen (instant down, very slow up), so it settles on room noise even when\n *   someone starts talking immediately — which a mean or median over a calibration window would not.\n */\n\n/**\n * A buffer that may be a view onto any `ArrayBufferLike` — what `Buffer.subarray()` and\n * `Buffer.concat()` hand back. Plain `Buffer` (= `Buffer<ArrayBuffer>`) assigns to it, not the reverse.\n */\nexport type Bytes = Buffer<ArrayBufferLike>;\n\n/** Root-mean-square amplitude (0…32767) of a mono 16-bit signed LE PCM buffer. */\nexport function rms(pcm: Bytes): number {\n    const samples = Math.floor(pcm.length / 2);\n    if (!samples) {\n        return 0;\n    }\n    let sum = 0;\n    for (let i = 0; i < samples; i++) {\n        const value = pcm.readInt16LE(i * 2);\n        sum += value * value;\n    }\n    return Math.sqrt(sum / samples);\n}\n\nexport interface SpeechDetectorOptions {\n    /** Sample rate of the incoming PCM (ESPHome satellites always capture at 16 kHz). */\n    sampleRate?: number;\n    /** Analysis window; 30 ms is the usual compromise between latency and stability. */\n    frameMs?: number;\n    /** RMS above which we consider speech to have started. Ignored when `adaptive` is on. */\n    startLevel?: number;\n    /** RMS below which a frame counts as silence. Ignored when `adaptive` is on. */\n    endLevel?: number;\n    /** Silence after speech that ends the utterance. */\n    silenceMs?: number;\n    /** Hard cap on one utterance, in case the room never falls quiet. */\n    maxMs?: number;\n    /**\n     * Give up when no speech has started this long after the stream began (the skipped lead-in included);\n     * 0 = only {@link maxMs}. A false wake would otherwise keep the microphone open for the whole `maxMs`.\n     */\n    startTimeoutMs?: number;\n    /**\n     * Leading audio to leave out of the analysis — for devices that chirp into their own microphone\n     * when the wake word fires. The audio itself is untouched; this only stops the chirp from being\n     * mistaken for speech and from poisoning the noise floor.\n     */\n    skipMs?: number;\n    /** Derive the thresholds from the tracked noise floor instead of using fixed levels. */\n    adaptive?: boolean;\n    /** Adaptive mode: `startLevel` is at least this, however quiet the room is. */\n    minStartLevel?: number;\n    /** Adaptive mode: `endLevel` is at least this. */\n    minEndLevel?: number;\n    /** Adaptive mode: speech threshold as a multiple of the noise floor. */\n    startFactor?: number;\n    /** Adaptive mode: silence threshold as a multiple of the noise floor. */\n    endFactor?: number;\n    /** Adaptive mode: settle the noise floor this long before speech may be declared. */\n    warmupMs?: number;\n}\n\n/** Why an utterance ended: the speaker stopped, we hit the hard cap, or nobody started speaking at all. */\nexport type SpeechEnd = 'speech-end' | 'timeout' | 'no-speech';\n\n/**\n * How fast the tracked noise floor may follow a *rising* ambient level, per analysed frame (30 ms).\n * Fast enough that a genuinely noisy room is matched within about a second, slow enough that a voice\n * cannot pull the floor up to its own level before it has been recognised as speech.\n */\nconst NOISE_RISE = 0.02;\n\nexport class SpeechDetector {\n    private readonly frameBytes: number;\n    private readonly frameMs: number;\n    private readonly fixedStart: number;\n    private readonly fixedEnd: number;\n    private readonly silenceMs: number;\n    private readonly maxMs: number;\n    private readonly startTimeoutMs: number;\n    private readonly skipMs: number;\n    private readonly adaptive: boolean;\n    private readonly minStartLevel: number;\n    private readonly minEndLevel: number;\n    private readonly startFactor: number;\n    private readonly endFactor: number;\n    private readonly warmupMs: number;\n\n    private pending: Bytes = Buffer.alloc(0);\n    private speechSeen = false;\n    private silentMs = 0;\n    /** Tracked room level in adaptive mode; null until the first analysed frame. */\n    private floor: number | null = null;\n    /** Audio seen so far *including* the skipped lead-in, in milliseconds. */\n    private elapsedMs = 0;\n    /** Audio analysed so far, in milliseconds (exposed for logging). */\n    totalMs = 0;\n    /** Loudest frame seen so far (exposed for logging — the usual clue when a mic is mis-configured). */\n    peak = 0;\n    /**\n     * Loudest frame after the skipped lead-in, i.e. without the wake chirp. Compared with {@link startLevel}\n     * it tells whether a dropped utterance was silence or a voice that was simply too quiet for the gate.\n     */\n    analysedPeak = 0;\n\n    constructor({\n        sampleRate = 16000,\n        frameMs = 30,\n        startLevel = 700,\n        endLevel = 400,\n        silenceMs = 900,\n        maxMs = 12000,\n        startTimeoutMs = 0,\n        skipMs = 0,\n        adaptive = false,\n        minStartLevel = 250,\n        minEndLevel = 150,\n        startFactor = 3.5,\n        endFactor = 2,\n        warmupMs = 150,\n    }: SpeechDetectorOptions = {}) {\n        this.frameBytes = Math.round((sampleRate * frameMs) / 1000) * 2;\n        this.frameMs = frameMs;\n        this.fixedStart = startLevel;\n        this.fixedEnd = endLevel;\n        this.silenceMs = silenceMs;\n        this.maxMs = maxMs;\n        this.startTimeoutMs = startTimeoutMs;\n        this.skipMs = skipMs;\n        this.adaptive = adaptive;\n        this.minStartLevel = minStartLevel;\n        this.minEndLevel = minEndLevel;\n        this.startFactor = startFactor;\n        this.endFactor = endFactor;\n        this.warmupMs = warmupMs;\n    }\n\n    /** True once any frame crossed {@link startLevel} — an utterance that never did is room noise. */\n    get sawSpeech(): boolean {\n        return this.speechSeen;\n    }\n\n    /** Tracked room level (adaptive mode), for logging. 0 before the first analysed frame. */\n    get noiseFloor(): number {\n        return this.floor ?? 0;\n    }\n\n    /** Current speech threshold — fixed, or derived from the noise floor in adaptive mode. */\n    get startLevel(): number {\n        return this.adaptive ? Math.max(this.minStartLevel, (this.floor ?? 0) * this.startFactor) : this.fixedStart;\n    }\n\n    /** Current silence threshold. Never above {@link startLevel}, so the gate keeps its hysteresis. */\n    get endLevel(): number {\n        if (!this.adaptive) {\n            return this.fixedEnd;\n        }\n        return Math.min(this.startLevel, Math.max(this.minEndLevel, (this.floor ?? 0) * this.endFactor));\n    }\n\n    /** Feed one audio chunk (any size). Returns why the utterance ended, or null to keep listening. */\n    push(chunk: Bytes): SpeechEnd | null {\n        this.pending = this.pending.length ? Buffer.concat([this.pending, chunk]) : chunk;\n        let verdict: SpeechEnd | null = null;\n\n        while (this.pending.length >= this.frameBytes) {\n            const frame = this.pending.subarray(0, this.frameBytes);\n            this.pending = this.pending.subarray(this.frameBytes);\n            this.elapsedMs += this.frameMs;\n\n            const level = rms(frame);\n            if (level > this.peak) {\n                this.peak = level;\n            }\n\n            // The device's own wake chirp: loud, clipped, and not speech. Leaving it out of the\n            // analysis is what makes `sawSpeech` mean anything, and keeps the noise floor honest.\n            if (this.elapsedMs <= this.skipMs) {\n                continue;\n            }\n            this.totalMs += this.frameMs;\n            if (level > this.analysedPeak) {\n                this.analysedPeak = level;\n            }\n\n            if (this.adaptive) {\n                // Three rules, each there to defeat a specific way of getting this wrong:\n                //  - start at zero, i.e. maximally sensitive. Seeding from the first frame instead\n                //    lets someone who talks straight after the wake word install their own voice as\n                //    the room's noise floor, which shuts the gate for good — the same trap an average\n                //    or median over a calibration window falls into.\n                //  - fall instantly, so a room that went quiet is believed at once.\n                //  - rise slowly, and not at all once speech has been recognised: otherwise a long\n                //    utterance drags the floor, and with it `endLevel`, up to its own level and cuts\n                //    itself off mid-sentence. Falling stays on, so the pauses between words still count.\n                this.floor =\n                    this.floor === null\n                        ? 0\n                        : level < this.floor\n                          ? level\n                          : this.speechSeen\n                            ? this.floor\n                            : this.floor + (level - this.floor) * NOISE_RISE;\n                if (this.totalMs < this.warmupMs) {\n                    continue; // let the floor settle before anything may count as speech\n                }\n            }\n\n            if (!this.speechSeen) {\n                if (level >= this.startLevel) {\n                    this.speechSeen = true;\n                    this.silentMs = 0;\n                }\n            } else if (level < this.endLevel) {\n                this.silentMs += this.frameMs;\n                if (this.silentMs >= this.silenceMs) {\n                    verdict ||= 'speech-end';\n                }\n            } else {\n                this.silentMs = 0;\n            }\n\n            if (!this.speechSeen && this.startTimeoutMs > 0 && this.elapsedMs >= this.startTimeoutMs) {\n                verdict ||= 'no-speech';\n            }\n            if (this.totalMs >= this.maxMs) {\n                verdict ||= 'timeout';\n            }\n        }\n        return verdict;\n    }\n}\n"]}

package/build/main.js

@@ -67,6 +67,8 @@ const wakeWords_1 = require("./lib/voice/wakeWords");
 const tone_1 = require("./lib/voice/tone");
 const engines_1 = require("./lib/voice/engines");
 const openrouter_1 = require("./lib/voice/openrouter");
+const ttsCache_1 = require("./lib/voice/ttsCache");
+const captures_1 = require("./lib/voice/captures");
 const piAgent_1 = require("./lib/piAgent");
 const systemAi_1 = require("./lib/systemAi");
 /**
@@ -81,6 +83,12 @@ const WEATHER_CTX_TTL = 5 * 60 * 1000;
  * that were added or renamed elsewhere.
  */
 const NLU_DEVICES_TTL_MS = 60_000;
+/**
+ * How long a question of the cloud model about a script keeps the next request of that source with the cloud model
+ * (the reply, e.g. "the kitchen light, every hour", says nothing about a script). As long as pi-agent waits for a
+ * confirmation by text.
+ */
+const SCRIPT_TOPIC_MS = 2 * 60_000;
 /** Default for `localLlmTimeoutSec`: after this the local model is stopped and the next tier answers. */
 const LOCAL_LLM_TIMEOUT_SEC = 15;
 /**
@@ -93,6 +101,8 @@ const LOCAL_LLM_MAX_TOKENS = 256;
  * the TTS cache at startup; everything else is cached on first use.
  */
 /** Fields of the Voice tab the voice test takes from the unsaved form (everything an STT or TTS engine is built from). */
+/** Transports whose answer is spoken by a satellite (and therefore cut at `ttsMaxChars`). */
+const VOICE_TRANSPORTS = new Set(['esphome', 'udp', 'native', 'wyoming']);
 const VOICE_FORM_FIELDS = [
     'voiceLanguage',
     'sttProvider',
@@ -644,6 +654,7 @@ class Assistant extends adapter_core_1.Adapter {
                 this.updateSatelliteControl(device, room, entity).catch(e => this.log.debug(`satellite control update failed: ${e.message}`));
             },
             expectsFollowUp: (answer, device) => this.followUpFor(device, answer),
+            onDiscarded: cfg.esphomeSaveCaptures ? capture => this.keepCapture(capture) : undefined,
             externalWakeWords: () => [...this.customWakeWords.values()].map(w => ({
                 id: w.id,
                 phrase: w.phrase,
@@ -680,6 +691,7 @@ class Assistant extends adapter_core_1.Adapter {
             openrouterSttModel: (cfg.openrouterSttModel || '').trim(),
             openrouterTtsModel: (cfg.openrouterTtsModel || '').trim(),
             decodeAudio: audio => this.decodeAudioBufferToPcm(audio),
+            ttsMaxChars: (0, ttsCache_1.parseTtsMaxChars)(cfg.ttsMaxChars),
         };
     }
     /**
@@ -863,6 +875,8 @@ class Assistant extends adapter_core_1.Adapter {
             const sttStart = Date.now();
             const text = (await engines.stt.transcribe(pcm, rate, language, await this.buildSttHints())).trim();
             if (!text) {
+                const ms = Math.round((pcm.length / 2 / rate) * 1000);
+                this.log.info(`Voice Q (${source}): (empty) — speech recognition returned no text for ${ms} ms of audio`);
                 return { text: '', answer: '' };
             }
             const answer = await this.answerVoice(text, source, {
@@ -1112,6 +1126,32 @@ class Assistant extends adapter_core_1.Adapter {
             ack: true,
         });
     }
+    /** Store for `esphomeSaveCaptures`, in the adapter's file storage (Admin → Files → assistant.N/captures). */
+    captureStore = null;
+    /** Keep a dropped ESPHome recording for diagnosis (`esphomeSaveCaptures`). Never blocks the voice pipeline. */
+    keepCapture(capture) {
+        this.captureStore ||= new captures_1.CaptureStore({
+            write: async (path, data) => {
+                await this.writeFileAsync(this.namespace, path, data);
+            },
+            list: async (dir) => {
+                try {
+                    const entries = await this.readDirAsync(this.namespace, dir);
+                    return entries.filter(e => !e.isDir).map(e => e.file);
+                }
+                catch {
+                    return []; // nothing kept yet
+                }
+            },
+            remove: async (path) => {
+                await this.delFileAsync(this.namespace, path);
+            },
+        });
+        this.captureStore
+            .save(capture)
+            .then(path => this.log.debug(`ESPHome ${capture.device}: recording kept as ${this.namespace}/${path}`))
+            .catch(e => this.log.warn(`Could not keep the recording of ${capture.device}: ${e.message}`));
+    }
     /** Read the uploaded wake words (`<instance>/wakewords/<id>.json` + `.tflite`) once. */
     loadCustomWakeWords() {
         this.customWakeWordsLoaded ||= (async () => {
@@ -2667,7 +2707,8 @@ class Assistant extends adapter_core_1.Adapter {
      * later turns have the full thread.
      */
     answer(question, source = '', origin = {}) {
-        return this.requestOrigin.run({ source, room: origin.room || '' }, () => this.journal
+        const voice = VOICE_TRANSPORTS.has(origin.transport || '');
+        return this.requestOrigin.run({ source, room: origin.room || '', voice }, () => this.journal
             ? this.journal.run(question, source, origin, () => {
                 this.traceSpeechInput(question, origin);
                 return this.answerTracked(question, source);
@@ -2709,12 +2750,20 @@ class Assistant extends adapter_core_1.Adapter {
                 data: history,
             });
         }
-        const raw = await this.produceAnswer(question, history, source);
+        const cloudOnly = this.cloudOnlyReason(question, source);
+        const raw = await this.produceAnswer(question, history, source, cloudOnly);
         // The LLM signals "I'm waiting for the user's reply" by appending the [[LISTEN]] control marker
         // (see followUpHint). Strip it here so it's neither stored, shown nor spoken, and keep it per source:
         // two satellites answered at the same time must not hand each other their mic-on.
         const followUp = /\[\[LISTEN\]\]/i.test(raw);
         this.followUps.set(source, followUp);
+        // A script conversation goes on while the cloud model asks back: the reply goes to it as well.
+        if (cloudOnly && followUp) {
+            this.scriptTopics.set(source, Date.now());
+        }
+        else {
+            this.scriptTopics.delete(source);
+        }
         if (followUp) {
             this.journal?.note({ followUp: true });
         }
@@ -2759,6 +2808,18 @@ class Assistant extends adapter_core_1.Adapter {
         }
         return 'If the request was only a command to switch devices on or off or to set them to a value, and everything worked, answer with the control marker [[DONE]] alone (a short beep plays instead of a sentence). For questions, errors or when you have something to tell, answer normally.';
     }
+    /**
+     * Length instruction for a request that came in by voice: the answer is cut at `ttsMaxChars` before it is
+     * spoken, so the model is asked to stay within it. Empty for text requests (chat, Telegram, scripts) and
+     * when the limit is off.
+     */
+    spokenLengthHint() {
+        if (!this.config.voiceEnabled || !this.requestOrigin.getStore()?.voice) {
+            return '';
+        }
+        const limit = (0, ttsCache_1.parseTtsMaxChars)(this.config.ttsMaxChars) ?? ttsCache_1.MAX_TTS_CHARS;
+        return (0, ttsCache_1.spokenLengthHint)(limit, String(this.config.voiceLanguage || this.language || 'en'));
+    }
     /** What [[DONE]] says where no beep can be played */
     doneText() {
         const lang = String(this.config.voiceLanguage || this.language || 'en');
@@ -2766,6 +2827,24 @@ class Assistant extends adapter_core_1.Adapter {
     }
     /** Per source: whether its last {@link answer} asked the user something (LLM-signalled via [[LISTEN]]). */
     followUps = new Map();
+    /** Per source: when the cloud model last asked back about a script (see {@link cloudOnlyReason}). */
+    scriptTopics = new Map();
+    /**
+     * Whether a request skips routines, YouTube, the rule NLU and the local model: when it is about a script, or answers
+     * a question the cloud model asked about one. Writing or changing a script is work for the cloud model, and the
+     * rules would read its details as commands of their own ("… that switches the kitchen light every hour" was answered
+     * with the time). Without a cloud tier the local ones are all there is, so nothing is skipped.
+     */
+    cloudOnlyReason(question, source) {
+        if (!this.agent && !this.piAgent) {
+            return null;
+        }
+        if ((0, nlu_1.mentionsScript)(question)) {
+            return 'script';
+        }
+        const since = this.scriptTopics.get(source);
+        return since !== undefined && Date.now() - since < SCRIPT_TOPIC_MS ? 'scriptReply' : null;
+    }
     /**
      * Should the satellite behind `source` re-open its mic after this reply? Primarily the LLM's own
      * [[LISTEN]] signal, with a question mark in the reply as the fallback (the NLU and the local tiers
@@ -2856,7 +2935,72 @@ class Assistant extends adapter_core_1.Adapter {
         const time = new Intl.DateTimeFormat(locale, { hour: '2-digit', minute: '2-digit' }).format(now);
         return lang === 'ru' ? `Сейчас ${time}.` : lang === 'de' ? `Es ist ${time} Uhr.` : `It's ${time}.`;
     }
-    async produceAnswer(question, history, source = '') {
+    /**
+     * The tiers that answer without a model: routines, YouTube and the rule NLU. Null when none of them understood the
+     * request.
+     */
+    async answerLocally(question, source) {
+        // A routine is a macro the user wrote down, so it wins over everything that interprets: the NLU
+        // would find "Licht" in "Gute Nacht, Licht aus" and do half of it, and the LLM would cost a
+        // round-trip for a decision that has already been made.
+        const routine = (0, routines_1.matchRoutine)(question, this.routines);
+        if (routine) {
+            this.log.info(`Routine '${routine.name}' triggered (source='${source}').`);
+            this.journal?.note({ tier: 'routine', detail: routine.name });
+            this.journal?.step({ stage: 'routine', title: `Routine "${routine.name}" matched`, data: routine });
+            await this.runRoutine(routine, source);
+            return routine.reply;
+        }
+        if (this.routines.length) {
+            this.journal?.step({
+                stage: 'routine',
+                title: `No routine matched (${this.routines.length} configured)`,
+                data: { phrases: this.routines.map(r => ({ name: r.name, phrases: r.phrases })) },
+            });
+        }
+        // Tier 0: rule-based NLU (device commands) — fastest, offline, free.
+        if (!this.config.useLocalNlu) {
+            this.journal?.step({ stage: 'nlu', title: 'Rule-based NLU is switched off (useLocalNlu)' });
+            return null;
+        }
+        // "Spiele den Kanal X ab" first: the device NLU would find the TV in "… auf dem Fernseher" and
+        // answer with its power state.
+        const yt = this.youtubePlayers.length ? (0, youtube_1.parseYouTubeCommand)(question, this.youtubePlayers) : null;
+        if (yt) {
+            this.log.info(`YouTube request understood locally: ${yt.kind} "${yt.query}" (source='${source}').`);
+            this.journal?.note({ tier: 'nlu', detail: `youtube ${yt.kind}` });
+            const start = Date.now();
+            const res = await this.playYouTube(yt.query, yt.kind, yt.player);
+            this.journal?.step({
+                stage: 'youtube',
+                title: `YouTube ${yt.kind} "${yt.query}"${yt.player ? ` on "${yt.player}"` : ''}`,
+                ms: Date.now() - start,
+                data: { parsed: yt, result: res },
+            });
+            return res.text;
+        }
+        if (this.youtubePlayers.length) {
+            this.journal?.step({ stage: 'youtube', title: 'Not a YouTube command' });
+        }
+        try {
+            const handled = await this.tryLocalNlu(question, source);
+            if (handled !== null) {
+                this.log.info(`Answered by rule-based NLU (source='${source}').`);
+                return handled;
+            }
+        }
+        catch (e) {
+            this.log.debug(`NLU skipped: ${e.message}`);
+            this.journal?.step({
+                stage: 'nlu',
+                level: 'warn',
+                title: `NLU gave up, the request goes on: ${e.message}`,
+                data: (0, journal_1.errorInfo)(e),
+            });
+        }
+        return null;
+    }
+    async produceAnswer(question, history, source = '', cloudOnly = null) {
         this.log.debug(`answer: source='${source}', context=${history.length} turn(s)`);
         // A ringing timer/alarm is silenced by a stop word ("stop"/"halt"/"aufhören"/…) — checked first so
         // it always wins over the normal pipeline while something is ringing.
@@ -2884,64 +3028,22 @@ class Assistant extends adapter_core_1.Adapter {
                 return '';
             }
         }
-        // A routine is a macro the user wrote down, so it wins over everything that interprets: the NLU
-        // would find "Licht" in "Gute Nacht, Licht aus" and do half of it, and the LLM would cost a
-        // round-trip for a decision that has already been made.
-        const routine = (0, routines_1.matchRoutine)(question, this.routines);
-        if (routine) {
-            this.log.info(`Routine '${routine.name}' triggered (source='${source}').`);
-            this.journal?.note({ tier: 'routine', detail: routine.name });
-            this.journal?.step({ stage: 'routine', title: `Routine "${routine.name}" matched`, data: routine });
-            await this.runRoutine(routine, source);
-            return routine.reply;
-        }
-        if (this.routines.length) {
+        if (cloudOnly) {
+            const why = cloudOnly === 'script'
+                ? 'it is about a script'
+                : 'it answers a question of the cloud model about a script';
+            this.log.info(`Routines, NLU and local LLM skipped (source='${source}'): ${why}.`);
             this.journal?.step({
-                stage: 'routine',
-                title: `No routine matched (${this.routines.length} configured)`,
-                data: { phrases: this.routines.map(r => ({ name: r.name, phrases: r.phrases })) },
+                stage: 'nlu',
+                title: `Routines, NLU and local LLM skipped: ${why}`,
+                data: { reason: cloudOnly },
             });
         }
-        // Tier 0: rule-based NLU (device commands) — fastest, offline, free.
-        if (this.config.useLocalNlu) {
-            // "Spiele den Kanal X ab" first: the device NLU would find the TV in "… auf dem Fernseher" and
-            // answer with its power state.
-            const yt = this.youtubePlayers.length ? (0, youtube_1.parseYouTubeCommand)(question, this.youtubePlayers) : null;
-            if (yt) {
-                this.log.info(`YouTube request understood locally: ${yt.kind} "${yt.query}" (source='${source}').`);
-                this.journal?.note({ tier: 'nlu', detail: `youtube ${yt.kind}` });
-                const start = Date.now();
-                const res = await this.playYouTube(yt.query, yt.kind, yt.player);
-                this.journal?.step({
-                    stage: 'youtube',
-                    title: `YouTube ${yt.kind} "${yt.query}"${yt.player ? ` on "${yt.player}"` : ''}`,
-                    ms: Date.now() - start,
-                    data: { parsed: yt, result: res },
-                });
-                return res.text;
-            }
-            if (this.youtubePlayers.length) {
-                this.journal?.step({ stage: 'youtube', title: 'Not a YouTube command' });
-            }
-            try {
-                const handled = await this.tryLocalNlu(question, source);
-                if (handled !== null) {
-                    this.log.info(`Answered by rule-based NLU (source='${source}').`);
-                    return handled;
-                }
-            }
-            catch (e) {
-                this.log.debug(`NLU skipped: ${e.message}`);
-                this.journal?.step({
-                    stage: 'nlu',
-                    level: 'warn',
-                    title: `NLU gave up, the request goes on: ${e.message}`,
-                    data: (0, journal_1.errorInfo)(e),
-                });
-            }
-        }
         else {
-            this.journal?.step({ stage: 'nlu', title: 'Rule-based NLU is switched off (useLocalNlu)' });
+            const local = await this.answerLocally(question, source);
+            if (local !== null) {
+                return local;
+            }
         }
         // Current weather from the configured adapter — prepended to the user turn of BOTH LLM tiers so
         // "how's the weather?" is answered from real data (the local model has no tools and would otherwise
@@ -2955,7 +3057,8 @@ class Assistant extends adapter_core_1.Adapter {
         // so it would answer a follow-up like "yes" context-free and swallow it — let the cloud LLM (which has
         // the thread and the tools) handle follow-ups instead. Without a cloud LLM there is nobody to hand
         // follow-ups to, so the local model takes them too.
-        const useLocal = !!(this.config.useLocalLlm && this.localLlm);
+        // A script request does not even fall back to it: a model without tools cannot write a script.
+        const useLocal = !cloudOnly && !!(this.config.useLocalLlm && this.localLlm);
         const cloud = !!(this.agent || this.piAgent);
         const localFirst = useLocal && (!cloud || !!this.config.localLlmFirst);
         if (localFirst && (!history.length || !cloud)) {
@@ -3003,9 +3106,12 @@ class Assistant extends adapter_core_1.Adapter {
         const sys = parts.length ? parts.join('\n\n') : undefined;
         this.log.info(`Cloud LLM [${this.agent.model || 'auto'}] (source='${source}', context=${history.length} turn(s)${mem ? ', memory' : ''}${weather ? ', weather' : ''}${this.presence?.configured ? ', presence' : ''}) — running tool loop…`);
         // Prepend the current date/time (and the weather line, if a source is configured) to the user turn —
-        // cache-safe, see buildTimeContext. The stored history keeps the untouched question.
+        // cache-safe, see buildTimeContext. The stored history keeps the untouched question. A spoken request
+        // also gets the length limit, after the question: in the system prompt it would bust the prompt cache
+        // every time voice and text requests alternate.
         const time = this.buildTimeContext();
-        const questionForLlm = [time, weather, question].filter(Boolean).join('\n\n');
+        const lengthHint = this.spokenLengthHint();
+        const questionForLlm = [time, weather, question, lengthHint].filter(Boolean).join('\n\n');
         this.journal?.note({
             tier: 'cloud',
             detail: `${this.llm?.provider || this.config.provider || 'openai'} · ${this.agent.model || 'auto'}`,
@@ -3015,11 +3121,12 @@ class Assistant extends adapter_core_1.Adapter {
         const deviceLines = ctx ? ctx.split('\n').length - 1 : 0;
         this.journal?.step({
             stage: 'context',
-            title: `Prompt: ${deviceLines} devices${mem ? ', memory' : ''}${weather ? ', weather' : ''}${followUp ? ', follow-up marker' : ''}`,
+            title: `Prompt: ${deviceLines} devices${mem ? ', memory' : ''}${weather ? ', weather' : ''}${followUp ? ', follow-up marker' : ''}${lengthHint ? ', length limit' : ''}`,
             data: {
                 systemPrompt: this.config.systemPrompt || '',
                 followUpHint: followUp || undefined,
                 doneHint: done || undefined,
+                lengthHint: lengthHint || undefined,
                 memory: mem || undefined,
                 devices: deviceLines,
                 time,
@@ -3056,7 +3163,7 @@ class Assistant extends adapter_core_1.Adapter {
         const followUp = this.config.voiceEnabled ? this.followUpHint() : '';
         // The device list maps names to state ids, so pi-agent can act without searching first. It is the
         // first to go when the instructions get too long — pi-agent can still search.
-        const { text: instructions, dropped } = (0, piAgent_1.composeInstructions)([this.config.systemPrompt || '', followUp, this.doneHint()], [this.buildMemoryContext(), await this.buildDeviceContext()]);
+        const { text: instructions, dropped } = (0, piAgent_1.composeInstructions)([this.config.systemPrompt || '', followUp, this.doneHint(), this.spokenLengthHint()], [this.buildMemoryContext(), await this.buildDeviceContext()]);
         if (dropped) {
             this.log.debug(`pi-agent: ${dropped} context block(s) left out, the instructions would be too long.`);
         }
@@ -3066,7 +3173,10 @@ class Assistant extends adapter_core_1.Adapter {
         this.log.info(`Cloud tier ${harness.instance} (source='${source}') — asking pi-agent…`);
         this.journal?.note({ tier: 'cloud', detail: harness.instance });
         try {
-            return await harness.ask({ text, conversation: source, instructions });
+            // pi-agent asks its questions to confirm a write ("… Say yes or no.") in this language, not in the system
+            // language: a satellite listening in Russian does not hear a German "Ja"
+            const language = String(this.config.voiceLanguage || this.language || '');
+            return await harness.ask({ text, conversation: source, instructions, language });
         }
         catch (e) {
             if (localFallback) {