react-native-sherpa-onnx 0.2.0 → 0.3.0

package/lib/typescript/src/tts/index.d.ts

@@ -1,251 +1,65 @@
-import type { TTSInitializeOptions, TtsUpdateOptions, SynthesisOptions, GeneratedAudio, GeneratedAudioWithTimestamps, TTSModelInfo, TtsStreamChunk, TtsStreamEnd, TtsStreamError } from './types';
-import type { InitializeOptions } from '../types';
+import type { TTSInitializeOptions, TTSModelType, GeneratedAudio, TtsEngine } from './types';
+import type { ModelPathConfig } from '../types';
 /**
- * Initialize Text-to-Speech (TTS) with model directory.
+ * Detect TTS model type and structure without initializing the engine.
+ * Uses the same native file-based detection as createTTS. Stateless; no instance required.
  *
- * Supports multiple model source types:
- * - Asset models (bundled in app)
- * - File system models (downloaded or user-provided)
- * - Auto-detection (tries asset first, then file system)
- *
- * Supported model types (auto-detected or explicit):
- * - VITS (includes Piper, Coqui, MeloTTS, MMS)
- * - Matcha (acoustic model + vocoder)
- * - Kokoro (multi-speaker, multi-language)
- * - KittenTTS (lightweight, multi-speaker)
- * - Zipvoice (voice cloning capable)
- *
- * @param options - TTS initialization options or model path configuration
- * @returns Promise resolving to result with success and detected models
+ * @param modelPath - Model path configuration (asset, file, or auto)
+ * @param options - Optional modelType (default: 'auto')
+ * @returns Object with success, detectedModels (array of { type, modelDir }), and modelType (primary detected type)
  * @example
  * ```typescript
- * // Simple string (auto-detect)
- * const result = await initializeTTS('models/sherpa-onnx-vits-piper-en_US-lessac-medium');
- * console.log('Detected models:', result.detectedModels);
- *
- * // Asset model
- * const result = await initializeTTS({
- *   modelPath: { type: 'asset', path: 'models/vits-piper-en' }
- * });
- *
- * // File system model with options
- * const result = await initializeTTS({
- *   modelPath: { type: 'file', path: '/path/to/model' },
- *   numThreads: 4,
- *   debug: true
- * });
- *
- * // With explicit model type
- * const result = await initializeTTS({
- *   modelPath: { type: 'asset', path: 'models/kokoro-en' },
- *   modelType: 'kokoro'
- * });
+ * const result = await detectTtsModel({ type: 'asset', path: 'models/vits-piper-en' });
+ * if (result.success) console.log('Detected type:', result.modelType, result.detectedModels);
  * ```
  */
