@qvac/tts-ggml 0.13.0 → 0.14.0

package/lib/engines/cosyvoice.d.ts

@@ -0,0 +1,87 @@
+import type { TTSConfigurationParams } from "../../tts";
+import type { EngineSetup, ModelPaths } from "../engineSetup";
+import { type NormalizedFiles } from "../modelFiles";
+export declare const COSYVOICE3_LLM_RE: RegExp;
+export declare const COSYVOICE_DIALECTS: {
+    readonly cantonese: "广东话";
+    readonly northeastern: "东北话";
+    readonly gansu: "甘肃话";
+    readonly guizhou: "贵州话";
+    readonly henan: "河南话";
+    readonly hubei: "湖北话";
+    readonly hunan: "湖南话";
+    readonly jiangxi: "江西话";
+    readonly minnan: "闽南话";
+    readonly ningxia: "宁夏话";
+    readonly shanxi: "山西话";
+    readonly shaanxi: "陕西话";
+    readonly shandong: "山东话";
+    readonly shanghai: "上海话";
+    readonly sichuan: "四川话";
+    readonly tianjin: "天津话";
+    readonly yunnan: "云南话";
+};
+export declare const COSYVOICE_VOLUMES: {
+    readonly loud: "Please say a sentence as loudly as possible.";
+    readonly soft: "Please say a sentence in a very soft voice.";
+};
+export declare const COSYVOICE_STYLES: {
+    readonly peppa: "我想体验一下小猪佩奇风格，可以吗？";
+    readonly robot: "你可以尝试用机器人的方式解答吗？";
+};
+/**
+ * CosyVoice3 controls that have no canonical cross-engine vocabulary yet.
+ * Emotion and speaking rate are NOT here -- use the top-level `emotion` /
+ * `pace` options, which work the same way on every engine that supports them.
+ * Exactly one field takes effect per synthesis, resolved by precedence
+ * dialect > volume > style. Pass a raw string instead for an arbitrary
+ * instruction (advanced escape hatch).
+ */
+export interface CosyvoiceInstruct {
+    /** Chinese dialect; renders "请用{dialect}表达。". */
+    dialect?: keyof typeof COSYVOICE_DIALECTS;
+    /** Loudness. */
+    volume?: keyof typeof COSYVOICE_VOLUMES;
+    /** Playful style preset. */
+    style?: keyof typeof COSYVOICE_STYLES;
+}
+/**
+ * Render a CosyVoice3 `instruct` option to the trained instruction string.
+ * A raw string passes through (trimmed); the structured form emits exactly one
+ * control by precedence dialect > volume > style. Returns "" for no
+ * instruction. An invalid structured key throws.
+ */
+export declare function renderCosyvoiceInstruct(instruct: string | CosyvoiceInstruct | undefined): string;
+/**
+ * CosyVoice3 per-call instruction. Same values as the constructor's
+ * `instruct`; a per-call conditioning control replaces the configured one for
+ * that synthesis, and one control takes effect per synthesis.
+ */
+export interface CosyvoiceJobFields {
+    instruct?: string | CosyvoiceInstruct;
+}
+/**
+ * True when `modelDir` contains a CosyVoice3 LLM GGUF (the sub-model that
+ * unambiguously identifies a CosyVoice3 model directory).
+ */
+export declare function dirHasCosyvoice3(modelDir?: string): boolean;
+/**
+ * CosyVoice3 discovers its sub-model GGUFs from a model directory; the native
+ * engine resolves the individual components. Explicit per-component paths win
+ * over the directory.
+ */
+export declare function resolveCosyvoiceModelPaths(files: NormalizedFiles): Pick<ModelPaths, "cosyvoiceModelDir" | "cosyvoiceLlmModelPath" | "cosyvoiceFlowModelPath" | "cosyvoiceHiftModelPath" | "cosyvoiceS3tokModelPath" | "cosyvoiceCampplusModelPath" | "cosyvoiceVocabPath" | "cosyvoiceMergesPath" | "cosyvoiceVoiceModelPath">;
+export declare function assertCosyvoiceOptionConsistency(setup: EngineSetup): void;
+/**
+ * `promptText` is deliberately not required: its absence selects
+ * cross-lingual mode. With a model dir present but no cloning GGUFs in it,
+ * the native load fail-closes instead.
+ */
+export declare function assertCosyvoiceCloneConsistent(setup: EngineSetup): void;
+/**
+ * CosyVoice3's per-call instruction, rendered like the constructor's. The
+ * native layer reads it next to emotion/pace, and any of the three replaces
+ * the configured conditioning for that synthesis.
+ */
+export declare function resolveJobInstruct(setup: EngineSetup, source: CosyvoiceJobFields | null | undefined, where: string): string | undefined;
+export declare function buildCosyvoiceParams(setup: EngineSetup): TTSConfigurationParams;

