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 ggerganov/whisper.cpp on Hugging Face.

could not decode audio (supported: WAV/MP3/FLAC)

The file couldn't be decoded. The library accepts WAV, MP3 and FLAC (any sample rate — it resamples to 16 kHz mono internally). Check that:

• The file path exists and points to a real audio file.
• The container is one of WAV/MP3/FLAC (not AAC/M4A/OGG — convert those first).
• The file isn't truncated or corrupted.

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.