chensiyuan040-hash/skill

HyperFrames Chinese Video Production Guide

Write video in HTML, render frame-by-frame to MP4. This skill is the practical distillation of a complete 6.5-minute Chinese educational video (with real data, voiceover, and screenshots) produced in October 2026. The focus is on pitfalls that official documentation omits and that only hands-on experience reveals.

Full Workflow (Five Steps)

1. Initialization: npx hyperframes init <dir> → requires Node22+, FFmpeg; locally need HYPERFRAMES_BROWSER_PATH=/usr/bin/google-chrome (the engine's automatic download of chrome-headless-shell may fail due to network issues, see pitfalls#1)
2. Structure & Content: Main index.html connects scene sub-comps; archive content materials (real data / screenshots) in scripts/sources.md before placing them on screen — information density is the lifeblood of any explainer video.
3. Animation: One paused GSAP timeline per scene; sentence-by-sentence subtitle system with rhythm highlighting (recipe in references/scene-recipe.md).
4. Validation: npx hyperframes check must be all green before rendering; fix patterns in references/pitfalls.md (90% of errors have pre-written solutions in the manual).
5. Voiceover (optional): Generate with edge-tts → adapt speech rate based on actual measured duration → audio MUST be placed inside the root of the main index (it won't work in sub-comps, see pitfalls#6) → re-render.
6. Quality Check & Delivery: After rendering, run npx hyperframes snapshot to extract keyframes and review each one (visual self-check loop: render → check frames → improve → re-render); use snapshot output for the cover image — no need for a separate tool.

Key commands: preview with --background (hot-reloadable); rendering 365s@1080p takes about 9-10 minutes (5-worker screenshot mode, no local GPU).

When to Read Which Reference

• Any error / rendering anomaly → first check references/pitfalls.md (search by symptom; includes conclusion on the unresolved engine bug with camera transform chains)
• Writing a new scene → references/scene-recipe.md (contains JS template for sentence-by-sentence subtitles, annotation animation patterns)
• Adding voiceover → references/voice-pipeline.md
• Analyzing reference videos (Douyin, etc.) → last section of pitfalls.md "Quantitative Reference Video Breakdown"
• Finding ready-made motion effect blocks / skills in the same domain / voiceover upgrades / Jianyin integration and other external tools → references/ecosystem.md (open-source ecosystem list, includes official capture --video 1:1 reproduction)

Included Scripts

• scripts/inject_subtitles.py — Batch inject sentence-by-sentence subtitles (HTML/CSS/JS in one pass, prevents manual errors)
• scripts/gen_voice.py — Batch generate voiceover via edge-tts + automatically adapt speech rate to scene duration (run with uv run)
• scripts/frame_audit.py — Render frame centroid audit (automatically detects image shift / blank frames, essential for troubleshooting camera issues)

Three Golden Rules

1. Always grep before modifying any scene file: Studio inserts data-hf-id elements; string replacement will silently fail (pitfalls#2).
2. Do not use the large canvas camera approach: The render pipeline misaligns with continuous transform chain driving; verified irreparable across multiple solutions (pitfalls#8). Use only element-level animation.
3. Narrative timeline first: Subtitle timing + voiceover duration determine all animation rhythm; lock the timeline before doing any animation to minimize rework costs.