Communitygithub.com

HTML Video Demo with Local Narration

Create and modify software demo or technical explanation videos with narration and subtitles using html-video and local Qwen3-TTS, including real interface capture, storyboarding, voice preview, subtitle alignment, and final export verification. Suitable for producing demos from project docs or existing products, and for fixing tail-end truncation, tonal jumps between segments, and scene transition desync.

What is HTML Video Demo with Local Narration?

This skill enables an AI agent to produce professional-grade software demo videos with localized narration and subtitles entirely on the user's machine, without requiring any cloud API or external service. It integrates the html-video rendering framework with a local Qwen3-TTS engine (Apple Silicon/MLX) to generate voiceovers, align them with subtitles, and compose the final MP4 output. The workflow is centered on a structured process: determine content and storyboard, prepare real on-screen captures, select and preview voices with consistent acoustic parameters, validate text and timing via ASR and forced alignment, compose scenes respecting natural pauses, render through html-video, and thoroughly verify the final video. The skill supports iterative modifications for script changes, image/layout updates, and voice swaps, with specific troubleshooting guidance for common issues like token limits, output repetition, and tail-end syllable truncation. It explicitly avoids bundling any AI agent, account, or model service API, making it suitable for local, private, and repeatable video production.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/insaneyilin/html-video-skills/tree/HEAD/skills/html-video-demo
View original→Browse all skills

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentation

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.

Related Skills

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community