vocal_helper.gui module
Vocal Helper — transcript-viewer GUI (“who spoke when” bench).
This module holds nothing but the self-contained HTML document served by the
FastAPI app at GET /gui (see vocal_helper.api). It is deliberately
build-step-free: one string of HTML + Tailwind (via CDN) + vanilla ES-module
JavaScript. There is no bundler, no framework, no npm — the whole page is a
static asset the API returns verbatim.
Where the words live
In the markup, in English. Each one is wrapped as {{_("…")}} in the HTML,
or listed in _JS_NAME_TO_SOURCE for the script, and
os_helper.Catalog translates it through the compiled gettext
catalogues under locales/ (CODING.md 21.3).
English is the msgid, so it needs no catalogue and cannot fall out of sync with
one; a string the French catalogue has not caught up with renders as readable
English instead of as a key. The cost is the mirror image: rewording the
English here orphans its French entry, and gettext would quietly serve the
English. tests/test_gui_i18n.py exists to catch that — it hands every
source string to os_helper.Catalog.problems(), so an orphaned
translation is a red build rather than a half-reverted page.
render_gui() resolves a language and returns the finished page.
Why a separate module
Keeping the (long) HTML out of vocal_helper.api keeps the route
definitions readable and mirrors the AI Helpers suite convention (see
audio_helper/gui.py): swap the operation for vocal-helper’s domain, keep
the same “one HTML string returned by a /gui route” plumbing.
What the page does
Drop / pick a local audio file or paste a URL (YouTube / podcast RSS / direct media) — both stay local: the file never leaves the machine and the URL is fetched by the local server, not the browser.
Run the full offline pipeline (VAD + diarization + STT + optional rolling Gemma summary) by POSTing to the same
/pipelineendpoint the CLI and MCP surfaces use — the GUI adds zero new server logic.Render a speaker-labelled, colour-coded transcript — one stable colour per speaker (S0, S1, …) — with each utterance’s start time, plus the rolling summary in its own panel.
Utterances reveal progressively (motion-guarded) so a long transcript reads like it is streaming in, the honest testable subset of a live view.
Local-first
Sovereign by design: the page talks ONLY to the local vocal-helper server it is served from. No CDN audio, no analytics, no third party sees your voice.
- vocal_helper.gui.default_language()[source]
The language an unknown or absent
?lang=falls back to.- Return type:
- vocal_helper.gui.render_gui(lang='')[source]
Render the single-page GUI in the requested language.
- Parameters:
lang (str) – Two-letter language code. Anything outside the locale file’s a compiled catalogue — including the empty string — falls back to
meta.default_locale, so an unknown?lang=never 500s.- Returns:
The complete HTML document for that language.
- Return type:
Examples
>>> "<!doctype html>" in render_gui("en") True >>> render_gui("tlh") == render_gui(default_language()) True