Install the Package
Install whisper.rn using your preferred package manager:
Current version: 0.6.0-rc.0Requirements:
- React Native 0.60+
- Node.js 18+
- iOS 11.0+ / tvOS 11.0+
- Android API 21+ (Android 5.0)
Install CocoaPods dependencies
By default, whisper.rn uses a pre-built rnwhisper.xcframework for faster builds. (Optional) Build from source
If you need to customize the native build, add this to your Podfile:# Force build whisper.rn from source
ENV['RNWHISPER_BUILD_FROM_SOURCE'] = '1'
(Optional) Add microphone permissions
If you plan to use realtime transcription, add microphone permission to ios/YourApp/Info.plist:<key>NSMicrophoneUsageDescription</key>
<string>This app requires microphone access to transcribe speech</string>
tvOS does not support microphone access.
(Optional) Enable Extended Virtual Addressing
For medium or large models, enable Extended Virtual Addressing in Xcode:
- Select your app target in Xcode
- Go to Signing & Capabilities
- Click + Capability
- Add Extended Virtual Addressing
This allows your app to use more memory for large models. iOS Build Options
You can customize the iOS build with environment variables in your Podfile:# Disable Core ML support
ENV['RNWHISPER_DISABLE_COREML'] = '1'
# Disable Metal GPU acceleration
ENV['RNWHISPER_DISABLE_METAL'] = '1'
Update NDK version (recommended)
For Apple Silicon Macs, use NDK version 24.0.8215888 or higher.Add to android/build.gradle:buildscript {
ext {
// ... other configs
ndkVersion = "24.0.8215888"
}
}
Add ProGuard rules
If ProGuard is enabled, add this to android/app/proguard-rules.pro:# whisper.rn
-keep class com.rnwhisper.** { *; }
(Optional) Add microphone permissions
If you plan to use realtime transcription, add to android/app/src/main/AndroidManifest.xml:<uses-permission android:name="android.permission.RECORD_AUDIO" />
import { PermissionsAndroid, Platform } from 'react-native';
if (Platform.OS === 'android') {
await PermissionsAndroid.request(
PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
{
title: 'Microphone Permission',
message: 'This app needs microphone access for transcription',
buttonNeutral: 'Ask Me Later',
buttonNegative: 'Cancel',
buttonPositive: 'OK',
}
);
}
Expo Go is not supported. You must use a development build or prebuild.
Install the package
npx expo install whisper.rn
Prebuild the native project
This generates the iOS and Android native projects. Add permissions to app.json (optional)
For microphone access:{
"expo": {
"plugins": [
[
"expo-build-properties",
{
"ios": {
"infoPlist": {
"NSMicrophoneUsageDescription": "This app needs microphone access to transcribe speech"
}
},
"android": {
"permissions": ["android.permission.RECORD_AUDIO"]
}
}
]
]
}
}
Run development build
npx expo run:ios
# or
npx expo run:android
Download a Whisper Model
whisper.rn requires a GGML-format Whisper model file. Models are available from the whisper.cpp repository.
Choose a model size
| Model | Size | Speed | Accuracy | Use Case |
|---|
tiny.en | 75 MB | Fastest | Good | Quick transcription, English only |
base.en | 148 MB | Fast | Better | General use, English only |
small.en | 488 MB | Medium | Great | High accuracy, English only |
medium.en | 1.5 GB | Slow | Excellent | Best quality, English only |
tiny | 75 MB | Fastest | Good | Multilingual, 99 languages |
base | 142 MB | Fast | Better | Multilingual |
small | 466 MB | Medium | Great | Multilingual |
For most mobile apps, tiny.en or base.en offers the best balance of speed and accuracy.
Download the model
Download from Hugging Face:curl -L https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin -o ggml-tiny.en.bin
Place model in your app
You have two options:Option 1: Bundle with app (development)Place the .bin file in your project (e.g., assets/ggml-tiny.en.bin) and use require():const modelPath = require('./assets/ggml-tiny.en.bin');
This increases app size significantly. Models are typically 75MB to 2.9GB.
import RNFS from 'react-native-fs';
const modelUrl = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin';
const modelPath = `${RNFS.DocumentDirectoryPath}/ggml-tiny.en.bin`;
// Check if already downloaded
const exists = await RNFS.exists(modelPath);
if (!exists) {
await RNFS.downloadFile({
fromUrl: modelUrl,
toFile: modelPath,
}).promise;
}
Using Bundled Assets (Optional)
To bundle models as assets, update metro.config.js:
const { getDefaultConfig } = require('metro-config');
const defaultAssetExts = require('metro-config/src/defaults/defaults').assetExts;
module.exports = {
resolver: {
assetExts: [
...defaultAssetExts,
'bin', // whisper.rn: GGML model files
'mil', // whisper.rn: Core ML model files
],
},
};
The React Native packager has a 2GB file size limit, so original f16 large models (2.9GB) cannot be bundled. Use quantized versions instead.
Verify Installation
Test your installation:
import { libVersion } from 'whisper.rn';
console.log('whisper.cpp version:', libVersion);
Installation complete! Continue to Quick Start to transcribe your first audio. Next Steps
Quick Start Guide
Transcribe your first audio file
Core ML Setup
Enable iOS encoder acceleration