Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
d8a45ab
name: hydrogen-captions
description: >-
Paint caption text on the Hydrogen workspace with adom-cli hydrogen caption
(seconds, auto-expire, part of the window's pixels) for demos and
walkthroughs. Use when asked to put text on screen, add a caption or
callout, label a demo step, caption over other apps, or clear a stuck
caption.
Hydrogen: On-Screen Captions (Linux)
You can paint labeled caption text inside the Hydrogen window for demos and walkthroughs ("Step 3: run DRC"). It is real pixels in Hydrogen's page, so a Hydrogen screenshot includes it.
Captions are visual on-screen narration — centered status / countdowns / "what I'm doing," great during demos and recordings. Distinct from:
- toasts — corner pop-ups via
POST /ui/toast(transient notifications, seehydrogen-notifications); a caption is centered narration, a toast is a corner alert.- TTS audio narration (
adom-tts) — pair a caption with TTS for a narrated walkthrough.- the internal auth-overlay caption Hydrogen draws for login/auth flows — not something you trigger for demos. The workspace caption below is the one you drive.
Only the workspace caption exists on Linux. The desktop overlay caption over other apps
(adom-bridge desktop_caption) is not available on a Linux desktop: Adom Bridge for Linux
refuses to create the caption window. To label something in another app, put the caption in
Hydrogen or narrate with TTS.
Workspace caption: adom-cli hydrogen caption
Reach for this FIRST. It's the same command on web Hydrogen and Hydrogen (adom-cli routes
through Hydrogen's workspace-events server → SSE → the frontend captionStore), so it stays
consistent across both — same principle as screenshots. Renders centered inside the Hydrogen
workspace webview. show takes the TEXT as a positional arg (NOT --text); the only
flags are -d/--duration, -p/--position, -s/--size (no id, x/y, or
fontSize — those are desktop-overlay-only). Subcommands: show / hide.
adom-cli hydrogen caption show "Step 1: open the board" -p center -s large # 30s auto-expire
adom-cli hydrogen caption show "Step 2: run DRC" -d 60 -p center -s large # hold 60 SECONDS
adom-cli hydrogen caption hide # clear now
⚠️⚠️ -d / duration is in SECONDS — NOT milliseconds ⚠️⚠️
THE gotcha. -d 30 = 30 seconds. -d 4000 = 66 MINUTES, not 4 seconds. If you're
thinking in ms you're off by 1000×. You almost never need a big number — the 30s
default already covers "leave it up while I do a thing."
Web-Hydrogen vs Hydrogen parity: the command + the SECONDS unit +
hideare identical on both (center/large rendering,-d 20held visibly). BUT the sane lifecycle below (30s default / 300s cap / persist) is verified on Hydrogen; web Hydrogen may still return the older terse_hint("auto-hides after the specified duration") and may not enforce the 30s-default/300s-cap yet. So on web Hydrogen, don't assume a fat-dself-heals — pass a sane duration.
Lifecycle (sane, never abandoned)
- No
-d(or-d 0) → auto-expires after 30s. The right default — you do NOT need tohideit. - Positive
-d <seconds>→ holds that many seconds, HARD-CAPPED at 300s (5 min). A larger value still clears at 5 min, so a fat-fingered-d 4000self-heals. - Newest wins: showing another caption replaces the current one;
hideclears immediately. - No "forever" via adom-cli — its
-dis an unsigned int (rejects negatives) by design. This is a feature, not a gap: adom-cli is the same binary on web-Hydrogen and Hydrogen, so "no persist via adom-cli" keeps both consistent and bounded (no abandoned captions). A persist-until-hidden escape exists ONLY on the raw HTTP endpoint ({"duration":-1}, below) — rarely needed. - No
caption statusverb (yet). There's no way to query "is a caption up / how long left" from adom-cli — and with newest-wins + the 30s auto-expire you rarely need to. -pposition:top/center/bottom(no corners).-ssize:small/medium/large.- Needs a live workspace/editor session (the server returns 409 if none).
Direct HTTP fallback — only for scripts already hitting Hydrogen's API
adom-cli is the consistent default; use HTTP only when a script talks to Hydrogen's API
directly. It's the same caption, same lifecycle — adom-cli just wraps this path with
the workspace owner/repo. The caption lives on the workspace-events server
(ADOM_HYDROGEN_URL, the proxy) — NOT the control port:
# show — duration in SECONDS, identical body/lifecycle to adom-cli
curl -s -X POST "$ADOM_HYDROGEN_URL/api/workspaces/editor/<owner>/<repo>/current/caption" \
-H 'Content-Type: application/json' \
-d '{"text":"Step 1: open the board","duration":60,"position":"center","size":"large"}'
# hide
curl -s -X POST "$ADOM_HYDROGEN_URL/api/workspaces/editor/<owner>/<repo>/current/caption" \
-d '{"hide":true}'
# persist until hidden (HTTP-ONLY escape — adom-cli can't send a negative):
# -d '{"text":"Recording…","duration":-1}'
Body: {text, duration (SECONDS), position, size}; clear with {hide:true}.
Patterns
- Walkthrough / demo callouts — drop a
centercaption per step. Combine with a recording so the callouts end up in the finished video. Pair with TTS for narration. - Cleanup:
hidewhen a step is done. - Hydrogen's native screen recorder does not run on Linux, so a caption ends up in a video only if whatever records the screen captures the Hydrogen window.
Related skills
hydrogen-self-screenshot: captions show up in Hydrogen screenshotshydrogen-notifications: toastsadom-tts: audio narration to pair with on-screen captions (captions are visual-only)
---
name: hydrogen-captions
description: >-
Paint caption text on the Hydrogen workspace with `adom-cli hydrogen caption`
(seconds, auto-expire, part of the window's pixels) for demos and
walkthroughs. Use when asked to put text on screen, add a caption or
callout, label a demo step, caption over other apps, or clear a stuck
caption.
---
# Hydrogen: On-Screen Captions (Linux)
You can **paint labeled caption text inside the Hydrogen window** for demos and
walkthroughs ("Step 3: run DRC"). It is real pixels in Hydrogen's page, so a Hydrogen
screenshot includes it.
> Captions are **visual on-screen narration** — centered status / countdowns / "what
> I'm doing," great during demos and recordings. Distinct from:
> - **toasts** — corner pop-ups via `POST /ui/toast` (transient notifications, see
> `hydrogen-notifications`); a caption is centered narration, a toast is a corner alert.
> - **TTS** *audio* narration (`adom-tts`) — pair a caption with TTS for a narrated walkthrough.
> - the internal **auth-overlay caption** Hydrogen draws for login/auth flows — not something
> you trigger for demos. The workspace caption below is the one you drive.
**Only the workspace caption exists on Linux.** The desktop overlay caption over other apps
(`adom-bridge desktop_caption`) is not available on a Linux desktop: Adom Bridge for Linux
refuses to create the caption window. To label something in another app, put the caption in
Hydrogen or narrate with TTS.
## Workspace caption: `adom-cli hydrogen caption`
**Reach for this FIRST.** It's the *same* command on web Hydrogen and Hydrogen (adom-cli routes
through Hydrogen's workspace-events server → SSE → the frontend `captionStore`), so it stays
consistent across both — same principle as screenshots. Renders centered **inside the Hydrogen
workspace webview**. `show` takes the TEXT as a **positional arg** (NOT `--text`); the only
flags are `-d`/`--duration`, `-p`/`--position`, `-s`/`--size` (no `id`, `x`/`y`, or
`fontSize` — those are desktop-overlay-only). Subcommands: `show` / `hide`.
```bash
adom-cli hydrogen caption show "Step 1: open the board" -p center -s large # 30s auto-expire
adom-cli hydrogen caption show "Step 2: run DRC" -d 60 -p center -s large # hold 60 SECONDS
adom-cli hydrogen caption hide # clear now
```
### ⚠️⚠️ `-d` / `duration` is in **SECONDS — NOT milliseconds** ⚠️⚠️
THE gotcha. `-d 30` = 30 seconds. `-d 4000` = **66 MINUTES**, not 4 seconds. If you're
thinking in ms you're off by **1000×**. You almost never need a big number — the 30s
default already covers "leave it up while I do a thing."
> **Web-Hydrogen vs Hydrogen parity:** the **command + the SECONDS unit + `hide` are identical**
> on both (center/large rendering, `-d 20` held visibly). BUT the sane **lifecycle below
> (30s default / 300s cap / persist)** is verified on Hydrogen; web Hydrogen may still return the
> *older terse `_hint`* ("auto-hides after the specified duration") and may not enforce the
> 30s-default/300s-cap yet. **So on web Hydrogen, don't assume a fat `-d` self-heals — pass
> a sane duration.**
### Lifecycle (sane, never abandoned)
- **No `-d` (or `-d 0`) → auto-expires after 30s.** The right default — you do NOT need
to `hide` it.
- **Positive `-d <seconds>` → holds that many seconds, HARD-CAPPED at 300s (5 min).** A
larger value still clears at 5 min, so a fat-fingered `-d 4000` self-heals.
- **Newest wins:** showing another caption replaces the current one; `hide` clears immediately.
- **No "forever" via adom-cli** — its `-d` is an unsigned int (rejects negatives) by
design. This is a **feature, not a gap**: adom-cli is the same binary on web-Hydrogen and
Hydrogen, so "no persist via adom-cli" keeps both consistent and bounded (no abandoned
captions). A persist-until-hidden escape exists ONLY on the raw HTTP endpoint
(`{"duration":-1}`, below) — rarely needed.
- **No `caption status` verb (yet).** There's no way to query "is a caption up / how long
left" from adom-cli — and with newest-wins + the 30s auto-expire you rarely need to.
- `-p` position: `top` / `center` / `bottom` (no corners). `-s` size: `small` / `medium` / `large`.
- Needs a live workspace/editor session (the server returns 409 if none).
### Direct HTTP fallback — only for scripts already hitting Hydrogen's API
adom-cli is the consistent default; use HTTP **only** when a script talks to Hydrogen's API
directly. It's the **same caption, same lifecycle** — adom-cli just wraps this path with
the workspace owner/repo. The caption lives on the **workspace-events server**
(`ADOM_HYDROGEN_URL`, the proxy) — **NOT the control port**:
```bash
# show — duration in SECONDS, identical body/lifecycle to adom-cli
curl -s -X POST "$ADOM_HYDROGEN_URL/api/workspaces/editor/<owner>/<repo>/current/caption" \
-H 'Content-Type: application/json' \
-d '{"text":"Step 1: open the board","duration":60,"position":"center","size":"large"}'
# hide
curl -s -X POST "$ADOM_HYDROGEN_URL/api/workspaces/editor/<owner>/<repo>/current/caption" \
-d '{"hide":true}'
# persist until hidden (HTTP-ONLY escape — adom-cli can't send a negative):
# -d '{"text":"Recording…","duration":-1}'
```
Body: `{text, duration (SECONDS), position, size}`; clear with `{hide:true}`.
## Patterns
- **Walkthrough / demo callouts** — drop a `center` caption per step. Combine with a
recording so the callouts end up in the finished video. Pair with TTS for narration.
- **Cleanup**: `hide` when a step is done.
- Hydrogen's native screen recorder does not run on Linux, so a caption ends up in a video
only if whatever records the screen captures the Hydrogen window.
## Related skills
- `hydrogen-self-screenshot`: captions show up in Hydrogen screenshots
- `hydrogen-notifications`: toasts
- `adom-tts`: audio narration to pair with on-screen captions (captions are visual-only)