Skip to main content

​
Overview

If your app uses another native library that ships its own libarchive, or you don’t need .tar.bz2 archive extraction for model bundles, you can disable libarchive in react-native-sherpa-onnx. When disabled, no libarchive.so is linked or shipped, and archive-dependent APIs return an error at runtime.

​
When to disable libarchive

  • Your app uses another library that includes libarchive
  • You only use single-file ONNX models (not .tar.bz2 archives)
  • You want to reduce APK size
  • You extract model archives through other means

​
What you’ll lose

When libarchive is disabled:
  • extractTarBz2() will reject with an error instead of extracting archives
  • cancelExtractTarBz2() becomes a no-op
  • The Download Manager can only download single-file models (.onnx), not archive models (.tar.bz2)
The computeFileSha256() function does NOT depend on libarchive and continues to work normally.

​
Configuration

1

Set the Gradle flag

Add the following property to your gradle.properties file (at the project or root level):
sherpaOnnxDisableLibarchive=true
Alternatively, pass it as a command-line project property:
./gradlew assembleRelease -PsherpaOnnxDisableLibarchive=true
2

Build your app

When this flag is set, the Android native build will:
  • Not link or ship libarchive (libarchive.so)
  • Not require libarchive prebuilts or headers during the build process
  • Complete successfully without libarchive dependencies
3

Adjust model handling

If you previously used archive models (.tar.bz2):
  • Switch to single-file .onnx models
  • Or extract archives manually before loading them
  • Or use bundled/PAD models that are already extracted
import { extractTarBz2 } from 'react-native-sherpa-onnx';

try {
  await extractTarBz2(archivePath, targetPath);
} catch (error) {
  console.error('libarchive not available:', error);
  // Use alternative: single-file models or pre-extracted archives
}

​
Impact on Download Manager

The Model Download Manager (react-native-sherpa-onnx/download) is significantly affected when libarchive is disabled:
APIEffect when libarchive is disabled
downloadModelByCategory()Archive models (.tar.bz2): Download completes but extraction fails - the promise rejects and the model is unusable. Single-file models (.onnx): Work normally.
getLocalModelPathByCategory()Returns null for archive models that were never successfully extracted. Single-file models are unaffected.
listDownloadedModelsByCategory()Only lists models with complete manifests. Archive models with failed extraction won’t appear.
isModelDownloadedByCategory()Returns false for archive models since extraction failed.
subscribeDownloadProgress()Download progress works, but the operation fails immediately after download when extraction is attempted.
Other APIsrefreshModelsByCategory, listModelsByCategory, getModelByIdByCategory, deleteModelByCategory, clearModelCacheByCategory do not depend on extraction and work normally.
With libarchive disabled, archive models (.tar.bz2) cannot be downloaded or used via the Download Manager. Only single-file models (.onnx) are supported.

​
Comparison

​
Before (Default)

  • libarchive is linked and shipped with your app
  • Can extract .tar.bz2 model archives
  • Download Manager supports both archive and single-file models
  • APK size includes libarchive (~100-200 KB per architecture)
  • Risk of conflicts if another library also includes libarchive

​
After (libarchive Disabled)

  • No libarchive in your APK
  • Smaller app bundle size
  • Archive extraction returns errors
  • Download Manager only supports single-file models
  • No risk of libarchive symbol conflicts
  • Compatible with other libraries that include libarchive

​
Affected APIs

​
Runtime errors

These APIs are built but return errors when libarchive is disabled:
APIDescription
extractTarBz2(sourcePath, targetPath, force, promise)Rejects with an error message (e.g., “libarchive not available”). Does not crash.
cancelExtractTarBz2()Becomes a no-op since there’s no extraction to cancel.

​
Still working

These APIs continue to work normally:
APIDescription
computeFileSha256(filePath, promise)Implemented using only standard I/O and bundled crypto code. Does not use libarchive.
All other features (STT, TTS, FFmpeg audio conversion, model detection) are unaffected by the libarchive flag.

​
Trade-offs and Limitations

​
1. No built-in archive extraction

You must handle .tar.bz2 extraction yourself if needed:
  • Use another JavaScript or native library for tar.bz2 extraction
  • Or ship models in extracted form (bundled assets or PAD)
  • Or only use single-file .onnx models

​
2. No runtime use of another libarchive

Disabling libarchive means this SDK’s native code is compiled without libarchive. The extraction helper is stubbed and always returns an error. The SDK does not call into another app’s libarchive library. This prevents shipping a duplicate libarchive.so but does not provide “shared” libarchive behavior.

​
3. Safe coexistence with other libarchive libraries

Because this SDK no longer links or uses libarchive when disabled, there is no risk of ABI or version mismatch with another libarchive in your app’s process.

​
Troubleshooting symbol conflicts

​
When crashes can still occur

If libarchive is NOT disabled and your app loads a different libarchive from another dependency:
  • Two libarchive implementations can exist in the same process
  • Depending on load order and symbol resolution, you can get conflicts or undefined behavior
  • Symptoms include crashes during archive operations or symbol resolution errors
Mitigation: Set sherpaOnnxDisableLibarchive=true so only one libarchive (or none from this SDK) is present. If libarchive is disabled and you call extraction APIs:
  • The promise is rejected with an error (e.g., “libarchive not available”)
  • It does not crash the process
  • Your app should handle the rejection gracefully

​
Summary

ConfigurationEffect
sherpaOnnxDisableLibarchive=trueNo libarchive linked or shipped; build succeeds without libarchive; extractTarBz2 rejects with error; cancelExtractTarBz2 is a no-op; computeFileSha256 still works. Download Manager: only single-file models work; archive models fail at extraction. Use when you have another libarchive in your app or don’t need archive extraction.
Default (unset or false)libarchive is required; extraction APIs work; Download Manager supports both archive and single-file models. Do not combine with another libarchive unless you accept the risk of conflicts.
This configuration only affects Android builds. iOS builds have different archive handling and are unaffected by this flag.

Build docs developers (and LLMs) love

Get started for freeTalk to us