main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-recording description: >- Recording the screen, a window or audio from Hydrogen on Linux: the native recorder is not available here, what works instead (the desktop's own screen recorder, audio-only via adom-cli, pup on another machine). Use when asked to record my screen, record kicad, record a window, record narration, or why recording start fails.

Hydrogen on Linux: Screen, Window and Audio Recording

Hydrogen's native screen and window recorder does not exist on Linux yet. Every /recording/native/* endpoint answers {"ok": false, "error": ...} saying native recording is not on this platform (status answers {"ok": true, "recording": false}), and adom-cli hydrogen recording start relays that same error, because in the Hydrogen app it drives those endpoints. Do not retry it and do not promise the user an mp4 from it.

What to do instead

The user wants Do this
A video of the screen, Hydrogen, KiCad, any app Ask the user to record with their desktop's own recorder (GNOME: Ctrl+Shift+Alt+R, or the screenshot tool's video toggle; other desktops ship their own, or OBS). Then fetch the file (below).
Just their voice, a narration track adom-cli hydrogen audio start/stop (below).
One browser tab adom-bridge --target <machine> pup_record_start on ANOTHER of the user's machines that runs Adom Bridge (pup lives there), or adom-bridge pup_record_start here once Hydrogen has installed Adom Bridge on this computer.
A still image, not a video POST /screenshot on the control API (see hydrogen-self-screenshot). On Linux it is a snapshot of the whole Hydrogen window.

Getting a desktop recording into the workspace

The workspace machine sees the host's /home at /mnt/host/home and the host's /tmp at /mnt/host/tmp (the workspace's own /tmp is separate). GNOME saves screencasts to ~/Videos/Screencasts/ of the host user, so look at /mnt/host/home/<host user>/Videos/Screencasts/. If that reads "Permission denied" (many distributions make home folders private to their owner), ask the user to copy the file to /tmp on their desktop and read it from /mnt/host/tmp/. Copy it into ~/project/recordings/ before you work on it.

Audio-only — record a narration / voice track (adom-cli hydrogen audio)

When the user wants just their voice, no video — "record a narration track for the video", "record my voice", "let me record some audio to narrate this" — use the dedicated audio verb, NOT the video recorder:

adom-cli hydrogen audio enable                                  # activate mic (silent if cached)
adom-cli hydrogen audio start --countdown 0 --reason "narration for the demo video"
# ... user speaks ...
adom-cli hydrogen audio stop        # → filePath: audio/<name>.webm  (relative to ~/project)
  • Output is a WebM / Opus audio file in ~/project/audio/. It records the microphone in Hydrogen's page (the browser media API; Hydrogen grants the page's microphone permission by itself). Reason is required.
  • Other subcommands: audio status (mic active? device label), audio level (rms/peak/clipping/gain — warn if clipping), audio gain <0.0-4.0> (persists), audio disable.

Stitching / post-processing (ffmpeg) — install it on demand

A common follow-on is "stitch these clips together" or "lay this narration over the video." ffmpeg/ffprobe are NOT pre-installed — the Hydrogen workspace image is intentionally lightweight, and the AI adds tools as the user needs them. That's not a blocker: when you need to concatenate clips, mux a narration .webm onto an .mp4, transcode, or probe a file, just install ffmpeg and proceed (passwordless sudo + apt are available; ffmpeg ~6.1 is in the repos):

sudo apt-get update -qq && sudo apt-get install -y ffmpeg   # pulls ffprobe too

Don't tell the user "ffmpeg isn't available here" — install it (a few seconds) and do the job. Same pattern for any other missing tool (imagemagick, pandoc, …): install on demand rather than declaring it impossible.

Quick reference

Intent On Linux
Record the screen or a window The desktop's own recorder, then read the file via /mnt/host/...
Record narration adom-cli hydrogen audio start/stop to ~/project/audio/
Record a pup tab pup_record_start on another machine with Adom Bridge (--target)
Is a recording running? GET /recording/native/status always says recording:false here
  • hydrogen-self-screenshot: screenshots of Hydrogen's own window
  • hydrogen-demo-recording: the demo recipe, adapted for Linux
  • hydrogen-volume: which host paths the workspace can see
  • hydrogen-screen-lock: why Hydrogen on Linux holds no display wake-lock