capture_helper.gui module

Capture Helper — live multi-source scene configurator (single-page GUI).

This module holds nothing but the self-contained HTML document served by the FastAPI app at GET /gui (see capture_helper.api). It is deliberately build-step-free: one string of HTML + Tailwind (via CDN) + vanilla ES-module JavaScript. 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.

What the page does

  • Enumerate every camera and microphone on the host (GET /sources).

  • Add sources to a visual scene canvas (click a device to place it).

  • Live-preview each camera tile as an MJPEG stream (GET /preview/camera.mjpeg) and each microphone as a live level meter polled from GET /preview/mic-level.

  • Arrange camera tiles: drag to move, edit x/y/w/z in the inspector.

  • Save the design as a reusable JSON scene artifact (POST /scene/save) and load one back (POST /scene/load via file upload, or the server’s auto-populated scene from GET /scene).

The page adds no server-side logic — it is purely a friendlier front door to the same HTTP surface the CLI and MCP tools use. It mirrors the AI Helpers minimal GUI convention (Tailwind CDN + vanilla JS, reduced-motion guard, focus rings).

Author

Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/

capture_helper.gui.default_language()[source]

The language an unknown or absent ?lang= falls back to.

Return type:

str

capture_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 _DEFAULT_LANGUAGE, so an unknown ?lang= never 500s.

Returns:

The complete HTML document for that language.

Return type:

str

Examples

>>> "<!doctype html>" in render_gui("en")
True
>>> render_gui("tlh") == render_gui(default_language())
True
capture_helper.gui.supported_languages()[source]

Language codes the GUI can render: English plus every compiled catalogue.

Return type:

tuple[str, …]