@qvac/tts-ggml 0.13.0 → 0.14.0

package/lib/sentenceStream.js

@@ -0,0 +1,367 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentenceStreamer = void 0;
+exports.normalizeError = normalizeError;
+exports.ttsOutputDebugString = ttsOutputDebugString;
+exports.isAudioOutputEvent = isAudioOutputEvent;
+exports.isStatsEvent = isStatsEvent;
+exports.emptyStreamAccumulator = emptyStreamAccumulator;
+exports.computeSentenceStreamStats = computeSentenceStreamStats;
+exports.resolveRunStreamingOptions = resolveRunStreamingOptions;
+exports.normalizeTextStream = normalizeTextStream;
+exports.requireStreamOutputText = requireStreamOutputText;
+exports.splitSentenceChunks = splitSentenceChunks;
+const error_1 = require("./error");
+const textChunker_1 = require("./textChunker");
+const textStreamAccumulator_1 = require("./textStreamAccumulator");
+function normalizeError(error) {
+    return typeof error === "string"
+        ? error
+        : error instanceof Error
+            ? error
+            : new Error("Unknown TTS error");
+}
+function defaultAccumulateSentencesForStreamInput(textStream) {
+    if (textStream == null ||
+        typeof textStream === "string" ||
+        Array.isArray(textStream)) {
+        return false;
+    }
+    return (typeof textStream[Symbol.asyncIterator] === "function");
+}
+function ttsOutputDebugString(data) {
+    if (!data)
+        return "";
+    if (typeof data === "string")
+        return data;
+    if (typeof data === "number" ||
+        typeof data === "boolean" ||
+        typeof data === "bigint") {
+        return data.toString();
+    }
+    if (typeof data === "symbol")
+        return data.description || "";
+    if (typeof data === "function")
+        return data.name;
+    const value = data;
+    const summary = {};
+    if (value.sampleRate != null)
+        summary.sampleRate = value.sampleRate;
+    if (value.chunkIndex != null)
+        summary.chunkIndex = value.chunkIndex;
+    if (value.isLast != null)
+        summary.isLast = value.isLast;
+    if (value.sentenceChunk != null) {
+        summary.sentenceChunk = value.sentenceChunk;
+    }
+    if (value.outputArray &&
+        typeof value.outputArray.length === "number") {
+        summary.outputArrayLen = value.outputArray.length;
+    }
+    return JSON.stringify(summary);
+}
+function isAudioOutputEvent(data) {
+    return (data != null &&
+        typeof data === "object" &&
+        "outputArray" in data &&
+        data.outputArray != null);
+}
+function isStatsEvent(data) {
+    return (data != null &&
+        typeof data === "object" &&
+        ("totalTime" in data ||
+            "audioDurationMs" in data ||
+            "totalSamples" in data));
+}
+/**
+ * What `tokensPerSecond` counts. Audio8 paces on the codec frame grid and
+ * reports frames per second in batch synthesis; the text-paced engines report
+ * characters per second. Streaming has to keep the same unit as `run()` or the
+ * number silently changes meaning between the two entry points.
+ */
+function emptyStreamAccumulator() {
+    return {
+        totalTime: 0,
+        audioDurationMs: 0,
+        totalSamples: 0,
+        generatedFrames: 0,
+    };
+}
+function streamedTokenCount(chunks, accumulator, countsFrames) {
+    return countsFrames
+        ? accumulator.generatedFrames
+        : chunks.join("").length;
+}
+function computeSentenceStreamStats(chunks, accumulator, countsFrames) {
+    const { generatedFrames, ...totals } = accumulator;
+    const produced = streamedTokenCount(chunks, accumulator, countsFrames);
+    const stats = {
+        ...totals,
+        tokensPerSecond: accumulator.totalTime > 0 ? produced / accumulator.totalTime : 0,
+        realTimeFactor: accumulator.audioDurationMs > 0
+            ? (accumulator.totalTime * 1000) /
+                accumulator.audioDurationMs
+            : 0,
+    };
+    if (countsFrames)
+        stats.generatedFrames = generatedFrames;
+    return stats;
+}
+function emptyRuntimeStats() {
+    return {
+        totalTime: 0,
+        tokensPerSecond: 0,
+        realTimeFactor: 0,
+        audioDurationMs: 0,
+        totalSamples: 0,
+    };
+}
+function resolveRunStreamingOptions(textStream, options) {
+    const normalized = options == null || typeof options !== "object" ? {} : options;
+    let accumulateSentences = normalized.accumulateSentences;
+    if (accumulateSentences === undefined) {
+        accumulateSentences =
+            defaultAccumulateSentencesForStreamInput(textStream);
+    }
+    return {
+        accumulateSentences: !!accumulateSentences,
+        sentenceDelimiterPreset: normalized.sentenceDelimiterPreset === "latin" ||
+            normalized.sentenceDelimiterPreset === "cjk" ||
+            normalized.sentenceDelimiterPreset === "multilingual"
+            ? normalized.sentenceDelimiterPreset
+            : "multilingual",
+        maxBufferScalars: normalized.maxBufferScalars,
+        flushAfterMs: normalized.flushAfterMs ?? textStreamAccumulator_1.DEFAULT_FLUSH_AFTER_MS,
+        sentenceDelimiter: normalized.sentenceDelimiter instanceof RegExp
+            ? normalized.sentenceDelimiter
+            : undefined,
+    };
+}
+function normalizeTextStream(textStream) {
+    if (textStream == null) {
+        throw new error_1.QvacErrorAddonTTSGgml({
+            code: error_1.ERR_CODES.FAILED_TO_APPEND,
+            adds: "runStreaming: text stream is required",
+        });
+    }
+    if (typeof textStream === "string") {
+        // eslint-disable-next-line @typescript-eslint/require-await -- async iterable shape is required by the public API.
+        return (async function* oneString() {
+            yield textStream;
+        })();
+    }
+    if (typeof textStream[Symbol.asyncIterator] === "function") {
+        return textStream;
+    }
+    if (Array.isArray(textStream) ||
+        typeof textStream[Symbol.iterator] === "function") {
+        // eslint-disable-next-line @typescript-eslint/require-await -- adapts synchronous iterables to the async iterable contract.
+        return (async function* fromIterable() {
+            for (const value of textStream) {
+                yield value;
+            }
+        })();
+    }
+    throw new error_1.QvacErrorAddonTTSGgml({
+        code: error_1.ERR_CODES.FAILED_TO_APPEND,
+        adds: "runStreaming: expected string, array of strings, Iterable, or AsyncIterable",
+    });
+}
+/** `run({ streamOutput: true })` splits its text, so it needs a non-empty string. */
+function requireStreamOutputText(input) {
+    if (typeof input !== "string" || input.trim().length === 0) {
+        throw new error_1.QvacErrorAddonTTSGgml({
+            code: error_1.ERR_CODES.FAILED_TO_APPEND,
+            adds: "run with streamOutput: non-empty string `input` is required",
+        });
+    }
+    return input;
+}
+/** The sentence chunks of `text`; an input that yields none is an error. */
+function splitSentenceChunks(text, options, language) {
+    const chunks = (0, textChunker_1.splitTtsText)(String(text), {
+        language,
+        locale: options.locale,
+        maxScalars: options.maxChunkScalars,
+    });
+    if (chunks.length === 0) {
+        throw new error_1.QvacErrorAddonTTSGgml({
+            code: error_1.ERR_CODES.FAILED_TO_APPEND,
+            adds: "chunked synthesis: text produced no chunks after split",
+        });
+    }
+    return chunks;
+}
+function mergeSentenceStreamStats(accumulator, data) {
+    if (accumulator.firstAudioMs === undefined &&
+        typeof data.firstAudioMs === "number" &&
+        Number.isFinite(data.firstAudioMs) &&
+        data.firstAudioMs >= 0) {
+        accumulator.firstAudioMs = data.firstAudioMs;
+    }
+    accumulator.totalTime +=
+        typeof data.totalTime === "number" ? data.totalTime : 0;
+    accumulator.audioDurationMs +=
+        typeof data.audioDurationMs === "number"
+            ? data.audioDurationMs
+            : 0;
+    accumulator.totalSamples +=
+        typeof data.totalSamples === "number" ? data.totalSamples : 0;
+    accumulator.generatedFrames +=
+        typeof data.generatedFrames === "number" ? data.generatedFrames : 0;
+    if (typeof data.codecSidecarLoaded === "number") {
+        accumulator.codecSidecarLoaded = data.codecSidecarLoaded;
+    }
+    if (typeof data.codecOnCoreml === "number") {
+        accumulator.codecOnCoreml = data.codecOnCoreml;
+    }
+}
+/**
+ * Drives one sentence stream at a time. The wrapper routes native output and
+ * stats events here while a context is active; a newer stream, a cancel or a
+ * reload replaces or clears the context, and the driver of the old stream
+ * notices and stops.
+ */
+class SentenceStreamer {
+    host;
+    /** The active stream, or null between streams. */
+    ctx = null;
+    constructor(host) {
+        this.host = host;
+    }
+    streamChunks(chunks, jobFields) {
+        const response = this.host.startJob();
+        const context = {
+            chunks,
+            chunkIdx: 0,
+            acc: emptyStreamAccumulator(),
+            chunkResolver: null,
+            jobFields,
+        };
+        this.ctx = context;
+        void this.driveChunks(context).catch((error) => this.abort(context, error));
+        return response;
+    }
+    streamText(source, jobFields) {
+        const response = this.host.startJob();
+        const context = {
+            textStreamMode: true,
+            asyncTextSource: source,
+            chunks: [],
+            chunkIdx: 0,
+            acc: emptyStreamAccumulator(),
+            chunkResolver: null,
+            jobFields,
+        };
+        this.ctx = context;
+        void this.driveText(context, source).catch((error) => this.abort(context, error));
+        return response;
+    }
+    rejectActiveChunk(error) {
+        const resolver = this.ctx?.chunkResolver;
+        if (!resolver)
+            return;
+        this.ctx.chunkResolver = null;
+        resolver.reject(error);
+    }
+    fail(reason) {
+        this.rejectActiveChunk(reason instanceof Error ? reason : new Error(reason));
+        this.ctx = null;
+        this.host.failJob(reason);
+    }
+    enrich(data) {
+        const context = this.ctx;
+        if (!context) {
+            return data;
+        }
+        const index = context.chunkIdx;
+        const enriched = {
+            outputArray: data.outputArray,
+            chunkIndex: index,
+            sentenceChunk: context.chunks[index] || "",
+        };
+        if (data.sampleRate != null) {
+            enriched.sampleRate = data.sampleRate;
+        }
+        if (!context.textStreamMode) {
+            enriched.isLast = index >= context.chunks.length - 1 && data.isLast !== false;
+        }
+        return enriched;
+    }
+    /**
+     * Folds a chunk's stats into the aggregate and releases the chunk; after the
+     * last pre-chunked sentence, ends the job. Returns false when no stream is
+     * active, so the caller can end a plain job with the stats as they are.
+     */
+    onStats(data) {
+        const context = this.ctx;
+        if (!context)
+            return false;
+        mergeSentenceStreamStats(context.acc, data);
+        if (context.chunkResolver) {
+            context.chunkResolver.resolve();
+            context.chunkResolver = null;
+        }
+        if (!context.textStreamMode &&
+            context.chunkIdx >= context.chunks.length - 1) {
+            this.host.endJob(computeSentenceStreamStats(context.chunks, context.acc, this.host.countsFrames()));
+        }
+        return true;
+    }
+    abort(context, error) {
+        if (context !== this.ctx)
+            return;
+        this.rejectActiveChunk(error);
+        this.ctx = null;
+        this.host.failJob(normalizeError(error));
+    }
+    async driveChunks(context) {
+        for (let index = 0; index < context.chunks.length; index++) {
+            if (context !== this.ctx)
+                return;
+            context.chunkIdx = index;
+            await this.synthesizeChunk(context, context.chunks[index]);
+        }
+        if (context !== this.ctx)
+            return;
+        this.ctx = null;
+    }
+    async driveText(context, source) {
+        try {
+            for await (const piece of source) {
+                if (context !== this.ctx)
+                    return;
+                const text = String(piece).trim();
+                if (text.length === 0)
+                    continue;
+                context.chunks.push(text);
+                context.chunkIdx = context.chunks.length - 1;
+                await this.synthesizeChunk(context, text);
+            }
+        }
+        catch (error) {
+            this.abort(context, error);
+            return;
+        }
+        if (context !== this.ctx)
+            return;
+        this.ctx = null;
+        this.host.endJob(context.chunks.length === 0
+            ? emptyRuntimeStats()
+            : computeSentenceStreamStats(context.chunks, context.acc, this.host.countsFrames()));
+    }
+    async synthesizeChunk(context, text) {
+        const done = new Promise((resolve, reject) => {
+            context.chunkResolver = { resolve, reject };
+        });
+        // Dispatch may fail before the completion promise is awaited.
+        void done.catch(() => { });
+        await this.host.dispatchJob({
+            type: "text",
+            input: text,
+            ...(context.jobFields ?? {}),
+        });
+        await done;
+    }
+}
+exports.SentenceStreamer = SentenceStreamer;

