Highlights #

• 🎙 Live transcription — partial transcripts stream in while recording, refined as more audio arrives. The model loads once per session and an adaptive energy gate keeps silence from producing hallucinated text.
• 📄 File transcription — one call to transcribe a recording.
• 📦 Offline-first — models download once and are cached, or ship them in your app's assets for fully offline use (see the example app).
• 🌍 99 languages — pick one ('en', 'fr', 'de', …) or use 'auto' to detect.
• 🎛 Decoding controls — vocabulary biasing, context conditioning, and non-speech token suppression exposed from whisper.cpp.
• ⚡ Fast — whisper.cpp v1.9.1 with Accelerate on Apple platforms; an 11-second clip transcribes in ~0.4 s with the base model on an Apple Silicon Mac.

Supported platforms #

Installation #

dependencies:
  whisper_ggml: ^2.6.0

Requires Dart 3.7+ (Flutter 3.29+).

Quick start #

import 'package:whisper_ggml/whisper_ggml.dart';

final controller = WhisperController();

final result = await controller.transcribe(
  model: WhisperModel.tiny,
  audioPath: '/path/to/audio.wav',
  lang: 'en',
);

print(result?.transcription.text);

Pass onProgress: (percent) => ... to receive transcription progress as a 0–100 percentage (coarse steps) while inference runs.

Pass withSegments: true to also get per-segment timestamps in result.transcription.segments (each segment has fromTs/toTs Durations and its text); add splitOnWord: true for one segment per word instead of per phrase.

Speaker-turn detection (diarization) #

With the tinydiarize model (WhisperModel.smallEnTdrz, English only), diarize: true marks the segments after which the speaker changes:

final result = await controller.transcribe(
  model: WhisperModel.smallEnTdrz,
  audioPath: '/path/to/audio.wav',
  lang: 'en',
  diarize: true,
  withSegments: true,
);

for (final segment in result?.transcription.segments ?? []) {
  print('${segment.text}${segment.speakerTurnNext ? ' [speaker turn]' : ''}');
}

This detects turn boundaries; it does not label or count speakers. With regular models diarize has no effect.

The model is downloaded automatically on first use. Non-WAV input is converted with the bundled FFmpeg — except on Windows and Linux, where FFmpeg is not bundled: an ffmpeg executable on PATH is used when present (on Linux, apt install ffmpeg or equivalent), otherwise the input must already be a 16 kHz mono WAV (the format the record package produces with AudioEncoder.wav, sampleRate: 16000, numChannels: 1).

Live (streaming) transcription #

transcribeLive accepts any stream of 16 kHz mono little-endian PCM16 audio and emits progressively refined transcripts while the audio flows. With the record package:

final pcmStream = await recorder.startStream(const RecordConfig(
  encoder: AudioEncoder.pcm16bits,
  sampleRate: 16000,
  numChannels: 1,
));

final session = await controller.transcribeLive(
  model: WhisperModel.base,
  pcm16Stream: pcmStream,
  lang: 'en',
);

session.partials.listen((text) {
  print(text); // full transcript so far, not a delta
});

// Later — stop recording, finalize, and free the model:
await recorder.stop();
final finalText = await session.stop();

Good to know:

• The model stays loaded for the whole session; inference runs on a background isolate and never blocks the UI.
• An adaptive energy gate keeps silence away from the decoder, which otherwise hallucinates on silent audio. For unusually loud rooms or quiet speakers, tune gateNoiseFloorCap, gateVoiceRatio, and gateRmsMin.
• Only one live session can run at a time.
• Real non-speech sounds (knocks, clicks) may transcribe as bracketed annotations like [door slams].
• Bring your own model: pass modelPath: instead of model: to run the session against any local ggml model file. For full manual control, startWhisperLiveSession(modelPath: ...) is exported too — no audio stream wiring, you call session.feed(pcm16Bytes) yourself.
• Session-per-utterance? Pass keepModelLoaded: true and the model is parked in native memory when the session stops, so the next session (or one-shot transcribe) with the same model starts without the multi-second load. See "Keeping the model loaded between transcriptions" below — the same cache, memory trade-off, and releaseModel() apply.

Models #

Smaller models are faster; larger models are more accurate. tiny and base are good defaults for live transcription; small is a strong accuracy/speed balance for file transcription on modern phones.

Decoding options #

Available on both transcribe and transcribeLive:

Keeping the model loaded between transcriptions #

By default every transcribe call loads the model from disk (seconds for the small models and up) and frees it when the request completes. For push-to-talk dictation, voice notes, and other short repeated requests against the same model, that load dominates the per-utterance latency. Pass keepModelLoaded: true to park the loaded model in native memory instead — the next transcription with the same model skips the load:

final result = await controller.transcribe(
  model: WhisperModel.base,
  audioPath: audioPath,
  keepModelLoaded: true, // model stays resident for the next request
);

// When dictation is over, free the parked model:
await controller.releaseModel();

Good to know:

• A reused model transcribes exactly like a freshly loaded one — no text or decoder state carries over between requests.

• The parked model keeps its weights in RAM (from ~100 MB for tiny up to several GB for the large models) until you release it. On phones, release it when dictation ends rather than keeping it forever.

• One model stays resident per process; parking a different model replaces and frees the previous one. A request for a different model with keepModelLoaded: false leaves the parked one alone.

• Requests stay fully concurrent: a second transcription that arrives while the parked model is in use simply loads its own copy, exactly as before.

• The native engine is compiled with -O3 on all platforms, including debug builds on iOS/macOS, Windows (/O2), and Linux — transcription speed there is close to release.

• Windows and Linux x64 builds target AVX2 by default, like upstream whisper.cpp's standard x64 binaries (supported by virtually every x64 CPU since ~2013). For very old CPUs, build with -DWHISPER_GGML_AVX2=OFF.

• Android debug builds run the Dart layer in JIT mode; use --release for representative performance.

• The bundled whisper.cpp v1.9.1 is roughly 15× faster than the engine in versions before 2.0.0.