Communitygithub.com

Sketch Explainer Video

Transform a Chinese voice-over script into a vertical sketch-style explainer video (creamy dot-grid paper, black hand-drawn text, yellow highlighter, red ✓✗?, and line icons drawn stroke by stroke, with MiniMax or Doubao TTS aligned word-by-word and bottom hand-written subtitles, 1080×1920 MP4).

What is Sketch Explainer Video?

This AI agent skill, named 'Sketch Explainer Video,' converts a Chinese voice-over script into a vertical, hand-drawn sketch-style explainer video ideal for platforms like Douyin (TikTok China), WeChat Channels, and Xiaohongshu. It automates the entire production pipeline: generating narration via the user's own MiniMax or Doubao API key, performing word-level alignment for subtitles, orchestrating scene animations, and rendering a 1080×1920 MP4 output. The visual style is distinctive: creamy dot-grid paper background, black hand-written text that appears stroke by stroke, yellow highlighter sweeps, red checkmarks/crosses/icons, and bottom hand-written subtitles synchronized with the audio. The skill is triggered by phrases like 'sketch video,' 'whiteboard animation,' 'note-style voice-over video,' or any request to turn a script into a vertical educational/short video—even if 'sketch' isn't explicitly mentioned. It supports custom voice profiles and parallel batch processing of multiple scripts. It should not be used for editing real footage, digital human lip-sync videos, or PPT conversions. The skill emphasizes careful scene design based solely on the provided script, ensuring all on-screen text comes directly from the script to avoid factual errors, and provides robust checking mechanisms to verify animations, timing, and visual density before final rendering.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/skychentian/sketch-explainer-video/tree/HEAD/skills/sketch-explainer-video

Ask in your favorite AI

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

Documentation

Sketch Voice-Over Video

The final output looks like this: as each sentence is spoken, the visuals are drawn stroke by stroke in real time—characters appear from left to right, keywords are highlighted with a yellow marker, icons are drawn stroke by stroke, and ✓/✗ pop up; each scene conveys a single idea and switches with the narration; a hand-written subtitle line appears at the bottom. Reference image: assets/style-ref.png.

Throughout the process, only the "scene design" requires your creative thinking; everything else is scripted: voice-over, recognition, word-level alignment, engine, checking, and rendering. Follow the steps and do not skip the checking phase.

Prerequisites (Confirm on First Use)

  • The user must have bound either a MiniMax or Doubao API Key. If neither is bound, stop and guide them through the application steps below for the user to bind themselves. Do not generate or ask for the Key directly.
  • coli (local speech recognition), ffmpeg, node/npx, python3
  • macOS: Automatically uses the system's built-in "Hannotate SC" font; other systems: provide --font path/to/a-chinese-handwriting-font.ttf
  • The first run will install fonttools in ~/.cache/sketch-explainer-video/venv
  • Checking and rendering always use [email protected]

Binding the Voice-Over Service

Guide the user to bind only these two services. If neither is bound, stop and let the user follow the steps:

  1. MiniMax (default; use this one if both are bound): Open https://platform.minimax.cn , go to "Account Management → API Keys" to create an API Key. For the international site, use https://platform.minimax.io and set MINIMAX_API_HOST=https://api.minimax.io. Then run bash <skill>/scripts/bind_tts.sh minimax.
  2. Doubao Voice: Open https://console.volcengine.com/speech/new , create an API Key, and activate the "Doubao Voice Synthesis Model 2.0". Then run bash <skill>/scripts/bind_tts.sh doubao.

The key won't be displayed during input, remains only on the local machine, and should not be pasted into the conversation. For pricing and voice profiles, see references/tts.md. After binding, proceed to create the project. If an MP3 file already exists, use --audio and do not re-synthesize. To specify a provider, use --provider minimax or --provider doubao.

Process

1. Create Project (Voice-Over + Alignment in One Step)

