CHENG-LIANG1/product-demo-video-skill

Product Demo Video

Turn a working web project into a repeatable product-demo video pipeline and a publishable video artifact. Treat the recording, narration, captions, music, and media validation as one deliverable.

Resolve the output

Before implementation, determine:

• target language or languages;
• destination and aspect ratio, such as Douyin/TikTok 9:16 or desktop 16:9;
• desired duration and call to action;
• whether the app already supports the target UI language;
• narration source: OpenAI TTS, an available system voice, or user-supplied audio.

If the user already chose a language or platform, proceed without asking again. For several languages, produce separate narration, captions, and final files while reusing the same visual plan when the localized UI remains geometrically sound.

Workflow

1. Inspect the current worktree, app commands, language support, and existing media tooling. Preserve unrelated changes.
2. Run the real app in production mode when practical. Avoid development overlays, hot-reload indicators, and unrelated browser chrome.
3. Create a project-local demo config and recording adapter. Copy and adapt assets/demo-video.config.example.json; read references/configuration.md for language selection and segment rules.
4. Validate the selected language before recording: visible UI, document.documentElement.lang, input guidance, dialogs, errors, and responsive layout must match.
5. Record a deterministic browser flow at the capture viewport. Keep test mocks inside the recording harness; do not add promo-only fake behavior to production code. Read references/recording-and-composition.md for the reliable Playwright and FFmpeg patterns.
6. Write the narration before final timing. Generate one clip per segment so subtitles and edits remain controllable. Clearly disclose that generated narration is synthetic.
7. Create both burned captions and a sidecar .srt. Keep captions inside platform-safe areas and use a font that supports the selected language.
8. Use original, generated, public-domain, or properly licensed music. Mix it below the narration and fade it cleanly.
9. Provide one project-local command that can rebuild, record, compose, and verify the video again.
10. Decode and inspect the final artifact before reporting completion. Return the video, subtitle file, narration text, command, language, dimensions, duration, and voice source.

Language rules

• Selection precedence is: explicit user request, CLI/config language override, then config default.
• UI, narration, captions, share text, and metadata should use the same selected language.
• Do not translate product names, URLs, code identifiers, repository names, or commands unless the product itself localizes them.
• Recheck line breaks and geometry for every language. A translation that technically renders but clips or wraps awkwardly is not complete.
• Choose language-appropriate voices and fonts. If the preferred TTS provider is unavailable, use a declared fallback or pause for the missing credential; never imply that a system voice came from a different provider.

Verification baseline

For a vertical social video, prefer:

• 1080x1920, square pixels, H.264, yuv420p, 30 FPS;
• AAC at 48 kHz;
• +faststart MP4 metadata;
• integrated loudness near -16 to -14 LUFS without clipping;
• a full decode pass, visual samples from several timestamps, and subtitle timing checks.

Run the included helpers when applicable:

python scripts/validate_config.py demo-video.config.json --language en-US
python scripts/generate_srt.py demo-video.config.json --language en-US --output output/demo-en.srt
python scripts/verify_media.py output/demo-en.mp4 --config demo-video.config.json

Do not commit raw recordings, generated speech, temporary caption images, or final videos unless the user explicitly wants media stored in version control.