Repository navigation
docs: add auto-updating animated --help demo to README - #3
Merged
Merged
Conversation
clintval
force-pushed
the
docs/readme-help-gif
branch
2 times, most recently
from
July 16, 2026 21:21
17f66d5 to
2cb332f
Compare
Record `unmux --help` with VHS and gently scroll the whole help so the CLI's inline, worked examples are visible at a glance. The terminal opens already full of help, then eases downward one line at a time to the footer. The tape and a reproducible generator script live in .github/img/. Rendering notes baked into the tooling: padding is trimmed so the 80-column help gets enough terminal width (otherwise lines with wide glyphs like >= and -> double-wrap and shift the second column); and gifsicle uses the median-cut color method, which weights the palette by frequency and so preserves the abundant dim gray annotation text that the default diversity method discards.
clintval
force-pushed
the
docs/readme-help-gif
branch
from
July 16, 2026 21:22
2cb332f to
6a0a811
Compare
Replace the discrete line-by-line GIF (which scrolls in visible one-line jumps) with a smooth video: the whole help is rendered as one tall image, then a viewport pans down it with motion blur for a buttery scroll. Encoded as H.264 (~6MB) since a smooth pan is impractical as a GIF (no motion compensation -> hundreds of MB). Embedded with a <video> tag (autoplay/loop/muted) and a poster of the first screen.
Committed MP4 cannot render in a README (GitHub's CSP/sanitizer blocks <video> from raw repo URLs; only uploaded assets play). Animated image formats do render and animate. AVIF uses the AV1 codec, so the smooth motion-blurred pan compresses to ~3MB (vs ~50MB WebP / 100MB+ GIF, which lack motion compensation) while staying committable and autoplaying inline via a plain image reference.
1074 -> 860px tall viewport for a less towering demo; same smooth motion-blurred pan and ~3MB AVIF.
Replace the old line-stepping GIF tooling with make-help-demo.sh: VHS renders the whole help as one tall image, ffmpeg pans a viewport down it with motion blur, and libsvtav1 encodes an animated AVIF. Also snapshots the plain help text to help.txt for change detection. The render relies on VHS's bundled default font so it reproduces anywhere without a system font install.
On push to main touching the CLI, rebuild unmux and diff its --help against the committed snapshot; if it changed, re-render the AVIF demo and open a PR for review. No-ops when the help text is unchanged.
clintval
force-pushed
the
docs/readme-help-gif
branch
from
July 17, 2026 00:38
232202c to
367e28d
Compare
clintval
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a smooth, autoplaying scroll through the full
unmux --helpto the README, and a workflow that keeps it in sync with the CLI automatically.The demo
.github/img/help.avif, ~3MB). It autoplays inline in the README from a committed file (plain), and AVIF's AV1 codec compresses the smooth pan to ~3MB where a GIF would be 100MB+ and a WebP ~50MB (neither has motion compensation). A committed MP4 was tried first, but GitHub's CSP blocks<video>from repo files so it never renders..github/img/make-help-demo.sh): VHS renders the entire help as one tall terminal image,ffmpegpans a 1200x860 viewport down it with motion blur for a buttery scroll, andlibsvtav1encodes the AVIF. Uses VHS's bundled default font so it reproduces anywhere.The automation (
.github/workflows/render-help-demo.yml)On pushes to
mainthat touch the CLI, it rebuildsunmux, diffs--helpagainst the committed.github/img/help.txtsnapshot, and: