react-native-sherpa-onnx 0.3.8 → 0.4.0

package/src/download/paths.ts

@@ -122,7 +122,8 @@ export function getExtractionStatePath(
 /**
  * Directory where native `resolveAssetPath` materializes a bundled model folder
  * (`DocumentDirectoryPath/models/{modelId}` — Android internal `files/models/...`).
- * Separate from {@link getModelDir}. Remove on delete so empty dirs do not break detection.
+ * Separate from {@link getModelDir}. `deleteModelByCategory` does not remove this tree; it
+ * only deletes download-manager installs under `sherpa-onnx/models/`.
  */
 export function getNativeAssetExtractedModelDir(modelId: string): string {
   const safeId = modelId.replace(/[/\\]/g, '');

package/src/download/postDownloadProcessing.ts

@@ -43,6 +43,15 @@ export type RunPostDownloadProcessingOptions = {
   onChecksumIssue?: (issue: ChecksumIssue) => Promise<boolean>;
   deleteArchiveAfterExtract?: boolean;
   onProgress?: (progress: DownloadProgress) => void;
+  /**
+   * **Android:** Native extraction progress notification (default true), aligned with the download-manager flow.
+   * **iOS:** No effect.
+   */
+  showExtractionNotifications?: boolean;
+  /** **Android:** Optional notification title (default: SDK/native default title). */
+  extractionNotificationTitle?: string;
+  /** **Android:** Optional notification body prefix (progress percent is appended natively). */
+  extractionNotificationText?: string;
   /** Called to get current list of downloaded models for emitModelsListUpdated. */
   getDownloadedList: () => Promise<ModelMetaBase[]>;
 };
@@ -63,6 +72,9 @@ export async function runPostDownloadProcessing(
     deleteArchiveAfterExtract,
     onProgress,
     getDownloadedList,
+    showExtractionNotifications,
+    extractionNotificationTitle,
+    extractionNotificationText,
   } = options;
 
   registerActivePostProcess(category, id);
@@ -80,6 +92,9 @@ export async function runPostDownloadProcessing(
       deleteArchiveAfterExtract,
       onProgress,
       getDownloadedList,
+      showExtractionNotifications,
+      extractionNotificationTitle,
+      extractionNotificationText,
     });
   } finally {
     unregisterActivePostProcess(category, id);
@@ -102,6 +117,9 @@ async function runPostDownloadProcessingBody(
     deleteArchiveAfterExtract,
     onProgress,
     getDownloadedList,
+    showExtractionNotifications,
+    extractionNotificationTitle,
+    extractionNotificationText,
   } = options;
 
   const isAborted = () => Boolean(signal?.aborted);
@@ -164,7 +182,12 @@ async function runPostDownloadProcessingBody(
         onProgress?.(progress);
         emitDownloadProgress(category, id, progress);
       },
-      signal
+      signal,
+      {
+        showNotificationsEnabled: showExtractionNotifications !== false,
+        notificationTitle: extractionNotificationTitle,
+        notificationText: extractionNotificationText,
+      }
     );
   }
 

package/src/enhancement/index.ts

@@ -1,69 +1,131 @@
-/**
- * Speech Enhancement feature module
- *
- * @remarks
- * This feature is not yet implemented. This module serves as a placeholder
- * for future speech enhancement functionality.
- *
- * @example
- * ```typescript
- * // Future usage:
- * import { initializeEnhancement, enhanceAudio } from 'react-native-sherpa-onnx/enhancement';
- *
- * await initializeEnhancement({ modelPath: { type: 'auto', path: 'models/enhancement-model' } });
- * const enhancedPath = await enhanceAudio('path/to/noisy-audio.wav');
- * ```
- */
-
+import SherpaOnnx from '../NativeSherpaOnnx';
 import type { ModelPathConfig } from '../types';
+import { resolveModelPath } from '../utils';
+import type {
+  EnhancedAudio,
+  EnhancementDetectResult,
+  EnhancementEngine,
+  EnhancementInitializeOptions,
+} from './types';
 
