@qvac/tts-ggml 0.13.0 → 0.14.0

package/lib/modelFiles.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Model file paths for the GGML TTS backend. Engine is auto-detected
+ * from these fields (Chatterbox vs Supertonic) unless overridden via
+ * `TTSGgmlOptions.engine`. All paths must be absolute and are passed
+ * through to the native layer as-is.
+ */
+export interface TTSGgmlFiles {
+    pocketFlowModel?: string;
+    pocketMimiModel?: string;
+    pocketFrontend?: string;
+    pocketVoice?: string;
+    /**
+     * Bundle root. For Chatterbox, expected to contain
+     * `chatterbox-t3-turbo.gguf` + `chatterbox-s3gen.gguf` (turbo) or
+     * `chatterbox-t3-mtl.gguf` + `chatterbox-s3gen-mtl.gguf` (multilingual).
+     * For Supertonic, expected to contain `supertonic.gguf`.
+     */
+    modelDir?: string;
+    /** Chatterbox T3 (text to speech tokens) GGUF path. Overrides `modelDir`. */
+    t3Model?: string;
+    t3ModelPath?: string;
+    t3?: string;
+    /** Chatterbox S3Gen + HiFT (speech tokens to 24 kHz wav) GGUF path. Overrides `modelDir`. */
+    s3genModel?: string;
+    s3genModelPath?: string;
+    s3gen?: string;
+    /** Supertonic single-file GGUF path. Overrides `modelDir`. */
+    supertonicModel?: string;
+    supertonicModelPath?: string;
+    supertonic?: string;
+    /** Parler single-file GGUF path (mini/large/indic). Overrides `modelDir`. */
+    parlerModel?: string;
+    parlerModelPath?: string;
+    parler?: string;
+    /** Audio8 DualAR language model GGUF path. Overrides `modelDir`. */
+    audio8Lm?: string;
+    audio8LmPath?: string;
+    /** Audio8 codec synthesis half (codes to 44.1 kHz wav). Overrides `modelDir`. */
+    audio8CodecDecoder?: string;
+    audio8CodecDecoderPath?: string;
+    /**
+     * Audio8 codec analysis half (wav to codes). Only needed to clone a voice
+     * from a recording; a text-only deployment can leave it out.
+     */
+    audio8CodecEncoder?: string;
+    audio8CodecEncoderPath?: string;
+    /**
+     * MOSS Delay backbone GGUF path: MOSS-TTS (`moss-tts-delay-*.gguf`) or the
+     * MOSS-TTSD dialogue checkpoint (`moss-ttsd-*.gguf`). Overrides `modelDir`.
+     */
+    mossBackbone?: string;
+    mossBackbonePath?: string;
+    /** MOSS codec synthesis half (codes to 24 kHz wav). Overrides `modelDir`. */
+    mossCodecDecoder?: string;
+    mossCodecDecoderPath?: string;
+    /**
+     * MOSS codec analysis half (wav to codes). Only needed to clone a voice
+     * from `referenceAudio` or for `dialogueReferences`; a text-only deployment
+     * can leave it out.
+     */
+    mossCodecEncoder?: string;
+    mossCodecEncoderPath?: string;
+    /**
+     * MOSS-SoundEffect GGUF (`moss-sfx-*.gguf`): text encoder, DiT and VAE in
+     * one file. Routes to the `moss-sfx` engine. Overrides `modelDir`.
+     */
+    mossSoundEffect?: string;
+    mossSoundEffectPath?: string;
+    /**
+     * MOSS-Speech language model GGUF (`moss-speech-*.gguf`, e.g.
+     * `moss-speech-q8_0.gguf`). Routes to the `moss-speech` engine together
+     * with `mossSpeechCodec`. Overrides `modelDir`.
+     */
+    mossSpeechModel?: string;
+    mossSpeechModelPath?: string;
+    /**
+     * MOSS-Speech codec GGUF (`moss-speech-codec-*.gguf`): speech tokenizer,
+     * reply decoder and the default reply voice. Overrides `modelDir`.
+     */
+    mossSpeechCodec?: string;
+    mossSpeechCodecPath?: string;
+    /**
+     * CosyVoice3 model directory holding the sub-model GGUFs
+     * (`cosyvoice3-{llm,flow,hift}-*.gguf`) plus `voice.gguf`, `vocab.json` and
+     * `merges.txt`. Routes to the CosyVoice3 engine. Falls back to the shared
+     * `modelDir` when unset.
+     */
+    cosyvoiceModelDir?: string;
+    /** CosyVoice3 per-component GGUF paths (override discovery under the model dir). */
+    cosyvoiceLlmModel?: string;
+    cosyvoiceLlmModelPath?: string;
+    cosyvoiceFlowModel?: string;
+    cosyvoiceFlowModelPath?: string;
+    cosyvoiceHiftModel?: string;
+    cosyvoiceHiftModelPath?: string;
+    /**
+     * CosyVoice3 voice-cloning add-on GGUFs, required only when
+     * `referenceAudio` is set: the speech_tokenizer_v3 speech tokenizer
+     * (`cosyvoice3-s3tok-*.gguf`) and the CAM++ speaker encoder
+     * (`cosyvoice3-campplus-*.gguf`). Auto-discovered under
+     * `cosyvoiceModelDir` by those name prefixes when unset.
+     */
+    cosyvoiceS3tokModel?: string;
+    cosyvoiceS3tokModelPath?: string;
+    cosyvoiceCampplusModel?: string;
+    cosyvoiceCampplusModelPath?: string;
+    /**
+     * CosyVoice3 Qwen2 BPE text frontend (`vocab.json` + `merges.txt`) and the
+     * baked default-voice GGUF (`voice.gguf`). Each is resolved under the model
+     * dir when unset; `cosyvoiceVoiceModel` is how a different baked voice is
+     * selected without a separate model directory.
+     */
+    cosyvoiceVocab?: string;
+    cosyvoiceVocabPath?: string;
+    cosyvoiceMerges?: string;
+    cosyvoiceMergesPath?: string;
+    cosyvoiceVoiceModel?: string;
+    cosyvoiceVoiceModelPath?: string;
+    /**
+     * LavaSR enhancer GGUF: single-file Vocos bandwidth extension produced by
+     * tts-cpp/scripts/convert-lavasr-enhancer-to-gguf.py. When supplied, output
+     * is neurally upsampled to 48 kHz (the canonical way to enable enhancement;
+     * `enhancer.enhancerPath` is the only alternative).
+     */
+    lavasrEnhancer?: string;
+    /**
+     * LavaSR denoiser GGUF: UL-UNAS speech denoiser produced by
+     * tts-cpp/scripts/convert-lavasr-denoiser-to-gguf.py. Runs before the
+     * enhancer and is rate-preserving (the canonical way to enable denoising;
+     * `denoiser.denoiserPath` is the only alternative).
+     *
+     * The tts-cpp UL-UNAS forward is implemented in qvac-fabric-speech.cpp
+     * PR #78 (scalar CPU port, validated bit-close to the ONNX reference).
+     */
+    lavasrDenoiser?: string;
+    /** Optional directory containing baked Chatterbox voice profiles. */
+    voicesDir?: string;
+    /**
+     * Chatterbox MTL only: directory holding the compiled MeCab/IPAdic
+     * dictionary used for Japanese morphological segmentation. Forwarded to
+     * tts-cpp's `EngineOptions::mecab_dict_path`. Alias: top-level
+     * `mecabDictPath`.
+     */
+    mecabDictDir?: string;
+    mecabDictPath?: string;
+    /**
+     * Chatterbox MTL only: path to the Cangjie TSV used for Chinese
+     * romanisation. Forwarded to tts-cpp's `EngineOptions::cangjie_tsv_path`.
+     */
+    cangjieTsvPath?: string;
+    cangjieTsv?: string;
+}
+/** `TTSGgmlFiles` with every alias collapsed onto one canonical key. */
+export interface NormalizedFiles {
+    pocketFlowModel?: string;
+    pocketMimiModel?: string;
+    pocketFrontend?: string;
+    pocketVoice?: string;
+    modelDir?: string;
+    t3Model?: string;
+    s3genModel?: string;
+    supertonicModel?: string;
+    cosyvoiceModelDir?: string;
+    cosyvoiceLlmModel?: string;
+    cosyvoiceFlowModel?: string;
+    cosyvoiceHiftModel?: string;
+    cosyvoiceS3tokModel?: string;
+    cosyvoiceCampplusModel?: string;
+    cosyvoiceVocab?: string;
+    cosyvoiceMerges?: string;
+    cosyvoiceVoiceModel?: string;
+    parlerModel?: string;
+    audio8Lm?: string;
+    audio8CodecDecoder?: string;
+    audio8CodecEncoder?: string;
+    mossBackbone?: string;
+    mossCodecDecoder?: string;
+    mossCodecEncoder?: string;
+    mossSoundEffect?: string;
+    mossSpeechModel?: string;
+    mossSpeechCodec?: string;
+    voicesDir?: string;
+    lavasrEnhancer?: string;
+    lavasrDenoiser?: string;
+    mecabDictDir?: string;
+    cangjieTsvPath?: string;
+}
+export declare function firstNonEmpty<T>(...candidates: Array<T | "" | null | undefined>): T | undefined;
+export declare function fileExistsSafe(filePath?: string): boolean;
+export declare function readDirSafe(modelDir?: string): string[];
+export declare function ggufQuantRank(name: string, pattern: RegExp): number;
+/**
+ * Find one Audio8 or MOSS GGUF in `modelDir`, preferring the quant tier that
+ * reads best for its size (q8_0 > f16 > q4_0 > f32).
+ */
+export declare function findQuantRankedGguf(modelDir: string | undefined, pattern: RegExp): string | undefined;
+type FileKey = keyof TTSGgmlFiles;
+type CanonicalFileKey = keyof NormalizedFiles;
+/**
+ * Alias table behind `normalizeGgmlFiles`: one row per `NormalizedFiles` key,
+ * the canonical key first and then its aliases in precedence order. The first
+ * non-empty value in a row wins, so the canonical key beats every alias and an
+ * earlier alias beats a later one.
+ */
+export declare const FILE_ALIAS_TABLE: ReadonlyArray<readonly [CanonicalFileKey, ...FileKey[]]>;
+export declare function normalizeGgmlFiles(files: TTSGgmlFiles | null | undefined): NormalizedFiles;
+export {};