package/lib/engines/cosyvoice.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COSYVOICE_STYLES = exports.COSYVOICE_VOLUMES = exports.COSYVOICE_DIALECTS = exports.COSYVOICE3_LLM_RE = void 0;
+exports.renderCosyvoiceInstruct = renderCosyvoiceInstruct;
+exports.dirHasCosyvoice3 = dirHasCosyvoice3;
+exports.resolveCosyvoiceModelPaths = resolveCosyvoiceModelPaths;
+exports.assertCosyvoiceOptionConsistency = assertCosyvoiceOptionConsistency;
+exports.assertCosyvoiceCloneConsistent = assertCosyvoiceCloneConsistent;
+exports.resolveJobInstruct = resolveJobInstruct;
+exports.buildCosyvoiceParams = buildCosyvoiceParams;
+/* eslint-disable @typescript-eslint/no-require-imports -- Bare modules expose CommonJS export shapes. */
+const fs = require("bare-fs");
+const engineIds_1 = require("../engineIds");
+const modelFiles_1 = require("../modelFiles");
+const nativeParams_1 = require("../nativeParams");
+// The LLM sub-model is the tell for CosyVoice3 modelDir auto-detection.
+exports.COSYVOICE3_LLM_RE = /^cosyvoice3-llm(-[a-z0-9_]+)?\.gguf$/i;
+// CosyVoice3 instruct2 control vocabulary (cosyvoice/utils/common.py
+// instruct_list). The structured `instruct` option renders to the exact
+// trained instruction string; the native engine wraps it as
+// "You are a helpful assistant. " + <instruction> + "<|endofprompt|>" and
+// drops the LM prompt speech tokens. One control applies per synthesis
+// (the model is trained on single instructions).
+exports.COSYVOICE_DIALECTS = {
+    cantonese: "广东话",
+    northeastern: "东北话",
+    gansu: "甘肃话",
+    guizhou: "贵州话",
+    henan: "河南话",
+    hubei: "湖北话",
+    hunan: "湖南话",
+    jiangxi: "江西话",
+    minnan: "闽南话",
+    ningxia: "宁夏话",
+    shanxi: "山西话",
+    shaanxi: "陕西话",
+    shandong: "山东话",
+    shanghai: "上海话",
+    sichuan: "四川话",
+    tianjin: "天津话",
+    yunnan: "云南话",
+};
+exports.COSYVOICE_VOLUMES = {
+    loud: "Please say a sentence as loudly as possible.",
+    soft: "Please say a sentence in a very soft voice.",
+};
+exports.COSYVOICE_STYLES = {
+    peppa: "我想体验一下小猪佩奇风格，可以吗？",
+    robot: "你可以尝试用机器人的方式解答吗？",
+};
+/**
+ * Look up a structured-instruct control value, throwing a clear error for an
+ * invalid key instead of letting an `undefined` render into the instruction
+ * string.
+ */
+function cosyvoiceInstructValue(map, key, kind) {
+    const value = map[key];
+    if (value == null) {
+        throw new Error(`Invalid CosyVoice instruct ${kind} "${key}". Valid ${kind}s: ${Object.keys(map).join(", ")}.`);
+    }
+    return value;
+}
+/**
+ * Render a CosyVoice3 `instruct` option to the trained instruction string.
+ * A raw string passes through (trimmed); the structured form emits exactly one
+ * control by precedence dialect > volume > style. Returns "" for no
+ * instruction. An invalid structured key throws.
+ */
+function renderCosyvoiceInstruct(instruct) {
+    // Only `undefined` means "omitted" (zero-shot). An explicit `null` is a
+    // malformed value, not an omission, so it is rejected below like any other
+    // non-object.
+    if (instruct === undefined)
+        return "";
+    if (typeof instruct === "string")
+        return instruct.trim();
+    // A JS caller can pass values the type forbids (null, a number, an array, a
+    // Date, a class instance). Check defensively as `unknown`: require an ordinary
+    // object literal so exotic objects can't slip past the presence checks below
+    // and degrade to zero-shot, and so control fields are read from the object's
+    // own properties rather than an inherited prototype.
+    const control = instruct;
+    if (control === null || typeof control !== "object" || Array.isArray(control)) {
+        throw new Error("Invalid CosyVoice instruct: expected a string or a plain control " +
+            "object such as { dialect: 'cantonese' }.");
+    }
+    const proto = Object.getPrototypeOf(control);
+    if (proto !== Object.prototype && proto !== null) {
+        throw new Error("Invalid CosyVoice instruct: expected a plain control object such as " +
+            "{ dialect: 'cantonese' }, not an instance of another type.");
+    }
+    // Reject unknown structured keys (typos like `{ dialekt: 'cantonese' }`)
+    // before the precedence chain, which would otherwise fall through to "".
+    const supportedControls = ["dialect", "volume", "style"];
+    const unknownKeys = Object.keys(instruct).filter((key) => !supportedControls.includes(key));
+    if (unknownKeys.length > 0) {
+        const hint = unknownKeys.some((key) => key === "emotion" || key === "speed")
+            ? " Emotion and speaking rate moved to the top-level `emotion` / `pace` options."
+            : "";
+        throw new Error(`Invalid CosyVoice instruct key(s): ${unknownKeys.join(", ")}. ` +
+            `Valid keys: dialect, volume, style.${hint}`);
+    }
+    // Presence, not truthiness: a control that is set to a malformed value
+    // (`{ dialect: '' }`, `{ dialect: null }`) must raise via
+    // cosyvoiceInstructValue rather than fall through to zero-shot. `undefined`
+    // means the field was not set, so it is skipped. Precedence: dialect >
+    // volume > style.
+    if (instruct.dialect !== undefined) {
+        return `请用${cosyvoiceInstructValue(exports.COSYVOICE_DIALECTS, instruct.dialect, "dialect")}表达。`;
+    }
+    if (instruct.volume !== undefined) {
+        return cosyvoiceInstructValue(exports.COSYVOICE_VOLUMES, instruct.volume, "volume");
+    }
+    if (instruct.style !== undefined) {
+        return cosyvoiceInstructValue(exports.COSYVOICE_STYLES, instruct.style, "style");
+    }
+    return "";
+}
+/**
+ * True when `modelDir` contains a CosyVoice3 LLM GGUF (the sub-model that
+ * unambiguously identifies a CosyVoice3 model directory).
+ */
+function dirHasCosyvoice3(modelDir) {
+    if (!modelDir)
+        return false;
+    let entries;
+    try {
+        entries = fs.readdirSync(modelDir);
+    }
+    catch {
+        return false;
+    }
+    return entries.some((name) => exports.COSYVOICE3_LLM_RE.test(name));
+}
+/**
+ * CosyVoice3 discovers its sub-model GGUFs from a model directory; the native
+ * engine resolves the individual components. Explicit per-component paths win
+ * over the directory.
+ */
+function resolveCosyvoiceModelPaths(files) {
+    return {
+        cosyvoiceModelDir: (0, modelFiles_1.firstNonEmpty)(files.cosyvoiceModelDir, files.modelDir),
+        cosyvoiceLlmModelPath: files.cosyvoiceLlmModel,
+        cosyvoiceFlowModelPath: files.cosyvoiceFlowModel,
+        cosyvoiceHiftModelPath: files.cosyvoiceHiftModel,
+        cosyvoiceS3tokModelPath: files.cosyvoiceS3tokModel,
+        cosyvoiceCampplusModelPath: files.cosyvoiceCampplusModel,
+        cosyvoiceVocabPath: files.cosyvoiceVocab,
+        cosyvoiceMergesPath: files.cosyvoiceMerges,
+        cosyvoiceVoiceModelPath: files.cosyvoiceVoiceModel,
+    };
+}
+function assertCosyvoiceOptionConsistency(setup) {
+    if (setup.engineType === engineIds_1.ENGINE_COSYVOICE3)
+        return;
+    const cosyvoiceOnly = [];
+    const cosyvoiceOnlyFields = {
+        instruct: setup.settings.instruct,
+        promptText: setup.settings.promptText,
+    };
+    for (const [key, value] of Object.entries(cosyvoiceOnlyFields)) {
+        if (value != null)
+            cosyvoiceOnly.push(key);
+    }
+    if (cosyvoiceOnly.length > 0) {
+        throw new Error(`tts-ggml: ${cosyvoiceOnly.join(", ")} are cosyvoice3-only options ` +
+            `(engine is ${setup.engineType})`);
+    }
+}
+/**
+ * `promptText` is deliberately not required: its absence selects
+ * cross-lingual mode. With a model dir present but no cloning GGUFs in it,
+ * the native load fail-closes instead.
+ */
+function assertCosyvoiceCloneConsistent(setup) {
+    if (setup.engineType !== engineIds_1.ENGINE_COSYVOICE3)
+        return;
+    if (!setup.settings.referenceAudio)
+        return;
+    const haveExplicit = setup.paths.cosyvoiceS3tokModelPath && setup.paths.cosyvoiceCampplusModelPath;
+    if (!haveExplicit && !setup.paths.cosyvoiceModelDir) {
+        throw new Error("tts-ggml: referenceAudio (CosyVoice3 voice cloning) needs the " +
+            "speech-tokenizer and speaker-encoder GGUFs: set " +
+            "files.cosyvoiceS3tokModel + files.cosyvoiceCampplusModel, or a " +
+            "files.cosyvoiceModelDir containing cosyvoice3-s3tok*.gguf and " +
+            "cosyvoice3-campplus*.gguf");
+    }
+}
+/**
+ * CosyVoice3's per-call instruction, rendered like the constructor's. The
+ * native layer reads it next to emotion/pace, and any of the three replaces
+ * the configured conditioning for that synthesis.
+ */
+function resolveJobInstruct(setup, source, where) {
+    if (source?.instruct === undefined)
+        return undefined;
+    if (setup.engineType !== engineIds_1.ENGINE_COSYVOICE3) {
+        throw new Error(`tts-ggml: ${where}: per-call instruct is cosyvoice3-only ` +
+            `(engine is ${setup.engineType})`);
+    }
+    return renderCosyvoiceInstruct(source.instruct) || undefined;
+}
+function buildCosyvoiceParams(setup) {
+    const parameters = {
+        engineType: engineIds_1.ENGINE_COSYVOICE3,
+        cosyvoiceModelDir: setup.paths.cosyvoiceModelDir || "",
+        language: setup.config.language || "en",
+    };
+    if (setup.paths.cosyvoiceLlmModelPath) {
+        parameters.cosyvoiceLlmModelPath = setup.paths.cosyvoiceLlmModelPath;
+    }
+    if (setup.paths.cosyvoiceFlowModelPath) {
+        parameters.cosyvoiceFlowModelPath = setup.paths.cosyvoiceFlowModelPath;
+    }
+    if (setup.paths.cosyvoiceHiftModelPath) {
+        parameters.cosyvoiceHiftModelPath = setup.paths.cosyvoiceHiftModelPath;
+    }
+    if (setup.paths.cosyvoiceS3tokModelPath) {
+        parameters.cosyvoiceS3tokModelPath = setup.paths.cosyvoiceS3tokModelPath;
+    }
+    if (setup.paths.cosyvoiceCampplusModelPath) {
+        parameters.cosyvoiceCampplusModelPath = setup.paths.cosyvoiceCampplusModelPath;
+    }
+    if (setup.paths.cosyvoiceVocabPath) {
+        parameters.cosyvoiceVocabPath = setup.paths.cosyvoiceVocabPath;
+    }
+    if (setup.paths.cosyvoiceMergesPath) {
+        parameters.cosyvoiceMergesPath = setup.paths.cosyvoiceMergesPath;
+    }
+    if (setup.paths.cosyvoiceVoiceModelPath) {
+        parameters.cosyvoiceVoiceModelPath = setup.paths.cosyvoiceVoiceModelPath;
+    }
+    if (setup.settings.vulkanDevice != null) {
+        parameters.vulkanDevice = setup.settings.vulkanDevice | 0;
+    }
+    if (setup.settings.flowCutPrompt != null) {
+        parameters.flowCutPrompt = !!setup.settings.flowCutPrompt;
+    }
+    if (setup.settings.referenceAudio != null) {
+        parameters.referenceAudio = setup.settings.referenceAudio;
+    }
+    if (setup.settings.promptText != null) {
+        parameters.promptText = String(setup.settings.promptText);
+    }
+    if (setup.settings.instruct)
+        parameters.instruct = setup.settings.instruct;
+    // Canonical values; the native layer maps them to the trained instructions.
+    if (setup.settings.emotion != null)
+        parameters.emotion = String(setup.settings.emotion);
+    if (setup.settings.pace != null)
+        parameters.pace = String(setup.settings.pace);
+    if (setup.settings.voice)
+        parameters.voice = setup.settings.voice;
+    (0, nativeParams_1.assignCommonNativeParams)(setup, parameters);
+    if (setup.settings.cfmSteps != null)
+        parameters.cfmSteps = setup.settings.cfmSteps | 0;
+    if (setup.settings.streamChunkTokens != null) {
+        parameters.streamChunkTokens = setup.settings.streamChunkTokens | 0;
+    }
+    if (setup.settings.streamFirstChunkTokens != null) {
+        parameters.streamFirstChunkTokens = setup.settings.streamFirstChunkTokens | 0;
+    }
+    if (setup.settings.streamLeftContextTokens != null) {
+        parameters.streamLeftContextTokens = setup.settings.streamLeftContextTokens | 0;
+    }
+    return parameters;
+}

