clip-cover

clip-cover

Pick a frame, overlay a title, export a cover.

Workflow

1. Identify the input video (and optional .srt). Default font fallback chain follows AGENTS.md → macOS font fallback chain.

2. Bootstrap the shared plugin venv (one-time ~10s; cached ~100ms after that), then launch the picker server. The server binds to 127.0.0.1 only and generates a per-session token:

   PY="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/preflight.sh")"
   "$PY" "${CLAUDE_PLUGIN_ROOT}/skills/clip-cover/scripts/server.py" \
       <video> [--srt path.srt] [--initial-text "line1|line2|line3"]
   

   The server prints a http://127.0.0.1:<port>/?token=… URL — open it.

3. In the browser:

   • Scrub the video, use ±1-frame buttons, or click a subtitle segment to jump to its start.
   • Enter up to 3 title lines (use 「…」 for yellow-highlighted segments).
   • Pick vertical position (top / upper-third / center) and font size (auto / manual).
   • Render preview calls ffmpeg -ss <t> -i video -frames:v 1 server-side and composites in Pillow, so the preview is byte-accurate to what gets exported (handles VFR / sparse keyframes).
   • Export writes <stem>_cover.jpg next to the source video and shuts the server down.

4. The server also auto-shuts down on POST /shutdown or after 30 min idle.

Security

• Server bound to 127.0.0.1 only — not reachable on the LAN.
• Every endpoint except GET / requires the per-session token.
• POST body capped at 64 KB.
• Output path locked to <video-dir>/<stem>_cover.jpg; arbitrary paths rejected.
• No shell: ffmpeg and Pillow are invoked via argv lists.

Compose details

See scripts/compose.py:

• Auto-fit width loop (font shrinks until each line fits).
• Character tracking for visual rhythm.
• Yellow highlight for any 「…」 segments.
• Black stroke at 10% of font size for legibility on any frame.
• Font fallback chain per AGENTS.md.