insaneyilin/html-video-demo

HTML Video with Local Narration

Deliver a playable MP4, subtitles, a modifiable HTML storyboard, and generation configuration. All work is based on the user's current project, assets, chosen voice, and style; these scripts do not bind to any AI agent, account, or model service API.

Before Starting

• Read the target project description, existing video output, and local working conventions to confirm actual functionality and demo scope. Do not present planned features as already implemented interfaces.
• Designate a dedicated video project directory, ensuring original code, production data, and previous outputs remain recoverable. When modifying an existing video, first read the latest configuration and back up relevant outputs.
• Reuse previously confirmed voices. When selecting a new voice, prefer listening to identical short scripts at equal loudness for auditioning; no need to repeatedly ask the user to confirm an already chosen option.
• On first run or when switching machines, read Environment & Commands. The TTS implementation in this package requires Apple Silicon / MLX; the Node rendering entry point is independent of TTS.

Production Workflow

1. Determine Content. Structure the operations the viewer needs to understand into a cause-and-effect storyboard. Each scene conveys one main piece of information; narration is conversational, and the screen retains key text. Decide on the number of scenes and total duration based on content, not a fixed nine-scene or two-minute template.
2. Prepare Real Assets. Capture interface screenshots, partial screen grabs, or actual interactions using demo data. Follow the current agent and project requirements for browser control. Read Visuals & Assets; do not reuse screenshots, personnel information, or internal addresses from other projects.
3. Determine Voice. Configure voice, style, and language in project.json; first listen to a short sample of a new voice, then batch generate. Form bounded narration groups from adjacent semantic paragraphs, using the same voice, style, and sampling parameters. Do not randomly change seeds per sentence, nor default to infinitely long concatenation of the entire script. Grouping principles are in Narration & Alignment.
4. Review Content and Timing. Use independent ASR to find missing or repeated sentences, then use forced alignment to locate the original script. These serve different purposes: alignment provides timestamps but does not prove the actual spoken text is correct. Check homophones, English terms, and the final few words.
5. Arrange Visuals According to Voice. Split scenes at natural pauses, ensure the last word finishes completely, and leave a suitable end time for the content. A default of about one second is a good starting point for technical explanations. Local emphasis and action recording follow speech tags, not fixed-length defaults from earlier versions.
6. Render with html-video. First check HTML for dropped frames, then export via ContentGraph, ProjectOrchestrator, and Hyperframes. External resources should be localized or embedded; animations use window.__hvPlayAll(), avoiding playback before fonts have loaded. See protocol in Visuals & Assets.
7. Verify the Final Video. Fully decode the MP4, check audio and video durations, and examine the audio track at each scene cut point. Then check browser playback, seeking, and visuals. Checking only the WAV or subtitle files is insufficient to prove the final video is correct. After verification, provide local preview, MP4, subtitles, and source files.

Executable Entry Points

All paths are provided via parameters. See full fields in Project Format. Below, SKILL_DIR refers to this skill's directory, and DEMO_PROJECT refers to the independent video project:

python "$SKILL_DIR/scripts/audio.py" init --project "$DEMO_PROJECT"
# Edit project.json, prepare assets/; run audition first if needed.
python "$SKILL_DIR/scripts/audio.py" validate --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" synthesize --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" check-text --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" align --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/compose.mjs" --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/verify.mjs" --project "$DEMO_PROJECT" --stage scenes
node "$SKILL_DIR/scripts/render.mjs" --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/verify.mjs" --project "$DEMO_PROJECT" --stage export
node "$SKILL_DIR/scripts/serve.mjs" --project "$DEMO_PROJECT"

Node rendering, browser inspection, and screenshot commands locate the installed html-video via HTML_VIDEO_ROOT or --html-video. Use Python in an isolated environment; do not install dependencies into the system Python.

Modifications and Troubleshooting

• Script changes: Re-synthesize the affected groups, then verify, align, build, and render. Image or layout changes: Rebuild, check scenes, render. Voice changes: Go through the entire voice and timing workflow again.
• Voice reaching token limit or producing repeated output: Shorten the problematic group, preserving already verified groups if possible. Do not deliver incomplete results as successful; if repeated failures occur, keep diagnostics and usable assets, and explain the specific blocker.
• Incomplete final syllable: Debug in the order "original synthesis → decode length → normalize → concatenate → MP4". Appending silence cannot recover syllables already clipped. The current script only activates a local correction when abnormal length is detected for Qwen3-12Hz without padding; it does not modify third-party installation directories. Read Syllable Tail Regression and Audio Troubleshooting.
• Do not turn the voice, color palette, scene count, or library defects of this particular run into fixed requirements for all future tasks. If using a different TTS or existing recorded narration, keep the same timing, sample, and export verification constraints.
• Publishing the final video to external platforms, uploading business assets, or notifying others is not part of the default local production steps; follow the user's explicit authorization.