package/lib/engines/moss.d.ts

@@ -0,0 +1,26 @@
+import type { TTSConfigurationParams } from "../../tts";
+import type { EngineSetup, ModelPaths, SynthesisSettings } from "../engineSetup";
+import { type NormalizedFiles } from "../modelFiles";
+export declare const MOSS_BACKBONE_RE: RegExp;
+export declare const MOSS_DIALOGUE_BACKBONE_RE: RegExp;
+export declare const MOSS_DECODER_RE: RegExp;
+export declare const MOSS_ENCODER_RE: RegExp;
+export declare const MOSS_NATIVE_SAMPLE_RATE = 24000;
+export declare const MOSS_FRAMES_PER_SECOND = 12.5;
+export declare const MOSS_MAX_NEW_TOKENS = 2048;
+export declare const MOSS_MAX_CHANNELS = 32;
+export declare const MOSS_TERMINATION_ROWS = 2;
+export declare const MOSS_MAX_DURATION_TOKENS: number;
+export declare const MOSS_INSTANCE_VOICE_KEYS: readonly ["referenceAudio", "dialogueReferences"];
+export declare function assertMossDurationTokens(value: number | null | undefined, where: string): void;
+export declare function resolveMossModelPaths(files: NormalizedFiles, dialogue: boolean): Pick<ModelPaths, "mossBackbonePath" | "mossCodecDecoderPath" | "mossCodecEncoderPath">;
+/** The MOSS voice and length options, read before model paths are resolved. */
+export declare function mossVoiceSettings(options: {
+    dialogueReferences?: string[];
+    durationTokens?: number;
+}): Pick<SynthesisSettings, "dialogueReferences" | "durationTokens">;
+export declare function assertMossOptions(setup: EngineSetup): void;
+export declare function assertMossOutputRate(setup: EngineSetup): void;
+export declare function buildMossParams(setup: EngineSetup): TTSConfigurationParams;
+export declare function assertMossReloadKeepsVoice(setup: EngineSetup, newConfig: Record<string, unknown>): void;
+export declare function applyMossReload(setup: EngineSetup, newConfig: Record<string, unknown>): void;

