Skip to main content
Get up and running with whisper.rn by transcribing your first audio file in just a few steps.

Prerequisites

Completed the Installation guide

Your First Transcription

1

Import whisper.rn

Import the initWhisper function in your React Native component:
import { initWhisper } from 'whisper.rn'
2

Initialize the Whisper Context

Initialize a Whisper context with a model file:
const whisperContext = await initWhisper({
  filePath: '/path/to/ggml-tiny.en.bin',
})
Download the ggml-tiny.en.bin model from Hugging Face. The tiny model is ~75MB and perfect for getting started.
3

Transcribe an Audio File

Call the transcribe() method with your audio file:
const { promise } = whisperContext.transcribe(
  '/path/to/audio.wav',
  { language: 'en' }
)

const { result } = await promise
console.log('Transcription:', result)
Audio files must be in WAV format, 16kHz sample rate, mono channel. See Audio Formats for details.
4

Clean Up

Always release the context when you’re done:
await whisperContext.release()

Complete Example

Here’s a full React Native component that transcribes an audio file:
import React, { useState, useEffect } from 'react'
import { View, Text, Button, ActivityIndicator } from 'react-native'
import { initWhisper } from 'whisper.rn'

export default function TranscribeScreen() {
  const [transcription, setTranscription] = useState('')
  const [loading, setLoading] = useState(false)

  const transcribeAudio = async () => {
    setLoading(true)
    
    try {
      // Initialize context
      const whisperContext = await initWhisper({
        filePath: require('./assets/ggml-tiny.en.bin'),
      })

      // Transcribe audio file
      const { promise } = whisperContext.transcribe(
        require('./assets/sample.wav'),
        { 
          language: 'en',
          maxThreads: 4,
        }
      )

      const { result } = await promise
      setTranscription(result)

      // Clean up
      await whisperContext.release()
    } catch (error) {
      console.error('Transcription failed:', error)
      setTranscription('Error: ' + error.message)
    } finally {
      setLoading(false)
    }
  }

  return (
    <View style={{ padding: 20 }}>
      <Button
        title="Transcribe Audio"
        onPress={transcribeAudio}
        disabled={loading}
      />
      
      {loading && <ActivityIndicator style={{ marginTop: 20 }} />}
      
      {transcription && (
        <Text style={{ marginTop: 20 }}>{transcription}</Text>
      )}
    </View>
  )
}
If you want to bundle the model and audio files with your app:
  1. Add .bin to Metro config (see Installation)
  2. Use require() instead of file paths:
const whisperContext = await initWhisper({
  filePath: require('./assets/ggml-tiny.en.bin'),
})

const { promise } = whisperContext.transcribe(
  require('./assets/sample.wav'),
  { language: 'en' }
)
Bundling models will increase your app size significantly. The tiny model is ~75MB.

Common Options

language
string
default:"auto"
Language code (e.g., ‘en’, ‘es’, ‘fr’) or ‘auto’ for automatic detection
translate
boolean
default:"false"
Translate speech to English
maxThreads
number
default:"2-4"
Number of CPU threads to use (2 for 4-core devices, 4 for more)
beamSize
number
default:"5"
Beam search size for better accuracy (higher = more accurate but slower)
onProgress
function
Callback function for transcription progress (0-100)
See TranscribeOptions for all available options.

Next Steps

Core Concepts

Learn about contexts and audio formats

Features

Explore transcription, VAD, and realtime features

Examples

See more code examples and patterns

API Reference

View complete API documentation

Troubleshooting

Error: Error: Model file not foundSolution: Verify the model file path is correct. If using require(), ensure the file exists in your project and Metro config includes .bin extensions.
Error: Error: Invalid audio formatSolution: Ensure your audio file is:
  • WAV format
  • 16kHz sample rate
  • Mono channel (1 channel)
  • 16-bit PCM encoding
Use ffmpeg to convert: ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav
Problem: Transcription takes too longSolution (iOS): Enable Core ML acceleration (see Core ML Setup)Solution (General):
  • Use a smaller or quantized model (e.g., tiny or base-q8_0)
  • Increase maxThreads (try 4)
  • Test in Release mode, not Debug mode
Error: App crashes with large modelsSolution: Enable Extended Virtual Addressing capability in Xcode:
  1. Open your iOS project in Xcode
  2. Select your app target
  3. Go to Signing & Capabilities
  4. Add “Extended Virtual Addressing” capability

Build docs developers (and LLMs) love