-export declare function initializeTTS(options: TTSInitializeOptions | InitializeOptions['modelPath']): Promise<{
+export declare function detectTtsModel(modelPath: ModelPathConfig, options?: {
+    modelType?: TTSModelType;
+}): Promise<{
     success: boolean;
     detectedModels: Array<{
         type: string;
         modelDir: string;
     }>;
+    modelType?: string;
 }>;
 /**
- * Update TTS parameters by re-initializing with stored config.
- */
-export declare function updateTtsParams(options: TtsUpdateOptions): Promise<{
-    success: boolean;
-    detectedModels: Array<{
-        type: string;
-        modelDir: string;
-    }>;
-}>;
-/**
- * Generate speech from text.
+ * Create a TTS engine instance. Call destroy() on the returned engine when done to free native resources.
  *
- * Returns raw audio samples as float array in range [-1.0, 1.0].
- * You can save these samples to a WAV file, stream them, or process them further.
- *
- * @param text - Text to convert to speech
- * @param options - Synthesis options (speaker ID, speed)
- * @returns Promise resolving to generated audio data
+ * @param options - TTS initialization options or model path configuration
+ * @returns Promise resolving to a TtsEngine instance
  * @example
  * ```typescript
- * // Basic usage
- * const audio = await generateSpeech('Hello, world!');
- * console.log(`Generated ${audio.samples.length} samples at ${audio.sampleRate} Hz`);
- *
- * // With options
- * const audio = await generateSpeech('Hello, world!', {
- *   sid: 0,      // Speaker ID (for multi-speaker models)
- *   speed: 1.2   // 20% faster
+ * const tts = await createTTS({
+ *   modelPath: { type: 'asset', path: 'models/vits-piper-en' },
+ *   modelType: 'vits',
+ *   modelOptions: { vits: { noiseScale: 0.667 } },
  * });
- *
- * // Slower speech
- * const audio = await generateSpeech('Speak slowly', { speed: 0.8 });
+ * const audio = await tts.generateSpeech('Hello world');
+ * await tts.destroy();
  * ```
  */
-export declare function generateSpeech(text: string, options?: SynthesisOptions): Promise<GeneratedAudio>;
-/**
- * Generate speech from text and return subtitle/timestamp metadata.
- *
- * Timestamps are estimated based on the output duration when models do not
- * provide native timing information.
- */
-export declare function generateSpeechWithTimestamps(text: string, options?: SynthesisOptions): Promise<GeneratedAudioWithTimestamps>;
-export type TtsStreamHandlers = {
-    onChunk?: (chunk: TtsStreamChunk) => void;
-    onEnd?: (event: TtsStreamEnd) => void;
-    onError?: (event: TtsStreamError) => void;
-};
-/**
- * Generate speech in streaming mode (emits chunk events).
- *
- * Returns an unsubscribe function to remove event listeners.
- */
-export declare function generateSpeechStream(text: string, options: SynthesisOptions | undefined, handlers: TtsStreamHandlers): Promise<() => void>;
-/**
- * Cancel ongoing streaming TTS generation.
- */
-export declare function cancelSpeechStream(): Promise<void>;
-/**
- * Start PCM playback for streaming TTS.
- */
-export declare function startTtsPcmPlayer(sampleRate: number, channels: number): Promise<void>;
-/**
- * Write PCM samples to the streaming TTS player.
- */
-export declare function writeTtsPcmChunk(samples: number[]): Promise<void>;
-/**
- * Stop PCM playback for streaming TTS.
- */
-export declare function stopTtsPcmPlayer(): Promise<void>;
-/**
- * Get TTS model information.
- *
- * Returns the sample rate and number of available speakers/voices.
- * Call this after initialization to check model capabilities.
- *
- * @returns Promise resolving to model information
- * @example
- * ```typescript
- * await initializeTTS('models/kokoro-en');
- * const info = await getModelInfo();
- *
- * console.log(`Sample rate: ${info.sampleRate} Hz`);
- * console.log(`Available speakers: ${info.numSpeakers}`);
- *
- * if (info.numSpeakers > 1) {
- *   // Multi-speaker model, can use different voices
- *   const audio = await generateSpeech('Hello', { sid: 1 });
- * }
- * ```
- */
-export declare function getModelInfo(): Promise<TTSModelInfo>;
-/**
- * Get the sample rate of the initialized TTS model.
- *
- * @returns Promise resolving to sample rate in Hz
- * @example
- * ```typescript
- * const sampleRate = await getSampleRate();
- * console.log(`Model outputs audio at ${sampleRate} Hz`);
- * ```
- */
-export declare function getSampleRate(): Promise<number>;
-/**
- * Get the number of speakers/voices available in the model.
- *
- * @returns Promise resolving to number of speakers
- * - 0 or 1: Single-speaker model
- * - >1: Multi-speaker model
- * @example
- * ```typescript
- * const numSpeakers = await getNumSpeakers();
- *
- * if (numSpeakers > 1) {
- *   console.log(`Model has ${numSpeakers} different voices`);
- *   // Generate with different voices
- *   for (let i = 0; i < numSpeakers; i++) {
- *     const audio = await generateSpeech('Hello', { sid: i });
- *     // ... use audio
- *   }
- * }
- * ```
- */
-export declare function getNumSpeakers(): Promise<number>;
-/**
- * Release TTS resources.
- *
- * Call this when you're done using TTS to free up memory.
- * After calling this, you must call `initializeTTS()` again before
- * using TTS functions.
- *
- * @example
- * ```typescript
- * await initializeTTS('models/vits-piper-en');
- * const audio = await generateSpeech('Hello');
- * // ... use audio
- * await unloadTTS(); // Free resources
- * ```
- */
-export declare function unloadTTS(): Promise<void>;
+export declare function createTTS(options: TTSInitializeOptions | ModelPathConfig): Promise<TtsEngine>;
 /**
  * Save generated TTS audio to a WAV file.
- *
- * @param audio - Generated audio from generateSpeech()
- * @param filePath - Absolute path where to save the WAV file
- * @returns Promise resolving to the file path where audio was saved
- * @example
- * ```typescript
- * import { Platform } from 'react-native';
- * import RNFS from 'react-native-fs';
- *
- * const audio = await generateSpeech('Hello, world!');
- *
- * // Save to documents directory
- * const documentsPath = Platform.OS === 'ios'
- *   ? RNFS.DocumentDirectoryPath
- *   : RNFS.ExternalDirectoryPath;
- * const filePath = `${documentsPath}/speech_${Date.now()}.wav`;
- *
- * const savedPath = await saveAudioToFile(audio, filePath);
- * console.log('Audio saved to:', savedPath);
- * ```
  */
 export declare function saveAudioToFile(audio: GeneratedAudio, filePath: string): Promise<string>;
 /**
  * Save generated TTS audio to a WAV file via Android SAF content URI.
- *
- * @param audio - Generated audio from generateSpeech()
- * @param directoryUri - Directory content URI from SAF
- * @param filename - Desired file name
- * @returns Promise resolving to content URI of the saved file
  */
 export declare function saveAudioToContentUri(audio: GeneratedAudio, directoryUri: string, filename: string): Promise<string>;
 /**
  * Save a text file via Android SAF content URI.
- *
- * @param text - Text content to write
- * @param directoryUri - Directory content URI from SAF
- * @param filename - Desired file name
- * @param mimeType - MIME type (default: text/plain)
- * @returns Promise resolving to content URI of the saved file
  */
 export declare function saveTextToContentUri(text: string, directoryUri: string, filename: string, mimeType?: string): Promise<string>;
 /**
  * Copy a SAF content URI to a cache file for local playback (Android only).
- *
- * @param fileUri - Content URI of the saved WAV file
- * @param filename - Desired cache filename
- * @returns Promise resolving to absolute path of the cached file
  */
 export declare function copyContentUriToCache(fileUri: string, filename: string): Promise<string>;
 /**
  * Share a TTS audio file (file path or content URI).
- *
- * @param fileUri - File path or content URI
- * @param mimeType - MIME type (default: audio/wav)
  */
 export declare function shareAudioFile(fileUri: string, mimeType?: string): Promise<void>;
-export type { TTSInitializeOptions, TTSModelType, SynthesisOptions, GeneratedAudio, GeneratedAudioWithTimestamps, TtsSubtitleItem, TTSModelInfo, } from './types';
+export type { TTSInitializeOptions, TTSModelType, TtsModelOptions, TtsVitsModelOptions, TtsMatchaModelOptions, TtsKokoroModelOptions, TtsKittenModelOptions, TtsPocketModelOptions, TtsUpdateOptions, TtsGenerationOptions, GeneratedAudio, GeneratedAudioWithTimestamps, TtsSubtitleItem, TTSModelInfo, TtsEngine, TtsStreamHandlers, TtsStreamChunk, TtsStreamEnd, TtsStreamError, } from './types';
+export { TTS_MODEL_TYPES } from './types';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/tts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tts/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tts/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EACpB,YAAY,EAIZ,cAAc,EAGd,SAAS,EAKV,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAqEhD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,eAAe,EAC1B,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,GACrC,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAGD;AA6BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,oBAAoB,GAAG,eAAe,GAC9C,OAAO,CAAC,SAAS,CAAC,CA4NpB;AAID;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAe,GACtB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,SAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf;AAGD,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,4BAA4B,EAC5B,eAAe,EACf,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}