package/lib/setup.d.ts

@@ -0,0 +1,7 @@
+import type { EngineSetup } from "./engineSetup";
+import type { TTSGgmlOptions } from "./types";
+export declare function resolveDefaultLazySessionLoading(lazySessionLoading?: boolean): boolean;
+export declare function validateOutputSampleRate(outputSampleRate?: number): number | null;
+export declare function assertGpuIntentConsistent(useGPU?: boolean, nGpuLayers?: number): void;
+/** Resolve and validate everything the constructor derives from `options`. */
+export declare function resolveEngineSetup(options: TTSGgmlOptions): EngineSetup;

package/lib/setup.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDefaultLazySessionLoading = resolveDefaultLazySessionLoading;
+exports.validateOutputSampleRate = validateOutputSampleRate;
+exports.assertGpuIntentConsistent = assertGpuIntentConsistent;
+exports.resolveEngineSetup = resolveEngineSetup;
+/**
+ * Turns constructor options into an `EngineSetup`: normalized files, the
+ * detected engine and its model paths, synthesis settings, backend paths, and
+ * (for Pocket) the native parameters, validated in the order the wrapper has
+ * always reported them.
+ */
+/* eslint-disable @typescript-eslint/no-require-imports -- Bare modules expose CommonJS export shapes. */
+const bareOs = require("bare-os");
+/* eslint-enable @typescript-eslint/no-require-imports */
+const engineDetection_1 = require("./engineDetection");
+const engineIds_1 = require("./engineIds");
+const cosyvoice_1 = require("./engines/cosyvoice");
+const moss_1 = require("./engines/moss");
+const modelFiles_1 = require("./modelFiles");
+const optionValidation_1 = require("./optionValidation");
+const pocketConfig_1 = require("./pocketConfig");
+const { platform } = bareOs;
+const MIN_OUTPUT_SAMPLE_RATE = 8000;
+const MAX_OUTPUT_SAMPLE_RATE = 192000;
+function resolveDefaultLazySessionLoading(lazySessionLoading) {
+    if (lazySessionLoading != null)
+        return lazySessionLoading;
+    return platform() === "ios" || platform() === "android";
+}
+function validateOutputSampleRate(outputSampleRate) {
+    if (outputSampleRate == null)
+        return null;
+    if (outputSampleRate < MIN_OUTPUT_SAMPLE_RATE ||
+        outputSampleRate > MAX_OUTPUT_SAMPLE_RATE) {
+        throw new Error(`outputSampleRate must be between ${MIN_OUTPUT_SAMPLE_RATE} and ` +
+            `${MAX_OUTPUT_SAMPLE_RATE}, got ${outputSampleRate}`);
+    }
+    return outputSampleRate;
+}
+function resolveEnhancerGgufPath(files, enhancer) {
+    if (enhancer != null && enhancer.type !== "lavasr") {
+        throw new Error(`tts-ggml: unknown enhancer.type '${String(enhancer.type)}', expected 'lavasr'.`);
+    }
+    return (0, modelFiles_1.firstNonEmpty)(files.lavasrEnhancer, enhancer?.enhancerPath);
+}
+function resolveDenoiserGgufPath(files, denoiser) {
+    if (denoiser != null && denoiser.type !== "lavasr") {
+        throw new Error(`tts-ggml: unknown denoiser.type '${String(denoiser.type)}', expected 'lavasr'.`);
+    }
+    return (0, modelFiles_1.firstNonEmpty)(files.lavasrDenoiser, denoiser?.denoiserPath);
+}
+function assertGpuIntentConsistent(useGPU, nGpuLayers) {
+    if (typeof useGPU !== "boolean" || nGpuLayers == null)
+        return;
+    if (useGPU === (nGpuLayers !== 0))
+        return;
+    throw new Error(`tts-ggml: useGPU=${String(useGPU)} conflicts with ` +
+        `nGpuLayers=${nGpuLayers}. Either drop one of the two, or make ` +
+        "them agree (useGPU:true + nGpuLayers!=0, or " +
+        "useGPU:false + nGpuLayers=0).");
+}
+/** Synthesis options with their aliases collapsed; may throw on a malformed `instruct`. */
+function settingsFromOptions(options) {
+    return {
+        referenceAudio: options.referenceAudio,
+        referenceText: options.referenceText,
+        greedy: options.greedy,
+        voiceDir: options.voiceDir,
+        seed: options.seed,
+        nGpuLayers: options.nGpuLayers,
+        nCtx: options.nCtx,
+        kvCacheType: options.kvCacheType,
+        threads: options.threads,
+        streamChunkTokens: options.streamChunkTokens,
+        streamFirstChunkTokens: options.streamFirstChunkTokens,
+        streamChunkTolerancePct: options.streamChunkTolerancePct,
+        streamMinChunkTokens: options.streamMinChunkTokens,
+        streamLeftContextTokens: options.streamLeftContextTokens,
+        cfmSteps: options.cfmSteps,
+        cfgRate: options.cfgRate,
+        batchCfmSteps: options.batchCfmSteps,
+        nPredict: options.nPredict,
+        maxSentenceChars: options.maxSentenceChars,
+        crossfadeMs: options.crossfadeMs,
+        repeatPenalty: options.repeatPenalty,
+        exaggeration: options.exaggeration,
+        cfgWeight: options.cfgWeight,
+        minP: options.minP,
+        voiceJsonPath: options.voiceJsonPath,
+        prewarmText: options.prewarmText,
+        vulkanDevice: options.vulkanDevice,
+        flowCutPrompt: options.flowCutPrompt,
+        promptText: options.promptText,
+        instruct: (0, cosyvoice_1.renderCosyvoiceInstruct)(options.instruct) || undefined,
+        voice: (0, modelFiles_1.firstNonEmpty)(options.voice, options.voiceName),
+        steps: (0, modelFiles_1.firstNonEmpty)(options.steps, options.numInferenceSteps),
+        speed: options.speed,
+        noiseNpyPath: options.noiseNpyPath,
+        description: (0, modelFiles_1.firstNonEmpty)(options.description, options.voiceDescription),
+        emotion: options.emotion,
+        pitch: options.pitch,
+        pace: options.pace,
+        expressivity: options.expressivity,
+        noise: options.noise,
+        reverb: options.reverb,
+        quality: options.quality,
+        temperature: options.temperature,
+        topK: options.topK,
+        topP: options.topP,
+        maxFrames: options.maxFrames,
+        minNewTokens: options.minNewTokens,
+        normalizeNumbers: options.normalizeNumbers,
+        ...(0, moss_1.mossVoiceSettings)(options),
+    };
+}
+function resolveBackendPaths(files, options, config) {
+    return {
+        enhancerGgufPath: resolveEnhancerGgufPath(files, options.enhancer),
+        denoiserGgufPath: resolveDenoiserGgufPath(files, options.denoiser),
+        backendsDir: (0, modelFiles_1.firstNonEmpty)(options.backendsDir, config.backendsDir),
+        openclCacheDir: (0, modelFiles_1.firstNonEmpty)(options.openclCacheDir, config.openclCacheDir),
+        vulkanCacheDir: (0, modelFiles_1.firstNonEmpty)(options.vulkanCacheDir, config.vulkanCacheDir),
+    };
+}
+function resolvePocketSetup(files, options, config) {
+    if (files.lavasrEnhancer || files.lavasrDenoiser) {
+        throw new Error("Pocket does not support LavaSR enhancement or denoising");
+    }
+    return {
+        files,
+        options: { ...options },
+        params: (0, pocketConfig_1.buildPocketParams)(files, options, config),
+    };
+}
+/** Resolve and validate everything the constructor derives from `options`. */
+function resolveEngineSetup(options) {
+    const files = (0, modelFiles_1.normalizeGgmlFiles)(options.files || {});
+    const config = { ...(options.config || {}) };
+    const outputSampleRate = validateOutputSampleRate(config.outputSampleRate);
+    const engineType = (0, engineDetection_1.detectEngineType)(options.engine, files);
+    const mossVoice = (0, moss_1.mossVoiceSettings)(options);
+    const pocket = engineType === engineIds_1.ENGINE_POCKET
+        ? resolvePocketSetup(files, options, config)
+        : null;
+    const paths = (0, engineDetection_1.resolveModelPaths)(engineType, files, {
+        mecabDictPath: options.mecabDictPath,
+        mecabDictDir: options.mecabDictDir,
+        cangjieTsvPath: options.cangjieTsvPath,
+        dialogue: mossVoice.dialogueReferences !== undefined,
+    });
+    const settings = settingsFromOptions(options);
+    const backend = resolveBackendPaths(files, options, config);
+    const setup = {
+        engineType,
+        config,
+        outputSampleRate,
+        paths,
+        settings,
+        backend,
+        pocket,
+    };
+    assertGpuIntentConsistent(config.useGPU, settings.nGpuLayers);
+    (0, optionValidation_1.validateEngineOptions)(setup);
+    if (config.useGPU === undefined && settings.nGpuLayers == null) {
+        config.useGPU = false;
+    }
+    return setup;
+}

