main
John Lauer Publish 0.1.0 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, 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.

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:

# 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.
  • 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)