react-native-sherpa-onnx 0.3.3 → 0.3.4

package/README.md

@@ -23,16 +23,57 @@ React Native SDK for sherpa-onnx – offline and streaming speech processing
 
 A React Native TurboModule that provides offline and streaming 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 and **online (streaming)** speech-to-text, text-to-speech (batch and streaming), speaker diarization, speech enhancement, source separation, and VAD (Voice Activity Detection).
 
+## 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. For execution provider support (CPU, NNAPI, XNNPACK, QNN) and optional QNN setup, see [Execution provider support](./docs/execution-providers.md). For building Android native libs yourself, see [sherpa-onnx-prebuilt](third_party/sherpa-onnx-prebuilt/README.md).
+
+### iOS
+
+The sherpa-onnx **XCFramework is not shipped in the repo or npm** (size ~80MB). It is **downloaded automatically** when you run `pod install`; no manual steps are required. The version used is pinned in `third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG` and the archive is fetched from [GitHub Releases](https://github.com/XDcobra/react-native-sherpa-onnx/releases?q=framework).
+
+#### Setup
+
+```sh
+cd your-app/ios
+bundle install
+bundle exec pod install
+```
+
+The podspec runs `scripts/setup-ios-framework.sh`, which downloads the XCFramework (and, if needed, libarchive sources) so the Pod builds correctly. Libarchive is compiled from source as part of the Pod; its version is pinned in `third_party/libarchive_prebuilt/IOS_RELEASE_TAG`.
+
+#### Building the iOS framework
+
+To build the sherpa-onnx iOS XCFramework yourself (e.g. custom version or patches), see [third_party/sherpa-onnx-prebuilt/README.md](third_party/sherpa-onnx-prebuilt/README.md) and the [build-sherpa-onnx-ios-framework](.github/workflows/build-sherpa-onnx-ios-framework.yml) workflow.
+
 ## Table of contents
 
+- [Installation](#installation)
+  - [Android](#android)
+  - [iOS](#ios)
 - [Feature Support](#feature-support)
 - [Platform Support Status](#platform-support-status)
 - [Supported Model Types](#supported-model-types)
   - [Speech-to-Text (STT) Models](#speech-to-text-stt-models)
   - [Text-to-Speech (TTS) Models](#text-to-speech-tts-models)
-- [Installation](#installation)
-  - [Android](#android)
-  - [iOS](#ios)
 - [Documentation](#documentation)
 - [Requirements](#requirements)
 - [Breaking changes (upgrading to 0.3.0)](#breaking-changes-upgrading-to-030)
@@ -50,12 +91,13 @@ A React Native TurboModule that provides offline and streaming speech processing
 | Feature | Status | Notes |
 |---------|--------|-------|
 | Offline Speech-to-Text | ✅ **Supported** | No internet required; multiple model types (Zipformer, Paraformer, Whisper, etc.). See [Supported Model Types](#supported-model-types) and [STT documentation](./docs/stt.md). |
-| Online (streaming) Speech-to-Text | ✅ **Supported** | Real-time recognition from microphone or stream; partial results, endpoint detection. Use streaming-capable models (e.g. transducer, paraformer). See [Streaming STT](./docs/stt_streaming.md). |
+| Online (streaming) Speech-to-Text | ✅ **Supported** | Real-time recognition from microphone or stream; partial results, endpoint detection. Use streaming-capable models (e.g. transducer, paraformer). See [Streaming STT](./docs/stt-streaming.md). |
+| Live capture API | ✅ **Supported** | Native microphone capture with resampling for live transcription (use with streaming STT). See [PCM Live Stream](./docs/pcm-live-stream.md). |
 | Text-to-Speech | ✅ **Supported** | Multiple model types (VITS, Matcha, Kokoro, etc.). See [Supported Model Types](#supported-model-types) and [TTS documentation](./docs/tts.md). |
-| Streaming Text-to-Speech | ✅ **Supported** | Incremental speech generation for low time-to-first-byte and playback while generating. See [Streaming TTS](./docs/tts_streaming.md). |
+| Streaming Text-to-Speech | ✅ **Supported** | Incremental speech generation for low time-to-first-byte and playback while generating. See [Streaming TTS](./docs/tts-streaming.md). |
 | Execution providers (CPU, NNAPI, XNNPACK, Core ML, QNN) | ✅ **Supported** | See [Execution provider support](./docs/execution-providers.md). |
-| Play Asset Delivery (PAD) | ✅ **Supported** | Android only. See [Model Setup](./docs/MODEL_SETUP.md). |
-| Automatic Model type detection | ✅ **Supported** | `detectSttModel()` and `detectTtsModel()` for a path. See [Model Setup: Model type detection](./docs/MODEL_SETUP.md#model-type-detection-without-initialization). |
+| Play Asset Delivery (PAD) | ✅ **Supported** | Android only. See [Model Setup](./docs/model-setup.md). |
+| Automatic Model type detection | ✅ **Supported** | `detectSttModel()` and `detectTtsModel()` for a path. See [Model Setup: Model type detection](./docs/model-setup.md#model-detection). |
 | Model quantization | ✅ **Supported** | Automatic detection and preference for quantized (int8) models. |
 | Flexible model loading | ✅ **Supported** | Asset models, file system models, or auto-detection. |
 | TypeScript | ✅ **Supported** | Full type definitions included. |
@@ -95,7 +137,7 @@ A React Native TurboModule that provides offline and streaming speech processing
 | **Telespeech CTC**       | `'telespeech_ctc'`| Telespeech CTC. Folder name should contain **telespeech**. | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/telespeech/index.html) |
 | **Tone CTC (t-one)**     | `'tone_ctc'`      | Lightweight streaming CTC (e.g. t-one). Folder name should contain **t-one**, **t_one**, or **tone** (as word). | [Download](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/online-ctc/index.html) |
 
-For **real-time (streaming) recognition** from a microphone or audio stream, use streaming-capable model types: `transducer`, `paraformer`, `zipformer2_ctc`, `nemo_ctc`, or `tone_ctc`. See [Streaming (Online) Speech-to-Text](./docs/stt_streaming.md).
+For **real-time (streaming) recognition** from a microphone or audio stream, use streaming-capable model types: `transducer`, `paraformer`, `zipformer2_ctc`, `nemo_ctc`, or `tone_ctc`. See [Streaming (Online) Speech-to-Text](./docs/stt-streaming.md).
 
 ### Text-to-Speech (TTS) Models
 
@@ -108,74 +150,26 @@ For **real-time (streaming) recognition** from a microphone or audio stream, use
 | **Zipvoice**     | `'zipvoice'`      | Voice cloning (encoder + decoder + vocoder). Detected by file layout; folder token optional. | [Download](https://k2-fsa.github.io/sherpa/onnx/tts/pretrained_models/zipvoice.html) |
 | **Pocket**       | `'pocket'`        | Flow-matching TTS. Detected by lm_flow, lm_main, text_conditioner, vocab/token_scores; no folder token required. | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models) |
 
-For **streaming TTS** (incremental generation, low latency), use `createStreamingTTS()` with supported model types. See [Streaming Text-to-Speech](./docs/tts_streaming.md).
-
-## 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. For execution provider support (CPU, NNAPI, XNNPACK, QNN) and optional QNN setup, see [Execution provider support](./docs/execution-providers.md). For building Android native libs yourself, see [sherpa-onnx-prebuilt](third_party/sherpa-onnx-prebuilt/README.md).
-
-
-### iOS
-
-The sherpa-onnx **XCFramework is not shipped in the repo or npm** (size ~80MB). It is **downloaded automatically** when you run `pod install`; no manual steps are required. The version used is pinned in `third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG` and the archive is fetched from [GitHub Releases](https://github.com/XDcobra/react-native-sherpa-onnx/releases?q=framework).
-
-#### Setup
-
-```sh
-cd your-app/ios
-bundle install
-bundle exec pod install
-```
-
-The podspec runs `scripts/setup-ios-framework.sh`, which downloads the XCFramework (and, if needed, libarchive sources) so the Pod builds correctly. Libarchive is compiled from source as part of the Pod; its version is pinned in `third_party/libarchive_prebuilt/IOS_RELEASE_TAG`.
-
-#### For Advanced Users: Building the Framework Locally
-#### Advanced: Building the iOS framework yourself
-
-If you need a custom sherpa-onnx build (e.g. different version or patches), you can build the XCFramework and place it in `ios/Frameworks/` before running `pod install`. The repo does not include an iOS build script; use one of:
-
-- **This repo's CI:** The [build-sherpa-onnx-ios-framework](.github/workflows/build-sherpa-onnx-ios-framework.yml) workflow produces the XCFramework and publishes it as a GitHub Release. You can run equivalent steps locally or inspect the workflow for the exact build and merge steps (including `libsherpa-onnx-cxx-api.a` and libarchive).
-- **Version and layout:** Pinned version and release layout are documented in [third_party/sherpa-onnx-prebuilt](third_party/sherpa-onnx-prebuilt/README.md) (Android focus; for iOS, see `IOS_RELEASE_TAG` and the [iOS framework workflow](.github/workflows/build-sherpa-onnx-ios-framework.yml)).
-
-The XCFramework must include the C++ API (`libsherpa-onnx-cxx-api.a` merged or linked) so that the iOS Obj-C++ code can use `sherpa_onnx::cxx::*`. The workflow's build script ensures this; if you use upstream `build-ios.sh` from sherpa-onnx, you may need to merge the C++ API into the static library yourself.
+For **streaming TTS** (incremental generation, low latency), use `createStreamingTTS()` with supported model types. See [Streaming Text-to-Speech](./docs/tts-streaming.md).
 
 ## Documentation
 
 - [Speech-to-Text (STT)](./docs/stt.md) – Offline transcription (file or samples)
-- [Streaming (Online) Speech-to-Text](./docs/stt_streaming.md) – Real-time recognition, partial results, endpoint detection
-- [PCM Live Stream](./docs/pcm_live_stream.md) – Native microphone capture with resampling for live transcription (use with streaming STT)
+- [Streaming (Online) Speech-to-Text](./docs/stt-streaming.md) – Real-time recognition, partial results, endpoint detection
+- [PCM Live Stream](./docs/pcm-live-stream.md) – Native microphone capture with resampling for live transcription (use with streaming STT)
 - [Text-to-Speech (TTS)](./docs/tts.md) – Offline and streaming generation
-- [Streaming Text-to-Speech](./docs/tts_streaming.md) – Incremental TTS (createStreamingTTS)
+- [Streaming Text-to-Speech](./docs/tts-streaming.md) – Incremental TTS (createStreamingTTS)
 - [Execution provider support (QNN, NNAPI, XNNPACK, Core ML)](./docs/execution-providers.md) – Checking and using acceleration backends
 - [Voice Activity Detection (VAD)](./docs/vad.md)
 - [Speaker Diarization](./docs/diarization.md)
 - [Speech Enhancement](./docs/enhancement.md)
 - [Source Separation](./docs/separation.md)
-- [Model Setup](./docs/MODEL_SETUP.md) – Bundled assets, Play Asset Delivery (PAD), model discovery APIs, and troubleshooting
+- [Model Setup](./docs/model-setup.md) – Bundled assets, Play Asset Delivery (PAD), model discovery APIs, and troubleshooting
 - [Model Download Manager](./docs/download-manager.md)
 - [Disable FFMPEG](./docs/disable-ffmpeg.md)
 - [Disable LIBARCHIVE](./docs/disable-libarchive.md)
 
-Note: For when to use `listAssetModels()` vs `listModelsAtPath()` and how to combine bundled and PAD/file-based models, see [Model Setup](./docs/MODEL_SETUP.md).
+Note: For when to use `listAssetModels()` vs `listModelsAtPath()` and how to combine bundled and PAD/file-based models, see [Model Setup](./docs/model-setup.md).
 
 ## Requirements
 

package/SherpaOnnx.podspec

@@ -2,40 +2,6 @@ require "json"
 
 package = JSON.parse(File.read(File.join(__dir__, "package.json")))
 pod_root = __dir__
-# Prefer libarchive_prebuilt layout (output of third_party/libarchive_prebuilt/build_libarchive_ios.sh).
-# Fallback: download via setup-ios-libarchive.sh to ios/Downloads/libarchive (e.g. when using SDK from npm).
-libarchive_prebuilt = File.join(pod_root, "third_party", "libarchive_prebuilt", "libarchive-ios-layout")
-libarchive_downloads = File.join(pod_root, "ios", "Downloads", "libarchive")
-unless File.directory?(libarchive_prebuilt) && Dir.glob(File.join(libarchive_prebuilt, "*.c")).any?
-  libarchive_script = File.join(pod_root, "ios", "scripts", "setup-ios-libarchive.sh")
-  if File.exist?(libarchive_script)
-    unless system("bash", libarchive_script)
-      abort("[SherpaOnnx] setup-ios-libarchive.sh failed. Check that third_party/libarchive_prebuilt/IOS_RELEASE_TAG exists and the release is available (network). Run the script manually: bash #{libarchive_script}")
-    end
-  end
-end
-libarchive_dir = (File.directory?(libarchive_prebuilt) && Dir.glob(File.join(libarchive_prebuilt, "*.c")).any?) ? libarchive_prebuilt : libarchive_downloads
-# Patch libarchive .c files (copy to ios/patched_libarchive with stdio.h/unistd.h added) so we don't modify the submodule.
-patched_dir = File.join(pod_root, "ios", "patched_libarchive")
-patch_script = File.join(pod_root, "ios", "scripts", "patch-libarchive-includes.sh")
-if File.directory?(libarchive_dir) && File.exist?(patch_script)
-  unless system("bash", patch_script, libarchive_dir)
-    abort("[SherpaOnnx] patch-libarchive-includes.sh failed. Check that #{libarchive_dir} contains libarchive .c/.h files.")
-  end
-end
-# Libarchive C sources: use patched copies (same exclude as before: test, windows, linux, sunos, freebsd).
-libarchive_sources = if File.directory?(patched_dir)
-  Dir.glob(File.join(patched_dir, "*.c")).reject { |f|
-    base = File.basename(f, ".c")
-    File.basename(f) =~ /^test\./ || base.include?("windows") || base.include?("linux") || base.include?("sunos") || base.include?("freebsd")
-  }.map { |f| Pathname.new(f).relative_path_from(Pathname.new(pod_root)).to_s.gsub("\\", "/") }
-else
-  []
-end
-
-if libarchive_sources.empty?
-  abort("[SherpaOnnx] Libarchive sources missing. Ensure third_party/libarchive_prebuilt/libarchive-ios-layout exists (run third_party/libarchive_prebuilt/build_libarchive_ios.sh) or ios/scripts/setup-ios-libarchive.sh has run, and that ios/scripts/patch-libarchive-includes.sh succeeds. Check pod install logs for patch script errors.")
-end
 
 # Run iOS framework setup when podspec is loaded (works for :path pods).
 setup_script = File.join(pod_root, "scripts", "setup-ios-framework.sh")
@@ -44,7 +10,7 @@ if File.exist?(setup_script)
   ENV["SHERPA_ONNX_PROJECT_ROOT"] = pod_root
   unless system("bash", setup_script)
     ENV["SHERPA_ONNX_PROJECT_ROOT"] = prev
-    abort("[SherpaOnnx] setup-ios-framework.sh failed. Check third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG and network. Run manually: bash #{setup_script}")
+    abort("[SherpaOnnx] setup-ios-framework.sh failed. Check IOS_RELEASE_TAG files (sherpa-onnx-prebuilt, ffmpeg_prebuilt, libarchive_prebuilt) and network. Run manually: bash #{setup_script}")
   end
   ENV["SHERPA_ONNX_PROJECT_ROOT"] = prev
 end
@@ -60,11 +26,31 @@ Pod::Spec.new do |s|
   s.platforms    = { :ios => min_ios_version_supported }
   s.source       = { :git => "https://github.com/XDcobra/react-native-sherpa-onnx.git", :tag => "#{s.version}" }
 
-  s.source_files = ["ios/**/*.{h,m,mm,swift,cpp}", *libarchive_sources]
+  s.source_files = ["ios/**/*.{h,m,mm,swift,cpp}"]
   s.private_header_files = "ios/**/*.h"
 
   s.frameworks = "Foundation", "Accelerate", "CoreML", "AVFoundation", "AudioToolbox"
-  s.vendored_frameworks = "ios/Frameworks/sherpa_onnx.xcframework"
+
+  ffmpeg_xcframework = File.join(pod_root, "ios", "Frameworks", "FFmpeg.xcframework")
+  libarchive_xcframework = File.join(pod_root, "ios", "Frameworks", "libarchive.xcframework")
+  
+  has_ffmpeg = false
+  disable_ffmpeg = ENV['SHERPA_ONNX_DISABLE_FFMPEG']
+  if (!disable_ffmpeg || disable_ffmpeg == '0' || disable_ffmpeg == 'false') && File.exist?(ffmpeg_xcframework)
+    has_ffmpeg = true
+  end
+
+  has_libarchive = false
+  disable_libarchive = ENV['SHERPA_ONNX_DISABLE_LIBARCHIVE']
+  if (!disable_libarchive || disable_libarchive == '0' || disable_libarchive == 'false') && File.exist?(libarchive_xcframework)
+    has_libarchive = true
+  end
+
+  vendored = ["ios/Frameworks/sherpa_onnx.xcframework"]
+  vendored << "ios/Frameworks/FFmpeg.xcframework" if has_ffmpeg
+  vendored << "ios/Frameworks/libarchive.xcframework" if has_libarchive
+  
+  s.vendored_frameworks = vendored
   # Absolute paths so headers are found regardless of PODS_TARGET_SRCROOT (e.g. when building via React Native CLI).
   xcframework_root = File.join(pod_root, "ios", "Frameworks", "sherpa_onnx.xcframework")
   simulator_headers = File.join(xcframework_root, "ios-arm64_x86_64-simulator", "Headers")
@@ -72,14 +58,54 @@ Pod::Spec.new do |s|
   simulator_slice = File.join(xcframework_root, "ios-arm64_x86_64-simulator")
   device_slice = File.join(xcframework_root, "ios-arm64")
 
+  libarchive_xcframework_root = File.join(pod_root, "ios", "Frameworks", "libarchive.xcframework")
+  libarchive_simulator_headers = File.join(libarchive_xcframework_root, "ios-arm64_x86_64-simulator", "Headers")
+  libarchive_device_headers = File.join(libarchive_xcframework_root, "ios-arm64", "Headers")
+
+  ffmpeg_simulator_headers = File.join(ffmpeg_xcframework, "ios-arm64_x86_64-simulator", "Headers")
+  ffmpeg_device_headers = File.join(ffmpeg_xcframework, "ios-arm64", "Headers")
+
+  gcc_defs = '$(inherited) PLATFORM_CONFIG_H=\\"libarchive_darwin_config.h\\"'
+  gcc_defs += ' HAVE_FFMPEG=1' if has_ffmpeg
+  gcc_defs += ' HAVE_LIBARCHIVE=1' if has_libarchive
+
+  ld_flags = '$(inherited) -lsherpa-onnx'
+  if has_ffmpeg
+    ld_flags += ' -lffmpeg -liconv -lbz2'
+  end
+  if has_libarchive
+    ld_flags += ' -larchive'
+  end
+
+  header_search_paths = [
+    "$(inherited)",
+    "\"#{pod_root}/ios\"",
+    "\"#{pod_root}/ios/archive\"",
+    "\"#{pod_root}/ios/model_detect\"",
+    "\"#{pod_root}/ios/stt\"",
+    "\"#{pod_root}/ios/tts\"",
+    "\"#{pod_root}/ios/online_stt\"",
+    "\"#{device_headers}\"",
+    "\"#{simulator_headers}\""
+  ]
+  if has_libarchive
+    header_search_paths << "\"#{libarchive_device_headers}\""
+    header_search_paths << "\"#{libarchive_simulator_headers}\""
+  end
+  if has_ffmpeg
+    header_search_paths << "\"#{ffmpeg_device_headers}\""
+    header_search_paths << "\"#{ffmpeg_simulator_headers}\""
+  end
+
   s.pod_target_xcconfig = {
-    "HEADER_SEARCH_PATHS" => "$(inherited) \"#{pod_root}/ios\" \"#{pod_root}/ios/archive\" \"#{pod_root}/ios/model_detect\" \"#{pod_root}/ios/stt\" \"#{pod_root}/ios/tts\" \"#{pod_root}/ios/online_stt\" \"#{libarchive_dir}\" \"#{device_headers}\" \"#{simulator_headers}\"",
-    "GCC_PREPROCESSOR_DEFINITIONS" => '$(inherited) PLATFORM_CONFIG_H=\\"libarchive_darwin_config.h\\"',
+    "HEADER_SEARCH_PATHS" => header_search_paths.join(" "),
+    "GCC_PREPROCESSOR_DEFINITIONS" => gcc_defs,
     "CLANG_CXX_LANGUAGE_STANDARD" => "c++17",
     "CLANG_CXX_LIBRARY" => "libc++",
+    "OTHER_CPLUSPLUSFLAGS" => "$(inherited)",
     "LIBRARY_SEARCH_PATHS[sdk=iphoneos*]" => "$(inherited) \"#{device_slice}\"",
     "LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*]" => "$(inherited) \"#{simulator_slice}\"",
-    "OTHER_LDFLAGS" => "$(inherited) -lsherpa-onnx"
+    "OTHER_LDFLAGS" => ld_flags
   }
 
   s.user_target_xcconfig = {
@@ -87,10 +113,10 @@ Pod::Spec.new do |s|
     "CLANG_CXX_LIBRARY" => "libc++",
     "LIBRARY_SEARCH_PATHS[sdk=iphoneos*]" => "$(inherited) \"#{device_slice}\"",
     "LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*]" => "$(inherited) \"#{simulator_slice}\"",
-    "OTHER_LDFLAGS" => "$(inherited) -lsherpa-onnx"
+    "OTHER_LDFLAGS" => ld_flags
   }
 
-  s.libraries = "c++", "z"
+  s.libraries = "c++", "z", "iconv", "bz2"
 
   install_modules_dependencies(s)
-end
+end

package/android/build.gradle

@@ -103,7 +103,7 @@ android {
       jniLibs {
         excludes += [
           "**/libavcodec.so", "**/libavformat.so", "**/libavutil.so",
-          "**/libavfilter.so", "**/libswresample.so", "**/libshine.so"
+          "**/libavfilter.so", "**/libswresample.so", "**/libshine.so", "**/libopus.so"
         ]
       }
     }
@@ -132,10 +132,16 @@ android {
   }
 }
 
+// Resolve com.xdcobra.sherpa only from this repo (never from JitPack or other app repos).
 repositories {
+  exclusiveContent {
+    forRepository { maven { url "https://xdcobra.github.io/maven" } }
+    filter {
+      includeGroup "com.xdcobra.sherpa"
+    }
+  }
   mavenCentral()
   google()
-  maven { url "https://xdcobra.github.io/maven" }
 }
 
 // Configurations used by prebuilt-download.gradle: downloadNativeLibsIfNeeded (AAR --> jniLibs + headers),

package/android/prebuilt-download.gradle

@@ -104,14 +104,32 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
     def storedSherpaVersion = (sherpaVersionFile.exists() ? sherpaVersionFile.text.trim() : null)
     def sherpaNeedsUpdate = !hasAllSherpaLibs() || !hasSherpaHeaders() || storedSherpaVersion == null || storedSherpaVersion != currentSherpaVersion
 
+    def currentFfmpegVersion = project.ext.ffmpegVersion
+    def ffmpegVersionFile = new File(downloadDir, "ffmpeg-version.txt")
+    def storedFfmpegVersion = (ffmpegVersionFile.exists() ? ffmpegVersionFile.text.trim() : null)
+    def ffmpegNeedsUpdate = !hasAllFfmpegLibs() || !hasFfmpegHeaders() || storedFfmpegVersion == null || storedFfmpegVersion != currentFfmpegVersion
+
+    def currentLibarchiveVersion = project.ext.libarchiveVersion
+    def libarchiveVersionFile = new File(downloadDir, "libarchive-version.txt")
+    def storedLibarchiveVersion = (libarchiveVersionFile.exists() ? libarchiveVersionFile.text.trim() : null)
+    def libarchiveNeedsUpdate = !hasAllLibarchiveLibs() || !hasLibarchiveHeaders() || storedLibarchiveVersion == null || storedLibarchiveVersion != currentLibarchiveVersion
+
     if (hasAllSherpaLibs() && hasSherpaHeaders() && !sherpaNeedsUpdate) {
       println "[sherpa-onnx] Native libs + headers: (1) already present, version ${currentSherpaVersion}"
     }
     if (sherpaNeedsUpdate && storedSherpaVersion != null && storedSherpaVersion != currentSherpaVersion) {
       println "[sherpa-onnx] Version change detected (${storedSherpaVersion} -> ${currentSherpaVersion}), refreshing libs and headers"
     }
+    if (ffmpegNeedsUpdate && storedFfmpegVersion != null && storedFfmpegVersion != currentFfmpegVersion) {
+      println "[FFmpeg] Version change detected (${storedFfmpegVersion} -> ${currentFfmpegVersion}), refreshing libs and headers"
+    }
+    if (libarchiveNeedsUpdate && storedLibarchiveVersion != null && storedLibarchiveVersion != currentLibarchiveVersion) {
+      println "[libarchive] Version change detected (${storedLibarchiveVersion} -> ${currentLibarchiveVersion}), refreshing libs and headers"
+    }
 
     def sherpaUpdatedFromAar = [false]
+    def ffmpegUpdatedFromAar = [false]
+    def libarchiveUpdatedFromAar = [false]
     if (sherpaNeedsUpdate) {
       try {
         def aarFiles = project.configurations.sherpaOnnxAar.files
@@ -145,7 +163,7 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
       }
     }
 
-    if (!sherpaOnnxDisableFfmpeg && (!hasAllFfmpegLibs() || !hasFfmpegHeaders())) {
+    if (!sherpaOnnxDisableFfmpeg && ffmpegNeedsUpdate) {
       try {
         def aarFiles = project.configurations.ffmpegAar.files
         if (!aarFiles.isEmpty()) {
@@ -168,6 +186,9 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
             copy { from aarIncludeDir; into ffmpegIncludeDir }
             println "Extracted FFmpeg headers from Maven AAR"
           }
+          downloadDir.mkdirs()
+          ffmpegVersionFile.text = currentFfmpegVersion
+          ffmpegUpdatedFromAar[0] = true
           println "[FFmpeg] Native libs + headers: (2) Maven AAR (${aar.name})"
         }
       } catch (Exception e) {
@@ -175,7 +196,7 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
       }
     }
 
-    if (!sherpaOnnxDisableLibarchive && (!hasAllLibarchiveLibs() || !hasLibarchiveHeaders())) {
+    if (!sherpaOnnxDisableLibarchive && libarchiveNeedsUpdate) {
       try {
         def aarFiles = project.configurations.libarchiveAar.files
         if (!aarFiles.isEmpty()) {
@@ -198,6 +219,9 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
             copy { from aarIncludeDir; into libarchiveIncludeDir }
             println "Extracted libarchive headers from Maven AAR"
           }
+          downloadDir.mkdirs()
+          libarchiveVersionFile.text = currentLibarchiveVersion
+          libarchiveUpdatedFromAar[0] = true
           println "[libarchive] Native libs + headers: (2) Maven AAR (${aar.name})"
         }
       } catch (Exception e) {
@@ -237,14 +261,27 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
 
     def repo = project.findProperty('prebuiltGitHubRepo') ?: getGitHubRepo()
     if (!repo) {
-      def needFfmpeg = !sherpaOnnxDisableFfmpeg && (!hasAllFfmpegLibs() || !hasFfmpegHeaders())
-      def needLibarchive = !sherpaOnnxDisableLibarchive && (!hasAllLibarchiveLibs() || !hasLibarchiveHeaders())
-      if (needFfmpeg || needLibarchive || (sherpaNeedsUpdate && !sherpaUpdatedFromAar[0])) {
+      def needFfmpeg = !sherpaOnnxDisableFfmpeg && ffmpegNeedsUpdate && !ffmpegUpdatedFromAar[0]
+      def needLibarchive = !sherpaOnnxDisableLibarchive && libarchiveNeedsUpdate && !libarchiveUpdatedFromAar[0]
+      def needSherpa = sherpaNeedsUpdate && !sherpaUpdatedFromAar[0]
+      if (needFfmpeg || needLibarchive || needSherpa) {
+        def diag = [
+          "prebuiltGitHubRepo=${project.findProperty('prebuiltGitHubRepo') ?: '(not set)'}",
+          "git remote origin=${getGitHubRepo() ?: '(not a GitHub URL or git unavailable)'}",
+          "sherpaOnnxDisableFfmpeg=${sherpaOnnxDisableFfmpeg}",
+          "sherpaOnnxDisableLibarchive=${sherpaOnnxDisableLibarchive}",
+          "sherpaNeedsUpdate=${sherpaNeedsUpdate} sherpaUpdatedFromAar=${sherpaUpdatedFromAar[0]}",
+          "ffmpegNeedsUpdate=${ffmpegNeedsUpdate} ffmpegUpdatedFromAar=${ffmpegUpdatedFromAar[0]}",
+          "libarchiveNeedsUpdate=${libarchiveNeedsUpdate} libarchiveUpdatedFromAar=${libarchiveUpdatedFromAar[0]}",
+          "needFfmpeg=${needFfmpeg} needLibarchive=${needLibarchive} needSherpa=${needSherpa}"
+        ].join(", ")
         throw new RuntimeException(
-          "Native libs/headers still missing and GitHub repo unknown. Set -PprebuiltGitHubRepo=owner/repo or ensure git remote origin is a GitHub URL. " +
+          "Native libs/headers still missing and GitHub repo unknown. " +
+          "Set -PprebuiltGitHubRepo=owner/repo or ensure git remote origin is a GitHub URL. " +
           "Alternatively run third_party/ffmpeg_prebuilt/copy_prebuilts_to_sdk.js, third_party/sherpa-onnx-prebuilt/copy_prebuilts_to_sdk.js, third_party/libarchive_prebuilt/copy_prebuilts_to_sdk.js, or use Maven (com.xdcobra.sherpa:ffmpeg / sherpa-onnx / libarchive), or ensure ANDROID_RELEASE_TAG releases exist. " +
           (sherpaOnnxDisableFfmpeg ? "(FFmpeg disabled via sherpaOnnxDisableFfmpeg=true.) " : "") +
-          (sherpaOnnxDisableLibarchive ? "(libarchive disabled via sherpaOnnxDisableLibarchive=true.)" : "")
+          (sherpaOnnxDisableLibarchive ? "(libarchive disabled via sherpaOnnxDisableLibarchive=true.) " : "") +
+          "Diagnostics: [${diag}]"
         )
       }
       return
@@ -252,13 +289,13 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
     def baseUrl = "https://github.com/${repo}/releases/download"
     downloadDir.mkdirs()
 
-    if (!sherpaOnnxDisableFfmpeg && (!hasAllFfmpegLibs() || !hasFfmpegHeaders())) {
+    if (!sherpaOnnxDisableFfmpeg && ffmpegNeedsUpdate && !ffmpegUpdatedFromAar[0]) {
       def tagFile = file("${project.projectDir.parent}/third_party/ffmpeg_prebuilt/ANDROID_RELEASE_TAG")
       def tag = readReleaseTag(tagFile)
       if (!tag) throw new RuntimeException("Missing or empty third_party/ffmpeg_prebuilt/ANDROID_RELEASE_TAG")
       def zipFile = new File(downloadDir, "ffmpeg-android.zip")
       def url = "${baseUrl}/${tag}/ffmpeg-android.zip"
-      exec { commandLine 'curl', '-sSL', '-o', zipFile, url; workingDir project.projectDir }
+      project.exec { commandLine 'curl', '-sSL', '-o', zipFile, url; workingDir project.projectDir }
       if (!zipFile.exists() || zipFile.length() == 0) throw new RuntimeException("Download failed or empty: ${url}")
       def ffmpegExtractDir = new File(downloadDir, "ffmpeg-extract")
       if (ffmpegExtractDir.exists()) ffmpegExtractDir.deleteDir()
@@ -273,16 +310,18 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
       if (ffmpegIncludeInZip.exists()) {
         copy { from fileTree(ffmpegIncludeInZip); into ffmpegIncludeDir }
       }
+      downloadDir.mkdirs()
+      ffmpegVersionFile.text = currentFfmpegVersion
       println "Downloaded and extracted FFmpeg prebuilts (libs + include) from ${tag}"
     }
 
-    if (!sherpaOnnxDisableLibarchive && (!hasAllLibarchiveLibs() || !hasLibarchiveHeaders())) {
+    if (!sherpaOnnxDisableLibarchive && libarchiveNeedsUpdate && !libarchiveUpdatedFromAar[0]) {
       def tagFile = file("${project.projectDir.parent}/third_party/libarchive_prebuilt/ANDROID_RELEASE_TAG")
       def tag = readReleaseTag(tagFile)
       if (!tag) throw new RuntimeException("Missing or empty third_party/libarchive_prebuilt/ANDROID_RELEASE_TAG")
       def zipFile = new File(downloadDir, "libarchive-android.zip")
       def url = "${baseUrl}/${tag}/libarchive-android.zip"
-      exec { commandLine 'curl', '-sSL', '-o', zipFile, url; workingDir project.projectDir }
+      project.exec { commandLine 'curl', '-sSL', '-o', zipFile, url; workingDir project.projectDir }
       if (!zipFile.exists() || zipFile.length() == 0) throw new RuntimeException("Download failed or empty: ${url}")
       def libarchiveExtractDir = new File(downloadDir, "libarchive-extract")
       if (libarchiveExtractDir.exists()) libarchiveExtractDir.deleteDir()
@@ -298,6 +337,8 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
         libarchiveIncludeDir.mkdirs()
         copy { from libarchiveIncludeInZip; into libarchiveIncludeDir }
       }
+      downloadDir.mkdirs()
+      libarchiveVersionFile.text = currentLibarchiveVersion
       println "Downloaded and extracted libarchive prebuilts (libs + include) from ${tag}"
     }
 
@@ -307,7 +348,7 @@ project.tasks.register("downloadNativeLibsIfNeeded") {
       if (!tag) throw new RuntimeException("Missing or empty third_party/sherpa-onnx-prebuilt/ANDROID_RELEASE_TAG")
       def zipFile = new File(downloadDir, "sherpa-onnx-android.zip")
       def url = "${baseUrl}/${tag}/sherpa-onnx-android.zip"
-      exec { commandLine 'curl', '-sSL', '-o', zipFile, url; workingDir project.projectDir }
+      project.exec { commandLine 'curl', '-sSL', '-o', zipFile, url; workingDir project.projectDir }
       if (!zipFile.exists() || zipFile.length() == 0) throw new RuntimeException("Download failed or empty: ${url}")
       def sherpaExtractDir = new File(downloadDir, "sherpa-onnx-extract")
       if (sherpaExtractDir.exists()) sherpaExtractDir.deleteDir()

package/android/prebuilt-versions.gradle

@@ -30,6 +30,7 @@ if (!ffmpegVersion) {
   ffmpegVersion = v ?: (project.hasProperty('ffmpegVersion') ? project.ffmpegVersion : '8.0.1')
 }
 project.ext.ffmpegVersion = ffmpegVersion
+println "[react-native-sherpa-onnx] ffmpeg version (extracted/used): ${ffmpegVersion}"
 
 // libarchive: 1. LIBARCHIVE_VERSION env 2. ANDROID_RELEASE_TAG 3. property 4. default
 def libarchiveVersion = System.getenv('LIBARCHIVE_VERSION')
@@ -38,10 +39,13 @@ if (!libarchiveVersion) {
   libarchiveVersion = v ?: (project.hasProperty('libarchiveVersion') ? project.libarchiveVersion : '3.8.5')
 }
 project.ext.libarchiveVersion = libarchiveVersion
+println "[react-native-sherpa-onnx] libarchive version (extracted/used): ${libarchiveVersion}"
 
-// onnxruntime (ORT Java bridge): 1. ORT_VERSION env 2. property 3. default
+// onnxruntime (ORT Java bridge): 1. ORT_VERSION env 2. ANDROID_RELEASE_TAG 3. property 4. default
 def ortVersion = System.getenv('ORT_VERSION')
 if (!ortVersion) {
-  ortVersion = project.hasProperty('ortVersion') ? project.ortVersion : '1.24.2-qnn2.43.1.260218'
+  def v = readVersionFromTagFile(new File(moduleRoot, 'third_party/onnxruntime_prebuilt/ANDROID_RELEASE_TAG'), 'ort-android-qnn-v')
+  ortVersion = v ?: (project.hasProperty('ortVersion') ? project.ortVersion : '1.24.2-qnn2.43.1.260218')
 }
 project.ext.ortVersion = ortVersion
+println "[react-native-sherpa-onnx] onnxruntime version (extracted/used): ${ortVersion}"

package/android/src/main/cpp/CMakeLists.txt

@@ -76,6 +76,8 @@ set(SOURCES
     jni/model_detect/sherpa-onnx-model-detect-helper.cpp
     jni/model_detect/sherpa-onnx-model-detect-stt.cpp
     jni/model_detect/sherpa-onnx-model-detect-tts.cpp
+    jni/model_detect/sherpa-onnx-validate-stt.cpp
+    jni/model_detect/sherpa-onnx-validate-tts.cpp
     jni/model_detect/sherpa-onnx-detect-jni-common.cpp
     jni/model_detect/sherpa-onnx-stt-wrapper.cpp
     jni/model_detect/sherpa-onnx-tts-wrapper.cpp