react-native-sherpa-onnx 0.3.6 → 0.3.7

package/src/download/validation.ts

@@ -3,6 +3,7 @@ import {
   stat,
   exists,
   readDir,
+  unlink,
   type ReadDirResItemT,
 } from '@dr.pogodin/react-native-fs';
 import SherpaOnnx from '../NativeSherpaOnnx';
@@ -25,6 +26,37 @@ export class ValidationResult {
   }
 }
 
+/**
+ * Delete a directory and all contents. No-op if the path is missing.
+ * Best-effort: continues on per-entry errors (permissions, race).
+ */
+export async function removeDirectoryRecursive(dirPath: string): Promise<void> {
+  if (!(await exists(dirPath))) return;
+  let entries: ReadDirResItemT[];
+  try {
+    entries = await readDir(dirPath);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const childPath = `${dirPath}/${entry.name}`.replace(/\/+/g, '/');
+    try {
+      if (entry.isDirectory()) {
+        await removeDirectoryRecursive(childPath);
+      } else {
+        await unlink(childPath);
+      }
+    } catch {
+      // ignore
+    }
+  }
+  try {
+    await unlink(dirPath);
+  } catch {
+    // ignore
+  }
+}
+
 /**
  * Parse checksum.txt format into a Map of filename -> hash
  * Expected format:
@@ -148,12 +180,15 @@ export async function validateExtractedFiles(
 
       for (const entry of entries) {
         if (entry.isDirectory()) {
-          const nested = await collectFilesRecursive(
-            entry.path,
-            depth + 1,
-            maxDepth
-          );
-          files.push(...nested);
+          const subPath = entry.path;
+          if (subPath != null) {
+            const nested = await collectFilesRecursive(
+              subPath,
+              depth + 1,
+              maxDepth
+            );
+            files.push(...nested);
+          }
         } else {
           files.push(entry);
         }
@@ -175,13 +210,13 @@ export async function validateExtractedFiles(
     }
 
     let hasModelLikeFiles = actualFiles.some((file) =>
-      isModelLikeFile(file.name)
+      isModelLikeFile(file.name ?? '')
     );
 
     if (!hasModelLikeFiles) {
       const nestedFiles = await collectFilesRecursive(modelDir);
       hasModelLikeFiles = nestedFiles.some((file) =>
-        isModelLikeFile(file.name)
+        isModelLikeFile(file.name ?? '')
       );
     }
 
@@ -203,6 +238,77 @@ export async function validateExtractedFiles(
   }
 }
 
+/** True if the file is a native sherpa-onnx model file (e.g. encoder.onnx). Excludes our metadata (.ready, manifest.json). */
+function isNativeModelFileName(name: string): boolean {
+  const lower = name.toLowerCase();
+  return lower.endsWith('.onnx') || lower.endsWith('.bin');
+}
+
+/**
+ * Check if a directory contains native model files (.onnx or .bin) at the top level or one level of subdirectories.
+ * Used to find the actual model dir; ignores our metadata (manifest.json, .ready).
+ */
+async function dirContainsModelFiles(dir: string): Promise<boolean> {
+  const entries = await readDir(dir);
+  const files = entries.filter((e) => !e.isDirectory());
+  if (files.some((f) => isNativeModelFileName(f.name ?? ''))) return true;
+  const subdirs = entries.filter((e) => e.isDirectory());
+  for (const sub of subdirs) {
+    const subPath = sub?.path;
+    if (subPath == null) continue;
+    const subEntries = await readDir(subPath);
+    const subFiles = subEntries.filter((e) => !e.isDirectory());
+    if (subFiles.some((f) => isNativeModelFileName(f.name ?? ''))) return true;
+  }
+  return false;
+}
+
+/**
+ * Resolve the directory that actually contains model files.
+ * After extracting a tarball, model files often end up in a single top-level subdirectory
+ * (e.g. installDir/modelId/encoder.onnx). Native APIs expect the path to the folder
+ * that directly contains encoder.onnx, decoder.onnx, etc.
+ *
+ * - If installDir itself contains native model files (.onnx/.bin), returns installDir.
+ * - If installDir has exactly one subdirectory that contains native model files, returns that subdirectory path.
+ *   (Ignores our metadata: .ready, manifest.json.) This can produce paths like
+ *   .../tts/vits-piper-de_DE-thorsten-medium-int8/vits-piper-de_DE-thorsten-medium-int8 when the
+ *   archive extracts a top-level folder with the same name as the model id; that is intentional.
+ * - Otherwise returns installDir unchanged.
+ */
+export async function resolveActualModelDir(
+  installDir: string
+): Promise<string> {
+  try {
+    const dirExists = await exists(installDir);
+    if (!dirExists) return installDir;
+
+    const entries = await readDir(installDir);
+    const topLevelFiles = entries.filter((e) => !e.isDirectory());
+    if (topLevelFiles.some((f) => isNativeModelFileName(f.name ?? ''))) {
+      return installDir;
+    }
+
+    const subdirs = entries.filter((e) => e.isDirectory());
+    const firstSubdir = subdirs[0];
+    const singleSubdir = subdirs.length === 1 ? firstSubdir : undefined;
+
+    if (singleSubdir != null) {
+      const candidatePath = singleSubdir.path;
+      if (
+        candidatePath != null &&
+        (await dirContainsModelFiles(candidatePath))
+      ) {
+        return candidatePath;
+      }
+    }
+
+    return installDir;
+  } catch {
+    return installDir;
+  }
+}
+
 /**
  * Get available disk space (in bytes)
  * This is a simplified version. For accurate values on Android/iOS, use native modules.

package/src/{download → extraction}/extractTarBz2.ts

@@ -47,7 +47,9 @@ export async function extractTarBz2(
   if (signal) {
     const onAbort = () => {
       try {
-        SherpaOnnx.cancelExtractTarBz2();
+        // Use per-path cancel so aborting this extraction doesn't affect
+        // other extractions that may be running in parallel.
+        SherpaOnnx.cancelExtractBySourcePath(sourcePath);
       } catch {
         // Ignore cancel errors to avoid crashing on abort.
       }

package/src/{download → extraction}/extractTarZst.ts

@@ -46,7 +46,9 @@ export async function extractTarZst(
   if (signal) {
     const onAbort = () => {
       try {
-        SherpaOnnx.cancelExtractTarZst();
+        // Use per-path cancel so aborting this extraction doesn't affect
+        // other extractions that may be running in parallel.
+        SherpaOnnx.cancelExtractBySourcePath(sourcePath);
       } catch {
         // Ignore cancel errors to avoid crashing on abort.
       }

package/src/extraction/index.ts

@@ -12,8 +12,8 @@
 import { DeviceEventEmitter, Platform } from 'react-native';
 import { readDir, stat, exists } from '@dr.pogodin/react-native-fs';
 import SherpaOnnx from '../NativeSherpaOnnx';
-import { extractTarZst } from '../download/extractTarZst';
-import { extractTarBz2 } from '../download/extractTarBz2';
+import { extractTarZst } from './extractTarZst';
+import { extractTarBz2 } from './extractTarBz2';
 import type {
   BundledArchive,
   ExtractArchiveOptions,
@@ -228,13 +228,9 @@ async function extractFromAsset(
   }
 
   if (signal) {
-    const cancel =
-      archive.format === 'tar.zst'
-        ? SherpaOnnx.cancelExtractTarZst
-        : SherpaOnnx.cancelExtractTarBz2;
     const onAbort = () => {
       try {
-        cancel();
+        SherpaOnnx.cancelExtractBySourcePath(archive.archivePath);
       } catch {
         // ignore
       }

package/src/index.tsx

@@ -18,6 +18,7 @@ export {
 
 export { copyFileToContentUri } from './tts';
 
+export { getModelLicenses, type ModelLicense } from './licenses';
 // Note: Feature-specific exports are available via subpath imports:
 // - import { createSTT, createStreamingSTT, ... } from 'react-native-sherpa-onnx/stt'
 // - import { createTTS, ... } from 'react-native-sherpa-onnx/tts'

package/src/licenses.ts

@@ -0,0 +1,100 @@
+import SherpaOnnx from './NativeSherpaOnnx';
+
+export interface ModelLicense {
+  asset_name: string;
+  license_type: string;
+  commercial_use: 'yes' | 'no' | 'conditional' | 'restricted' | 'unknown';
+  confidence: string;
+  detection_source: string;
+  license_file: string;
+}
+
+export async function getModelLicenses(): Promise<ModelLicense[]> {
+  const asrPath = 'model_licenses/asr-models-license-status.csv';
+  const qnnPath = 'model_licenses/qnn-asr-models-license-status.csv';
+  const ttsPath = 'model_licenses/tts-models-license-status.csv';
+
+  const results = await Promise.allSettled([
+    SherpaOnnx.readAssetFileAsUtf8(asrPath),
+    SherpaOnnx.readAssetFileAsUtf8(qnnPath),
+    SherpaOnnx.readAssetFileAsUtf8(ttsPath),
+  ]);
+
+  const [asrResult, qnnResult, ttsResult] = results;
+
+  const licenses: ModelLicense[] = [];
+
+  if (asrResult.status === 'fulfilled') {
+    licenses.push(...parseCsv(asrResult.value));
+  } else {
+    console.warn(
+      `[SherpaOnnx] Failed to load ASR model licenses: ${asrResult.reason}`
+    );
+  }
+
+  if (qnnResult.status === 'fulfilled') {
+    licenses.push(...parseCsv(qnnResult.value));
+  } else {
+    console.warn(
+      `[SherpaOnnx] Failed to load QNN model licenses: ${qnnResult.reason}`
+    );
+  }
+
+  if (ttsResult.status === 'fulfilled') {
+    licenses.push(...parseCsv(ttsResult.value));
+  } else {
+    console.warn(
+      `[SherpaOnnx] Failed to load TTS model licenses: ${ttsResult.reason}`
+    );
+  }
+
+  return licenses;
+}
+
+function parseCsv(csvString: string): ModelLicense[] {
+  const lines = csvString.split(/\r?\n/);
+  if (lines.length === 0) {
+    return [];
+  }
+
+  // The first line is the header
+  const headerLine = lines[0];
+  if (!headerLine) return [];
+
+  const headers = headerLine.split(',').map((h) => h.trim());
+
+  const results: ModelLicense[] = [];
+
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line || line.trim() === '') continue;
+
+    // The CSV has 6 columns: asset_name, license_type, commercial_use,
+    // confidence, detection_source, license_file.  The last column
+    // (license_file) may itself contain commas (e.g. URLs with query strings),
+    // so split into at most 6 parts and join any excess back into the last field.
+    const COLUMN_COUNT = 6;
+    const rawParts = line.split(',');
+    const parts =
+      rawParts.length <= COLUMN_COUNT
+        ? rawParts
+        : [
+            ...rawParts.slice(0, COLUMN_COUNT - 1),
+            rawParts.slice(COLUMN_COUNT - 1).join(','),
+          ];
+
+    const entry: Record<string, string> = {};
+    for (let j = 0; j < headers.length; j++) {
+      const header = headers[j];
+      if (header) {
+        entry[header] = (parts[j] ?? '').trim();
+      }
+    }
+
+    if (entry['asset_name']) {
+      results.push(entry as unknown as ModelLicense);
+    }
+  }
+
+  return results;
+}

package/src/stt/index.ts

@@ -40,7 +40,7 @@ function normalizeSttResult(raw: {
  *
  * @param modelPath - Model path configuration (asset, file, or auto)
  * @param options - Optional preferInt8 and modelType (default: auto)
- * @returns Object with success, detectedModels (array of { type, modelDir }), and modelType (primary detected type)
+ * @returns Object with success, detectedModels (array of { type, modelDir }), modelType (primary detected type), optional error when success is false, and optionally isHardwareSpecificUnsupported
  * @example
  * ```typescript
  * const path = { type: 'asset' as const, path: 'models/sherpa-onnx-whisper-tiny-en' };
@@ -55,15 +55,33 @@ export async function detectSttModel(
   options?: { preferInt8?: boolean; modelType?: STTModelType }
 ): Promise<{
   success: boolean;
+  /** Native validation/detect failure. */
+  error?: string;
   detectedModels: Array<{ type: string; modelDir: string }>;
   modelType?: string;
