Transcription strategy
VoiceFlow uses an accuracy-first, two-pass Whisper strategy: transcribe, score the result, and only re-run with different settings when quality looks poor.
Model
whisper-large-v3
Strategy
v2_accuracy_first
Re-run threshold
score < 0.70
The transcription request
The WAV is posted as multipart form data to Groq's OpenAI-compatible endpoint, authenticated with your API key.
file: recording.wav (audio/wav)
model: whisper-large-v3
response_format: verbose_json
temperature: 0
language: en (or omitted for auto-detect)
prompt: dictionary spellings + "transcribe exactly"verbose_json returns the text plus a detected language and per-segment data, which feeds the quality scoring below.
Two-pass accuracy strategy
A first pass (Pass A) runs at temperature 0 with the dictionary-biased prompt. Its output is scored. Only if the score falls below 0.70 does a second pass (Pass B) run with a neutral prompt and a small temperature bump, giving the model a different shot at ambiguous audio. The higher-scoring pass wins; ties break toward the longer transcript.
Quality scoring
Each candidate starts at a score of 1.0 and loses points against heuristics that catch common Whisper failure modes — runaway repetition, implausible speaking rates, and dictionary echoing. The remaining score decides whether Pass B runs and which pass is kept.
Penalties are subtracted from a starting score of 1.0, then clamped to [0, 1]. A recording that trips several checks drops below the 0.70 re-run threshold.
| Check | Triggers when | Catches |
|---|---|---|
| few-tokens | ≤1 token, >2.5s | Long audio that transcribed to almost nothing. |
| words-per-second | <0.45 or >6 | Implausibly slow or fast output relative to duration. |
| repetition-ratio | >0.6 unique loss | The same words repeated — a classic Whisper loop. |
| repeat-run | ≥4 in a row | A single token stuttered many times. |
| dictionary-ratio | ≥0.85 dict tokens | Output that is mostly dictionary terms — likely prompt echo. |
Diagnostics
The chosen pass, both scores, and their reasons are attached to the result as diagnosticsand saved with the history record. They're also logged, so you can see why a particular transcription was re-run or rejected.