Vocal Analyzer Docs

← Back to app

Methodology and caveats

This page explains how Vocal Analyzer turns audio into a result: the philosophy, the confidence model, the measurement-warning codes (with plain-language explanations), the quality thresholds, and the continuity rules that hold across analyses.

Philosophy

Vocal Analyzer is a descriptive tool. Every value, band, and warning is framed that way deliberately:

See Voice and gender perception for the research context behind this framing.

Confidence levels

Every metric carries one of four confidence labels:

The confidence system is described in detail in _build_metric_evidence in src/vocal_analyzer/engine/analyzer.py.

Measurement-warning codes

When a recording triggers one or more degraded conditions, the dashboard surfaces a warning tile. Internally each condition is a short reason code that upstream code emits; the prose strings below are the plain-language expansions users see.

Reason code Plain-language explanation
sample_rate_below_16khz The recording is below the 16 kHz threshold; voice-quality and formant pipelines are skipped.
high_f0_burg_instability F0 above 200 Hz makes LPC (Burg) formant tracking less reliable.
source_filter_coupling F0 is within 80% of F1; source (folds) and filter (tract) couple and bias both sides.
low_snr Estimated SNR is below 30 dB; HNR and voice-quality metrics are the most affected.
high_f0_suppression F0 above 175 Hz; raw H1-H2 is suppressed (see Voice quality).
insufficient_usable_formants Whole-recording formant aggregation did not have enough stable frames.
correction_failed The voice-quality correction pipeline (Iseli-Alwan family) could not complete; the ladder fell back a rung.
voice_quality_extraction_failed Voice-quality extraction itself failed; the tile is unavailable.
ltas_unavailable LTAS complements could not be computed; reported as a reason without downgrading primary voice-quality confidence.
perturbation_unavailable Local jitter/shimmer could not be computed; reported as a reason without downgrading primary voice-quality confidence.
heuristic_detector Sibilant tile is capped at moderate because the detector is a heuristic, not phone-level segmentation.
word_gated Transcript word timing and the spectral sibilant detector agreed, so sibilant confidence can rise above the heuristic cap.
phone_gated Aligned /s/ or /z/ phone timing and the spectral sibilant detector agreed, so sibilant confidence can rise above the heuristic cap.
sibilant_analysis_disabled Sibilant analysis was turned off in settings.
no_sibilant_detected The detector ran but did not find enough sibilant-like segments.
transcript_unavailable Word-gated sibilant analysis was selected, but neither transcript words nor aligned phone intervals were available.
no_sibilant_words_in_transcript Transcript words were available, but none matched the narrow /s/ or /z/ word filter.
no_sibilant_frames_in_words Candidate transcript words were present, but the spectral detector rejected every frame inside them.
no_sibilant_phones_in_alignment Phone alignment was present, but it did not include aligned /s/ or /z/ intervals.
no_sibilant_frames_in_phones Aligned /s/ or /z/ phones were present, but the spectral detector rejected every frame inside them.
descriptive_cue Speaker similarity is capped at moderate because it is a progress-tracking cue, not verification.
speaker_similarity_disabled No reference selected.
no_reference No enrolled reference is available for the selected name.
onnxruntime_not_available Neural extra (uv sync --extra neural) is not installed.
model_not_downloaded The speaker-embedding model file is not present locally.
model_not_installed The browser version does not include speaker similarity yet; the speaker model is not shipped with it.
model_integrity_mismatch The speaker-embedding model file did not match the expected checksum.
audio_too_short Recording is shorter than the minimum duration the similarity pipeline can use.
embedding_model_mismatch The enrolled reference used a different embedding model than the current build.
insufficient_data Coherence could not be computed because an upstream metric was unavailable.

The prose voice-quality / formant warnings that appear as warning tiles come from _build_measurement_warnings in the same file; they reference the same underlying conditions but phrase them for humans.

Quality thresholds

A handful of named thresholds drive the confidence machinery:

All of these are Python constants. Values shown here are the values in src/vocal_analyzer/engine/analyzer.py and src/vocal_analyzer/engine/voice_quality.py at the time this page was built; if the code changes, make docs updates this page and the build test pins the values against the code.

Benchmark continuity

The regression and benchmark suites anchor their continuity on the whole-recording formant mode. Per-vowel aggregation is additive — useful as an additional lens but never the baseline for cross-session comparison. This matters in practice:

Limitations

References