react-native-sherpa-onnx 0.3.6 → 0.3.8

package/LICENSE

@@ -1,6 +1,7 @@
 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

package/README.md

@@ -48,7 +48,7 @@ No additional setup required. The library automatically handles native dependenc
 
 ### 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).
+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` (format: `sherpa-onnx-ios-vX.Y.Z` or `sherpa-onnx-ios-vX.Y.Z-N` with optional build number) and the archive is fetched from [GitHub Releases](https://github.com/XDcobra/react-native-sherpa-onnx/releases?q=sherpa-onnx-ios).
 
 #### Setup
 
@@ -62,15 +62,33 @@ The podspec runs `scripts/setup-ios-framework.sh`, which downloads the XCFramewo
 
 #### 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.
+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 [Framework - Sherpa-Onnx (iOS) Release](.github/workflows/framework-sherpa-onnx-ios-framework.yml) workflow.
+
+#### Model download (optional)
+
+If you use the [download manager](docs/download-manager.md) to fetch models at runtime, add the following to your **AppDelegate** so background downloads can finish when the app is in the background or after it was terminated. Without it, downloads only work reliably while the app is in the foreground.
+
+- **Swift (RN 0.77+):** In your bridging header add `#import <RNBackgroundDownloader.h>`. In `AppDelegate.swift`, implement:
+  ```swift
+  func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
+    RNBackgroundDownloader.setCompletionHandlerWithIdentifier(identifier, completionHandler: completionHandler)
+  }
+  ```
+- **Objective-C:** In `AppDelegate.m` add `#import <RNBackgroundDownloader.h>` and the `application:handleEventsForBackgroundURLSession:completionHandler:` implementation that calls `[RNBackgroundDownloader setCompletionHandlerWithIdentifier:identifier completionHandler:completionHandler]`.
+
+Full step-by-step: [Download manager – Setup (iOS & Android)](docs/download-manager.md#setup-ios--android). Expo users can use the library’s config plugin to apply this automatically.
+
+**Android:** Foreground service permissions (Play Console), visible download notifications, and **`POST_NOTIFICATIONS` (API 33+)** are covered in [Download manager – Android: foreground service & notifications](docs/download-manager.md#android-foreground-service--notifications).
 
 ## Table of contents
 
+- [Bundled sherpa-onnx version](#bundled-sherpa-onnx-version)
 - [Installation](#installation)
   - [Android](#android)
   - [iOS](#ios)
 - [Feature Support](#feature-support)
 - [Platform Support Status](#platform-support-status)
+- [Known issues](#known-issues)
 - [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)
@@ -86,25 +104,32 @@ To build the sherpa-onnx iOS XCFramework yourself (e.g. custom version or patche
 - [Contributing](#contributing)
 - [License](#license)
 
+## Bundled sherpa-onnx version
+
+| Platform | Version |
+|----------|---------|
+| Android | 1.12.31 |
+| iOS | 1.12.31 |
+
 ## Feature Support
 
-| 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). |
-| 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). |
-| 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) & [Extraction API](./docs/extraction.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. |
-| 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 |
+| Feature | Status | Docs | Notes |
+|---------|--------|------|-------|
+| Offline Speech-to-Text | ✅ **Supported** | [STT](./docs/stt.md) | No internet required; multiple model types (Zipformer, Paraformer, Whisper, etc.). See [Supported Model Types](#supported-model-types). |
+| Online (streaming) Speech-to-Text | ✅ **Supported** | [Streaming STT](./docs/stt-streaming.md) | Real-time recognition from microphone or stream; partial results, endpoint detection. Use streaming-capable models (e.g. transducer, paraformer). |
+| Live capture API | ✅ **Supported** | [PCM live stream](./docs/pcm-live-stream.md) | Native microphone capture with resampling for live transcription (use with streaming STT). |
+| Text-to-Speech | ✅ **Supported** | [TTS](./docs/tts.md) | Multiple model types (VITS, Matcha, Kokoro, etc.). See [Supported Model Types](#supported-model-types). |
+| Streaming Text-to-Speech | ✅ **Supported** | [Streaming TTS](./docs/tts-streaming.md) | Incremental speech generation for low time-to-first-byte and playback while generating. |
+| Execution providers (CPU, NNAPI, XNNPACK, Core ML, QNN) | ✅ **Supported** | [Execution providers](./docs/execution-providers.md) | CPU default; optional accelerators per platform. |
+| Play Asset Delivery (PAD) | ✅ **Supported** | [Model setup](./docs/model-setup.md) | Android only. Archives: [Extraction API](./docs/extraction.md). |
+| Automatic Model type detection | ✅ **Supported** | [Model detection](./docs/model-setup.md#model-detection) | `detectSttModel()` and `detectTtsModel()` for a path. |
+| Model quantization | ✅ **Supported** | [Model setup](./docs/model-setup.md) | Automatic detection and preference for quantized (int8) models. |
+| Flexible model loading | ✅ **Supported** | [Model setup](./docs/model-setup.md) | Asset models, file system models, or auto-detection. |
+| TypeScript | ✅ **Supported** | — | Full type definitions included. |
+| Speaker Diarization | ❌ Not yet supported | [Diarization](./docs/diarization.md) | Scheduled for release 0.4.0 |
+| Speech Enhancement | ❌ Not yet supported | [Enhancement](./docs/enhancement.md) | Scheduled for release 0.5.0 |
+| Source Separation | ❌ Not yet supported | [Separation](./docs/separation.md) | Scheduled for release 0.6.0 |
+| VAD (Voice Activity Detection) | ❌ Not yet supported | [VAD](./docs/vad.md) | Scheduled for release 0.7.0 |
 
 ## Platform Support Status
 
@@ -113,6 +138,10 @@ To build the sherpa-onnx iOS XCFramework yourself (e.g. custom version or patche
 | **Android** | ✅ **Production Ready** | CI/CD automated, multiple models supported |
 | **iOS** | ✅ **Production Ready** | CI/CD automated, multiple models supported |
 
+## Known issues
+
+- **[Pocket TTS (voice cloning)](docs/KNOWN_ISSUES.md)** — voice cloning: **Android** supported; **iOS** experimental. Heuristic EOS and **iOS vs Android drift** (length/quality); not a React Native–only issue. Full notes: [investigation doc](docs/github-issue-pocket-tts-eos-frame-zero.md).
+
 ## Supported Model Types
 
 ### Speech-to-Text (STT) Models
@@ -147,13 +176,15 @@ For **real-time (streaming) recognition** from a microphone or audio stream, use
 | **Matcha**       | `'matcha'`        | High-quality acoustic model + vocoder. Detected by acoustic_model + vocoder; no folder token required. | [Download](https://k2-fsa.github.io/sherpa/onnx/tts/pretrained_models/matcha.html) |
 | **Kokoro**       | `'kokoro'`        | Multi-speaker, multi-language. Folder name should contain **kokoro** (not kitten) for auto-detection. | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models)          |
 | **KittenTTS**    | `'kitten'`        | Lightweight, multi-speaker. Folder name should contain **kitten** (not kokoro) for auto-detection. | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models)          |
-| **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) |
+| **Zipvoice**     | `'zipvoice'`      | Standard TTS with **`sid`**. **Voice cloning** (reference audio + `referenceText`): batch via **`generateSpeech`** only—streaming TTS does not support reference audio for Zipvoice. Default **`numSteps`** when omitted is **5** on **Android and iOS** (matches sherpa-onnx `GenerationConfig` / Kotlin helper). Cloning is **supported on Android & iOS**. Encoder + decoder + vocoder. | [Download](https://k2-fsa.github.io/sherpa/onnx/tts/pretrained_models/zipvoice.html) |
+| **Pocket**       | `'pocket'`        | Flow-matching TTS. **Voice cloning** on **Android:** batch and streaming TTS. **iOS:** cloning is experimental. Detected by lm_flow, lm_main, text_conditioner, vocab/token_scores. | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models) |
+| **Supertonic**    | `'supertonic'`        | Lightning-fast, on-device text-to-speech system designed for extreme performance with minimal computational overhead. | [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).
 
 ## Documentation
 
+- [Known issues](./docs/KNOWN_ISSUES.md) – SDK-facing notes (e.g. Pocket TTS cloning / cross-platform behavior)
 - [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)
@@ -248,6 +279,46 @@ This app showcases how to integrate `react-native-sherpa-onnx` into a real-world
 
 MIT
 
+## Third-Party Libraries
+
+This SDK includes the following open source components:
+
+- [sherpa-onnx (Apache License 2.0)](/THIRD_PARTY_LICENSES/sherpa-onnx.txt): https://github.com/k2-fsa/sherpa-onnx
+
+- [ONNX Runtime (MIT License)](/THIRD_PARTY_LICENSES/onnxruntime.txt): https://github.com/microsoft/onnxruntime
+
+- [FFmpeg (LGPL v2.1)](/THIRD_PARTY_LICENSES/ffmpeg.txt): https://ffmpeg.org
+
+- [Shine MP3 Encoder (LGPL)](/THIRD_PARTY_LICENSES/shine.txt): https://github.com/toots/shine
+
+- [Opus Codec (BSD License)](/THIRD_PARTY_LICENSES/opus.txt): https://opus-codec.org
+
+- [Zstandard (zstd) (BSD License)](/THIRD_PARTY_LICENSES/zstd.txt): https://github.com/facebook/zstd
+
+- [libarchive (BSD License)](/THIRD_PARTY_LICENSES/libarchive.txt): https://github.com/libarchive/libarchive
+
+Full license texts are available in the [THIRD_PARTY_LICENSES](/THIRD_PARTY_LICENSES/) directory.
+
+### LGPL Notice
+
+This SDK includes LGPL-licensed components such as FFmpeg and Shine.  
+Applications using this SDK must ensure compliance with LGPL requirements when distributing binaries.
+
+FFmpeg source code can be obtained at: https://ffmpeg.org
+
+### Qualcomm QNN Support
+
+This SDK supports optional integration with Qualcomm AI Runtime (QNN).
+
+QNN is proprietary software provided by Qualcomm and is not included in this SDK.  
+To use QNN acceleration, users must obtain and include the required QNN libraries separately and comply with Qualcomm's license terms:
+
+https://softwarecenter.qualcomm.com/
+
+### Responsibility
+
+By using this SDK, you are responsible for complying with all third-party licenses included in this project.
+
 ---
 
 Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/SherpaOnnx.podspec

@@ -139,5 +139,8 @@ Pod::Spec.new do |s|
 
   s.libraries = "c++", "z", "iconv", "bz2"
 
+  # Per-release-model license metadata (synced from CI; same CSV as android/src/main/assets/model_licenses/).
+  s.resources = ["ios/Resources/model_licenses/*.csv"]
+
   install_modules_dependencies(s)
 end

package/THIRD_PARTY_LICENSES/README.md

@@ -0,0 +1,62 @@
+# Third-party license texts
+
+This directory contains **full license texts** for libraries shipped with this module (e.g. sherpa-onnx, ONNX Runtime, FFmpeg). See the repository [README](../README.md#third-party-libraries) for links.
+
+## Prebuilt model release assets (per-model metadata)
+
+**Model-specific license status** (which release `.tar.bz2` / asset has which `license_type`, `commercial_use`, provenance URL, etc.) is **not** stored here.
+
+It is maintained as CSV and **bundled with the native library** so apps can ship it without extra Metro assets:
+
+| Platform | Path (in this repo) |
+|----------|---------------------|
+| **Android** | [`android/src/main/assets/model_licenses/`](../android/src/main/assets/model_licenses/) |
+| **iOS** | [`ios/Resources/model_licenses/`](../ios/Resources/model_licenses/) |
+
+Files:
+
+- `asr-models-license-status.csv` — ASR / STT release models  
+- `tts-models-license-status.csv` — TTS release models  
+
+Columns: `asset_name`, `license_type`, `commercial_use`, `confidence`, `detection_source`, `license_file`.
+
+Set `detection_source` to `manual` for rows you maintain by hand; `scripts/ci/update_model_license_csv.sh` **never** re-scans or overwrites those assets (clear `manual` if you want automation to run again).
+
+CI updates these CSVs via `scripts/ci/update_model_license_csv.sh`, which writes the primary file passed with `--csv` and **syncs the same content** to both Android and iOS paths above.
+
+**Not legal advice** — consumers should verify licenses for their use case.
+
+## License Types & Commercial Use
+
+The following table explains the `license_type` and `commercial_use` values used in the CSV metadata.
+
+| License Type | Commercial Use | Notes | Reference |
+| :--- | :--- | :--- | :--- |
+| **agpl-3.0** | `conditional` | Strong copyleft; requires source code disclosure if the model is used over a network. | [GNU AGPL v3](https://opensource.org/license/agpl-v3/) |
+| **apache-2.0** | `yes` | Permissive license; allows commercial use, modification, and redistribution. | [Apache 2.0](https://opensource.org/license/apache-2-0/) |
+| **bsd-3-clause** | `yes` | Permissive license; similar to MIT but includes a non-endorsement clause. | [BSD 3-Clause](https://opensource.org/license/bsd-3-clause/) |
+| **cc-by** | `yes` | Attribution required; allows commercial use. | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
+| **cc-by-3.0** | `yes` | Attribution required; allows commercial use. | [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) |
+| **cc-by-4.0** | `yes` | Attribution required; allows commercial use. | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
+| **cc-by-nc-4.0** | `no` | **Non-Commercial** use only. | [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) |
+| **cc-by-nc-nd-4.0** | `no` | **Non-Commercial** and no derivatives/modifications allowed. | [CC BY-NC-ND 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/) |
+| **cc-by-nc-sa-4.0** | `no` | **Non-Commercial** and Share-Alike (derivatives must be under the same license). | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) |
+| **cc-by-sa** | `conditional` | Share-Alike; commercial use allowed, but any derivative must be under the same license. | [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) |
+| **cc-by-sa-3.0-es** | `conditional` | Share-Alike (Spain jurisdiction). | [CC BY-SA 3.0 ES](https://creativecommons.org/licenses/by-sa/3.0/es/) |
+| **cc-by-sa-4.0** | `conditional` | Share-Alike; commercial use allowed, but any derivative must be under the same license. | [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) |
+| **cc0** | `yes` | Public domain; no restrictions on use. | [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) |
+| **gpl-2.0** | `conditional` | Copyleft; requires sharing the source code of any derivative works. | [GNU GPL v2](https://opensource.org/license/gpl-2-0/) |
+| **mit** | `yes` | Highly permissive; allows commercial use with simple attribution. | [MIT](https://opensource.org/license/mit/) |
+| **ngc-terms-of-use** | `restricted` | NVIDIA NGC Terms; often restricts redistribution or specific commercial weight use. | [Terms](https://ngc.nvidia.com/legal/terms) |
+| **no-license** | `no` | No explicit permission granted; all rights reserved by the author. | N/A |
+| **nvidia-open-model-license** | `yes` | Allows commercial use under specific conditions (e.g. no benchmarking). | [License](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/) |
+| **proprietary-restricted** | `no` | Closed or custom license with significant restrictions. | N/A |
+| **public-domain** | `yes` | Free for any use; no copyright protection. | N/A |
+| **research-only** | `no` | Limited strictly to non-commercial research and evaluation. | N/A |
+| **unlicense** | `yes` | Public domain equivalent; no restrictions. | [Unlicense](https://unlicense.org/) |
+
+### Commercial Use Status Definitions:
+- **`yes`**: Allowed for commercial purposes with minimal restrictions (permissive).
+- **`no`**: Explicitly forbidden for commercial purposes.
+- **`conditional`**: Allowed, but requires adherence to specific distribution/license conditions (e.g. copyleft).
+- **`restricted`**: Limited use or redistribution permitted; requires careful legal review.