react-native-sherpa-onnx 0.1.0 → 0.3.0

package/README.md

@@ -2,50 +2,75 @@
 
 React Native SDK for sherpa-onnx - providing offline speech processing capabilities
 
+<div align="center">
+  <img src="./docs/images/banner.png" alt="Banner" width="560" />
+</div>
+
+<div align="center">
+
 [![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/)
 
+</div>
+
+> **⚠️ SDK 0.3.0 – Breaking changes from 0.2.0**  
+> Since the last release I have restructured and improved the SDK significantly: full iOS support, smoother behaviour, fewer failure points, and a much smaller footprint (~95% size reduction). As a result, **logic and the public API have changed**. If you are upgrading from 0.2.x, please follow the [Breaking changes (upgrading to 0.3.0)](docs/migration.md#breaking-changes-upgrading-to-030) section and the updated API documentation 
+
 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).
 
+## Table of contents
+
+- [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)
+  - [Instance-based API (TTS + STT)](#instance-based-api-tts--stt)
+  - [Speech-to-Text (STT)](#speech-to-text-stt)
+  - [Text-to-Speech (TTS)](#text-to-speech-tts)
+- [Example Apps](#example-apps)
+  - [Example App (Audio to Text)](#example-app-audio-to-text)
+  - [Video to Text Comparison App](#video-to-text-comparison-app)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## 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 |
+| 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). |
+| Text-to-Speech | ✅ **Supported** | Multiple model types (VITS, Matcha, Kokoro, etc.). See [Supported Model Types](#supported-model-types). |
+| 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). |
+| 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. |
+| Speaker Diarization | ❌ Not yet supported | Scheduled for release 0.4.0 |
+| Speech Enhancement | ❌ Not yet supported | Scheduled for release 0.5.0 |
+| Source Separation | ❌ Not yet supported | Scheduled for release 0.6.0 |
+| VAD (Voice Activity Detection) | ❌ Not yet supported | Scheduled for release 0.7.0 |
 
 ## 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**
+| **Android** | ✅ **Production Ready** | CI/CD automated, multiple models supported |
+| **iOS** | ✅ **Production Ready** | CI/CD automated, multiple models supported |
 
 ## Supported Model Types
 
+### Speech-to-Text (STT) Models
+
 | 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) |
@@ -56,16 +81,16 @@ A React Native TurboModule that provides offline speech processing capabilities
 | **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
+### Text-to-Speech (TTS) Models
 
-- ✅ **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
+| Model Type       | `modelType` Value | Description                                                                                          | Download Links                                                                      |
+| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **VITS**         | `'vits'`          | Fast, high-quality TTS. Includes Piper, Coqui, MeloTTS, MMS variants. Requires `model.onnx`, `tokens.txt` | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models)          |
+| **Matcha**       | `'matcha'`        | High-quality acoustic model + vocoder. Requires `acoustic_model.onnx`, `vocoder.onnx`, `tokens.txt` | [Download](https://k2-fsa.github.io/sherpa/onnx/tts/pretrained_models/matcha.html) |
+| **Kokoro**       | `'kokoro'`        | Multi-speaker, multi-language. Requires `model.onnx`, `voices.bin`, `tokens.txt`, `espeak-ng-data/` | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models)          |
+| **KittenTTS**    | `'kitten'`        | Lightweight, multi-speaker. Requires `model.onnx`, `voices.bin`, `tokens.txt`, `espeak-ng-data/`    | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models)          |
+| **Zipvoice**     | `'zipvoice'`      | Voice cloning capable. Requires `encoder.onnx`, `decoder.onnx`, `vocoder.onnx`, `tokens.txt`        | [Download](https://k2-fsa.github.io/sherpa/onnx/tts/pretrained_models/zipvoice.html) |
+| **Pocket**       | `'pocket'`        | Flow-matching TTS. Requires `lm_flow.onnx`, `lm_main.onnx`, `encoder.onnx`, `decoder.onnx`, `text_conditioner.onnx`, `vocab.json`, `token_scores.json` | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models) |
 
 ## Installation
 
@@ -88,255 +113,51 @@ YARN_NODE_LINKER=node-modules yarn install
 
 ### Android
 
-No additional setup required. The library automatically handles native dependencies via Gradle.
+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 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`.
+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).
 
-#### Quick Setup
+#### Setup
 
 ```sh
-cd example
+cd your-app/ios
 bundle install
-bundle exec pod install --project-directory=ios
+bundle exec pod install
 ```
 
-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
+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 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.
+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:
 
-## Quick Start
+- **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)).
 
-```typescript
-import { resolveModelPath } from 'react-native-sherpa-onnx';
-import {
-  initializeSTT,
-  transcribeFile,
-  unloadSTT,
-} from 'react-native-sherpa-onnx/stt';
+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.
 
-// Initialize with a model
-const modelPath = await resolveModelPath({
-  type: 'asset',
-  path: 'models/sherpa-onnx-model',
-});
+## Documentation
 
-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,
-});
-```
+- [Text-to-Speech (TTS)](./docs/tts.md)
+- [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 Download Manager](./docs/download-manager.md)
 
-### 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
+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
 
 - React Native >= 0.70
 - Android API 24+ (Android 7.0+)
-- iOS 13.0+ (requires sherpa-onnx XCFramework - see iOS Setup below)
+- iOS 13.0+
 
 ## Example Apps
 
@@ -360,9 +181,17 @@ 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%" />
+<table>
+<tr>
+<td><img src="./docs/images/example_home_screen.png" alt="Model selection home screen" width="240" /></td>
+<td><img src="./docs/images/example_stt_1.png" alt="Transcribe english audio" width="240" /></td>
+<td><img src="./docs/images/example_stt_2.png" alt="Transcribe cantonese audio" width="240" /></td>
+</tr>
+<tr>
+<td><img src="./docs/images/example_tts.png" alt="Text to speech generation" width="240" /></td>
+<td><img src="./docs/images/example_provider.png" alt="Text to speech generation" width="240" /></td>
+</tr>
+</table>
 </div>
 
 ### Video to Text Comparison App
@@ -400,3 +229,4 @@ MIT
 ---
 
 Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
+

package/SherpaOnnx.podspec

@@ -1,11 +1,41 @@
 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')
+# 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
 
 Pod::Spec.new do |s|
   s.name         = "SherpaOnnx"
@@ -17,68 +47,42 @@ 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}" }
-  
-  # 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/**/*'
-  ]
-  
+
+  # Download sherpa-onnx XCFramework from GitHub Releases before pod install (uses IOS_RELEASE_TAG for pinned version).
+  setup_script = File.join(pod_root, "scripts", "setup-ios-framework.sh")
+  s.prepare_command = "bash \"#{setup_script}\""
+
+  s.source_files = ["ios/**/*.{h,m,mm,swift,cpp}", *libarchive_sources]
+  s.private_header_files = "ios/**/*.h"
+
+  s.frameworks = "Foundation", "Accelerate", "CoreML"
+  s.vendored_frameworks = "ios/Frameworks/sherpa_onnx.xcframework"
+  # 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")
+  device_headers = File.join(xcframework_root, "ios-arm64", "Headers")
+  simulator_slice = File.join(xcframework_root, "ios-arm64_x86_64-simulator")
+  device_slice = File.join(xcframework_root, "ios-arm64")
+
   s.pod_target_xcconfig = {
-    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
-    'CLANG_CXX_LIBRARY' => 'libc++',
-    'HEADER_SEARCH_PATHS' => "$(inherited) \"#{ios_include_path}\"",
+    "HEADER_SEARCH_PATHS" => "$(inherited) \"#{pod_root}/ios\" \"#{pod_root}/ios/archive\" \"#{pod_root}/ios/model_detect\" \"#{pod_root}/ios/stt\" \"#{pod_root}/ios/tts\" \"#{libarchive_dir}\" \"#{device_headers}\" \"#{simulator_headers}\"",
+    "GCC_PREPROCESSOR_DEFINITIONS" => '$(inherited) PLATFORM_CONFIG_H=\\"libarchive_darwin_config.h\\"',
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++17",
+    "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"
   }
-  
+
   s.user_target_xcconfig = {
-    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
-    'CLANG_CXX_LIBRARY' => 'libc++',
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++17",
+    "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"
   }
-  
+
+  s.libraries = "c++", "z"
+
   install_modules_dependencies(s)
-end
+end