package/lib/typescript/src/tts/types.d.ts

@@ -6,10 +6,53 @@ import type { ModelPathConfig } from '../types';
  * - 'matcha': Matcha models (acoustic model + vocoder)
  * - 'kokoro': Kokoro models (multi-speaker, multi-language)
  * - 'kitten': KittenTTS models (lightweight, multi-speaker)
+ * - 'pocket': Pocket TTS models
  * - 'zipvoice': Zipvoice models (voice cloning capable)
  * - 'auto': Auto-detect model type based on files present (default)
  */
-export type TTSModelType = 'vits' | 'matcha' | 'kokoro' | 'kitten' | 'zipvoice' | 'auto';
+export type TTSModelType = 'vits' | 'matcha' | 'kokoro' | 'kitten' | 'pocket' | 'zipvoice' | 'auto';
+/** Runtime list of supported TTS model types. */
+export declare const TTS_MODEL_TYPES: readonly TTSModelType[];
+/** Options for VITS models. Applied only when modelType is 'vits'. Kotlin OfflineTtsVitsModelConfig. */
+export interface TtsVitsModelOptions {
+    /** Noise scale. If omitted, model default (or model.json) is used. */
+    noiseScale?: number;
+    /** Noise scale W. If omitted, model default is used. */
+    noiseScaleW?: number;
+    /** Length scale. If omitted, model default is used. */
+    lengthScale?: number;
+}
+/** Options for Matcha models. Applied only when modelType is 'matcha'. Kotlin OfflineTtsMatchaModelConfig. */
+export interface TtsMatchaModelOptions {
+    /** Noise scale. If omitted, model default is used. */
+    noiseScale?: number;
+    /** Length scale. If omitted, model default is used. */
+    lengthScale?: number;
+}
+/** Options for Kokoro models. Applied only when modelType is 'kokoro'. Kotlin OfflineTtsKokoroModelConfig. */
+export interface TtsKokoroModelOptions {
+    /** Length scale. If omitted, model default is used. */
+    lengthScale?: number;
+}
+/** Options for KittenTTS models. Applied only when modelType is 'kitten'. Kotlin OfflineTtsKittenModelConfig. */
+export interface TtsKittenModelOptions {
+    /** Length scale. If omitted, model default is used. */
+    lengthScale?: number;
+}
+/** Options for Pocket TTS models. Applied only when modelType is 'pocket'. Kotlin has no init-time model config for pocket; reserved for future use. */
+export interface TtsPocketModelOptions {
+}
+/**
+ * Model-specific TTS options. Only the block for the actually loaded model type is applied;
+ * others are ignored (e.g. vits options have no effect when a kokoro model is loaded).
+ */
+export interface TtsModelOptions {
+    vits?: TtsVitsModelOptions;
+    matcha?: TtsMatchaModelOptions;
+    kokoro?: TtsKokoroModelOptions;
+    kitten?: TtsKittenModelOptions;
+    pocket?: TtsPocketModelOptions;
+}
 /**
  * Configuration for TTS initialization.
  */