<skill>/scripts/new_video.sh <project-directory> <voiceover-script.txt> --title "Video Title"
  • The script must be provided verbatim as a .txt file. The script reads the original text and aligns it using local speech recognition.
  • If a voice-over file already exists, do not regenerate it: use --audio existing.mp3.
  • At the end, check the output for matched x/y: ≥95% is normal (mismatches are often homophones, which don't affect the result); significantly lower means the voice-over and script are not from the same source.
  • Outputs: sentences.txt (start time for each sentence), assets/timing.js, index.html (engine is ready, has <!--SCENES--> placeholder).

Voice profiles (--speaker): MiniMax default is Chinese (Mandarin)_Gentle_Senior, can also use Chinese (Mandarin)_News_Anchor, Chinese (Mandarin)_Gentleman. Doubao default is zh_female_xiaohe_uranus_bigtts, can also use zh_female_vv_uranus_bigtts, zh_male_m191_uranus_bigtts. Do not pass ListenHub voice IDs.

2. Write the Storyboard (STORYBOARD.md)

Read sentences.txt and divide the entire video into 8–13 scenes, each lasting 6–16 seconds:

  • Scene cuts = start time of a sentence − 0.15 seconds; the first scene starts at 0; the last scene ends at the data-duration attribute of the root element in index.html (= voice-over end + 1 second); adjacent scenes must be strictly contiguous.
  • Each scene should be a single sentence explaining "what this frame is about," paired with a main visual. Write as a table: Scene | Start-End Seconds | Visual Content | Anchor Phrase.
  • Long sentences (>16 seconds) can be cut mid-sentence; the cut point takes the time of that character − 0.15.

3. Write the Scenes

First read references/components.md (component library: title group, chapter capsule, chain, comparison, ≠, checklist, steps, calendar, room overlay, closing, icons). Then, pick the closest complete example and read it:

  • references/examples/event-overview.html — Event timeline / Fact-based chapters
  • references/examples/relationship-chain.html — Relationships / Supply chain
  • references/examples/step-checklist.html — Step-by-step / Practical checklist

Then insert all <section> elements into index.html at the <!--SCENES--> placeholder. The scenes must be designed specifically for this script: examples are for learning the syntax only; do not copy scenes from other video projects on the local machine—they correspond to different scripts and timings, and copying will cause the anchors and rhythm to be completely wrong, effectively doing nothing. Do not modify the <script> engine; add new styles at the end of <style>.

How to declare animations (the value is the phrase from the script; the engine finds it after data-from and starts the animation when that character is spoken):

AttributeEffectApplied To
data-wLeft-to-right hand-drawn revealBlock elements, or span with class="ib"
data-dDraw all lines stroke by stroke; data-dur adjusts seconds per stroke<svg>
data-hHighlighter sweepElement with class="hl"
data-pPop in (✓✗?≠, chapter capsule)span with .ib
data-f / data-dimFade in / DimAny block

Value syntax: "phrase" · "phrase|-0.4" (0.4 seconds early) · "@0.2" (0.2 seconds after scene start).

Scene Principles (and Why)

  • Text on screen can only come from the voice-over script. You can abbreviate (e.g., turn "none of them" into "0 of them"), but cannot add facts, numbers, or brand judgments not in the script—these videos often involve real brands and controversies, and one extra sentence on screen can cause factual errors.
  • Appear one by one, following the speech: Elements should be anchored to the corresponding words. If everything appears at the start, the audience will read ahead and lose focus.
  • The last animation must finish ≥0.5 seconds before the scene cuts away: Otherwise, the highlighter/✓ will be cut off immediately after appearing, rendering it useless. Elements anchored at the end of a sentence are particularly prone to this—move the anchor earlier.
  • Content only occupies the top 120–1480px: The area below is reserved for the subtitle strip and Douyin bottom UI.
  • Scenes must be full and visual: Content should fill the vertical area from 150–1400px (main visual scaled to 60–85% of the scene width). Each frame must have at least one graphic element (icon/box/comparison/chain/diagram) — avoid just a few lines of small text crowded in the top half of the screen; on mobile, half-empty screens look cheap and convey insufficient information. check.py will flag scenes with an empty bottom half.
  • Style discipline: Black lines + yellow highlighter + minimal red; red is only used for ✓✗?≠, circles, and warning words. No emojis, photos, logos, or portraits.
  • Subtitles: Sentences longer than 16 characters must have line breaks defined in assets/cap_breaks.js: window.CAP_BREAKS = ["phrase to start a new line from", …], breaking between words (colons are not automatic break points—long sentences with colons especially need manual breaks). check.py will list sentences that need breaks.

4. Checking (Run Repeatedly Until All Pass)

<skill>/scripts/verify.sh

This sequentially performs: font subset → check.py (checks anchor existence, animations at end of scenes, scene continuity, subtitle length, encroachment into subtitle area) → hyperframes lint/check → screenshots (1.2 seconds after each scene start + 0.4 seconds before end) → density.py (measures how far down the content extends at the end of each frame; <1000px is considered half-empty, too many such frames cause failure).

  • All failures from check.py and density.py must be fixed: the former calculates based on the engine's actual timing, the latter measures from screenshots—both are non-negotiable findings.
  • Open snapshots/contact-sheet*.jpg and visually inspect each screenshot: look for overlapping, elements outside frame, wrapped text crowding other characters, unrecognizable icons, large empty areas. The script cannot detect "it's hard to understand"—only you can. Fix and re-run verify.
  • nested_structure / track_too_dense warnings from lint can be ignored.

5. Render and Deliver

<skill>/scripts/render.sh      # → renders/video.mp4, approximately 2–4 minutes

When delivering, state: output path and duration, number of scenes, contact sheet path, what you fixed during self-review, and which on-screen text is your summarization (not original quote).

Common Pitfalls

IssueCause → Solution
Engine reports "phrase not found" / check reports phrase not foundPhrase must match the script verbatim (including spaces like 9 月中旬 and full-width punctuation); must appear after data-from
Element doesn't reveal with hand-draw effectdata-w placed on a regular inline span → add class="ib"
Long text wraps into two lines overlapping belowReduce font size or add white-space:nowrap, or split into two blocks
All elements appear at scene startThe anchor phrase matched earlier in the script → replace with a unique phrase within this scene
Creating projects for multiple videos simultaneouslyIt's fine to run in parallel; the recognition script has a built-in queue lock

Batch Processing Multiple Videos

See references/batch.md: Collect scripts uniformly → generate voice-over in parallel → create individual projects → assign one sub-task per video for scene writing → unified review → delivery.

Related Skills