package/lib/engines/moss.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOSS_INSTANCE_VOICE_KEYS = exports.MOSS_MAX_DURATION_TOKENS = exports.MOSS_TERMINATION_ROWS = exports.MOSS_MAX_CHANNELS = exports.MOSS_MAX_NEW_TOKENS = exports.MOSS_FRAMES_PER_SECOND = exports.MOSS_NATIVE_SAMPLE_RATE = exports.MOSS_ENCODER_RE = exports.MOSS_DECODER_RE = exports.MOSS_DIALOGUE_BACKBONE_RE = exports.MOSS_BACKBONE_RE = void 0;
+exports.assertMossDurationTokens = assertMossDurationTokens;
+exports.resolveMossModelPaths = resolveMossModelPaths;
+exports.mossVoiceSettings = mossVoiceSettings;
+exports.assertMossOptions = assertMossOptions;
+exports.assertMossOutputRate = assertMossOutputRate;
+exports.buildMossParams = buildMossParams;
+exports.assertMossReloadKeepsVoice = assertMossReloadKeepsVoice;
+exports.applyMossReload = applyMossReload;
+const engineIds_1 = require("../engineIds");
+const modelFiles_1 = require("../modelFiles");
+const nativeParams_1 = require("../nativeParams");
+const options_1 = require("../options");
+exports.MOSS_BACKBONE_RE = /^moss-tts-delay(-[a-z0-9_]+)?\.gguf$/i;
+exports.MOSS_DIALOGUE_BACKBONE_RE = /^moss-ttsd(-[a-z0-9_]+)?\.gguf$/i;
+exports.MOSS_DECODER_RE = /^moss-codec-decoder(-[a-z0-9_]+)?\.gguf$/i;
+exports.MOSS_ENCODER_RE = /^moss-codec-encoder(-[a-z0-9_]+)?\.gguf$/i;
+exports.MOSS_NATIVE_SAMPLE_RATE = 24000;
+exports.MOSS_FRAMES_PER_SECOND = 12.5;
+exports.MOSS_MAX_NEW_TOKENS = 2048;
+exports.MOSS_MAX_CHANNELS = 32;
+exports.MOSS_TERMINATION_ROWS = 2;
+exports.MOSS_MAX_DURATION_TOKENS = exports.MOSS_MAX_NEW_TOKENS - (exports.MOSS_MAX_CHANNELS - 1) - exports.MOSS_TERMINATION_ROWS;
+exports.MOSS_INSTANCE_VOICE_KEYS = ["referenceAudio", "dialogueReferences"];
+function isValidDurationTokens(value) {
+    return Number.isInteger(value) && value >= 0 && value <= exports.MOSS_MAX_DURATION_TOKENS;
+}
+function assertMossDurationTokens(value, where) {
+    if (value == null || isValidDurationTokens(value))
+        return;
+    throw new Error(`tts-ggml: ${where}: durationTokens must be an integer from 0 to ` +
+        `${exports.MOSS_MAX_DURATION_TOKENS} (0 = free length)`);
+}
+function copyDialogueReferences(references) {
+    if (references == null)
+        return undefined;
+    return Array.isArray(references)
+        ? [...references]
+        : references;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value !== "";
+}
+function assertDialogueReferenceList(references) {
+    if (Array.isArray(references) &&
+        references.length > 0 &&
+        references.every(isNonEmptyString)) {
+        return;
+    }
+    throw new Error("tts-ggml: dialogueReferences must be a non-empty array of WAV paths, " +
+        "one per speaker");
+}
+/** Dialogue synthesis needs the MOSS-TTSD backbone; plain TTS takes either. */
+function mossBackbonePatterns(dialogue) {
+    return dialogue
+        ? [exports.MOSS_DIALOGUE_BACKBONE_RE]
+        : [exports.MOSS_BACKBONE_RE, exports.MOSS_DIALOGUE_BACKBONE_RE];
+}
+function findMossBackbone(modelDir, dialogue) {
+    return (0, modelFiles_1.firstNonEmpty)(...mossBackbonePatterns(dialogue).map((pattern) => (0, modelFiles_1.findQuantRankedGguf)(modelDir, pattern)));
+}
+function resolveMossModelPaths(files, dialogue) {
+    return {
+        mossBackbonePath: (0, modelFiles_1.firstNonEmpty)(files.mossBackbone, findMossBackbone(files.modelDir, dialogue)),
+        mossCodecDecoderPath: (0, modelFiles_1.firstNonEmpty)(files.mossCodecDecoder, (0, modelFiles_1.findQuantRankedGguf)(files.modelDir, exports.MOSS_DECODER_RE)),
+        mossCodecEncoderPath: (0, modelFiles_1.firstNonEmpty)(files.mossCodecEncoder, (0, modelFiles_1.findQuantRankedGguf)(files.modelDir, exports.MOSS_ENCODER_RE)),
+    };
+}
+/** The MOSS voice and length options, read before model paths are resolved. */
+function mossVoiceSettings(options) {
+    return {
+        dialogueReferences: copyDialogueReferences(options.dialogueReferences),
+        durationTokens: options.durationTokens ?? undefined,
+    };
+}
+function assertMossOptions(setup) {
+    if (setup.engineType !== engineIds_1.ENGINE_MOSS) {
+        assertNoMossOnlyOptions(setup);
+        return;
+    }
+    if (setup.backend.enhancerGgufPath || setup.backend.denoiserGgufPath) {
+        throw new Error("tts-ggml: the LavaSR enhancer/denoiser are not supported with " +
+            "the moss engine. Drop lavasrEnhancer / lavasrDenoiser.");
+    }
+    assertMossOutputRate(setup);
+    assertMossVoiceConsistent(setup);
+    assertMossDurationTokens(setup.settings.durationTokens, "constructor");
+    assertMossDialogueReferences(setup);
+}
+function assertNoMossOnlyOptions(setup) {
+    const mossOnly = (0, options_1.setOptionNames)({
+        durationTokens: setup.settings.durationTokens,
+        dialogueReferences: setup.settings.dialogueReferences !== undefined || undefined,
+    });
+    if (mossOnly.length === 0)
+        return;
+    throw new Error(`tts-ggml: ${mossOnly.join(", ")} are moss-only options ` +
+        `(engine is ${setup.engineType})`);
+}
+function assertMossDialogueReferences(setup) {
+    if (setup.settings.dialogueReferences === undefined)
+        return;
+    assertDialogueReferenceList(setup.settings.dialogueReferences);
+    if (setup.settings.referenceAudio) {
+        throw new Error("tts-ggml: referenceAudio and dialogueReferences are exclusive; " +
+            "pass one recording per speaker in dialogueReferences");
+    }
+    if (!setup.paths.mossCodecEncoderPath) {
+        throw new Error("tts-ggml: dialogue synthesis with the moss engine needs the codec " +
+            "encoder GGUF (files.mossCodecEncoder)");
+    }
+    if (!setup.paths.mossBackbonePath) {
+        throw new Error("tts-ggml: dialogue synthesis with the moss engine needs the MOSS-TTSD " +
+            "backbone: stage moss-ttsd-*.gguf in modelDir or set files.mossBackbone");
+    }
+}
+function assertMossOutputRate(setup) {
+    if (setup.outputSampleRate == null ||
+        setup.outputSampleRate === exports.MOSS_NATIVE_SAMPLE_RATE) {
+        return;
+    }
+    throw new Error(`tts-ggml: the moss engine emits ${exports.MOSS_NATIVE_SAMPLE_RATE} Hz only; ` +
+        `drop outputSampleRate (got ${setup.outputSampleRate}).`);
+}
+function assertMossVoiceConsistent(setup) {
+    if (!setup.settings.referenceAudio || setup.paths.mossCodecEncoderPath)
+        return;
+    throw new Error("tts-ggml: voice cloning with the moss engine needs the codec " +
+        "encoder GGUF (files.mossCodecEncoder)");
+}
+function buildMossParams(setup) {
+    assertMossOutputRate(setup);
+    const parameters = {
+        engineType: engineIds_1.ENGINE_MOSS,
+        mossBackbonePath: setup.paths.mossBackbonePath || "",
+        mossCodecDecoderPath: setup.paths.mossCodecDecoderPath || "",
+        language: setup.config.language || "en",
+    };
+    if (setup.paths.mossCodecEncoderPath) {
+        parameters.mossCodecEncoderPath = setup.paths.mossCodecEncoderPath;
+    }
+    if (setup.settings.referenceAudio != null) {
+        parameters.referenceAudio = setup.settings.referenceAudio;
+    }
+    if (setup.settings.dialogueReferences) {
+        parameters.dialogueReferences = [...setup.settings.dialogueReferences];
+    }
+    if (setup.settings.durationTokens != null) {
+        parameters.durationTokens = setup.settings.durationTokens | 0;
+    }
+    if (setup.settings.streamChunkTokens != null) {
+        parameters.streamChunkTokens = setup.settings.streamChunkTokens | 0;
+    }
+    (0, nativeParams_1.assignBackendParams)(setup, parameters);
+    return parameters;
+}
+function assertMossReloadKeepsVoice(setup, newConfig) {
+    if (setup.engineType !== engineIds_1.ENGINE_MOSS)
+        return;
+    const voiceKeys = exports.MOSS_INSTANCE_VOICE_KEYS.filter((key) => newConfig[key] !== undefined);
+    if (voiceKeys.length === 0)
+        return;
+    throw new Error(`tts-ggml: reload: the moss engine encodes ${voiceKeys.join(", ")} ` +
+        "once per instance; create a new instance to clone different recordings");
+}
+function applyMossReload(setup, newConfig) {
+    if (setup.engineType !== engineIds_1.ENGINE_MOSS)
+        return;
+    const durationTokens = newConfig
+        .durationTokens;
+    if (durationTokens === undefined)
+        return;
+    assertMossDurationTokens(durationTokens, "reload");
+    setup.settings.durationTokens = durationTokens ?? undefined;
+}

