Troubleshooting

What to do when a recording produces surprising numbers, a stuck analysis, or an unavailable tile.

The pitch value looks extreme

Far too low (below ~50 Hz): the pitch tracker is probably picking up creak or noise. Check the pitch floor setting (a command-line option in the installed app; see Configuration) — the default 75 Hz is usually fine; drop to 60 Hz if you know you have regular creak frames you want to keep, or raise it to 90 Hz to reject creak outright.
Far too high (above ~600 Hz): likely an octave-jump error, where the tracker locks onto the first harmonic instead of the fundamental. Check whether the recording includes falsetto or very high-pitched content; if so, raise the pitch ceiling. If not, re-record — octave errors usually mean the signal has strong harmonic energy without a clear fundamental.

See Pitch for how the two-pass adaptive extraction actually works.

The dashboard hides the value and shows a reason. Common causes:

sample_rate_below_16khz — record at 16 kHz or higher. See Recording tips.
insufficient_usable_formants — the recording is too short or too unvoiced to aggregate stable formants. Record 3–30 seconds of connected speech.
voice_quality_extraction_failed — an internal error in the voice-quality pipeline. Rare; see the job-status error text on the dashboard.
sibilant_analysis_disabled — turned off in settings.
model_not_installed — the browser version does not include speaker similarity yet.
onnxruntime_not_available (installed app) — install the neural extra: uv sync --extra neural.
model_not_downloaded (installed app) — the WeSpeaker model file has not been fetched. See docs/neural/wespeaker.md in the repository.

The full reason-code enumeration lives in Methodology.

The value still renders, with a reason. Treat it as informational — the metric is usable but less reliable than usual. Common reasons:

high_f0_suppression — F0 above 175 Hz; voice-quality metrics fall back from the raw rung to the corrected rungs.
low_snr — SNR below 30 dB; HNR and voice-quality metrics are the most affected. See the SNR warning tile for a full explanation.
correction_failed — voice-quality correction could not complete; ladder fell back a rung.
perturbation_unavailable — local jitter/shimmer could not be computed for this recording; other voice-quality fields may still render normally.

Status has not changed for a while. The dashboard shows the current stage. In the browser version, the first analysis waits for the analysis software to download, and the analysis stops if you close the tab (the recording is kept; use Retry). In the installed app, Whisper transcription is the slowest step on CPU — a multi-minute recording can take 5–10 minutes with the medium Whisper model.
Status is stuck for more than 30 minutes (installed app). The server marks stuck jobs as error at 30 minutes with a message suggesting a shorter recording or a smaller Whisper model. If you hit this, pick tiny or base and retry.
Status shows "error" immediately. The recording failed to load. Most likely the file is corrupt, unsupported, or zero-length.

The browser asks for permission every time. Allow microphone access for the exact address you are using. In the installed app, if you switch between localhost and 127.0.0.1, the browser treats them as different sites.
Permission was denied. Re-enable microphone access in browser site settings, then reload the page and press Start on Practice again.
No microphone was found. Check the operating-system input device, then restart the browser if a newly attached USB interface does not appear.
AudioWorklet or WebSocket is unsupported. Use a current desktop browser. Live recording depends on AudioWorklet, and the installed app also on WebSocket; uploading still works without them.
The realtime connection closes during Stop (installed app). The take may still have been saved. Check Home before recording the same take again.

See Live microphone preview for the full lifecycle, storage, and live-vs-final explanation.

The app drops stale live packets rather than letting memory grow without bound. If the Status tile reports dropped packets or the display lags:

close other CPU-heavy apps;
keep takes short while testing microphone placement;
in the installed app, prefer running the browser and server on the same machine;
use upload mode for canonical analysis when the live preview is under load.

Dropped live packets are a preview-quality warning. A stopped final report is produced from the recorded WAV through the normal batch pipeline.

Most variability across short, back-to-back takes is real — voice is variable. But systematic, large jumps usually point to one of:

Different recording conditions — mic, distance, room, input gain. See Recording tips.
Different formant mode between sessions — whole vs per-vowel aggregation are not the same value. See Methodology.
A warning fired on one session and not the other — check the warning tile row.

Spectrum bars empty: the analysis did not produce valid pitch or dispersion values. Check for "unavailable" confidence and the reason codes listed above.
Vowel space / per-vowel cards hidden: vowel detection did not find vowels of enough distinct classes, often because the recording is short, quiet or has little varied speech. These cards hide silently when empty rather than showing a placeholder.
History sidebar empty: in the browser version, check that you opened the same web address as before (storage belongs to one address), that you are not in a private window, and that the site's data was not cleared; the app shows an error when the browser does not allow it to store data. In the installed app, the local storage layer may not be writable; check disk permissions on the platform-data directory. See Storage and privacy.

When something looks wrong and you want to report it:

That set of information is usually enough to reproduce or disambiguate a dashboard surprise.