--- name: adom-video-post description: > Post-production for demo recordings: speed up boring parts with overlay captions, add voiceover narration after the fact, or publish the final video to a wiki page. For pre-production and recording (writing demo scripts, setting up panels, driving the recording), use the demo-recording skill instead. Trigger words: speed up demo recording, speed up video, timelapse video, fast forward boring parts, compress slow parts of video, video post-production, voiceover after recording, narrate a recording, demo speedup, demo post-process, post-process demo, publish demo video to wiki. --- # adom-video-post Post-production CLI for demo recordings. For pre-production and recording (writing scripts, setting up panels, driving the recording), use the **demo-recording** skill. ## πŸ›‘ Storyboard review is MANDATORY for Flow A demos β€” do not skip The whole point of building a demo as per-section clips is so the human reviewer can **look at each clip individually** and tell you which ones are broken. AI-made demos fail in specific, localized ways β€” "clip 5 measured the wrong pads," "clip 8 never clicked anything," "clip 11 walkthrough didn't advance." The reviewer spots those instantly when clips are numbered, described, and separately playable. Asked to watch a 3–5 minute uninterrupted video, they can't β€” they'd have to scrub to a timestamp and guess which segment was broken. Skipping storyboard makes their job genuinely hard and turns the feedback loop from precise ("clip 5 is wrong") to useless ("something's off somewhere"). Don't do that to them. **The rule, in one line:** after `manifest add` for all clips, the next command MUST be `adom-video-post storyboard `, and you MUST wait for the user's per-clip feedback before concat / upload. ```bash # Open storyboard β†’ user reviews β†’ you fix bad clips β†’ repeat β†’ only then concat adom-video-post storyboard /tmp/my-demo-manifest.json \ --tab-name 'adom-video-post: review' --port 8797 # Activate + screenshot to confirm it rendered adom-cli hydrogen workspace active-tab --name 'adom-video-post: review' adom-cli hydrogen screenshot panel --name 'adom-video-post: review' \ --reason 'show user the clip storyboard for review' # Then point the user at the tab and wait for "clip N is broken" / "looks good" ``` ### Every clip needs a `--description` `adom-video-post manifest add --description ""` is how the storyboard UI explains what each clip is supposed to show. Without descriptions, the user is still blind β€” they see a player but no context. Write descriptions that are **concrete about the intent**, not just the feature name. Compare: - ❌ "inspect tool" β€” no hint what's expected to happen - ❌ "measure demo" β€” can't tell if a bad clip is your intent being wrong or your execution being wrong - βœ… "BME680 cinematic slow orbit for 15s. Camera starts iso, completes one rotation, no HUDs opened." - βœ… "iCE40-USB Measure: commit MP1β†’MP3 (diagonal 181 mm), then U1β†’J1, then MC_USB_DPβ†’DM. Each shows Ξ”X/Ξ”Y/distance HUD." Rule of thumb: if a teammate reading just the description couldn't write the clip's interaction script, the description is too vague. ### Known bug: `adom-video-post concat` drops audio Today `adom-video-post concat --kind raw` only writes the video stream. Until fixed, use ffmpeg's concat demuxer as a drop-in replacement AFTER storyboard approval: ```bash LIST=$(mktemp) for c in $(jq -r '.clips[].raw' /tmp/my-demo-manifest.json); do echo "file '$c'" >> $LIST done ffmpeg -y -f concat -safe 0 -i $LIST -c copy ~/project/recordings/final.webm ffprobe -v error -show_streams ~/project/recordings/final.webm | grep codec_type # Both `video` AND `audio` must appear. If audio is missing, the concat dropped TTS. ``` ## πŸ—£οΈ TTS pronunciation β€” consult the `tts-pronunciation` skill, not a table here `edge-tts` and other neural engines mispronounce many Adom tool names and acronyms (`adom-tsci` β†’ "adom-sci", `JLCPCB` β†’ garbled, `UART` β†’ "yoo-art", etc.). The canonical pronunciation table lives in the **`tts-pronunciation` skill** at `gallia/skills/tts-pronunciation/SKILL.md` (data file: `pronunciations.json`). **Always consult that skill when drafting or validating narration** β€” do not maintain a parallel table in this skill. **Rule:** before muxing a clip, every Adom-ish proper noun in its narration text must match the `narration` column of an entry in `pronunciations.json`. If a term isn't in the table, stop and add it (contribution flow documented in that skill). **Verify before rendering** with a one-shot: ```bash edge-tts --voice en-US-AndrewMultilingualNeural \ --text "adom t s c i version one point three point seven" \ --write-media /tmp/_test.mp3 # Listen with ffplay β€” it should spell out T S C I, not say "sci" as a word. ``` Fixing one clip pre-mux is cheap; re-rendering 13 clips after mux because you skipped the pronunciation check is not. ## πŸ“ Clip duration must match narration duration β€” don't ship loose clips A clip where the video is 2:17 and the narration is 0:30 is broken regardless of which one is "correct." The viewer stares at the last frame for a minute and a half, or the narration cuts off while the video keeps going. **Rule:** **video length β‰ˆ narration length, Β±15%.** If they diverge, fix whichever is wrong: - Narration too long: tighten the script, drop filler ("So…", "What we're looking at here…"). - Video too long: either trim on recording, split the clip into N smaller clips (each with its own matched narration), or apply `adom-video-post process` speedups in the boring bits with caption overlays. **Split before you speedup when:** - The sub-sections are genuinely different things you'd narrate separately ("open it / click around / close it" β†’ three clips, three narrations). - One sub-section loads slowly from the app side (e.g. cycling through 8 example molecules where each takes 3 s to render). Speed-up masks the lag but smaller-clip recording lets you control the pacing. - You want surgical re-shoots β€” a 2:17 "examples" clip is too coarse to re-record if one of the 8 fails; eight 15-second clips let you re-shoot just the broken one. **Check duration fit before muxing:** ```bash for f in /tmp/clips-raw/*.webm; do vd=$(ffprobe -v error -show_entries format=duration -of default=nk=1:nw=1 "$f") ad=$(ffprobe -v error -show_entries format=duration -of default=nk=1:nw=1 "${f%.webm}.mp3") ratio=$(python3 -c "print(max($vd,$ad)/min($vd,$ad))") echo "$(basename $f): video=${vd}s tts=${ad}s ratio=$ratio" done # Anything with ratio > 1.15 needs a tighten or a split. ``` ## πŸ–₯️ Fullscreen review in a Hydrogen webview is blocked β€” route users to pup Hydrogen's webview panel wraps the storyboard URL in an iframe without `allow="fullscreen"` (filed as `adom-inc/hydrogen#329`). The β›Ά Expand button on each clip card calls `element.requestFullscreen()` which throws silently. This is OUT OF scope for `adom-video-post` to fix. **When the user asks why fullscreen doesn't work** (and they will), tell them: same URL, standalone Chrome window via `pup`: ```bash # Open the storyboard in a standalone Chrome window (fullscreen works there) pup open-tab --url "https://.adom.cloud/proxy/8797/" --name "storyboard fullscreen review" ``` Do not wait for hydrogen#329 to ship before offering this β€” the workaround is fine and it's the better place to review clips anyway (larger screen real-estate, native fullscreen). ## 🚨 Wiki webm: keyframes every 1 s β€” non-negotiable on the final encode Every webm/mp4 you upload to the Adom Wiki must have a keyframe interval of ~1 s (`-g 30 -keyint_min 30` for 30 fps content). Without that, the `