Configuration

Vocal Analyzer separates saved app preferences from advanced, one-off analysis overrides:

• The web app's Settings page holds the choices that persist across Home, Studio, and Practice: goal profile and target bands, gender coding, resonance unit, timeline zoom, and (in the installed app) Whisper model/backend.
• The Studio upload flow uses tuned analysis defaults. It does not expose the old analysis-settings sidebar.
• In the installed app, use the command-line tool vocal-analyzer analyze when a particular recording needs an advanced per-run override such as pitch bounds, formant mode, sibilant method, or a speaker reference. Run vocal-analyzer analyze --help for the current list.

The browser version has no command-line tool, so the per-run overrides on this page are not available there; it always uses the tuned defaults. Most recordings need neither a Settings change nor a CLI override.

Pitch floor and ceiling

The CLI's --pitch-floor and --pitch-ceiling options bound F0 extraction for one analysis. Defaults:

• Pitch floor: 75 Hz
• Pitch ceiling: 600 Hz

Override them when:

• You have a very low-pitched voice and the default floor is cutting off creak frames you want to keep. Drop to 60 Hz.
• You have a very high-pitched voice and the default ceiling is clipping peaks. Raise to 800 Hz or 1000 Hz.
• You are analysing a non-speech recording (sung falsetto, sine tones) and the speech-range defaults are wrong.

The analyzer uses a two-pass adaptive algorithm (De Looze & Hirst 2008) internally, so the initial floor/ceiling mostly sets the outer envelope for that adaptation. See Pitch.

Formant mode

Choose this per run with --formant-mode whole, per_vowel, or both:

• Whole recording — one set of F1/F2/F3 medians across every voiced frame. The benchmark-continuity baseline; see Methodology.
• Per vowel — per-class aggregates when enough vowel timing is available from heuristic detection or aligned vowel intervals.
• Both (default) — compute both, render both. Recommended.

Sibilant analysis

Choose this per run with --sibilant-method:

• Energy heuristic (default) — run the sibilant detector.
• Word-gated — restrict the same detector to transcript words, or to aligned /s/ and /z/ phone intervals when phone alignment is available.
• Off — skip the detector entirely.

See Sibilants for when "Off" is the better choice (noisy recordings, music backgrounds, or lossy-compressed audio that lacks the high-frequency content the detector needs).

Speaker reference (optional)

Installed app only; the browser version does not include speaker similarity. After enrolling a reference via the CLI, pass its name with --speaker-reference. This turns on the speaker-similarity tile and runs the embedding comparison against that reference. See Speaker similarity.

Adaptive pitch range

The web analyzer enables adaptive pitch by default: it computes a speaker-specific F0 range from a first pass and uses that for the second pass. There is no web toggle for this advanced analysis behavior.

Optimize formant ceiling

The web analyzer automatically selects a formant ceiling from the estimated F0 range. To pin a ceiling for a reproducibility experiment, use the CLI's --max-formant option for that analysis.

Whisper model

Installed app only; the browser version does not transcribe.

Drop-down listing the Whisper model sizes supported in this build. Choices include tiny, base, small, medium, large. Larger models are more accurate but slower, especially on CPU.

The web Settings page persists both the model and backend. The CLI equivalents are vocal-analyzer config set whisper-model … and vocal-analyzer config set whisper-backend ….

Sample-rate guidance

The analyzer does not resample your input. To stay out of the measurement-warning territory:

• 16 kHz or higher — the hard floor for voice-quality / formant extraction. Below this, the whole voice-quality pipeline is skipped.
• 44.1 kHz or 48 kHz — safe defaults for speech recording on consumer hardware.
• Higher rates are fine. The analyzer down-samples internally only when needed for specific sub-pipelines; your input is preserved for playback.

See Recording tips and Troubleshooting.

Transcription availability

The browser version does not include transcription. Core acoustic metrics run as usual; timeline words and word/phone-gated analysis are unavailable.

In the installed app, transcription is enabled automatically when a Whisper model is available. If the transcribe optional extra is not installed, the dashboard surfaces an "unavailable" transcription status with an install hint (uv sync --extra transcribe).

There is no transcription switch in the current web Settings page. Without a supported transcription backend, core acoustic metrics still run; only timeline-word features and word/phone-gated analysis are unavailable.

Goal profile

The web Settings page selects which built-in profile the app applies to its target overlay, and lets you reshape the target bands. See Goal profiles for the full list and dashboard behavior.

Errored-analysis retention

When an analysis fails it is kept as a failed row in the Studio library (with its error message, plus Retry and Delete), so nothing disappears silently.

In the browser version, failed analyses stay in the library until you delete them.

In the installed app, a background sweep reclaims failed analyses — and any audio they still hold — once they are older than errored_job_retention_days (default 14; set 0 to disable the sweep and keep failures until you delete them by hand). The sweep only ever touches failed analyses, never saved sessions, held takes, or in-progress jobs.

The server runs the sweep at startup and, while it remains running, once every 24 hours. Periodic runs are single-flight and stop with the server, so a server left running for a long time still honors the retention window without a restart. Each run re-reads the configured window, so with a zero-day setting the retention pass reclaims nothing — and changing the value takes effect on the next run without a restart. (Deferred cleanup of deletions you initiated yourself still completes on the same schedule regardless of the retention setting; that is finishing your own deletes, not retention policy.)

The setting is a persisted CLI scalar, alongside goal_profile in config.toml:

vocal-analyzer config set errored-job-retention-days 30