Skip to content

README.md

Latest commit

 

History

History
104 lines (76 loc) · 4.96 KB

README.md

File metadata and controls

104 lines (76 loc) · 4.96 KB
Raw

UFFS demo capture kit

VHS tapes and tooling for the demo clips embedded in the README, the docs, and the project site. Everything here is built so the clips are reproducible, honest, and re-renderable each release.

Each clip has a full reel (*-demo.tape), a short loop (*-demo-short.tape, TUI/CLI), and a video cut (*-demo-video.tape → MP4). The video cuts are identical to the GIF tapes in shot list, commands, and keystrokes; only the static card holds (banner, intro, outro) are shorter. Command typing speed and all measured latencies are the same in every variant.

Capture must run on a Windows box with live NTFS (the only place uffs reads the MFT directly); macOS/Linux can only show offline-MFT analysis.

Two binaries gotcha. Releases ship both the Rust daemon client (uffs.exe) and the legacy C++ reference (uffs.com). On Windows, PATHEXT ranks .COM before .EXE, so a bare uffs runs the C++ tool — which has no daemon subcommand and uses --drives=/--columns= syntax. The prep tool (scripts/windows/record-demo-prep.rs) resolves uffs.exe by name and gates on a >= 0.5.0 semver parsed from uffs --version, so the C++ tool or an old build is refused up front. Override with --bin <path>.

TL;DR

# 1. Put the machine in a known, honest recording state (Windows, elevated)
rust-script scripts/windows/record-demo-prep.rs --mode hot --drives C,D,E,F,G,M,S

# 2. Record interactive clips on Windows with ScreenToGif.
#    VHS is NOT available natively on Windows (it needs `ttyd`, Linux/macOS only).

# 2-alt. Reproducible GIF/MP4 via VHS — only under WSL/Linux/macOS:
vhs scripts/dev/demo/cli-demo.tape          # -> uffs-cli.gif        (needs ttyd + ffmpeg)
vhs scripts/dev/demo/cli-demo-video.tape    # -> uffs-cli-video.mp4

Recorders

Tool Use for Why Platform
ScreenToGif TUI clip and CLI clip on Windows (primary) Free, Windows-native, captures a real interactive session faithfully; built-in crop/trim/optimize + palette reduction. Windows
VHS (charmbracelet/vhs) Reproducible clips from the .tape files Scripted tapes → deterministic, pixel-stable GIF/MP4/WebM you can re-render every release. Drives the real binary, so all timings are genuine. Requires ttyd, which has no native Windows build — run tapes under WSL/Linux/macOS only.
ffmpeg post-processing Trim, scale, palette-optimize any capture (snippets below). All

Install on Windows: winget install NickeManarin.ScreenToGif. VHS is Linux/macOS-only for our purposes (brew install vhs ttyd / apt install ttyd + go install ...).

Honesty guardrails (non-negotiable)

These clips demo a benchmark-honest project. Do not undermine that.

  • Never fake or speed-edit latency. VHS runs the real binary; with ScreenToGif, do not cut frames to make a query look faster than it is.
  • State the daemon tier. The "instant" story is a hot/warm daemon. record-demo-prep.rs --mode hot warms it first; the caption must say so. If you want to show the cold build, use --mode cold --confirm-destructive and label it COLD.
  • Show real counts. Don't trim the result count or the "N results in X ms" line out of frame.
  • Match the published numbers. Latency on screen should be consistent with docs/benchmarks/. If it drifts, update the benchmark hub too — don't cherry-pick.
  • No doctored prompt. Use a clean but real shell; don't hand-edit recorded text.

The bundled uffs-tui is the free demo edition (capped result counts, exports disabled — DEMO-LICENSE.txt). That's fine and honest for a clip; don't imply uncapped/export features.

Outputs

Each .tape names its output file. GIF outputs live in assets/demo/ (this repo) and are the only demo media committed to git. The *-video.tape MP4 outputs are upload artifacts (gitignored, never committed).

Tape Output
tui-demo.tape / tui-demo-short.tape / tui-demo-video.tape uffs-tui.gif / uffs-tui-short.gif / uffs-tui-video.mp4
cli-demo.tape / cli-demo-short.tape / cli-demo-video.tape uffs-cli.gif / uffs-cli-short.gif / uffs-cli-video.mp4
mcp-demo.tape / mcp-demo-video.tape uffs-mcp-claude.gif / uffs-mcp-claude-video.mp4

Keep GIFs small: prefer the smallest optimized GIF (< ~3 MB). If a clip won't fit under ~5 MB as a GIF, ship an MP4/WebM and let GitHub/the site autoplay it.

Post-processing snippets

# Trim to a clean window (start 00:02, length 18s) from an MP4 capture
ffmpeg -ss 00:00:02 -t 18 -i raw.mp4 -an trimmed.mp4

# MP4 -> optimized GIF (palette pass keeps it crisp + small)
ffmpeg -i trimmed.mp4 -vf "fps=15,scale=1200:-1:flags=lanczos,palettegen" palette.png
ffmpeg -i trimmed.mp4 -i palette.png -vf "fps=15,scale=1200:-1:flags=lanczos,paletteuse" uffs-cli.gif

Aim for: 1200px wide, 12–15 fps.