vulh1209/product-video-skill

product-video

Real footage + an event log -> a declarative plan (YAML) -> pvk render -> contact sheet -> final. The scripts do the timing, zooms, overlays and audio; you storyboard, write the plan, and look at frames.

PVK=~/.claude/skills/product-video/bin/pvk      # or `pvk` after `pip install -e ~/.claude/skills/product-video`

When to use

The user wants	Make	Read first
Users to learn a feature or a whole app ("video hướng dẫn", tutorial, onboarding)	tutorial: chapters of 1-3 min, then pvk join	references/storyboard.md
Attention for a product or release ("video quảng cáo", promo, launch, teaser)	promo: one 30-45 s 16:9 cut on the beat	references/storyboard.md
A short web-app demo or a bug repro clip	the web-video skill alone	-

Hard rules

1. Real app, sample data. Film the real product with realistic, made-up sample data. No mockups, and never real customer data, secrets or production accounts (references/privacy.md).
2. Storyboard first, then a yes. Write the storyboard in plain language and get approval before any take.
3. The project's design. Run theme init on the project, check the result against its design guide.
4. Music and SFX are mandatory. Every video gets a bed and UI sounds; master at -16 LUFS.
5. Draft, look, then final. Render --draft --check, open every contact sheet, fix, and only then --final.
6. Nothing leaves the machine (uploads, posts, issue attachments) without the owner's yes.
7. Never drive security, keychain or sign-in dialogs. Hand those to the user.

Step 0. Setup (once per machine)

$PVK doctor                 # ffmpeg, Python 3.11+, packages, Chromium, fonts, optional tools
python3 -m pip install -r ~/.claude/skills/product-video/requirements.txt && python3 -m playwright install chromium
$PVK fonts                  # downloads Inter, Playfair Display, JetBrains Mono (OFL) into ~/.cache/product-video
$PVK sfx gen && $PVK music beds
$PVK selftest               # renders a short chapter and promo from the bundled demo (~1 min)

Missing tools: print the install command and ask; do not install silently.

Step 1. Theme from the project

cd <video-folder>                          # e.g. <project>/video (keep outputs out of git)
$PVK theme init --repo <project> --out theme.json
$PVK fonts --theme theme.json
$PVK overlay chapter title="Preview" --theme theme.json --out preview.png   # look at it

Fix colours, fonts, brand and logo in theme.json by hand where the design guide says more (references/theme.md).

Step 2. Storyboard

Tutorial: one chapter per task the user must learn; each chapter = chapter card, footage with 3-8 numbered captions, recap card. Promo: 5-8 highlights, each a short headline card + a 2-4 s footage moment, end card. Write it as a table (time, screen, caption, sound) and get a yes. Details: references/storyboard.md.

Step 3. Capture

Product	How
Native macOS app	write scene.py (see examples/scene_native.py), then $PVK capture native scene.py --app "App" --out takes/s1 --rehearse, then without --rehearse
Web app	record with web-video (record.py --slug x), then $PVK capture import video-out/x/v1 --name w1
Anything else	put raw.mp4 and an events.json (see references/plan-format.md) in takes/<name>/
No app yet / trying it out	$PVK demo --out takes/demo

Before each take: sample data loaded, notifications off (Do Not Disturb), old toasts closed, window size fixed. After each take: $PVK check popups takes/s1 and $PVK check grab takes/s1 grab.png 1 5 9 to look at it. macOS pitfalls (Mission Control keys, Cmd vs Ctrl, the real pointer, HUDs): references/pitfalls.md.

Step 4. Plan

Copy examples/tutorial.yaml or examples/promo.yaml next to the takes and edit it. Times in footage clips are source seconds from the take's events.json; boxes are source pixels. Full format: references/plan-format.md.

$PVK render ch01.yaml --only-plan     # fast: out/plan/ch01.md lists every clip, caption, zoom, sound, warning

Fix every warning (short captions, overlaps, callouts that span a zoom, 2-digit step numbers).

Step 5. Draft and check

$PVK render ch01.yaml --draft --check            # 720p; out/drafts/ch01.mp4 + out/check/ch01/contact-*.png
$PVK render ch01.yaml --frames 3.2,7.5           # stills at output times, for a closer look
$PVK promo promo.yaml --draft --check            # promos: same engine, cuts snapped to the beat grid

Open every contact sheet (Read the PNGs). Check: captions readable and not covering the action, zoom on the right place, no OS pop-up or leftover toast, cursor where the click is, cards spelled right, loudness about -16 LUFS. Up to 3 fix passes, then show the user the draft and the sheet.

Step 6. Final and full cut

$PVK render ch01.yaml --final                    # 1080p, out/final/ch01.mp4
$PVK join out/final/tutorial.mp4 out/final/ch0*.mp4
$PVK check out/final/tutorial.mp4

Report: file paths, durations, loudness, what you could not check (you cannot hear the mix: say so).

Music and sound

music: bed:soft-piano | bed:ambient | bed:promo are synthesized beds (own work, free). For licensed tracks: $PVK music fetch (where to get them), then $PVK music add track.mp3 --title ... --author ... --source URL --license ... (normalizes to -20 LUFS and logs music/LICENSES.md). Never commit third-party tracks. SFX map, ducking and loudness: references/audio.md.

References

• references/storyboard.md: tutorial vs promo, chapter structure, caption writing, beat cuts
• references/plan-format.md: every plan key, the events.json format, the timeline math
• references/theme.md: theme.json, theme init, fonts (OFL), logo
• references/audio.md: beds, licensed music, SFX map, loudness targets
• references/capture.md: native macOS capture, web-video import, take layout
• references/pitfalls.md: everything that went wrong in real projects and the fix
• references/privacy.md: data and sharing rules