package/lib/modelFiles.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_ALIAS_TABLE = void 0;
+exports.firstNonEmpty = firstNonEmpty;
+exports.fileExistsSafe = fileExistsSafe;
+exports.readDirSafe = readDirSafe;
+exports.ggufQuantRank = ggufQuantRank;
+exports.findQuantRankedGguf = findQuantRankedGguf;
+exports.normalizeGgmlFiles = normalizeGgmlFiles;
+/* eslint-disable @typescript-eslint/no-require-imports -- Bare modules expose CommonJS export shapes. */
+const fs = require("bare-fs");
+const path = require("bare-path");
+function firstNonEmpty(...candidates) {
+    for (const value of candidates) {
+        if (value != null && value !== "")
+            return value;
+    }
+    return undefined;
+}
+function fileExistsSafe(filePath) {
+    if (!filePath)
+        return false;
+    try {
+        return fs.existsSync(filePath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Preferred quant tier when a model directory holds several copies of the same
+ * GGUF (Audio8 and MOSS): the tier that reads best for its size.
+ */
+const QUANT_TIER_ORDER = ["q8_0", "f16", "q4_0", "f32"];
+function readDirSafe(modelDir) {
+    if (!modelDir)
+        return [];
+    try {
+        return fs.readdirSync(modelDir);
+    }
+    catch {
+        return [];
+    }
+}
+function ggufQuantRank(name, pattern) {
+    const match = name.match(pattern);
+    if (!match)
+        return Number.MAX_SAFE_INTEGER;
+    if (!match[1])
+        return 0;
+    const index = QUANT_TIER_ORDER.indexOf(match[1].slice(1).toLowerCase());
+    return index === -1 ? QUANT_TIER_ORDER.length + 1 : index + 1;
+}
+/**
+ * Find one Audio8 or MOSS GGUF in `modelDir`, preferring the quant tier that
+ * reads best for its size (q8_0 > f16 > q4_0 > f32).
+ */
+function findQuantRankedGguf(modelDir, pattern) {
+    if (!modelDir)
+        return undefined;
+    const matches = readDirSafe(modelDir).filter((name) => pattern.test(name));
+    if (matches.length === 0)
+        return undefined;
+    matches.sort((left, right) => ggufQuantRank(left, pattern) - ggufQuantRank(right, pattern));
+    return path.join(modelDir, matches[0]);
+}
+/**
+ * Alias table behind `normalizeGgmlFiles`: one row per `NormalizedFiles` key,
+ * the canonical key first and then its aliases in precedence order. The first
+ * non-empty value in a row wins, so the canonical key beats every alias and an
+ * earlier alias beats a later one.
+ */
+exports.FILE_ALIAS_TABLE = [
+    ["modelDir"],
+    ["pocketFlowModel"],
+    ["pocketMimiModel"],
+    ["pocketFrontend"],
+    ["pocketVoice"],
+    ["t3Model", "t3ModelPath", "t3"],
+    ["s3genModel", "s3genModelPath", "s3gen"],
+    ["supertonicModel", "supertonicModelPath", "supertonic"],
+    // CosyVoice3: either a dedicated modelDir of cosyvoice3-*.gguf files, or
+    // explicit per-component paths. Falls back to the shared `modelDir`.
+    ["cosyvoiceModelDir"],
+    ["cosyvoiceLlmModel", "cosyvoiceLlmModelPath"],
+    ["cosyvoiceFlowModel", "cosyvoiceFlowModelPath"],
+    ["cosyvoiceHiftModel", "cosyvoiceHiftModelPath"],
+    ["cosyvoiceS3tokModel", "cosyvoiceS3tokModelPath"],
+    ["cosyvoiceCampplusModel", "cosyvoiceCampplusModelPath"],
+    ["cosyvoiceVocab", "cosyvoiceVocabPath"],
+    ["cosyvoiceMerges", "cosyvoiceMergesPath"],
+    ["cosyvoiceVoiceModel", "cosyvoiceVoiceModelPath"],
+    ["parlerModel", "parlerModelPath", "parler"],
+    ["audio8Lm", "audio8LmPath"],
+    ["audio8CodecDecoder", "audio8CodecDecoderPath"],
+    ["audio8CodecEncoder", "audio8CodecEncoderPath"],
+    ["mossBackbone", "mossBackbonePath"],
+    ["mossCodecDecoder", "mossCodecDecoderPath"],
+    ["mossCodecEncoder", "mossCodecEncoderPath"],
+    ["mossSoundEffect", "mossSoundEffectPath"],
+    ["mossSpeechModel", "mossSpeechModelPath"],
+    ["mossSpeechCodec", "mossSpeechCodecPath"],
+    ["voicesDir"],
+    ["lavasrEnhancer"],
+    ["lavasrDenoiser"],
+    ["mecabDictDir", "mecabDictPath"],
+    ["cangjieTsvPath", "cangjieTsv"],
+];
+function normalizeGgmlFiles(files) {
+    if (files == null || typeof files !== "object")
+        return {};
+    const normalized = {};
+    for (const row of exports.FILE_ALIAS_TABLE) {
+        normalized[row[0]] = firstNonEmpty(...row.map((key) => files[key]));
+    }
+    return normalized;
+}

package/lib/nativeParams.d.ts

@@ -0,0 +1,12 @@
+import type { TTSConfigurationParams } from "../tts";
+import type { EngineSetup } from "./engineSetup";
+/** The knobs every engine in SAMPLING_ENGINES reads. */
+export declare function assignSamplingParams(setup: EngineSetup, parameters: TTSConfigurationParams): void;
+/**
+ * Backend and output plumbing for the engines that take no `language`,
+ * where `assignCommonNativeParams` would be the wrong shape.
+ */
+export declare function assignBackendParams(setup: EngineSetup, parameters: TTSConfigurationParams): void;
+export declare function assignCommonNativeParams(setup: EngineSetup, parameters: TTSConfigurationParams): void;
+/** LavaSR post-processing paths, shared by every engine that supports them. */
+export declare function assignLavasrParams(setup: EngineSetup, parameters: TTSConfigurationParams): void;

package/lib/nativeParams.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assignSamplingParams = assignSamplingParams;
+exports.assignBackendParams = assignBackendParams;
+exports.assignCommonNativeParams = assignCommonNativeParams;
+exports.assignLavasrParams = assignLavasrParams;
+/** The knobs every engine in SAMPLING_ENGINES reads. */
+function assignSamplingParams(setup, parameters) {
+    if (setup.settings.temperature != null) {
+        parameters.temperature = Number(setup.settings.temperature);
+    }
+    if (setup.settings.topK != null)
+        parameters.topK = setup.settings.topK | 0;
+    if (setup.settings.topP != null)
+        parameters.topP = Number(setup.settings.topP);
+    if (setup.settings.maxFrames != null) {
+        parameters.maxFrames = setup.settings.maxFrames | 0;
+    }
+}
+/**
+ * Backend and output plumbing for the engines that take no `language`,
+ * where `assignCommonNativeParams` would be the wrong shape.
+ */
+function assignBackendParams(setup, parameters) {
+    if (setup.settings.seed != null)
+        parameters.seed = setup.settings.seed | 0;
+    if (setup.settings.threads != null)
+        parameters.threads = setup.settings.threads | 0;
+    if (setup.outputSampleRate != null) {
+        parameters.outputSampleRate = setup.outputSampleRate | 0;
+    }
+    if (setup.settings.nGpuLayers != null) {
+        parameters.nGpuLayers = setup.settings.nGpuLayers | 0;
+    }
+    if (setup.config.useGPU != null) {
+        parameters.useGPU = !!setup.config.useGPU;
+    }
+    assignLavasrParams(setup, parameters);
+    if (setup.backend.backendsDir) {
+        parameters.backendsDir = setup.backend.backendsDir;
+    }
+}
+function assignCommonNativeParams(setup, parameters) {
+    if (setup.settings.seed != null)
+        parameters.seed = setup.settings.seed | 0;
+    if (setup.settings.threads != null)
+        parameters.threads = setup.settings.threads | 0;
+    if (setup.settings.nGpuLayers != null) {
+        parameters.nGpuLayers = setup.settings.nGpuLayers | 0;
+    }
+    if (setup.outputSampleRate != null) {
+        parameters.outputSampleRate = setup.outputSampleRate | 0;
+    }
+    if (setup.config.useGPU != null) {
+        parameters.useGPU = !!setup.config.useGPU;
+    }
+    assignLavasrParams(setup, parameters);
+    if (setup.backend.backendsDir) {
+        parameters.backendsDir = setup.backend.backendsDir;
+    }
+    if (setup.backend.openclCacheDir) {
+        parameters.openclCacheDir = setup.backend.openclCacheDir;
+    }
+}
+/** LavaSR post-processing paths, shared by every engine that supports them. */
+function assignLavasrParams(setup, parameters) {
+    if (setup.backend.enhancerGgufPath) {
+        parameters.lavasrEnhancerPath = setup.backend.enhancerGgufPath;
+    }
+    if (setup.backend.denoiserGgufPath) {
+        parameters.lavasrDenoiserPath = setup.backend.denoiserGgufPath;
+    }
+}

package/lib/optionValidation.d.ts

@@ -0,0 +1,2 @@
+import type { EngineSetup } from "./engineSetup";
+export declare function validateEngineOptions(setup: EngineSetup): void;

package/lib/optionValidation.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEngineOptions = validateEngineOptions;
+/**
+ * Constructor-time option validation, in the order the errors are reported:
+ * streaming capability, Parler, sampler and engine-scoped options, then each
+ * engine's own consistency rules, cross-engine conditioning, and finally the
+ * denoiser's batch-only rule.
+ */
+const conditioning_1 = require("./conditioning");
+const engineIds_1 = require("./engineIds");
+const audio8_1 = require("./engines/audio8");
+const cosyvoice_1 = require("./engines/cosyvoice");
+const moss_1 = require("./engines/moss");
+const mossSoundEffect_1 = require("./engines/mossSoundEffect");
+const mossSpeech_1 = require("./engines/mossSpeech");
+const parler_1 = require("./engines/parler");
+const options_1 = require("./options");
+const streamingSupport_1 = require("./streamingSupport");
+function validateEngineOptions(setup) {
+    (0, streamingSupport_1.assertChunkStreamingSupport)(setup);
+    // Runs before the denoiser guard so a Parler description/template conflict
+    // is reported ahead of the engine-agnostic streaming constraints.
+    (0, parler_1.assertParlerOptions)(setup);
+    assertSamplerOptionSupport(setup);
+    assertEngineScopedOptions(setup);
+    (0, cosyvoice_1.assertCosyvoiceOptionConsistency)(setup);
+    (0, cosyvoice_1.assertCosyvoiceCloneConsistent)(setup);
+    (0, audio8_1.assertAudio8Options)(setup);
+    (0, moss_1.assertMossOptions)(setup);
+    (0, mossSoundEffect_1.assertMossSoundEffectOptions)(setup);
+    (0, mossSpeech_1.assertMossSpeechOptions)(setup);
+    (0, conditioning_1.assertConditioningConsistency)(setup, "constructor");
+    (0, streamingSupport_1.assertDenoiserBatchOnly)(setup);
+}
+function assertSamplerOptionSupport(setup) {
+    if (setup.engineType === engineIds_1.ENGINE_POCKET || engineIds_1.SAMPLING_ENGINES.includes(setup.engineType))
+        return;
+    // Chatterbox's T3 samples too, but its length cap is nPredict, not maxFrames.
+    const tokenSampling = setup.engineType === engineIds_1.ENGINE_CHATTERBOX
+        ? {}
+        : {
+            temperature: setup.settings.temperature,
+            topK: setup.settings.topK,
+            topP: setup.settings.topP,
+        };
+    const sampling = (0, options_1.setOptionNames)({
+        ...tokenSampling,
+        maxFrames: setup.settings.maxFrames,
+    });
+    if (sampling.length === 0)
+        return;
+    throw new Error(`tts-ggml: ${sampling.join(", ")} are parler/audio8-only options ` +
+        `(engine is ${setup.engineType})`);
+}
+/**
+ * Options only some engines read. Set on any other engine they would be
+ * dropped without effect, so they are rejected by name instead.
+ */
+function assertEngineScopedOptions(setup) {
+    const scoped = [
+        [
+            [engineIds_1.ENGINE_CHATTERBOX],
+            {
+                batchCfmSteps: setup.settings.batchCfmSteps,
+                nPredict: setup.settings.nPredict,
+                maxSentenceChars: setup.settings.maxSentenceChars,
+                crossfadeMs: setup.settings.crossfadeMs,
+                repeatPenalty: setup.settings.repeatPenalty,
+                exaggeration: setup.settings.exaggeration,
+                cfgWeight: setup.settings.cfgWeight,
+                minP: setup.settings.minP,
+            },
+        ],
+        [
+            [engineIds_1.ENGINE_CHATTERBOX, engineIds_1.ENGINE_COSYVOICE3],
+            { streamLeftContextTokens: setup.settings.streamLeftContextTokens },
+        ],
+        [
+            [engineIds_1.ENGINE_SUPERTONIC],
+            {
+                voiceJsonPath: setup.settings.voiceJsonPath,
+                prewarmText: setup.settings.prewarmText,
+                streamChunkTolerancePct: setup.settings.streamChunkTolerancePct,
+                streamMinChunkTokens: setup.settings.streamMinChunkTokens,
+            },
+        ],
+        [
+            [engineIds_1.ENGINE_SUPERTONIC, engineIds_1.ENGINE_COSYVOICE3],
+            { vulkanDevice: setup.settings.vulkanDevice },
+        ],
+        [[engineIds_1.ENGINE_COSYVOICE3], { flowCutPrompt: setup.settings.flowCutPrompt }],
+    ];
+    for (const [engines, fields] of scoped) {
+        if (engines.includes(setup.engineType))
+            continue;
+        const names = (0, options_1.setOptionNames)(fields);
+        if (names.length === 0)
+            continue;
+        throw new Error(`tts-ggml: ${names.join(", ")} are ${engines.join("/")}-only ` +
+            `options (engine is ${setup.engineType})`);
+    }
+}

package/lib/options.d.ts

@@ -0,0 +1,4 @@
+/** Names of the entries that carry a value, for "wrong engine" messages. */
+export declare function setOptionNames(options: Record<string, string | number | boolean | undefined>): string[];
+/** Which of `keys` are set on `source`. Used to name stray options in errors. */
+export declare function keysPresent(source: object | null | undefined, keys: readonly string[]): string[];

package/lib/options.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setOptionNames = setOptionNames;
+exports.keysPresent = keysPresent;
+/** Names of the entries that carry a value, for "wrong engine" messages. */
+function setOptionNames(options) {
+    return Object.entries(options)
+        .filter(([, value]) => value != null)
+        .map(([name]) => name);
+}
+/** Which of `keys` are set on `source`. Used to name stray options in errors. */
+function keysPresent(source, keys) {
+    if (source == null || typeof source !== "object")
+        return [];
+    const record = source;
+    return keys.filter((key) => record[key] != null && record[key] !== "");
+}

package/lib/pocketLifecycle.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The Pocket engine's execution rules. Pocket runs one native job at a time
+ * and reports its end through a terminal callback (stats or error), so each
+ * job sits behind a completion barrier that is drained before the next
+ * request, and lifecycle operations (load, unload, destroy, reload) refuse to
+ * overlap.
+ */
+import type { QvacResponse } from "@qvac/infer-base";
+import type QvacLoggerType from "@qvac/logging";
+import type { TTSConfigurationParams, TTSInterface, TTSJobData } from "../tts";
+import type { EngineSetup } from "./engineSetup";
+import type { InferenceState } from "./types";
+/** What the Pocket rules need from the wrapper that owns the native instance. */
+export interface PocketHost {
+    readonly setup: EngineSetup;
+    readonly state: InferenceState;
+    logger(): QvacLoggerType;
+    /** The live native instance, or null. */
+    optionalAddon(): TTSInterface | null;
+    /** Makes `addon` the instance the wrapper reports and routes events from. */
+    setAddon(addon: TTSInterface): void;
+    /** A new native instance wired to the wrapper's output callback. */
+    createAddon(params: TTSConfigurationParams): TTSInterface;
+    unloadModel(): Promise<void>;
+    /** The response a job is running for, or null when idle. */
+    activeJob(): QvacResponse | null;
+    /** Fails the active sentence stream, if any, with `reason`. */
+    failStream(reason: string): void;
+}
+interface PendingJob {
+    promise: Promise<void>;
+    resolve: () => void;
+}
+export declare class PocketLifecycle {
+    private readonly host;
+    /** The native job awaiting its terminal callback, or null. */
+    jobPending: PendingJob | null;
+    private cancelPromise;
+    private inProgress;
+    constructor(host: PocketHost);
+    /** A cancel in flight finishes, terminal callback included, before anything else starts. */
+    waitCancel(): Promise<void>;
+    /** One lifecycle operation at a time; requests are refused while one runs. */
+    checkReload(): void;
+    /** A synthesis request needs a loaded instance and no job in flight. */
+    checkRequest(): void;
+    withLifecycle(action: () => Promise<void>): Promise<void>;
+    /** Runs the job behind a completion barrier that its terminal callback releases. */
+    runJob(addon: TTSInterface, input: TTSJobData): Promise<void>;
+    /** A terminal native callback (error or stats) releases the completion barrier. */
+    onNativeEvent(data: unknown, error: unknown): void;
+    /**
+     * Fails `response` with the caller's reason and stops native work. The
+     * completion barrier stays until the terminal callback arrives.
+     */
+    attachAbort(response: QvacResponse, signal: AbortSignal): void;
+    /** Stops native work and waits for the job in flight to report its end. */
+    cancel(): Promise<void>;
+    /**
+     * Replaces the native instance with one built from the merged options.
+     * Native work is drained and the old model released before the replacement
+     * is allocated; a failed activation leaves the instance unloaded with its
+     * last good configuration.
+     */
+    reload(newConfig: Record<string, unknown>): Promise<void>;
+}
+export {};