podcast_helper.gui module
Podcast Helper — minimal single-page GUI (“episode browser”).
This module holds nothing but the self-contained HTML document served by the
FastAPI app at GET /gui (see podcast_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 podcast_helper.api keeps the route
definitions readable and mirrors the AI Helpers suite convention (see
audio_helper/gui.py): sibling repos copy the plumbing and swap the domain
widgets. Here the domain widget is a feed / episode browser, not an audio
“audition bench”.
What the page does
Enter any feed / RSS / audio / yt-dlp URL in a single box.
List episodes (calls
GET /feed) → a scrollable list of episode cards with cover art, title, publish date and duration.Probe any URL (calls
GET /probe) → shows how podcast-helper classified it (source_kind / is_live / header count) so ambiguity is never buried.Pick an episode → its metadata renders on the right, its
enclosure_urlloads into an inline<audio>player for instant preview (the browser streams the enclosure directly — no server round-trip for playback).Record the selected episode (or any raw URL) to a compressed archive via
POST /recordand offer the resulting file as a download.
Everything talks to the SAME FastAPI endpoints the CLI surface uses — the GUI adds zero new server logic and never uploads the user’s data anywhere.
- podcast_helper.gui.default_language()[source]
The language an unknown or absent
?lang=falls back to.- Return type:
- podcast_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