package/lib/streamingSupport.d.ts

@@ -0,0 +1,8 @@
+import type { EngineSetup, SynthesisSettings } from "./engineSetup";
+export declare function requestsChunkStreaming(settings: SynthesisSettings): boolean;
+/** Native chunk streaming against what the engine can actually do. */
+export declare function assertChunkStreamingSupport(setup: EngineSetup): void;
+/** The LavaSR denoiser has no streaming form yet. */
+export declare function assertDenoiserBatchOnly(setup: EngineSetup): void;
+/** Sentence-level streaming (runStream / runStreaming / streamOutput). */
+export declare function assertSentenceStreamingAllowed(setup: EngineSetup, where: string): void;

package/lib/streamingSupport.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestsChunkStreaming = requestsChunkStreaming;
+exports.assertChunkStreamingSupport = assertChunkStreamingSupport;
+exports.assertDenoiserBatchOnly = assertDenoiserBatchOnly;
+exports.assertSentenceStreamingAllowed = assertSentenceStreamingAllowed;
+const engineIds_1 = require("./engineIds");
+const moss_1 = require("./engines/moss");
+// Every streaming engine starts native chunk streaming on
+// streamChunkTokens > 0 alone: a count of 0 means batch, and
+// streamFirstChunkTokens only sizes the first chunk once streaming is on.
+function requestsChunkStreaming(settings) {
+    return (settings.streamChunkTokens ?? 0) > 0;
+}
+/** Native chunk streaming against what the engine can actually do. */
+function assertChunkStreamingSupport(setup) {
+    const { engineType, settings, backend } = setup;
+    // Checked ahead of the shared denoiser guard: Supertonic rejects both
+    // LavaSR stages for one reason (tts-cpp has only one-shot enhance /
+    // denoise, and the engine reports no native rate before synthesis).
+    if (engineType === engineIds_1.ENGINE_SUPERTONIC &&
+        (backend.enhancerGgufPath || backend.denoiserGgufPath) &&
+        requestsChunkStreaming(settings)) {
+        throw new Error("tts-ggml: the LavaSR enhancer/denoiser are not supported with " +
+            "supertonic native chunk streaming (streamChunkTokens > 0). Use " +
+            "batch synthesis or sentence-level streaming via runStream() / " +
+            "runStreaming() / run({ streamOutput: true }) for enhanced or " +
+            "denoised output.");
+    }
+    if (engineType === engineIds_1.ENGINE_AUDIO8 &&
+        (settings.streamChunkTokens != null ||
+            settings.streamFirstChunkTokens != null)) {
+        throw new Error("tts-ggml: streamChunkTokens / streamFirstChunkTokens are not " +
+            "supported by the audio8 engine, which synthesizes a whole " +
+            "utterance at a time. Use sentence-level streaming via " +
+            "runStream() / runStreaming() / run({ streamOutput: true }).");
+    }
+    if ((engineType === engineIds_1.ENGINE_MOSS_SFX || engineType === engineIds_1.ENGINE_MOSS_SPEECH) &&
+        (settings.streamChunkTokens != null ||
+            settings.streamFirstChunkTokens != null)) {
+        throw new Error("tts-ggml: streamChunkTokens / streamFirstChunkTokens are not " +
+            `supported by the ${engineType} engine, which returns a ` +
+            "whole result at a time. Use run().");
+    }
+    if (engineType === engineIds_1.ENGINE_MOSS && settings.streamFirstChunkTokens != null) {
+        throw new Error("tts-ggml: streamFirstChunkTokens is not supported by the moss " +
+            "engine, which streams fixed-size chunks; set streamChunkTokens " +
+            `(codec frames per chunk, ${moss_1.MOSS_FRAMES_PER_SECOND} per second) only.`);
+    }
+}
+/** The LavaSR denoiser has no streaming form yet. */
+function assertDenoiserBatchOnly(setup) {
+    if (!setup.backend.denoiserGgufPath || !requestsChunkStreaming(setup.settings)) {
+        return;
+    }
+    throw new Error("tts-ggml: the LavaSR denoiser is not yet supported with " +
+        "native chunk streaming (streamChunkTokens > 0). Use batch " +
+        "synthesis, or drop the denoiser for streaming. Streaming " +
+        "denoise is a planned follow-up (needs a stateful streaming " +
+        "denoiser).");
+}
+/** Sentence-level streaming (runStream / runStreaming / streamOutput). */
+function assertSentenceStreamingAllowed(setup, where) {
+    if (setup.engineType === engineIds_1.ENGINE_MOSS_SPEECH) {
+        throw new Error(`tts-ggml: ${where}: the moss-speech engine answers one turn at a ` +
+            "time and does not stream; use run()");
+    }
+    if (setup.engineType === engineIds_1.ENGINE_MOSS_SFX) {
+        throw new Error(`tts-ggml: ${where}: the moss-sfx engine generates a whole sound ` +
+            "effect from one prompt and does not stream; use run()");
+    }
+    if (setup.settings.dialogueReferences === undefined)
+        return;
+    throw new Error(`tts-ggml: ${where}: MOSS dialogue cannot be split into sentences, ` +
+        "because every job must open with the reference transcripts; use " +
+        "run() or native streaming (streamChunkTokens)");
+}