iOS Setup

​

Overview

​

Requirements

• iOS 13.0+
• Xcode 14+
• CocoaPods or equivalent dependency manager
• Bundler (recommended for consistent Ruby/Pod versions)

​

Installation

​

1. Install the npm package

npm install react-native-sherpa-onnx

​

2. Install CocoaPods dependencies

cd ios
bundle install           # Install Ruby dependencies (recommended)
bundle exec pod install  # Install iOS dependencies

cd ios
pod install

​

What happens during pod install

1. Downloads the sherpa-onnx XCFramework (~80MB) from GitHub Releases
2. Downloads libarchive sources for archive extraction support
3. Configures build settings for device and simulator architectures
4. Sets up header search paths for sherpa-onnx C++ API

​

Architecture and Framework Structure

​

XCFramework Layout

ios/Frameworks/sherpa_onnx.xcframework/
├── ios-arm64/                          # Device (iPhone/iPad)
│   ├── libsherpa-onnx.a                # Static library
│   └── Headers/
│       └── sherpa-onnx/c-api/
│           ├── c-api.h
│           └── cxx-api.h               # C++ API
└── ios-arm64_x86_64-simulator/         # Simulator (M1 + Intel)
    ├── libsherpa-onnx.a
    └── Headers/
        └── sherpa-onnx/c-api/
            ├── c-api.h
            └── cxx-api.h

​

Supported Architectures

• Device: arm64 (iPhone 5S and later, all iPads with A7+)
• Simulator: arm64 (Apple Silicon Macs) and x86_64 (Intel Macs)

​

Frameworks and Libraries

• Foundation - Core system services
• Accelerate - Optimized math and DSP operations
• CoreML - Apple Neural Engine and on-device ML

• libc++ - C++ standard library
• libz - Compression (used by libarchive)

​

libarchive Integration

1. Download: ios/scripts/setup-ios-libarchive.sh downloads libarchive sources from GitHub Releases
2. Patch: ios/scripts/patch-libarchive-includes.sh adds required headers (stdio.h, unistd.h) to .c files
3. Compile: CocoaPods compiles the patched sources as part of the Pod build

​

Execution Provider: Core ML

​

Checking Core ML Support

import { getCoreMlSupport } from 'react-native-sherpa-onnx';
import { initializeTTS } from 'react-native-sherpa-onnx/tts';

const coreml = await getCoreMlSupport();
console.log('Core ML compiled:', coreml.providerCompiled);  // Always true on iOS
console.log('Has Neural Engine:', coreml.hasAccelerator);   // true on A12+ devices (iOS 15+)

if (coreml.hasAccelerator) {
  await initializeTTS({
    modelPath: { type: 'asset', path: 'models/vits-piper' },
    modelType: 'auto',
    provider: 'coreml',
  });
}

• providerCompiled: Always true (Core ML is available on iOS 11+)
• hasAccelerator: true if the device has an Apple Neural Engine (A12 Bionic and later, requires iOS 15+)
• canInit: Not currently implemented (returns false)

​

Apple Neural Engine (ANE) Availability

• iPhone: XS/XS Max/XR and later (A12 Bionic+)
• iPad: iPad Air (3rd gen) and later, iPad mini (5th gen) and later, iPad Pro 2018 and later
• Mac: All Apple Silicon Macs (M1/M2/M3 series)

​

Build Configuration

​

Header Search Paths

• ios/ - iOS Objective-C++/Swift source
• ios/archive/ - Archive helper headers
• ios/model_detect/ - Model detection headers
• ios/stt/, ios/tts/, ios/online_stt/ - Feature-specific headers
• XCFramework Headers (device + simulator slices)
• libarchive headers (downloaded sources)

​

Library Search Paths

• Device builds (iphoneos*): Links to ios-arm64/libsherpa-onnx.a
• Simulator builds (iphonesimulator*): Links to ios-arm64_x86_64-simulator/libsherpa-onnx.a

​

Compiler Settings

• C++ Standard: C++17 (CLANG_CXX_LANGUAGE_STANDARD)
• C++ Library: libc++ (CLANG_CXX_LIBRARY)
• Force Load: -lsherpa-onnx (ensures all symbols are included)

​

Preprocessor Definitions

PLATFORM_CONFIG_H="libarchive_darwin_config.h"

​

Advanced: Building the Framework Yourself

​

Using the CI Workflow

1. Builds sherpa-onnx for iOS (device + simulator)
2. Merges the C++ API static library (libsherpa-onnx-cxx-api.a)
3. Creates an XCFramework with headers
4. Publishes to GitHub Releases

​

Manual Build Steps

1. Build sherpa-onnx for iOS:
   • Use upstream build-ios.sh from k2-fsa/sherpa-onnx
   • Or adapt the CI workflow’s build script
2. Merge C++ API:
   • The XCFramework must include the C++ API (libsherpa-onnx-cxx-api.a)
   • The iOS Objective-C++ code uses sherpa_onnx::cxx::* namespaces
3. Place the XCFramework:
   # Copy your built framework to:
   ios/Frameworks/sherpa_onnx.xcframework/
   
4. Run pod install:
   cd ios
   pod install
   

​

Version Pinning

third_party/sherpa-onnx-prebuilt/IOS_RELEASE_TAG

​

Troubleshooting

​

Framework download failed

1. Check network connectivity:
   • The script downloads from GitHub Releases
   • Corporate firewalls may block api.github.com
2. Use a GitHub token (for rate limits):
   export GITHUB_TOKEN=your_token_here
   pod install
   
3. Force re-download:
   rm -rf ios/Frameworks/sherpa_onnx.xcframework
   pod install
   

​

Framework headers not found

1. Verify XCFramework structure:
   ls ios/Frameworks/sherpa_onnx.xcframework/ios-arm64_x86_64-simulator/Headers/sherpa-onnx/c-api/
   
   Should contain c-api.h and cxx-api.h
2. Clean and rebuild:
   cd ios
   rm -rf Pods/ Podfile.lock
   pod install
   

​

libarchive compilation failed

1. Run the download script manually:
   bash ios/scripts/setup-ios-libarchive.sh
   
2. Check the downloaded sources:
   ls ios/Downloads/libarchive/
   
   Should contain archive.h, archive_xxhash.h, and *.c files
3. Check for patching errors:
   bash ios/scripts/patch-libarchive-includes.sh ios/Downloads/libarchive
   ls ios/patched_libarchive/
   

​

Simulator vs. Device architecture mismatch

1. Clean build folder:
   • In Xcode: Product → Clean Build Folder (⇧⌘K)
2. Verify XCFramework has both slices:
   ls ios/Frameworks/sherpa_onnx.xcframework/
   
   Should show:
   • ios-arm64/ (device)
   • ios-arm64_x86_64-simulator/ (simulator)

​

Related Documentation

• Execution Providers - Detailed Core ML documentation
• Model Setup - Asset bundling for iOS
• Building sherpa-onnx - Upstream build instructions