+  isHardwareSpecificUnsupported?: boolean;
 }> {
   const resolvedPath = await resolveModelPath(modelPath);
-  return SherpaOnnx.detectSttModel(
+  const raw = await SherpaOnnx.detectSttModel(
     resolvedPath,
     options?.preferInt8,
     options?.modelType
   );
+  const err =
+    typeof (raw as { error?: unknown }).error === 'string'
+      ? String((raw as { error: string }).error).trim()
+      : '';
+  return {
+    success: raw.success,
+    ...(err.length > 0 ? { error: err } : {}),
+    ...(raw.isHardwareSpecificUnsupported === true
+      ? { isHardwareSpecificUnsupported: true }
+      : {}),
+    detectedModels: raw.detectedModels ?? [],
+    ...(raw.modelType != null && raw.modelType !== ''
+      ? { modelType: raw.modelType }
+      : {}),
+  };
 }
 
 /**

package/src/stt/streaming.ts

@@ -82,6 +82,7 @@ function flattenInitOptionsForNative(options: StreamingSttInitOptions): {
   provider?: string;
   ruleFsts?: string;
   ruleFars?: string;
+  dither?: number;
   blankPenalty?: number;
   debug?: boolean;
   rule1MustContainNonSilence?: boolean;
@@ -107,6 +108,7 @@ function flattenInitOptionsForNative(options: StreamingSttInitOptions): {
     provider: options.provider,
     ruleFsts: options.ruleFsts,
     ruleFars: options.ruleFars,
+    dither: options.dither,
     blankPenalty: options.blankPenalty,
     debug: options.debug,
     rule1MustContainNonSilence: ep?.rule1?.mustContainNonSilence,
@@ -200,6 +202,7 @@ export async function createStreamingSTT(
   if (flat.provider !== undefined) nativeOptions.provider = flat.provider;
   if (flat.ruleFsts !== undefined) nativeOptions.ruleFsts = flat.ruleFsts;
   if (flat.ruleFars !== undefined) nativeOptions.ruleFars = flat.ruleFars;
+  if (flat.dither !== undefined) nativeOptions.dither = flat.dither;
   if (flat.blankPenalty !== undefined)
     nativeOptions.blankPenalty = flat.blankPenalty;
   if (flat.debug !== undefined) nativeOptions.debug = flat.debug;

package/src/stt/streamingTypes.ts

@@ -75,6 +75,11 @@ export interface StreamingSttInitOptions {
   ruleFsts?: string;
   /** Path(s) to rule FARs for ITN. */
   ruleFars?: string;
+  /**
+   * Feature extraction dither. **Android:** applied natively. **iOS:** ignored (C/CXX API has no
+   * `dither` on `FeatureConfig`); library default applies.
+   */
+  dither?: number;
   /** Blank penalty. */
   blankPenalty?: number;
   /** Enable debug logging. Default: false. */

package/src/stt/types.ts

@@ -228,7 +228,9 @@ export interface STTInitializeOptions {
   ruleFars?: string;
 
   /**
-   * Dither for feature extraction (Kotlin FeatureConfig.dither). Default 0.
+   * Dither for feature extraction (Kotlin `FeatureConfig.dither`). Default: no dither.
+   * **Android:** applied natively. **iOS:** ignored — the bundled sherpa-onnx C/CXX API does not
+   * expose this field; the native default is used.
    */
   dither?: number;
 

package/src/tts/index.ts

@@ -86,7 +86,7 @@ function flattenTtsModelOptionsForNative(
  *
  * @param modelPath - Model path configuration (asset, file, or auto)
  * @param options - Optional modelType (default: 'auto')
- * @returns Object with success, detectedModels (array of { type, modelDir }), modelType (primary detected type), and optionally lexiconLanguageCandidates (language ids for multi-lang Kokoro/Kitten)
+ * @returns Object with success, detectedModels (array of { type, modelDir }), modelType (primary detected type), optional error when success is false, and optionally lexiconLanguageCandidates (language ids for multi-lang Kokoro/Kitten)
  * @example
  * ```typescript
  * const result = await detectTtsModel({ type: 'asset', path: 'models/vits-piper-en' });
@@ -101,13 +101,31 @@ export async function detectTtsModel(
   options?: { modelType?: TTSModelType }
 ): Promise<{
   success: boolean;
+  /** Native validation/detect failure (e.g. missing lexicon for Zipvoice). */
+  error?: string;
   detectedModels: Array<{ type: string; modelDir: string }>;
   modelType?: string;
   /** Language ids from detected lexicon files ("default" for lexicon.txt, or e.g. "us-en", "zh" from lexicon-us-en.txt, lexicon-zh.txt). Present for Kokoro/Kitten; use for language selection UI. */
   lexiconLanguageCandidates?: string[];
 }> {
   const resolvedPath = await resolveModelPath(modelPath);
-  return SherpaOnnx.detectTtsModel(resolvedPath, options?.modelType);
+  const raw = await SherpaOnnx.detectTtsModel(resolvedPath, options?.modelType);
+  const err =
+    typeof (raw as { error?: unknown }).error === 'string'
+      ? String((raw as { error: string }).error).trim()
+      : '';
+  return {
+    success: raw.success,
+    ...(err.length > 0 ? { error: err } : {}),
+    detectedModels: raw.detectedModels ?? [],
+    ...(raw.modelType != null && raw.modelType !== ''
+      ? { modelType: raw.modelType }
+      : {}),
+    ...(raw.lexiconLanguageCandidates != null &&
+    raw.lexiconLanguageCandidates.length > 0
+      ? { lexiconLanguageCandidates: raw.lexiconLanguageCandidates }
+      : {}),
+  };
 }
 
 /**
@@ -124,6 +142,16 @@ function toNativeTtsOptions(
   if (options.silenceScale !== undefined)
     out.silenceScale = options.silenceScale;
   if (options.referenceAudio != null) {
+    const sr = options.referenceAudio.sampleRate;
+    if (
+      typeof __DEV__ !== 'undefined' &&
+      __DEV__ &&
+      (!Number.isFinite(sr) || sr <= 0)
+    ) {
+      console.warn(
+        '[react-native-sherpa-onnx] TTS referenceAudio.sampleRate must be > 0 for voice cloning (Zipvoice/Pocket).'
+      );
+    }
     out.referenceAudio = options.referenceAudio.samples;
     out.referenceSampleRate = options.referenceAudio.sampleRate;
   }

package/src/tts/streaming.ts

@@ -90,6 +90,16 @@ function toNativeTtsOptions(
   if (options.silenceScale !== undefined)
     out.silenceScale = options.silenceScale;
   if (options.referenceAudio != null) {
+    const sr = options.referenceAudio.sampleRate;
+    if (
+      typeof __DEV__ !== 'undefined' &&
+      __DEV__ &&
+      (!Number.isFinite(sr) || sr <= 0)
+    ) {
+      console.warn(
+        '[react-native-sherpa-onnx] TTS referenceAudio.sampleRate must be > 0 for voice cloning (Zipvoice/Pocket).'
+      );
+    }
     out.referenceAudio = options.referenceAudio.samples;
     out.referenceSampleRate = options.referenceAudio.sampleRate;
   }

package/src/tts/types.ts

@@ -202,15 +202,16 @@ export interface TtsGenerationOptions {
   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.
+   * Reference audio for voice cloning (native GenerationConfig / Zipvoice prompt).
+   * **Native (iOS & Android):** Requires non-empty samples and `sampleRate > 0`. Used for **Zipvoice** (cloning) and **Pocket** (Mimi encoder).
+   * Other model types (vits, matcha, kokoro, kitten) are **rejected** if reference audio is passed.
+   * Mono float samples in [-1, 1].
    */
   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.
+   * Transcript of the reference utterance for **Zipvoice** voice cloning (prompt text); **required** when cloning with Zipvoice (non-empty after trim).
+   * **Pocket:** not read by sherpa-onnx native code; optional, e.g. for app metadata only.
    */
   referenceText?: string;
 

package/src/utils.ts

@@ -1,6 +1,7 @@
 import { Platform } from 'react-native';
 import type { ModelPathConfig } from './types';
 import SherpaOnnx from './NativeSherpaOnnx';
+import { resolveActualModelDir } from './download';
 
 /**
  * Utility functions for model path handling
@@ -73,13 +74,33 @@ export function autoModelPath(path: string): ModelPathConfig {
  * This handles different path types (asset, file, auto) and returns
  * a platform-specific absolute path that can be used by native code.
  *
+ * For type 'file', the path is normalized so that when the given path is an
+ * install directory (e.g. with .ready and manifest.json and one model subdir),
+ * the returned path is the subdirectory that actually contains the .onnx files.
+ * This allows apps that build paths as baseDir/modelId to work without change.
+ *
  * @param config - Model path configuration
  * @returns Promise resolving to absolute path usable by native code
  */
 export async function resolveModelPath(
   config: ModelPathConfig
 ): Promise<string> {
-  return SherpaOnnx.resolveModelPath(config);
+  const path = await SherpaOnnx.resolveModelPath(config);
+  if (config.type === 'file') {
+    const resolved = await resolveActualModelDir(path);
+    // Diagnostic: log so we can tell if /usr/share/espeak-ng-data is due to our path or sherpa-onnx fallback.
+    if (__DEV__) {
+      console.log(
+        '[SherpaOnnx] resolveModelPath(file): native path=',
+        path,
+        resolved !== path
+          ? `resolvedActualModelDir=> ${resolved}`
+          : '(unchanged)'
+      );
+    }
+    return resolved;
+  }
+  return path;
 }
 
 /**

package/third_party/sherpa-onnx-prebuilt/ANDROID_RELEASE_TAG

@@ -1 +1 @@
-sherpa-onnx-android-v1.12.28
+sherpa-onnx-android-v1.12.31-1

package/third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG

@@ -1 +1 @@
-framework-v1.12.28
+sherpa-onnx-ios-v1.12.31-1