@@ -18,7 +61,7 @@ export interface TTSInitializeOptions {
      * Path to the model directory.
      * Can be an asset path, file system path, or auto-detection path.
      */
-    modelPath: ModelPathConfig | string;
+    modelPath: ModelPathConfig;
     /**
      * Model type to use.
      * If not specified or 'auto', the model type will be auto-detected
@@ -27,6 +70,13 @@ export interface TTSInitializeOptions {
      * @default 'auto'
      */
     modelType?: TTSModelType;
+    /**
+     * Execution provider (e.g. `'cpu'`, `'coreml'`, `'xnnpack'`, `'nnapi'`, `'qnn'`).
+     * Use getCoreMlSupport(), getXnnpackSupport(), etc. to check availability. See execution-providers.md.
+     *
+     * @default 'cpu'
+     */
+    provider?: string;
     /**
      * Number of threads to use for inference.
      * More threads = faster processing but more CPU usage.
@@ -41,45 +91,51 @@ export interface TTSInitializeOptions {
      */
     debug?: boolean;
     /**
-     * Noise scale for VITS/Matcha models.
-     *
-     * If omitted, the model default (or model.json) is used.
+     * Model-specific options. Only options for the loaded model type are applied.
+     * E.g. when modelType is 'vits', only modelOptions.vits is used.
      */
-    noiseScale?: number;
+    modelOptions?: TtsModelOptions;
     /**
-     * Noise scale W for VITS models.
-     *
-     * If omitted, the model default (or model.json) is used.
+     * Path(s) to rule FSTs for TTS (OfflineTtsConfig.ruleFsts).
+     * Used for text normalization / ITN.
      */
-    noiseScaleW?: number;
+    ruleFsts?: string;
     /**
-     * Length scale for VITS/Matcha/Kokoro/Kitten models.
-     *
-     * If omitted, the model default (or model.json) is used.
+     * Path(s) to rule FARs for TTS (OfflineTtsConfig.ruleFars).
+     * Used for text normalization / ITN.
      */
-    lengthScale?: number;
+    ruleFars?: string;
+    /**
+     * Max number of sentences per streaming callback (OfflineTtsConfig.maxNumSentences).
+     * Default: 1.
+     */
+    maxNumSentences?: number;
+    /**
+     * Silence scale on config level (OfflineTtsConfig.silenceScale).
+     * Default: 0.2.
+     */
+    silenceScale?: number;
 }
 /**
- * Options for updating TTS model parameters.
+ * Options for updating TTS model parameters at runtime.
+ * Only the block for the given modelType is applied; flattened to native noiseScale / noiseScaleW / lengthScale.
  */
 export interface TtsUpdateOptions {
     /**
-     * Noise scale for VITS/Matcha models.
-     */
-    noiseScale?: number | null;
-    /**
-     * Noise scale W for VITS models.
+     * Model type currently loaded. When omitted or 'auto', the SDK uses the model type from the last
+     * successful initializeTTS(). After unloadTTS(), pass modelType explicitly until init is called again.
      */
-    noiseScaleW?: number | null;
+    modelType?: TTSModelType;
     /**
-     * Length scale for VITS/Matcha/Kokoro/Kitten models.
+     * Model-specific options. Only the block for the effective model type is used (e.g. modelOptions.vits when type is 'vits').
      */
-    lengthScale?: number | null;
+    modelOptions?: TtsModelOptions;
 }
 /**
- * Options for speech synthesis.
+ * Options for TTS generation. Maps to Kotlin GenerationConfig when reference
+ * audio or advanced options are used; otherwise simple sid/speed are used.
  */
