react-native-sherpa-onnx 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 XDcobra
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,402 @@
+# react-native-sherpa-onnx
+
+React Native SDK for sherpa-onnx - providing offline speech processing capabilities
+
+[![npm version](https://img.shields.io/npm/v/react-native-sherpa-onnx.svg)](https://www.npmjs.com/package/react-native-sherpa-onnx)
+[![npm downloads](https://img.shields.io/npm/dm/react-native-sherpa-onnx.svg)](https://www.npmjs.com/package/react-native-sherpa-onnx)
+[![npm license](https://img.shields.io/npm/l/react-native-sherpa-onnx.svg)](https://www.npmjs.com/package/react-native-sherpa-onnx)
+[![Android](https://img.shields.io/badge/Android-Supported-green)](https://www.android.com/)
+[![iOS](https://img.shields.io/badge/iOS-Supported-blue)](https://www.apple.com/ios/)
+
+A React Native TurboModule that provides offline speech processing capabilities using [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx). The SDK aims to support all functionalities that sherpa-onnx offers, including offline speech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD (Voice Activity Detection).
+
+## Feature Support
+
+| Feature | Status |
+|---------|--------|
+| Offline Speech-to-Text | ✅ Supported |
+| Text-to-Speech | ❌ Not yet supported |
+| Speaker Diarization | ❌ Not yet supported |
+| Speech Enhancement | ❌ Not yet supported |
+| Source Separation | ❌ Not yet supported |
+| VAD (Voice Activity Detection) | ❌ Not yet supported |
+
+## Platform Support Status
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| **Android** | ✅ **Production Ready** | Fully tested, CI/CD automated, multiple models supported |
+| **iOS** | 🟡 **Beta / Experimental** | XCFramework + Podspec ready<br/>✅ GitHub Actions builds pass<br/>❌ **No local Xcode testing** *(Windows-only dev)* |
+
+### 🔧 **iOS Contributors WANTED!** 🙌
+
+**Full iOS support is a priority!** Help bring sherpa-onnx to iOS devices.
+
+**What's ready:**
+- ✅ XCFramework integration
+- ✅ Podspec configuration  
+- ✅ GitHub Actions CI (macOS runner) 
+- ✅ TypeScript bindings
+
+**What's needed:**
+- **Local Xcode testing** (Simulator + Device)
+- **iOS example app** (beyond CI)
+- **TurboModule iOS testing** 
+- **Edge case testing**
+
+## Supported Model Types
+
+| Model Type               | `modelType` Value | Description                                                                              | Download Links                                                                                   |
+| ------------------------ | ----------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **Zipformer/Transducer** | `'transducer'`    | Requires `encoder.onnx`, `decoder.onnx`, `joiner.onnx`, and `tokens.txt`                 | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/offline-transducer/index.html) |
+| **Paraformer**           | `'paraformer'`    | Requires `model.onnx` (or `model.int8.onnx`) and `tokens.txt`                            | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/offline-paraformer/index.html) |
+| **NeMo CTC**             | `'nemo_ctc'`      | Requires `model.onnx` (or `model.int8.onnx`) and `tokens.txt`                            | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/offline-ctc/nemo/index.html)   |
+| **Whisper**              | `'whisper'`       | Requires `encoder.onnx`, `decoder.onnx`, and `tokens.txt`                                | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/whisper/index.html)            |
+| **WeNet CTC**            | `'wenet_ctc'`     | Requires `model.onnx` (or `model.int8.onnx`) and `tokens.txt`                            | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/offline-ctc/wenet/index.html)  |
+| **SenseVoice**           | `'sense_voice'`   | Requires `model.onnx` (or `model.int8.onnx`) and `tokens.txt`                            | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/sense-voice/index.html)        |
+| **FunASR Nano**          | `'funasr_nano'`   | Requires `encoder_adaptor.onnx`, `llm.onnx`, `embedding.onnx`, and `tokenizer` directory | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/funasr-nano/index.html)        |
+
+## Features
+
+- ✅ **Offline Speech-to-Text** - No internet connection required for speech recognition
+- ✅ **Multiple Model Types** - Supports Zipformer/Transducer, Paraformer, NeMo CTC, Whisper, WeNet CTC, SenseVoice, and FunASR Nano models
+- ✅ **Model Quantization** - Automatic detection and preference for quantized (int8) models
+- ✅ **Flexible Model Loading** - Asset models, file system models, or auto-detection
+- ✅ **Android Support** - Fully supported on Android
+- ✅ **iOS Support** - Fully supported on iOS (requires sherpa-onnx XCFramework)
+- ✅ **TypeScript Support** - Full TypeScript definitions included
+- 🚧 **Additional Features Coming Soon** - Text-to-Speech, Speaker Diarization, Speech Enhancement, Source Separation, and VAD support are planned for future releases
+
+## Installation
+
+```sh
+npm install react-native-sherpa-onnx
+```
+
+If your project uses Yarn (v3+) or Plug'n'Play, configure Yarn to use the Node Modules linker to avoid postinstall issues:
+
+```yaml
+# .yarnrc.yml
+nodeLinker: node-modules
+```
+
+Alternatively, set the environment variable during install:
+
+```sh
+YARN_NODE_LINKER=node-modules yarn install
+```
+
+### Android
+
+No additional setup required. The library automatically handles native dependencies via Gradle.
+
+### iOS
+
+The sherpa-onnx XCFramework is **not included in the repository or npm package** due to its size (~80MB), but **no manual action is required**! The framework is automatically downloaded during `pod install`.
+
+#### Quick Setup
+
+```sh
+cd example
+bundle install
+bundle exec pod install --project-directory=ios
+```
+
+That's it! The `Podfile` automatically:
+1. Copies required header files from the git submodule
+2. Downloads the latest XCFramework from [GitHub Releases](https://github.com/XDcobra/react-native-sherpa-onnx/releases?q=framework)
+3. Verifies everything is in place before building
+
+#### For Advanced Users: Building the Framework Locally
+
+If you want to build the XCFramework yourself instead of using the prebuilt release:
+
+```sh
+# Clone sherpa-onnx repository
+git clone https://github.com/k2-fsa/sherpa-onnx.git
+cd sherpa-onnx
+git checkout v1.12.23
+
+# Build the iOS XCFramework (requires macOS, Xcode, CMake, and ONNX Runtime)
+./build-ios.sh
+
+# Copy to your project
+cp -r build-ios/sherpa_onnx.xcframework /path/to/react-native-sherpa-onnx/ios/Frameworks/
+```
+
+Then run `pod install` as usual.
+
+**Note:** The iOS implementation uses the same C++ wrapper as Android, ensuring consistent behavior across platforms.
+
+## Quick Start
+
+```typescript
+import { resolveModelPath } from 'react-native-sherpa-onnx';
+import {
+  initializeSTT,
+  transcribeFile,
+  unloadSTT,
+} from 'react-native-sherpa-onnx/stt';
+
+// Initialize with a model
+const modelPath = await resolveModelPath({
+  type: 'asset',
+  path: 'models/sherpa-onnx-model',
+});
+
+await initializeSTT({
+  modelPath: modelPath,
+  preferInt8: true, // Optional: prefer quantized models
+});
+
+// Transcribe an audio file
+const transcription = await transcribeFile('path/to/audio.wav');
+console.log('Transcription:', transcription);
+
+// Release resources when done
+await unloadSTT();
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+import {
+  initializeSherpaOnnx,
+  assetModelPath,
+  autoModelPath,
+} from 'react-native-sherpa-onnx';
+
+// Option 1: Asset model (bundled in app)
+await initializeSherpaOnnx({
+  modelPath: assetModelPath('models/sherpa-onnx-model'),
+  preferInt8: true, // Prefer quantized models
+});
+
+// Option 2: Auto-detect (tries asset, then file system)
+await initializeSherpaOnnx({
+  modelPath: autoModelPath('models/sherpa-onnx-model'),
+});
+
+// Option 3: Simple string (backward compatible)
+await initializeSherpaOnnx('models/sherpa-onnx-model');
+```
+
+### Transcription (Speech-to-Text)
+
+```typescript
+import { transcribeFile } from 'react-native-sherpa-onnx/stt';
+
+// Transcribe a WAV file (16kHz, mono, 16-bit PCM)
+const result = await transcribeFile('path/to/audio.wav');
+console.log('Transcription:', result);
+```
+
+### Model Quantization
+
+Control whether to prefer quantized (int8) or regular models:
+
+```typescript
+import { initializeSTT } from 'react-native-sherpa-onnx/stt';
+import { resolveModelPath } from 'react-native-sherpa-onnx';
+
+const modelPath = await resolveModelPath({
+  type: 'asset',
+  path: 'models/my-model',
+});
+
+// Default: try int8 first, then regular
+await initializeSTT({ modelPath });
+
+// Explicitly prefer int8 models (smaller, faster)
+await initializeSTT({
+  modelPath,
+  preferInt8: true,
+});
+
+// Explicitly prefer regular models (higher accuracy)
+await initializeSTT({
+  modelPath,
+  preferInt8: false,
+});
+```
+
+### Explicit Model Type
+
+For robustness, you can explicitly specify the model type to avoid auto-detection issues:
+
+```typescript
+import { initializeSTT } from 'react-native-sherpa-onnx/stt';
+import { resolveModelPath } from 'react-native-sherpa-onnx';
+
+const modelPath = await resolveModelPath({
+  type: 'asset',
+  path: 'models/sherpa-onnx-nemo-parakeet-tdt-ctc-en',
+});
+
+// Explicitly specify model type
+await initializeSTT({
+  modelPath,
+  modelType: 'nemo_ctc', // 'transducer', 'paraformer', 'nemo_ctc', 'whisper', 'wenet_ctc', 'sense_voice', 'funasr_nano'
+});
+
+// Auto-detection (default behavior)
+await initializeSTT({
+  modelPath,
+  // modelType defaults to 'auto'
+});
+```
+
+### Cleanup (Speech-to-Text)
+
+```typescript
+import { unloadSTT } from 'react-native-sherpa-onnx/stt';
+
+// Release resources when done
+await unloadSTT();
+```
+
+## Model Setup
+
+The library does **not** bundle models. You must provide your own models. See [MODEL_SETUP.md](./MODEL_SETUP.md) for detailed setup instructions.
+
+### Model File Requirements
+
+- **Zipformer/Transducer**: Requires `encoder.onnx`, `decoder.onnx`, `joiner.onnx`, and `tokens.txt`
+- **Paraformer**: Requires `model.onnx` (or `model.int8.onnx`) and `tokens.txt`
+- **NeMo CTC**: Requires `model.onnx` (or `model.int8.onnx`) and `tokens.txt`
+- **Whisper**: Requires `encoder.onnx`, `decoder.onnx`, and `tokens.txt`
+- **WeNet CTC**: Requires `model.onnx` (or `model.int8.onnx`) and `tokens.txt`
+- **SenseVoice**: Requires `model.onnx` (or `model.int8.onnx`) and `tokens.txt`
+
+### Model Files
+
+Place models in:
+
+- **Android**: `android/app/src/main/assets/models/`
+- **iOS**: Add to Xcode project as folder reference
+
+## API Reference
+
+### Speech-to-Text (STT) Module
+
+Import from `react-native-sherpa-onnx/stt`:
+
+#### `initializeSTT(options)`
+
+Initialize the speech-to-text engine with a model.
+
+**Parameters:**
+
+- `options.modelPath`: Absolute path to the model directory
+- `options.preferInt8` (optional): Prefer quantized models (`true`), regular models (`false`), or auto-detect (`undefined`, default)
+- `options.modelType` (optional): Explicit model type (`'transducer'`, `'paraformer'`, `'nemo_ctc'`, `'whisper'`, `'wenet_ctc'`, `'sense_voice'`, `'funasr_nano'`), or auto-detect (`'auto'`, default)
+
+**Returns:** `Promise<void>`
+
+#### `transcribeFile(filePath)`
+
+Transcribe an audio file.
+
+**Parameters:**
+
+- `filePath`: Path to WAV file (16kHz, mono, 16-bit PCM)
+
+**Returns:** `Promise<string>` - Transcribed text
+
+#### `unloadSTT()`
+
+Release resources and unload the speech-to-text model.
+
+**Returns:** `Promise<void>`
+
+### Utility Functions
+
+Import from `react-native-sherpa-onnx`:
+
+#### `resolveModelPath(config)`
+
+Resolve a model path configuration to an absolute path.
+
+**Parameters:**
+
+- `config.type`: Path type (`'asset'`, `'file'`, or `'auto'`)
+- `config.path`: Path to resolve (relative for assets, absolute for files)
+
+**Returns:** `Promise<string>` - Absolute path to model directory
+
+#### `testSherpaInit()`
+
+Test that the sherpa-onnx native module is properly loaded.
+
+**Returns:** `Promise<string>` - Test message confirming module is loaded
+
+## Requirements
+
+- React Native >= 0.70
+- Android API 24+ (Android 7.0+)
+- iOS 13.0+ (requires sherpa-onnx XCFramework - see iOS Setup below)
+
+## Example Apps
+
+We provide example applications to help you get started with `react-native-sherpa-onnx`:
+
+### Example App (Audio to Text)
+
+The example app included in this repository demonstrates basic audio-to-text transcription capabilities. It includes:
+
+- Multiple model type support (Zipformer, Paraformer, NeMo CTC, Whisper, WeNet CTC, SenseVoice, FunASR Nano)
+- Model selection and configuration
+- Audio file transcription
+- Test audio files for different languages
+
+**Getting started:**
+
+```sh
+cd example
+yarn install
+yarn android  # or yarn ios
+```
+
+<div align="center">
+  <img src="./docs/images/example_home_screen.png" alt="Model selection home screen" width="30%" />
+  <img src="./docs/images/example_english.png" alt="Transcribe english audio" width="30%" />
+  <img src="./docs/images/example_multilanguage.png" alt="Transcribe english and chinese audio" width="30%" />
+</div>
+
+### Video to Text Comparison App
+
+A comprehensive comparison app that demonstrates video-to-text transcription using `react-native-sherpa-onnx` alongside other speech-to-text solutions:
+
+**Repository:** [mobile-videototext-comparison](https://github.com/XDcobra/mobile-videototext-comparison)
+
+**Features:**
+
+- Video to audio conversion (using native APIs)
+- Audio to text transcription
+- Video to text (video --> WAV --> text)
+- Comparison between different STT providers
+- Performance benchmarking
+
+This app showcases how to integrate `react-native-sherpa-onnx` into a real-world application that processes video files and converts them to text.
+
+<div align="center">
+  <img src="./docs/images/vtt_model_overview.png" alt="Video-to-Text Model Overview" width="30%" />
+  <img src="./docs/images/vtt_result_file_picker.png" alt="Video-to-Text file picker" width="30%" />
+  <img src="./docs/images/vtt_result_test_audio.png" alt="Video-to-Text test audio" width="30%" />
+</div>
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/SherpaOnnx.podspec

@@ -0,0 +1,84 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+# Compute absolute paths
+pod_root = __dir__
+ios_include_path = File.join(pod_root, 'ios', 'include')
+framework_path = File.join(pod_root, 'ios', 'Frameworks', 'sherpa_onnx.xcframework')
+
+Pod::Spec.new do |s|
+  s.name         = "SherpaOnnx"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/XDcobra/react-native-sherpa-onnx.git", :tag => "#{s.version}" }
+  
+  # Source files (implementation)
+  # Include .cc for cxx-api.cc (C++ wrapper around C API)
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp,cc}"
+  
+  # Private headers (our wrapper headers)
+  s.private_header_files = [
+    "ios/*.h",
+    "ios/include/**/*.h"
+  ]
+  
+  # Link with required frameworks and libraries
+  # CoreML is required by ONNX Runtime's CoreML execution provider
+  s.frameworks = 'Foundation', 'Accelerate', 'CoreML'
+  s.libraries = 'c++'
+  
+  # Note: Header files and framework are set up by postinstall script (yarn setup-assets)
+  # This runs automatically after yarn/npm install and handles all setup tasks
+  
+  # Verify XCFramework exists
+  unless File.exist?(framework_path)
+    raise <<~MSG
+      [SherpaOnnx] ERROR: iOS Framework not found.
+      
+      The sherpa-onnx XCFramework should have been downloaded automatically during pod install.
+      If the automatic download failed, you can manually download it by running:
+      
+      yarn download-ios-framework
+      
+      Or download from GitHub Releases:
+      https://github.com/XDcobra/react-native-sherpa-onnx/releases?q=framework
+      
+      Then extract to: #{framework_path}
+    MSG
+  end
+  
+  # Log paths for debugging (visible during pod install)
+  puts "[SherpaOnnx] Pod root: #{pod_root}"
+  puts "[SherpaOnnx] Include path: #{ios_include_path}"
+  puts "[SherpaOnnx] Framework path: #{framework_path}"
+  framework_version = File.read(File.join(pod_root, 'ios', 'Frameworks', '.framework-version')).strip rescue 'unknown'
+  puts "[SherpaOnnx] Framework version: #{framework_version}"
+  
+  # Use vendored_frameworks for the XCFramework
+  s.vendored_frameworks = 'ios/Frameworks/sherpa_onnx.xcframework'
+  
+  # Preserve headers and config files
+  s.preserve_paths = [
+    'ios/SherpaOnnx.xcconfig',
+    'ios/include/**/*'
+  ]
+  
+  s.pod_target_xcconfig = {
+    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
+    'CLANG_CXX_LIBRARY' => 'libc++',
+    'HEADER_SEARCH_PATHS' => "$(inherited) \"#{ios_include_path}\"",
+  }
+  
+  s.user_target_xcconfig = {
+    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
+    'CLANG_CXX_LIBRARY' => 'libc++',
+  }
+  
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,193 @@
+// Configurable sherpa-onnx version (default: 1.12.23)
+def sherpaOnnxVersion = project.hasProperty('sherpaOnnxVersion') ? project.sherpaOnnxVersion : '1.12.23'
+
+buildscript {
+  ext.SherpaOnnx = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return SherpaOnnx[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.sherpaonnx"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+
+    // NDK configuration
+    ndkVersion getExtOrDefault("ndkVersion")
+    externalNativeBuild {
+      cmake {
+        cppFlags "-std=c++17", "-Wall", "-Wextra", "-fvisibility=hidden"
+        arguments "-DANDROID_STL=c++_shared"
+      }
+    }
+
+    // Supported ABIs
+    ndk {
+      abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  // CMake configuration
+  externalNativeBuild {
+    cmake {
+      path "src/main/cpp/CMakeLists.txt"
+      version "3.22.1"
+    }
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+
+repositories {
+  mavenCentral()
+  google()
+  maven { url 'https://jitpack.io' }
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+  
+  // sherpa-onnx prebuilt AAR from JitPack
+  // This includes the native .so libraries for all ABIs
+  implementation "com.github.k2-fsa:sherpa-onnx:v${sherpaOnnxVersion}"
+}
+
+// Create resolvable configuration for extraction
+configurations {
+  extractNativeLibs {
+    canBeResolved = true
+    canBeConsumed = false
+  }
+}
+
+dependencies {
+  extractNativeLibs "com.github.k2-fsa:sherpa-onnx:v${sherpaOnnxVersion}"
+}
+
+// Extract native libraries from AAR before CMake runs
+def extractNativeLibs = tasks.register("extractNativeLibs") {
+  doLast {
+    def extractedLibsDir = file("${buildDir}/extracted_native_libs")
+    extractedLibsDir.mkdirs()
+    
+    def resolvedConfig = configurations.extractNativeLibs.resolvedConfiguration
+    def foundAar = false
+    
+    resolvedConfig.resolvedArtifacts.each { artifact ->
+      def aarFile = artifact.file
+      println "Checking artifact: ${aarFile.name} (exists: ${aarFile.exists()})"
+      
+      if (aarFile.exists() && (aarFile.name.endsWith(".aar") || aarFile.name.endsWith(".jar"))) {
+        foundAar = true
+        println "Extracting native libraries from: ${aarFile.name}"
+        
+        copy {
+          from(zipTree(aarFile)) {
+            include "jni/**/*.so"
+          }
+          into extractedLibsDir
+        }
+        
+        // Verify extraction succeeded
+        def extractedFiles = fileTree(extractedLibsDir).matching { include "**/*.so" }
+        if (extractedFiles.isEmpty()) {
+          println "WARNING: No .so files extracted from ${aarFile.name}"
+          println "Contents of AAR:"
+          zipTree(aarFile).each { entry ->
+            if (entry.name.contains("jni") || entry.name.endsWith(".so")) {
+              println "  ${entry.name}"
+            }
+          }
+        }
+      }
+    }
+    
+    if (!foundAar) {
+      throw new RuntimeException("No AAR file found for sherpa-onnx. Check if the dependency is correctly resolved.")
+    }
+  }
+}
+
+// NOTE: Header files are now set up by postinstall script (yarn setup-assets)
+// This runs automatically after yarn/npm install and handles copying headers
+// We no longer need a Gradle task for this - headers will be present when build starts
+
+// Task to check and log header source before CMake runs
+def checkHeaderSource = tasks.register("checkHeaderSource") {
+  doLast {
+    def cppDir = file("src/main/cpp")
+    def bundledHeaderPath = file("${cppDir}/include/sherpa-onnx/c-api/cxx-api.h")
+    
+    if (bundledHeaderPath.exists()) {
+      println "[SherpaOnnx] Header files present"
+    } else {
+      println "[SherpaOnnx] ERROR: Header files not found at ${bundledHeaderPath.absolutePath}"
+      throw new RuntimeException("Header files not found. Run 'yarn setup-assets' or 'yarn copy-headers'")
+    }
+  }
+}
+
+// Make CMake depend on extraction and header verification - ensure they run before any CMake task
+afterEvaluate {
+  tasks.matching { it.name.contains("configureCMake") || it.name.contains("externalNativeBuild") }.configureEach {
+    dependsOn extractNativeLibs
+    dependsOn checkHeaderSource
+  }
+  
+  // Also ensure all extraction and verification tasks run before preBuild
+  preBuild.dependsOn extractNativeLibs
+  preBuild.dependsOn checkHeaderSource
+}