package/lib/engines/mossSoundEffect.d.ts

@@ -0,0 +1,41 @@
+import type { TTSConfigurationParams } from "../../tts";
+import type { EngineSetup, ModelPaths } from "../engineSetup";
+import { type NormalizedFiles } from "../modelFiles";
+export declare const MOSS_SFX_RE: RegExp;
+export declare const MOSS_SFX_NATIVE_SAMPLE_RATE = 48000;
+export declare const MOSS_SFX_MAX_SECONDS = 30;
+export declare const MOSS_SFX_MAX_STEPS = 1000;
+export declare const MOSS_SFX_MAX_GUIDANCE = 50;
+export declare const MOSS_SFX_MAX_SHIFT = 100;
+export declare const MOSS_SFX_CALL_KEYS: readonly ["seconds", "negativePrompt", "steps", "guidance", "shift"];
+/**
+ * MOSS-SoundEffect per-call generation controls (moss-sfx only). Each one is
+ * optional; unset `steps` / `guidance` / `shift` use the defaults stored in the
+ * model file (100 steps, guidance 4, shift 5).
+ */
+export interface MossSoundEffectFields {
+    /** Length of the sound effect, in (0, 30] seconds, rounded to 0.1 s. Defaults to 10. */
+    seconds?: number;
+    /** What the sound effect should avoid (classifier-free guidance negative). */
+    negativePrompt?: string;
+    /** Diffusion steps, 1..1000. More steps cost proportionally more time. */
+    steps?: number;
+    /** Classifier-free guidance scale, 1..50; 1 skips the negative branch. */
+    guidance?: number;
+    /** Flow-matching schedule shift, (0, 100]. */
+    shift?: number;
+}
+export declare function assertSoundEffectFields(fields: MossSoundEffectFields): void;
+/**
+ * Collect the MOSS-SoundEffect generation controls present on `source`.
+ * Returns undefined when none are set.
+ */
+export declare function pickSoundEffectFields(source: MossSoundEffectFields | null | undefined): MossSoundEffectFields | undefined;
+export declare function resolveMossSoundEffectModelPaths(files: NormalizedFiles): Pick<ModelPaths, "mossSoundEffectPath">;
+export declare function assertMossSoundEffectOptions(setup: EngineSetup): void;
+/**
+ * Extract + validate the per-call MOSS-SoundEffect controls from a run
+ * input. Returns undefined when none are present.
+ */
+export declare function resolveSoundEffectJobFields(setup: EngineSetup, source: MossSoundEffectFields | null | undefined, where: string): MossSoundEffectFields | undefined;
+export declare function buildMossSoundEffectParams(setup: EngineSetup): TTSConfigurationParams;