react-native-sherpa-onnx 0.1.0

package/src/NativeSherpaOnnx.ts

@@ -0,0 +1,44 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+export interface Spec extends TurboModule {
+  /**
+   * Test method to verify sherpa-onnx native library is loaded.
+   * Phase 1: Minimal "Hello World" test.
+   */
+  testSherpaInit(): Promise<string>;
+
+  /**
+   * Resolve model path based on configuration.
+   * Handles asset paths, file system paths, and auto-detection.
+   * Returns an absolute path that can be used by native code.
+   *
+   * @param config - Object with 'type' ('asset' | 'file' | 'auto') and 'path' (string)
+   */
+  resolveModelPath(config: { type: string; path: string }): Promise<string>;
+
+  /**
+   * Initialize sherpa-onnx with model directory.
+   * Expects an absolute path (use resolveModelPath first for asset/file paths).
+   * @param modelDir - Absolute path to model directory
+   * @param preferInt8 - Optional: true = prefer int8 models, false = prefer regular models, undefined = try int8 first (default)
+   * @param modelType - Optional: explicit model type ('transducer', 'paraformer', 'nemo_ctc', 'auto'), undefined = auto (default)
+   */
+  initializeSherpaOnnx(
+    modelDir: string,
+    preferInt8?: boolean,
+    modelType?: string
+  ): Promise<void>;
+
+  /**
+   * Transcribe an audio file.
+   * Phase 1: Stub implementation.
+   */
+  transcribeFile(filePath: string): Promise<string>;
+
+  /**
+   * Release sherpa-onnx resources.
+   */
+  unloadSherpaOnnx(): Promise<void>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('SherpaOnnx');

package/src/diarization/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Speaker Diarization feature module
+ *
+ * @remarks
+ * This feature is not yet implemented. This module serves as a placeholder
+ * for future speaker diarization functionality.
+ *
+ * @example
+ * ```typescript
+ * // Future usage:
+ * import { initializeDiarization, diarizeAudio } from 'react-native-sherpa-onnx/diarization';
+ *
+ * await initializeDiarization({ modelPath: 'models/diarization-model' });
+ * const segments = await diarizeAudio('path/to/audio.wav');
+ * ```
+ */
+
+/**
+ * Diarization initialization options (placeholder)
+ */
+export interface DiarizationInitializeOptions {
+  modelPath: string;
+  // Additional diarization-specific options will be added here
+}
+
+/**
+ * Speaker segment with speaker ID
+ */
+export interface SpeakerSegment {
+  speakerId: string;
+  start: number;
+  end: number;
+  // Additional segment fields will be added here
+}
+
+/**
+ * Initialize Speaker Diarization with model directory.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export async function initializeDiarization(
+  _options: DiarizationInitializeOptions
+): Promise<void> {
+  throw new Error(
+    'Speaker Diarization feature is not yet implemented. This is a placeholder module.'
+  );
+}
+
+/**
+ * Perform speaker diarization on an audio file.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export function diarizeAudio(_filePath: string): Promise<SpeakerSegment[]> {
+  throw new Error(
+    'Speaker Diarization feature is not yet implemented. This is a placeholder module.'
+  );
+}
+
+/**
+ * Release diarization resources.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export function unloadDiarization(): Promise<void> {
+  throw new Error(
+    'Speaker Diarization feature is not yet implemented. This is a placeholder module.'
+  );
+}

package/src/enhancement/index.ts

@@ -0,0 +1,67 @@
+/**
+ * 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: 'models/enhancement-model' });
+ * const enhancedPath = await enhanceAudio('path/to/noisy-audio.wav');
+ * ```
+ */
+
+/**
+ * Enhancement initialization options (placeholder)
+ */
+export interface EnhancementInitializeOptions {
+  modelPath: string;
+  // Additional enhancement-specific options will be added here
+}
+
+/**
+ * Enhancement result
+ */
+export interface EnhancementResult {
+  outputPath: string;
+  // Additional result fields will be added here
+}
+
+/**
+ * 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.'
+  );
+}
+
+/**
+ * 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.'
+  );
+}
+
+/**
+ * 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.'
+  );
+}

package/src/index.tsx

@@ -0,0 +1,30 @@
+import SherpaOnnx from './NativeSherpaOnnx';
+
+// Export types and utilities
+export type { InitializeOptions, ModelPathConfig, ModelType } from './types';
+export {
+  assetModelPath,
+  autoModelPath,
+  fileModelPath,
+  getDefaultModelPath,
+  resolveModelPath,
+} from './utils';
+
+// Re-export STT functionality
+export { initializeSTT, transcribeFile, unloadSTT } from './stt';
+export type { STTInitializeOptions, TranscriptionResult } from './stt';
+
+// TODO: Uncomment these exports once the features are implemented
+// Re-export other features (when implemented)
+// export * from './tts';
+// export * from './vad';
+// export * from './diarization';
+// export * from './enhancement';
+// export * from './separation';
+
+/**
+ * Test method to verify sherpa-onnx native library is loaded.
+ */
+export function testSherpaInit(): Promise<string> {
+  return SherpaOnnx.testSherpaInit();
+}

package/src/separation/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Source Separation feature module
+ *
+ * @remarks
+ * This feature is not yet implemented. This module serves as a placeholder
+ * for future source separation functionality.
+ *
+ * @example
+ * ```typescript
+ * // Future usage:
+ * import { initializeSeparation, separateSources } from 'react-native-sherpa-onnx/separation';
+ *
+ * await initializeSeparation({ modelPath: 'models/separation-model' });
+ * const sources = await separateSources('path/to/mixed-audio.wav');
+ * ```
+ */
+
+/**
+ * Separation initialization options (placeholder)
+ */
+export interface SeparationInitializeOptions {
+  modelPath: string;
+  // Additional separation-specific options will be added here
+}
+
+/**
+ * Separated audio source
+ */
+export interface SeparatedSource {
+  sourceId: string;
+  outputPath: string;
+  // Additional source fields will be added here
+}
+
+/**
+ * Initialize Source Separation with model directory.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export async function initializeSeparation(
+  _options: SeparationInitializeOptions
+): Promise<void> {
+  throw new Error(
+    'Source Separation feature is not yet implemented. This is a placeholder module.'
+  );
+}
+
+/**
+ * Separate audio sources from a mixed audio file.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export function separateSources(_filePath: string): Promise<SeparatedSource[]> {
+  throw new Error(
+    'Source Separation feature is not yet implemented. This is a placeholder module.'
+  );
+}
+
+/**
+ * Release separation resources.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export function unloadSeparation(): Promise<void> {
+  throw new Error(
+    'Source Separation feature is not yet implemented. This is a placeholder module.'
+  );
+}

package/src/stt/index.ts

@@ -0,0 +1,83 @@
+import SherpaOnnx from '../NativeSherpaOnnx';
+import type { STTInitializeOptions } from './types';
+import type { InitializeOptions } from '../types';
+import { resolveModelPath } from '../utils';
+
+/**
+ * Initialize Speech-to-Text (STT) with model directory.
+ *
+ * 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)
+ *
+ * @param options - STT initialization options or model path configuration
+ * @example
+ * ```typescript
+ * // Simple string (auto-detect)
+ * await initializeSTT('models/sherpa-onnx-model');
+ *
+ * // Asset model
+ * await initializeSTT({
+ *   modelPath: { type: 'asset', path: 'models/sherpa-onnx-model' }
+ * });
+ *
+ * // File system model with preferInt8 option
+ * await initializeSTT({
+ *   modelPath: { type: 'file', path: '/path/to/model' },
+ *   preferInt8: true  // Prefer quantized int8 models (smaller, faster)
+ * });
+ *
+ * // With explicit model type
+ * await initializeSTT({
+ *   modelPath: { type: 'asset', path: 'models/sherpa-onnx-nemo-parakeet-tdt-ctc-en' },
+ *   modelType: 'nemo_ctc'
+ * });
+ * ```
+ */
+export async function initializeSTT(
+  options: STTInitializeOptions | InitializeOptions['modelPath']
+): Promise<void> {
+  // Handle both object syntax and direct path syntax
+  let modelPath: InitializeOptions['modelPath'];
+  let preferInt8: boolean | undefined;
+  let modelType: string | undefined;
+
+  if (typeof options === 'object' && 'modelPath' in options) {
+    modelPath = options.modelPath;
+    preferInt8 = options.preferInt8;
+    modelType = options.modelType;
+  } else {
+    modelPath = options as InitializeOptions['modelPath'];
+    preferInt8 = undefined;
+    modelType = undefined;
+  }
+
+  const resolvedPath = await resolveModelPath(modelPath);
+  return SherpaOnnx.initializeSherpaOnnx(resolvedPath, preferInt8, modelType);
+}
+
+/**
+ * Transcribe an audio file.
+ *
+ * @param filePath - Path to WAV file (16kHz, mono, 16-bit PCM)
+ * @returns Promise resolving to transcribed text
+ * @example
+ * ```typescript
+ * const transcription = await transcribeFile('path/to/audio.wav');
+ * console.log('Transcription:', transcription);
+ * ```
+ */
+export function transcribeFile(filePath: string): Promise<string> {
+  return SherpaOnnx.transcribeFile(filePath);
+}
+
+/**
+ * Release STT resources.
+ */
+export function unloadSTT(): Promise<void> {
+  return SherpaOnnx.unloadSherpaOnnx();
+}
+
+// Export types
+export type { STTInitializeOptions, TranscriptionResult } from './types';

package/src/stt/types.ts

@@ -0,0 +1,42 @@
+import type { InitializeOptions, ModelType } from '../types';
+
+/**
+ * STT-specific initialization options
+ */
+export interface STTInitializeOptions {
+  /**
+   * Model directory path configuration
+   */
+  modelPath: InitializeOptions['modelPath'];
+
+  /**
+   * 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 for STT models
+   * - '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;
+}
+
+/**
+ * Transcription result
+ */
+export interface TranscriptionResult {
+  /**
+   * Transcribed text
+   */
+  text: string;
+}

package/src/tts/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Text-to-Speech (TTS) feature module
+ *
+ * @remarks
+ * This feature is not yet implemented. This module serves as a placeholder
+ * for future TTS functionality.
+ *
+ * @example
+ * ```typescript
+ * // Future usage:
+ * import { initializeTTS, synthesizeText } from 'react-native-sherpa-onnx/tts';
+ *
+ * await initializeTTS({ modelPath: 'models/tts-model' });
+ * const audioPath = await synthesizeText('Hello, world!');
+ * ```
+ */
+
+/**
+ * TTS initialization options (placeholder)
+ */
+export interface TTSInitializeOptions {
+  modelPath: string;
+  // Additional TTS-specific options will be added here
+}
+
+/**
+ * TTS synthesis result (placeholder)
+ */
+export interface SynthesisResult {
+  audioPath: string;
+  // Additional result fields will be added here
+}
+
+/**
+ * Initialize Text-to-Speech (TTS) with model directory.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export async function initializeTTS(
+  _options: TTSInitializeOptions
+): Promise<void> {
+  throw new Error(
+    'TTS feature is not yet implemented. This is a placeholder module.'
+  );
+}
+
+/**
+ * Synthesize text to speech audio.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export function synthesizeText(_text: string): Promise<string> {
+  throw new Error(
+    'TTS feature is not yet implemented. This is a placeholder module.'
+  );
+}
+
+/**
+ * Release TTS resources.
+ *
+ * @throws {Error} Not yet implemented
+ */
+export function unloadTTS(): Promise<void> {
+  throw new Error(
+    'TTS feature is not yet implemented. This is a placeholder module.'
+  );
+}

package/src/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Model path configuration options
+ */
+export type ModelPathConfig =
+  | {
+      /**
+       * Path type: 'asset' - Model is bundled in app assets
+       * On iOS: Bundle path (e.g., "models/sherpa-onnx-model")
+       * On Android: Asset path (e.g., "models/sherpa-onnx-model")
+       */
+      type: 'asset';
+      path: string;
+    }
+  | {
+      /**
+       * Path type: 'file' - Model is in file system
+       * Absolute path to model directory
+       */
+      type: 'file';
+      path: string;
+    }
+  | {
+      /**
+       * Path type: 'auto' - Automatically detect path type
+       * Tries asset first, then file system
+       */
+      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; // string for backward compatibility
+
+  /**
+   * 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;
+}

package/src/utils.ts

@@ -0,0 +1,97 @@
+import { Platform } from 'react-native';
+import type { ModelPathConfig } from './types';
+import SherpaOnnx from './NativeSherpaOnnx';
+
+/**
+ * Utility functions for model path handling
+ */
+
+/**
+ * Predefined model identifiers
+ */
+export const MODELS = {
+  ZIPFORMER_EN: 'sherpa-onnx-zipformer-small-en',
+  PARAFORMER_ZH: 'sherpa-onnx-paraformer-zh-small',
+} as const;
+
+export type ModelId = (typeof MODELS)[keyof typeof MODELS];
+
+/**
+ * Get the default model directory path for the current platform.
+ * This is a helper for apps that want to use a standard location.
+ *
+ * @returns Platform-specific default path
+ */
+export function getDefaultModelPath(): string {
+  if (Platform.OS === 'ios') {
+    // iOS: Documents directory
+    return 'Documents/models';
+  } else {
+    // Android: Internal storage
+    return 'models';
+  }
+}
+
+/**
+ * Create a model path configuration for asset models.
+ * Use this when models are bundled in your app's assets.
+ *
+ * @param assetPath - Path relative to assets (e.g., "models/sherpa-onnx-model")
+ * @returns Model path configuration
+ */
+export function assetModelPath(assetPath: string): ModelPathConfig {
+  return {
+    type: 'asset',
+    path: assetPath,
+  };
+}
+
+/**
+ * Create a model path configuration for file system models.
+ * Use this when models are downloaded or stored in file system.
+ *
+ * @param filePath - Absolute path to model directory
+ * @returns Model path configuration
+ */
+export function fileModelPath(filePath: string): ModelPathConfig {
+  return {
+    type: 'file',
+    path: filePath,
+  };
+}
+
+/**
+ * Create a model path configuration with auto-detection.
+ * Tries asset first, then file system.
+ *
+ * @param path - Path to try (will be checked as both asset and file)
+ * @returns Model path configuration
+ */
+export function autoModelPath(path: string): ModelPathConfig {
+  return {
+    type: 'auto',
+    path: path,
+  };
+}
+
+/**
+ * Resolve model path based on configuration.
+ * This handles different path types (asset, file, auto) and returns
+ * a platform-specific absolute path that can be used by native code.
+ *
+ * @param config - Model path configuration or simple string path
+ * @returns Promise resolving to absolute path usable by native code
+ */
+export async function resolveModelPath(
+  config: ModelPathConfig | string
+): Promise<string> {
+  // Backward compatibility: if string is passed, treat as auto
+  if (typeof config === 'string') {
+    return SherpaOnnx.resolveModelPath({
+      type: 'auto',
+      path: config,
+    });
+  }
+
+  return SherpaOnnx.resolveModelPath(config);
+}