-/**
- * Enhancement initialization options (placeholder)
- */
-export interface EnhancementInitializeOptions {
-  modelPath: ModelPathConfig;
-  // Additional enhancement-specific options will be added here
-}
+let enhancementInstanceCounter = 0;
 
-/**
- * Enhancement result
- */
-export interface EnhancementResult {
-  outputPath: string;
-  // Additional result fields will be added here
+function normalizeEnhancedAudio(raw: {
+  samples?: number[] | Float32Array;
+  sampleRate?: number;
+}): EnhancedAudio {
+  const samplesArray = Array.isArray(raw.samples)
+    ? raw.samples
+    : Array.from(raw.samples ?? []);
+  return {
+    samples: Float32Array.from(samplesArray),
+    sampleRate: Number(raw.sampleRate ?? 0),
+  };
 }
 
-/**
- * Initialize Speech Enhancement with model directory.
- *
- * @throws {Error} Not yet implemented
- */
-export async function initializeEnhancement(
-  _options: EnhancementInitializeOptions
-): Promise<void> {
-  throw new Error(
-    'Speech Enhancement feature is not yet implemented. This is a placeholder module.'
+export async function detectEnhancementModel(
+  modelPath: ModelPathConfig,
+  options?: { modelType?: EnhancementInitializeOptions['modelType'] }
+): Promise<EnhancementDetectResult> {
+  const resolvedPath = await resolveModelPath(modelPath);
+  const raw = await SherpaOnnx.detectEnhancementModel(
+    resolvedPath,
+    options?.modelType
   );
+  const err = typeof raw.error === 'string' ? raw.error.trim() : '';
+  return {
+    success: raw.success,
+    ...(err.length > 0 ? { error: err } : {}),
+    detectedModels: raw.detectedModels ?? [],
+    ...(raw.modelType != null && raw.modelType !== ''
+      ? { modelType: raw.modelType }
+      : {}),
+  };
 }
 
-/**
- * Enhance speech quality in an audio file.
- *
- * @throws {Error} Not yet implemented
- */
-export function enhanceAudio(_filePath: string): Promise<EnhancementResult> {
-  throw new Error(
-    'Speech Enhancement feature is not yet implemented. This is a placeholder module.'
+export async function createEnhancement(
+  options: EnhancementInitializeOptions
+): Promise<EnhancementEngine> {
+  const instanceId = `enhancement_${++enhancementInstanceCounter}`;
+  const resolvedPath = await resolveModelPath(options.modelPath);
+  const init = await SherpaOnnx.initializeEnhancement(
+    instanceId,
+    resolvedPath,
+    options.modelType ?? 'auto',
+    options.numThreads,
+    options.provider,
+    options.debug
   );
-}
 
-/**
- * Release enhancement resources.
- *
- * @throws {Error} Not yet implemented
- */
-export function unloadEnhancement(): Promise<void> {
-  throw new Error(
-    'Speech Enhancement feature is not yet implemented. This is a placeholder module.'
-  );
+  if (!init.success) {
+    const nativeError = typeof init.error === 'string' ? init.error.trim() : '';
+    throw new Error(
+      nativeError.length > 0
+        ? `Enhancement initialization failed: ${nativeError}`
+        : `Enhancement initialization failed for ${instanceId}`
+    );
+  }
+
+  let destroyed = false;
+  const guard = () => {
+    if (destroyed) {
+      throw new Error(
+        `Enhancement instance ${instanceId} has been destroyed; cannot call methods on it.`
+      );
+    }
+  };
+
+  return {
+    get instanceId() {
+      return instanceId;
+    },
+    async enhanceFile(
+      inputPath: string,
+      outputPath?: string
+    ): Promise<EnhancedAudio> {
+      guard();
+      const raw = await SherpaOnnx.enhanceFile(
+        instanceId,
+        inputPath,
+        outputPath
+      );
+      return normalizeEnhancedAudio(raw);
+    },
+    async enhanceSamples(
+      samples: number[],
+      sampleRate: number
+    ): Promise<EnhancedAudio> {
+      guard();
+      const raw = await SherpaOnnx.enhanceSamples(
+        instanceId,
+        samples,
+        sampleRate
+      );
+      return normalizeEnhancedAudio(raw);
+    },
+    async getSampleRate(): Promise<number> {
+      guard();
+      return SherpaOnnx.getEnhancementSampleRate(instanceId);
+    },
+    async destroy(): Promise<void> {
+      if (destroyed) return;
+      destroyed = true;
+      await SherpaOnnx.unloadEnhancement(instanceId);
+    },
+  };
 }
+
+export { createStreamingEnhancement } from './streaming';
+export type {
+  OnlineEnhancementEngine,
+  StreamingEnhancementInitializeOptions,
+} from './streamingTypes';
+
+export type {
+  EnhancementModelType,
+  EnhancedAudio,
+  EnhancementInitializeOptions,
+  EnhancementDetectResult,
+  EnhancementEngine,
+} from './types';
+export { ENHANCEMENT_MODEL_TYPES } from './types';

package/src/enhancement/streaming.ts

@@ -0,0 +1,105 @@
+import SherpaOnnx from '../NativeSherpaOnnx';
+import { resolveModelPath } from '../utils';
+import type { EnhancedAudio, EnhancementModelType } from './types';
+import type {
+  OnlineEnhancementEngine,
+  StreamingEnhancementInitializeOptions,
+} from './streamingTypes';
+
+let streamingEnhancementInstanceCounter = 0;
+
+function normalizeEnhancedAudio(raw: {
+  samples?: number[] | Float32Array;
+  sampleRate?: number;
+}): EnhancedAudio {
+  const samplesArray = Array.isArray(raw.samples)
+    ? raw.samples
+    : Array.from(raw.samples ?? []);
+  return {
+    samples: Float32Array.from(samplesArray),
+    sampleRate: Number(raw.sampleRate ?? 0),
+  };
+}
+
+export async function createStreamingEnhancement(
+  options: StreamingEnhancementInitializeOptions
+): Promise<OnlineEnhancementEngine> {
+  const instanceId = `streaming_enhancement_${++streamingEnhancementInstanceCounter}`;
+  const resolvedPath = await resolveModelPath(options.modelPath);
+  const result = await SherpaOnnx.initializeOnlineEnhancement(
+    instanceId,
+    resolvedPath,
+    options.modelType ?? 'auto',
+    options.numThreads,
+    options.provider,
+    options.debug
+  );
+
+  if (!result.success) {
+    const nativeError =
+      typeof result.error === 'string' ? result.error.trim() : '';
+    throw new Error(
+      nativeError.length > 0
+        ? `Streaming enhancement initialization failed: ${nativeError}`
+        : `Streaming enhancement initialization failed for ${instanceId}`
+    );
+  }
+
+  let destroyed = false;
+  const guard = () => {
+    if (destroyed) {
+      throw new Error(
+        `Streaming enhancement instance ${instanceId} has been destroyed; cannot call methods on it.`
+      );
+    }
+  };
+
+  return {
+    get instanceId() {
+      return instanceId;
+    },
+
+    async feedSamples(
+      samples: number[],
+      sampleRate: number
+    ): Promise<EnhancedAudio> {
+      guard();
+      const raw = await SherpaOnnx.feedEnhancementSamples(
+        instanceId,
+        samples,
+        sampleRate
+      );
+      return normalizeEnhancedAudio(raw);
+    },
+
+    async flush(): Promise<EnhancedAudio> {
+      guard();
+      const raw = await SherpaOnnx.flushOnlineEnhancement(instanceId);
+      return normalizeEnhancedAudio(raw);
+    },
+
+    async reset(): Promise<void> {
+      guard();
+      await SherpaOnnx.resetOnlineEnhancement(instanceId);
+    },
+
+    async getSampleRate(): Promise<number> {
+      guard();
+      return SherpaOnnx.getEnhancementSampleRate(instanceId);
+    },
+
+    async getFrameShiftInSamples(): Promise<number> {
+      guard();
+      return Number(result.frameShiftInSamples ?? 0);
+    },
+
+    async destroy(): Promise<void> {
+      if (destroyed) return;
+      destroyed = true;
+      await SherpaOnnx.unloadOnlineEnhancement(instanceId);
+    },
+  };
+}
+
+export type { OnlineEnhancementEngine } from './streamingTypes';
+export type { EnhancementModelType };

package/src/enhancement/streamingTypes.ts

@@ -0,0 +1,14 @@
+import type { EnhancedAudio, EnhancementInitializeOptions } from './types';
+
+export type StreamingEnhancementInitializeOptions =
+  EnhancementInitializeOptions;
+
+export interface OnlineEnhancementEngine {
+  readonly instanceId: string;
+  feedSamples(samples: number[], sampleRate: number): Promise<EnhancedAudio>;
+  flush(): Promise<EnhancedAudio>;
+  reset(): Promise<void>;
+  getSampleRate(): Promise<number>;
+  getFrameShiftInSamples(): Promise<number>;
+  destroy(): Promise<void>;
+}

package/src/enhancement/types.ts

@@ -0,0 +1,36 @@
+import type { ModelPathConfig } from '../types';
+
+export type EnhancementModelType = 'gtcrn' | 'dpdfnet';
+
+export const ENHANCEMENT_MODEL_TYPES: readonly EnhancementModelType[] = [
+  'gtcrn',
+  'dpdfnet',
+] as const;
+
+export type EnhancedAudio = {
+  samples: Float32Array;
+  sampleRate: number;
+};
+
+export interface EnhancementInitializeOptions {
+  modelPath: ModelPathConfig;
+  modelType?: EnhancementModelType | 'auto';
+  numThreads?: number;
+  provider?: string;
+  debug?: boolean;
+}
+
+export type EnhancementDetectResult = {
+  success: boolean;
+  error?: string;
+  detectedModels: Array<{ type: string; modelDir: string }>;
+  modelType?: string;
+};
+
+export interface EnhancementEngine {
+  readonly instanceId: string;
+  enhanceFile(inputPath: string, outputPath?: string): Promise<EnhancedAudio>;
+  enhanceSamples(samples: number[], sampleRate: number): Promise<EnhancedAudio>;
+  getSampleRate(): Promise<number>;
+  destroy(): Promise<void>;
+}

package/src/extraction/extractTarBz2.ts

@@ -1,5 +1,6 @@
 import { DeviceEventEmitter } from 'react-native';
 import SherpaOnnx from '../NativeSherpaOnnx';
+import type { ExtractNotificationArgs } from './types';
 
 export type ExtractProgressEvent = {
   bytes: number;
@@ -19,7 +20,8 @@ export async function extractTarBz2(
   targetPath: string,
   force = true,
   onProgress?: (event: ExtractProgressEvent) => void,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  notification?: ExtractNotificationArgs
 ): Promise<ExtractResult> {
   let subscription: { remove: () => void } | null = null;
   let removeAbortListener: (() => void) | null = null;
@@ -62,7 +64,10 @@ export async function extractTarBz2(
     const result = await SherpaOnnx.extractTarBz2(
       sourcePath,
       targetPath,
-      force
+      force,
+      notification?.showNotificationsEnabled,
+      notification?.notificationTitle,
+      notification?.notificationText
     );
     if (!result.success) {
       const message = result.reason || 'Extraction failed';

package/src/extraction/extractTarZst.ts

@@ -1,5 +1,6 @@
 import { DeviceEventEmitter } from 'react-native';
 import SherpaOnnx from '../NativeSherpaOnnx';
+import type { ExtractNotificationArgs } from './types';
 
 export type ExtractProgressEvent = {
   bytes: number;
@@ -19,7 +20,8 @@ export async function extractTarZst(
   targetPath: string,
   force = true,
   onProgress?: (event: ExtractProgressEvent) => void,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  notification?: ExtractNotificationArgs
 ): Promise<ExtractResult> {
   let subscription: { remove: () => void } | null = null;
   let removeAbortListener: (() => void) | null = null;
@@ -61,7 +63,10 @@ export async function extractTarZst(
     const result = await SherpaOnnx.extractTarZst(
       sourcePath,
       targetPath,
-      force
+      force,
+      notification?.showNotificationsEnabled,
+      notification?.notificationTitle,
+      notification?.notificationText
     );
     if (!result.success) {
       const message = result.reason || 'Extraction failed';

package/src/extraction/index.ts

@@ -17,6 +17,7 @@ import { extractTarBz2 } from './extractTarBz2';
 import type {
   BundledArchive,
   ExtractArchiveOptions,
+  ExtractNotificationArgs,
   ExtractResult,
   ExtractProgressEvent,
 } from './types';
@@ -24,6 +25,7 @@ import type {
 export type {
   BundledArchive,
   ExtractArchiveOptions,
+  ExtractNotificationArgs,
   ExtractResult,
   ExtractProgressEvent,
 } from './types';
@@ -160,6 +162,11 @@ export async function extractArchive(
   const force = options?.force !== false;
   const onProgress = options?.onProgress;
   const signal = options?.signal;
+  const notification = {
+    showNotificationsEnabled: options?.showNotificationsEnabled,
+    notificationTitle: options?.notificationTitle,
+    notificationText: options?.notificationText,
+  };
 
   if (signal?.aborted) {
     const err = new Error('Extraction aborted');
@@ -173,7 +180,14 @@ export async function extractArchive(
       archive.archivePath.startsWith('asset_packs/'));
 
   if (useAssetStream) {
-    return extractFromAsset(archive, targetPath, force, onProgress, signal);
+    return extractFromAsset(
+      archive,
+      targetPath,
+      force,
+      onProgress,
+      signal,
+      notification
+    );
   }
 
   if (archive.format === 'tar.zst') {
@@ -182,7 +196,8 @@ export async function extractArchive(
       targetPath,
       force,
       onProgress,
-      signal
+      signal,
+      notification
     );
   }
   return extractTarBz2(
@@ -190,7 +205,8 @@ export async function extractArchive(
     targetPath,
     force,
     onProgress,
-    signal
+    signal,
+    notification
   );
 }
 
@@ -201,7 +217,8 @@ async function extractFromAsset(
   targetPath: string,
   force: boolean,
   onProgress?: (event: ExtractProgressEvent) => void,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  notification?: ExtractNotificationArgs
 ): Promise<ExtractResult> {
   const eventName =
     archive.format === 'tar.zst'
@@ -245,12 +262,18 @@ async function extractFromAsset(
         ? await SherpaOnnx.extractTarZstFromAsset(
             archive.archivePath,
             targetPath,
-            force
+            force,
+            notification?.showNotificationsEnabled,
+            notification?.notificationTitle,
+            notification?.notificationText
           )
         : await SherpaOnnx.extractTarBz2FromAsset(
             archive.archivePath,
             targetPath,
-            force
+            force,
+            notification?.showNotificationsEnabled,
+            notification?.notificationTitle,
+            notification?.notificationText
           );
 
     if (!result.success) {

package/src/extraction/types.ts

@@ -60,4 +60,20 @@ export type ExtractArchiveOptions = {
   onProgress?: (event: ExtractProgressEvent) => void;
   /** AbortSignal to cancel the extraction. */
   signal?: AbortSignal;
+  /**
+   * **Android:** When true (default), the native layer posts a system notification with extraction
+   * progress. Set to false to disable (e.g. first-run bundled-model prep with in-app UI only).
+   * **iOS:** Accepted for API parity; no notification is shown.
+   */
+  showNotificationsEnabled?: boolean;
+  /** **Android:** Notification title. Default: generic “unpacking” title. Ignored on iOS. */
+  notificationTitle?: string;
+  /** **Android:** Notification body (progress text is appended). Default: generic. Ignored on iOS. */
+  notificationText?: string;
 };
+
+/** Subset of `ExtractArchiveOptions` passed through to path- and asset-stream extractors. */
+export type ExtractNotificationArgs = Pick<
+  ExtractArchiveOptions,
+  'showNotificationsEnabled' | 'notificationTitle' | 'notificationText'
+>;

package/src/licenses.ts

@@ -13,14 +13,17 @@ 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 speechEnhancementPath =
+    'model_licenses/speech-enhancement-models-license-status.csv';
 
   const results = await Promise.allSettled([
     SherpaOnnx.readAssetFileAsUtf8(asrPath),
     SherpaOnnx.readAssetFileAsUtf8(qnnPath),
     SherpaOnnx.readAssetFileAsUtf8(ttsPath),
+    SherpaOnnx.readAssetFileAsUtf8(speechEnhancementPath),
   ]);
 
-  const [asrResult, qnnResult, ttsResult] = results;
+  const [asrResult, qnnResult, ttsResult, enhancementResult] = results;
 
   const licenses: ModelLicense[] = [];
 
@@ -48,6 +51,14 @@ export async function getModelLicenses(): Promise<ModelLicense[]> {
     );
   }
 
+  if (enhancementResult.status === 'fulfilled') {
+    licenses.push(...parseCsv(enhancementResult.value));
+  } else {
+    console.warn(
+      `[SherpaOnnx] Failed to load speech enhancement model licenses: ${enhancementResult.reason}`
+    );
+  }
+
   return licenses;
 }
 
@@ -91,7 +102,7 @@ function parseCsv(csvString: string): ModelLicense[] {
       }
     }
 
-    if (entry['asset_name']) {
+    if (entry.asset_name) {
       results.push(entry as unknown as ModelLicense);
     }
   }

package/src/stt/index.ts

@@ -67,10 +67,7 @@ export async function detectSttModel(
     options?.preferInt8,
     options?.modelType
   );
-  const err =
-    typeof (raw as { error?: unknown }).error === 'string'
-      ? String((raw as { error: string }).error).trim()
-      : '';
+  const err = typeof raw.error === 'string' ? raw.error.trim() : '';
   return {
     success: raw.success,
     ...(err.length > 0 ? { error: err } : {}),
@@ -170,10 +167,13 @@ export async function createSTT(
   );
 
   if (!result.success) {
+    const nativeError =
+      typeof result.error === 'string' ? result.error.trim() : '';
+    const detected = JSON.stringify(result.detectedModels ?? []);
     throw new Error(
-      `STT initialization failed: ${JSON.stringify(
-        result.detectedModels ?? []
-      )}`
+      nativeError.length > 0
+        ? `STT initialization failed: ${nativeError}`
+        : `STT initialization failed: ${detected}`
     );
   }
 
@@ -259,6 +259,7 @@ export type {
   STTInitializeOptions,
   STTModelType,
   SttModelOptions,
+  SttQwen3AsrModelOptions,
   SttRecognitionResult,
   SttRuntimeConfig,
   SttEngine,

package/src/stt/streaming.ts

@@ -231,7 +231,13 @@ export async function createStreamingSTT(
   );
 
   if (!result.success) {
-    throw new Error(`Streaming STT initialization failed for ${instanceId}`);
+    const nativeError =
+      typeof result.error === 'string' ? result.error.trim() : '';
+    throw new Error(
+      nativeError.length > 0
+        ? `Streaming STT initialization failed: ${nativeError}`
+        : `Streaming STT initialization failed for ${instanceId}`
+    );
   }
 
   const enableInputNormalization = options.enableInputNormalization !== false;