-export interface SynthesisOptions {
+export interface TtsGenerationOptions {
     /**
      * Speaker ID for multi-speaker models.
      * For single-speaker models, this is ignored.
@@ -99,6 +155,34 @@ export interface SynthesisOptions {
      * @default 1.0
      */
     speed?: number;
+    /**
+     * Silence scale (Kotlin GenerationConfig.silenceScale). Used at generate time.
+     */
+    silenceScale?: number;
+    /**
+     * Reference audio for voice cloning (Kotlin GenerationConfig).
+     * In the Kotlin/RN stack, only Pocket TTS uses this; other model types (vits, matcha, kokoro, kitten) ignore it.
+     * Mono float samples in [-1, 1] and sample rate in Hz.
+     */
+    referenceAudio?: {
+        samples: number[];
+        sampleRate: number;
+    };
+    /**
+     * Transcript text of the reference audio (Kotlin GenerationConfig.referenceText).
+     * Required for Pocket TTS when referenceAudio is provided; ignored by other model types.
+     */
+    referenceText?: string;
+    /**
+     * Number of steps, e.g. flow-matching steps (Kotlin GenerationConfig.numSteps).
+     * Used by models such as Pocket.
+     */
+    numSteps?: number;
+    /**
+     * Extra options as key-value pairs (Kotlin GenerationConfig.extra).
+     * Model-specific (e.g. temperature, chunk_size for Pocket).
+     */
+    extra?: Record<string, string>;
 }
 /**
  * Generated audio data from TTS synthesis.
@@ -153,6 +237,8 @@ export interface GeneratedAudioWithTimestamps extends GeneratedAudio {
  * Streaming chunk event payload for TTS generation.
  */
 export interface TtsStreamChunk {
+    /** Instance ID (set by native for multi-instance routing). */
+    instanceId?: string;
     samples: number[];
     sampleRate: number;
     progress: number;
@@ -162,14 +248,51 @@ export interface TtsStreamChunk {
  * Streaming end event payload.
  */
 export interface TtsStreamEnd {
+    /** Instance ID (set by native for multi-instance routing). */
+    instanceId?: string;
     cancelled: boolean;
 }
 /**
  * Streaming error event payload.
  */
 export interface TtsStreamError {
+    /** Instance ID (set by native for multi-instance routing). */
+    instanceId?: string;
     message: string;
 }
+/**
+ * Handlers for TTS streaming generation (chunk, end, error).
+ */
+export interface TtsStreamHandlers {
+    onChunk?: (chunk: TtsStreamChunk) => void;
+    onEnd?: (event: TtsStreamEnd) => void;
+    onError?: (event: TtsStreamError) => void;
+}
+/**
+ * Instance-based TTS engine returned by createTTS().
+ * Call destroy() when done to free native resources.
+ */
+export interface TtsEngine {
+    readonly instanceId: string;
+    generateSpeech(text: string, options?: TtsGenerationOptions): Promise<GeneratedAudio>;
+    generateSpeechWithTimestamps(text: string, options?: TtsGenerationOptions): Promise<GeneratedAudioWithTimestamps>;
+    generateSpeechStream(text: string, options: TtsGenerationOptions | undefined, handlers: TtsStreamHandlers): Promise<() => void>;
+    cancelSpeechStream(): Promise<void>;
+    startPcmPlayer(sampleRate: number, channels: number): Promise<void>;
+    writePcmChunk(samples: number[]): Promise<void>;
+    stopPcmPlayer(): Promise<void>;
+    updateParams(options: TtsUpdateOptions): Promise<{
+        success: boolean;
+        detectedModels: Array<{
+            type: string;
+            modelDir: string;
+        }>;
+    }>;
+    getModelInfo(): Promise<TTSModelInfo>;
+    getSampleRate(): Promise<number>;
+    getNumSpeakers(): Promise<number>;
+    destroy(): Promise<void>;
+}
 /**
  * Information about TTS model capabilities.
  */

package/lib/typescript/src/tts/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/tts/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,SAAS,EAAE,eAAe,GAAG,MAAM,CAAC;IAEpC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IAEzB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,4BAA6B,SAAQ,cAAc;IAClE;;OAEG;IACH,SAAS,EAAE,eAAe,EAAE,CAAC;IAE7B;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/tts/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/types.d.ts

@@ -24,36 +24,4 @@ export type ModelPathConfig = {
     type: 'auto';
     path: string;
 };
-/**
- * Model type for explicit model detection
- */
-export type ModelType = 'transducer' | 'paraformer' | 'nemo_ctc' | 'whisper' | 'wenet_ctc' | 'sense_voice' | 'funasr_nano' | 'auto';
-/**
- * Model initialization options
- */
-export interface InitializeOptions {
-    /**
-     * Model directory path configuration
-     */
-    modelPath: ModelPathConfig | string;
-    /**
-     * Model quantization preference
-     * - true: Prefer int8 quantized models (model.int8.onnx) - smaller, faster
-     * - false: Prefer regular models (model.onnx) - higher accuracy
-     * - undefined: Try int8 first, then fall back to regular (default behavior)
-     */
-    preferInt8?: boolean;
-    /**
-     * Explicit model type specification
-     * - 'transducer': Force detection as Zipformer/Transducer model
-     * - 'paraformer': Force detection as Paraformer model
-     * - 'nemo_ctc': Force detection as NeMo CTC model
-     * - 'whisper': Force detection as Whisper model
-     * - 'wenet_ctc': Force detection as WeNet CTC model
-     * - 'sense_voice': Force detection as SenseVoice model
-     * - 'funasr_nano': Force detection as FunASR Nano model
-     * - 'auto': Automatic detection based on files (default)
-     */
-    modelType?: ModelType;
-}
 //# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB;IACE;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEN;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,SAAS,GACT,WAAW,GACX,aAAa,GACb,aAAa,GACb,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,EAAE,eAAe,GAAG,MAAM,CAAC;IAEpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB;IACE;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC"}