@moolam/bindings-speech 1.0.0

package/dist/tts_binding.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Local TTS behind SpeechInterface.synthesize.
+ *
+ * supportedLanguages lists only languages with loaded voice models.
+ * Unsupported BCP-47 codes route to the declared fallback language and
+ * surface `outcome: "fallback"` telemetry — never throw, never silent
+ * English substitution without that signal.
+ */
+import type { AudioChunk, SpeechInterface, SpeechSynthesisOptions, TranscriptSegment } from "@moolam/contracts";
+import type { SpeechConformanceHarness } from "@moolam/contract-conformance";
+export declare const TTS_PACKAGE_ROOT: string;
+export declare const DEFAULT_TTS_VOICES_MANIFEST: string;
+/** Human+machine Indic TTS coverage card (language → voice + fallback policy). */
+export declare const DEFAULT_TTS_MODEL_CARD: string;
+export declare const LOCAL_TTS_ENGINE = "local-tts-v1";
+export declare const TTS_SAMPLE_RATE_HZ = 16000;
+export declare const TTS_STREAM_CHUNK_LIMIT = 64;
+/** Max UTF-16 code units accepted per synthesize call (NFR / scalability). */
+export declare const TTS_TEXT_CHAR_LIMIT = 4096;
+/** PCM samples per streamed audio chunk (~40ms @ 16kHz). */
+export declare const TTS_SAMPLES_PER_CHUNK = 640;
+export type TtsVoiceCard = {
+    voiceId: string;
+    language: string;
+    sampleRateHz: number;
+};
+export type TtsVoicesManifest = {
+    schemaVersion: string;
+    engine: string;
+    fallbackLanguage: string;
+    voices: TtsVoiceCard[];
+    mixedScriptPolicy?: string;
+    description?: string;
+};
+export type TtsLanguageVoiceCoverageRow = {
+    language: string;
+    voiceId: string;
+    sampleRateHz: number;
+    script: string;
+    role: string;
+};
+export type TtsVoiceModelCard = {
+    schemaVersion: string;
+    engine: string;
+    locality: "on-device" | "self-hosted";
+    description: string;
+    fallbackLanguage: string;
+    fallbackPolicy: {
+        unsupportedBcp47: string;
+        emptyText: string;
+        mixedScript: string;
+    };
+    coverage: TtsLanguageVoiceCoverageRow[];
+    observability: {
+        event: string;
+        neverEmit: string;
+        requiredFields: string[];
+    };
+    voicesManifestRelpath: string;
+};
+export type LocalTtsTelemetryOp = "load" | "unload" | "synthesize" | "transcribe";
+/** Metadata-only telemetry — never raw synthesis text bodies. */
+export type LocalTtsTelemetryEvent = {
+    event: "bindings_speech.tts";
+    op: LocalTtsTelemetryOp;
+    outcome: "ok" | "error" | "fallback";
+    subjectId: string;
+    deviceId: string;
+    engine: typeof LOCAL_TTS_ENGINE;
+    languageCount?: number;
+    chunkCount?: number;
+    /** Effective BCP-47 after fallback resolution. */
+    effectiveLanguage?: string;
+    /** Requested BCP-47 (may differ when fallback fired). */
+    requestedLanguage?: string;
+    voiceId?: string;
+    usedFallback?: boolean;
+    failureClass?: "config" | "validation" | "not_loaded" | "native";
+    detail?: string;
+};
+export type LoadLocalTtsOptions = {
+    subjectId: string;
+    deviceId: string;
+    voicesManifestPath?: string;
+    onTelemetry?: (event: LocalTtsTelemetryEvent) => void;
+    backend?: LocalTtsNativeBackend;
+};
+export declare class LocalTtsError extends Error {
+    readonly failureClass: NonNullable<LocalTtsTelemetryEvent["failureClass"]>;
+    constructor(message: string, failureClass: NonNullable<LocalTtsTelemetryEvent["failureClass"]>);
+}
+export type LocalTtsNativeHandle = {
+    readonly id: string;
+};
+export type LocalTtsSynthesizeNativeParams = {
+    text: string;
+    language: string;
+    voiceId: string;
+    sampleRateHz: number;
+    speakingRate: number;
+    signal?: AbortSignal;
+};
+export type LocalTtsSynthesizeNativeResult = {
+    /** Streamed PCM chunks (s16le mono). */
+    chunks: Uint8Array[];
+    sampleRateHz: number;
+};
+export type LocalTtsNativeBackend = {
+    readonly kind: "in-process" | "native-addon";
+    load(modelId: string): Promise<LocalTtsNativeHandle>;
+    unload(handle: LocalTtsNativeHandle): Promise<void>;
+    synthesize(handle: LocalTtsNativeHandle, params: LocalTtsSynthesizeNativeParams): Promise<LocalTtsSynthesizeNativeResult>;
+};
+/**
+ * In-process local TTS stand-in: streams PCM chunks; mixed-script text
+ * does not crash. Production injects a real on-device TTS addon.
+ */
+export declare function createInProcessLocalTtsBackend(): LocalTtsNativeBackend;
+export declare function loadTtsVoicesManifest(manifestPath?: string): TtsVoicesManifest;
+/** Languages actually backed by a loaded voice model (truthful declaration). */
+export declare function languagesFromVoices(voices: readonly TtsVoiceCard[]): string[];
+/**
+ * Load the TTS voice model card and require parity with the voices manifest
+ * (language set, voiceIds, fallbackLanguage). Coverage is never aspirational.
+ */
+export declare function loadTtsVoiceModelCard(cardPath?: string, voicesManifestPath?: string): TtsVoiceModelCard;
+/** Language → voiceId rows for README / hosts (order matches model card). */
+export declare function languageVoiceCoverageTable(card?: TtsVoiceModelCard): ReadonlyArray<{
+    language: string;
+    voiceId: string;
+    role: string;
+}>;
+export declare function assertTtsModelCardMatchesVoices(card: TtsVoiceModelCard, manifest: TtsVoicesManifest): void;
+export declare function resolveTtsVoice(args: {
+    voices: readonly TtsVoiceCard[];
+    fallbackLanguage: string;
+    requestedLanguage: string;
+    voiceId?: string;
+}): {
+    voice: TtsVoiceCard;
+    effectiveLanguage: string;
+    usedFallback: boolean;
+};
+export declare class LocalTtsBinding implements SpeechInterface {
+    #private;
+    constructor(args: {
+        subjectId: string;
+        deviceId: string;
+        voices: readonly TtsVoiceCard[];
+        fallbackLanguage: string;
+        backend: LocalTtsNativeBackend;
+        handle: LocalTtsNativeHandle;
+        onTelemetry?: (event: LocalTtsTelemetryEvent) => void;
+        mixedScriptPolicy?: string;
+    });
+    get supportedLanguages(): string[];
+    get fallbackLanguage(): string;
+    get voices(): TtsVoiceCard[];
+    get subjectId(): string;
+    get deviceId(): string;
+    get engine(): typeof LOCAL_TTS_ENGINE;
+    get mixedScriptPolicy(): string | undefined;
+    unload(): Promise<void>;
+    /**
+     * STT stub so SpeechInterface is complete for CK-05.1 when using TTS-first
+     * hosts. Full STT is {@link WhisperCppSpeechBinding}.
+     */
+    transcribe(audio: AsyncIterable<AudioChunk>): AsyncIterable<TranscriptSegment>;
+    synthesize(text: string, options: SpeechSynthesisOptions): AsyncIterable<AudioChunk>;
+}
+/**
+ * Load local TTS: voices manifest → truthful supportedLanguages → FFI seam.
+ */
+export declare function loadLocalTts(options: LoadLocalTtsOptions): Promise<LocalTtsBinding>;
+export type CreateLocalTtsSpeechHarnessOptions = {
+    subjectId?: string;
+    deviceId?: string;
+    voicesManifestPath?: string;
+    onTelemetry?: (event: LocalTtsTelemetryEvent) => void;
+    backend?: LocalTtsNativeBackend;
+};
+/** Conformance factory for CK-05 against the local TTS binding. */
+export declare function createLocalTtsSpeechHarnessFactory(options?: CreateLocalTtsSpeechHarnessOptions): (ctx?: {
+    subjectId?: string;
+    deviceId?: string;
+}) => Promise<SpeechConformanceHarness>;
+//# sourceMappingURL=tts_binding.d.ts.map

package/dist/tts_binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts_binding.d.ts","sourceRoot":"","sources":["../src/tts_binding.ts"],"names":[],"mappings":"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"}