Troubleshooting

Troubleshooting

ModelLoadException: Model not found

The path you passed doesn't exist. Check:

• You actually pushed/downloaded the model to that exact path.
• For getExternalFilesDir("models"), the full path is /sdcard/Android/data/<your.app.id>/files/models/.
• Use File(path).exists() to confirm before calling loadModel.

ModelLoadException: Failed to initialise model

The file exists but whisper.cpp rejected it. Usually:

• The download is corrupted or incomplete — re-download and compare sizes.
• It's not a ggml model (e.g. you downloaded an HTML error page). Ggml files start with the magic bytes ggml.
• Wrong file for the API version — use models from ggml-org/whisper.cpp.

InvalidAudioException / could not read audio

The audio isn't the required format. whisper-android expects 16 kHz, mono, 16-bit PCM WAV. Convert it:

ffmpeg -i input.<ext> -ar 16000 -ac 1 -c:a pcm_s16le output.wav

UnsatisfiedLinkError: libwhisper.so

The native library couldn't load. Causes:

• Unsupported ABI — the Free tier is arm64-v8a only. It will not run on an x86_64 emulator. Use an arm64 device/emulator, or the Pro build.
• Check Whisper.getSystemInfo() early — if the class initialises, the .so loaded.

Empty transcription

• The audio may be silent, too quiet, or the wrong channel. Verify the WAV plays.
• Wrong language — set WhisperConfig(language = "auto") to let Whisper detect it.

Out of memory / app crash on large models

small and larger need substantial RAM. Drop to base or tiny, or test on a device with more memory.

Microphone permission

File-based transcription needs no permissions. If you record audio yourself, request RECORD_AUDIO — that's your app's responsibility, not the library's.

---

Still stuck? Open an issue on the repo or contact contact@jokobee.com.