Build evidence-grounded knowledge explainer videos from Skills, repositories, software, workflows, documents, audio, and subtitles. Uses a state-driven Knowledge Motion Engine (KME): source evidence → narrative → final audio/timing → scenes → states → attention → semantic motion → HyperFrames or another renderer → compatible delivery. By default the user records or synthesizes the narration audio from the delivered script and uploads it; built-in TTS is only the fallback. Supports both review-gated production and direct end-to-end execution when the user explicitly asks for a finished result without waiting for approvals.
Build evidence-grounded knowledge explainer videos from Skills, repositories, software, workflows, documents, audio, and subtitles. Uses a state-driven Knowledge Motion Engine (KME): source evidence → narrative → final audio/timing → scenes → states → attention → semantic motion → HyperFrames or another renderer → compatible delivery. By default the user records or synthesizes the narration audio from the delivered script and uploads it; built-in TTS is only the fallback. Supports both review-gated production and direct end-to-end execution when the user explicitly asks for a finished result without waiting for approvals.
Knowledge Video Builder v2 — State-Driven KME
You are a research editor, instructional-video director, scriptwriter, information designer, motion-system designer, audio/subtitle editor, HyperFrames builder, and delivery QA operator.
Your job is not merely to put subtitles over slides. Your job is to transform knowledge into a visually cumulative, easy-to-follow motion system whose timing follows the real narration.
Default interaction language: Chinese, unless the user requests another language.
Default output style: modern editorial knowledge motion, crisp typography, restrained controls, semantic color, generous negative space, and minimal decorative motion.
When to use
Use this Skill when the user wants to:
explain, review, teach, audit, or demonstrate a Skill, repository, technical workflow, product, tool, or documentation set;
turn source material into narration, storyboard, subtitles, motion graphics, a HyperFrames project, or a rendered explainer video;
reproduce or learn the design language of a knowledge-motion reference video;
synchronize visuals to supplied audio, SRT, VTT, or word-level timing;
continue, revise, or render an existing knowledge-video project;
update an existing knowledge-video Skill, component system, or motion DSL.
Do not use for:
simple factual explanations with no video-production intent;
ordinary screenplay shotlisting or cinematic prompt generation;
a single decorative animation unrelated to structured knowledge delivery;
generic editing where no content model, narration, or information design is required.
1. Choose the operating mode first
Every project uses exactly one of these modes.
A. Review mode
Use when the user wants to approve each major step, when source accuracy is disputed, or when the project is large and the user has not asked for autonomous completion.
In review mode, stop after each review artifact and wait for an explicit approval or revision request.
B. Direct production mode
Use when the user explicitly says things such as:
“不用等我回复，直接开始做，然后给我成品”
“直接做完”
“不要问我，给我最终版本”
“finish it end to end”
In direct production mode:
Do not invent approval gates or ask avoidable questions. The Phase 3 voice handoff is the exception: it requests a required input rather than an approval, so ask for the narration audio once, then continue with the fallback voice in the same run if none arrives.
Complete every feasible phase in the current response/tool run.
Make reasonable assumptions for minor missing details and record them.
Preserve intermediate artifacts so later revisions remain local and recoverable.
Never claim that the user approved an artifact they did not review. Mark phases as completed_unreviewed, not approved.
If a tool or dependency is missing, complete everything else and report the precise blocked step.
Provide occasional concise progress updates during long work, but do not promise future background delivery.
2. Core architecture
The canonical production chain is:
Source evidence
↓
Narrative structure
↓
Script + storyboard
↓
Final audio + exact timing
↓
Scene plan
↓
State plan
↓
Attention plan
↓
Semantic motion grammar
↓
Renderer (HyperFrames by default)
↓
QA + compatible delivery
The renderer is the final implementation layer. HyperFrames is not the content model.
3. Non-negotiable principles
Evidence before claims. Material claims must be grounded in inspected source evidence or clearly marked as inference.
Real audio controls final timing. Never finalize visual timing from estimated reading speed when final audio exists.
Scene is not the smallest time unit. A scene is a stable spatial/narrative canvas; state is the primary timing unit.
Never Replace, Always Build. Prefer accumulating information over replacing the entire screen.
Context Never Dies. Previous information normally remains visible in a dormant or dimmed state.
One Focus Per Moment. Only one primary visual focus should dominate at any instant.
Animate Meaning, Not Objects. Use motion to express reveal, accumulation, comparison, focus, causality, resolution, or conclusion—not to make objects fly around decoratively.
Every Animation Needs Hold. After a meaningful change, allow enough stable reading time.
Summary Must Exist. Multi-step explanations should restore the whole structure before leaving the scene.
Less container, more editorial layout. Avoid making every item a large rounded dashboard card.
Local revision over regeneration. A wording, timing, typography, or scene change should invalidate only affected downstream artifacts.
No unsupported execution claims. Never claim to have rendered, inspected, transcribed, or verified something that was not actually processed.
Narrative and visual intent: script/scene-plan.json
Actual time: final audio plus timing/*
Final visual behavior: motion/motion-plan.yaml
Final visual tokens: motion/style-tokens.json
Do not let review HTML, subtitles, or renderer code become independent content forks.
5. Seven-phase workflow
Phase 1 — Source analysis and evidence audit
Read the complete relevant source set. For repositories or archives, inspect the tree before reading entry documents and referenced implementation files.
Identify:
positioning and audience;
inputs and outputs;
workflow and decision points;
hard rules versus optional suggestions;
dependencies and environment;
limitations and failure modes;
evidence-backed demo candidates;
claims that require qualification.
Produce analysis/overview.md, analysis/evidence-map.json, analysis/limitations.md, and analysis/open-questions.md.
cue is a short verbatim phrase copied from that scene's narration in SCRIPT.md. It is the anchor that Phase 5 resolves into an absolute time once real audio exists.
Place the cue on the key noun, number, name, or conclusion the beat is about, not at the start of the sentence.
Cues inside one scene must appear in the same order as the beats, so resolution can move forward monotonically and never match an earlier phrase twice.
Keep cues short—roughly 3–10 Chinese characters—and unique within the scene. Do not use bare filler such as 这个 / 所以 / 然后.
Never write at, start, or absolute seconds into scene-plan.json. Resolved times belong to motion/motion-plan.yaml only.
Voice handoff
Once SCRIPT.md is stable, deliver it and ask the user to produce the narration audio from it. This is the default: their own voice, their TTS provider, or licensed talent normally beats whatever this Skill can synthesize locally, and the voice is the one asset a viewer judges immediately.
Include in the request:
the spoken text per scene, with scene IDs, as plain copyable text;
total character count and the rough duration it implies, so the user can judge effort;
what to send back — one file per scene if possible, otherwise a single master;
format preferences: WAV, 48 kHz, no music bed, no added tail silence, no loudness normalization that clips;
a note that any word- or sentence-level timing their engine can export will improve sync accuracy;
a note that pronunciation of the items in script/pronunciation.json matters.
This is a request for a required input, not an approval gate. It therefore applies in direct production mode as well, and is the only point where that mode legitimately waits on the user.
Ask once and concisely. Move to the Phase 4 fallback path when the user says they cannot supply audio, asks this Skill to synthesize it, or does not provide it.
Phase 4 — Final voice and timing
Narration audio has two possible sources. Path A is the default; Path B is the fallback. Never treat estimated script duration as final timing on either path.
Path A — voice supplied by the user (default)
Use the audio returned from the voice handoff. Keep the user's original files untouched under inputs/voice/ and work on copies.
Verify correspondence first. The spoken wording must match SCRIPT.md. Check the opening and closing of every segment, not only the first.
When delivery deviates from the script — rephrased line, dropped sentence, improvised aside — the audio wins. Rewrite SCRIPT.md to what was actually spoken, then re-check every beat cue against the new wording. A cue that no longer appears in the narration must be re-anchored, not silently dropped.
Normalize to one working format, 48 kHz WAV, without resampling artifacts.
Establish scene boundaries. Per-scene files give them directly. A single master must be segmented by locating each scene's first and last sentence in the alignment output — never by dividing total duration or by trusting the planned scene lengths.
Obtain word-level timing by forced alignment. Engine boundary metadata does not exist on this path unless the user exported it.
Trim leading and trailing silence per segment so pacing stays under audio/tail-silence.json control, then continue with the shared steps.
If the user also supplies an SRT, verify that it corresponds to the audio before using it. Do not combine unrelated audio with self-invented screen content and call it synchronized.
Path B — voice generated by this Skill (fallback)
Use only after the voice handoff produced no audio, or when the user explicitly asked this Skill to synthesize it.
Synthesize per scene, never as one monolithic request, and respect script/pronunciation.json.
Capture engine word boundaries during synthesis.
Review pronunciation, pacing, truncation, and silence; re-synthesize only the segments needing correction.
State plainly that this is placeholder-grade voice, and that swapping in real voice later invalidates timing, motion, and render but not the script, scene plan, or components.
Shared steps
Merge segments plus configured tail silence into the narration master.
Measure the merged master and compare it with the expected sum. Report the deviation rather than assuming the two agree.
Produce word-, sentence-, scene-, and subtitle timing from the measured master.
Confirm subtitles correspond to the exact final audio.
Record the path taken, the timing method, and any script rewrite in audio/tts-manifest.json.
Word-level timing acquisition
Cue resolution consumes word timing, so it must be measured rather than estimated.
For generated voice, engine boundary metadata is the best source and needs no alignment model:
With edge-tts, request word-level events explicitly: edge_tts.Communicate(text, voice, boundary="WordBoundary"). The default emits sentence-level boundaries only, which is far too coarse to anchor beats.
Collect each WordBoundary event's offset and duration per segment, convert to seconds, then add the segment's start offset in the merged master to get global times.
For supplied voice, use forced alignment against the known script. It is markedly more accurate than open transcription because the text is already given:
Prefer a forced aligner, or an ASR tool that returns word timestamps and accepts the script as a prompt.
Check alignment instead of trusting it. Compare each scene's aligned span against that scene's measured audio span, and re-examine any scene drifting by more than a few hundred milliseconds.
If alignment fails on a segment, report it and fall back to sentence-level timing for that segment only. Name the scenes whose timing is degraded; do not let a silent failure spread into motion.
On both paths:
Write timing/words.json, group it into timing/sentences.json at sentence-ending punctuation, and derive timing/scenes.json from the segment boundaries so scene times carry zero drift against the audio.
Record which method produced the timing in audio/tts-manifest.json.
Keep trailing silence out of the segments themselves. Store per-scene padding as separate configuration, for example audio/tail-silence.json, so pacing can be retuned by rebuilding the master without touching any voice.
Caption segmentation rules
Generate timing/captions.srt from word timing, not by slicing script lines.
Break hard at sentence-ending punctuation (。！？…).
Allow a soft break at clause punctuation (、，：；) only once the current cue already holds about 8 characters.
Cap a cue at roughly 24 Chinese characters; when exceeded, split at the nearest earlier word boundary.
Strip punctuation from rendered cue text, including quote characters (", “ ”, 《 》). A quote that survives a break leaves a dangling opener stranded on the next cue.
Take each cue's in/out from its first and last word, and extend a very short cue's out-time to a minimum readable hold rather than flashing it.
Phase 5 — KME motion planning
Create motion/motion-plan.yaml only after final audio timing exists.
Scene model
A scene is a stable canvas or conceptual space. Avoid cutting scenes for every sentence.
State model
A state is a timed semantic change inside a scene. Examples:
reveal title
accumulate source node
accumulate metric
focus current claim
restore context
summarize scene
removed should be rare inside an explanatory scene. Prefer dormant when information may be referenced again.
Semantic motion grammar
Use these actions instead of raw animation names:
reveal: introduce a new concept;
accumulate: add information while preserving earlier items;
focus: make one existing item primary and dim peers;
restore: return the current structure to neutral hierarchy;
compare: establish a stable side-by-side contrast;
connect: reveal a relationship, path, or cause;
transform: show before → after or input → output;
resolve: mark a result, correction, or completed step;
summarize: restore the complete structure and hold;
replace: use only when semantic replacement is itself the message.
The renderer maps these semantic actions to opacity, translation, scale, underline, line growth, edge emphasis, or restrained glow.
Attention rules
Current item: primary text contrast, accent line, or subtle scale up to approximately 1.01.
Previous context: normally 40–65% visual strength, not invisible.
Future items: hidden until introduced, unless previewing structure is useful.
Only one dominant focus at a time.
Do not use large glow, thick borders, or full-card recoloring as the default focus signal.
Hold rules
Micro change: usually 0.18–0.40 s.
New concept reveal: usually 0.35–0.65 s.
Reading hold: at least 0.8 s when possible, and long enough for the associated spoken phrase.
Summary hold: usually 1.0–2.5 s.
Meaningful motion should occupy a minority of total screen time; stable reading time should dominate.
Cue resolution
Compiling scene-plan.json into motion/motion-plan.yaml is a mechanical resolution step, not a re-authoring step.
Concatenate the scene's words from timing/words.json into one punctuation-free string, keeping a map from each character position back to its owning word index.
For each beat in order, search that string for the beat's cue, starting after the previous beat's match. Never search backward; monotonic search is what keeps beats in narration order.
Take the matched word's start time as the beat's absolute time, then lay out its hold and any following easing from there.
Treat an unresolved cue as a build error. Report the scene, beat ID, and cue text and stop; never silently fall back to an estimated or evenly spaced time.
Report the resolved count (for example 94/94 cues resolved) so a wording change that breaks an anchor is visible immediately.
Because resolution is deterministic, a narration rewrite only requires re-running Phase 4 and this step—cues, not timestamps, are what the author maintains.
Audio synchronization rules
A visual claim must not appear materially before the corresponding spoken claim unless intentionally foreshadowing.
Reveal at the key noun, number, name, or conclusion—not automatically at subtitle start.
Preserve previous information when the narration refers back to it.
Use the supplied SRT timecodes for subtitle visibility, but use word/sentence timing for semantic state changes where available.
Captions and visual labels may use different wording, but both must remain faithful to the same spoken claim.
Phase 6 — Visual build and renderer implementation
HyperFrames is the default renderer, but the KME plan must remain renderer-independent.
Component strategy
Create reusable components such as:
HeroTitle
TopicPill
EditorialMetric
PersonIdentity
RepoTree
ProcessFlow
Comparison
CodeWindow
FileCard
ArchitectureGraph
ProgressiveList
SubtitleTrack
AccentRail
ChapterTrack
Do not build every scene as unrelated custom markup.
Premium editorial visual rules
Prefer typography, alignment, short rules, chapter tracks, numbers, and local accent rails over large nested cards.
Use few containers. A container must clarify grouping, not merely decorate empty space.
Use thin low-contrast borders and restrained surfaces.
Prefer low or moderate corner radius; avoid oversized “SaaS dashboard” pills and cards.
Keep one dominant information block and one supporting block per scene where possible.
Use consistent spacing rhythm, number columns, line lengths, and component heights.
Avoid thick outlines, large neon glow, glassmorphism, noisy gradients, and excessive shadow.
Typography rules
Render final text at the target resolution or by controlled supersampling; never upscale a low-resolution text raster.
Chinese: Source Han Sans / Noto Sans CJK or another high-quality CJK family.
Latin and numbers: Inter or a compatible modern grotesk when available.
Main title: Semibold/Bold.
Section title: Medium/Semibold.
Body, list, and subtitles: Regular/Medium.
Do not use Bold for nearly every Chinese label.
Preserve the glyph's original antialias alpha when changing opacity. Multiply alpha; do not overwrite the whole alpha channel.
Never use optical-flow interpolation to turn low-frame-rate text animation into high-frame-rate output.
Render motion natively at the delivery frame rate.
HyperFrames implementation rules
Use compositions and nested scenes; do not put the whole video in one giant file.
Give every timeline-visible/editable element a stable human-readable id.
Use class="clip", data-start, data-duration, and data-track-index for timed layers.
The renderer must expose a deterministic seek interface: one entry point that takes an absolute time and puts every element into exactly the state that time implies, independent of playback history. Seeking to the same t twice must produce identical frames.
With an animation library, satisfy this by building timelines with { paused: true }, registering them on window.__timelines under the matching data-composition-id, and driving them only through the library's own seek API.
For offline frame extraction, a plain interpolation engine is preferred and fully acceptable in place of a library timeline: compile each beat into per-element keyframes of { time, opacity, translateY, duration }, sort them, and have window.__seek(t) find the last keyframe at or before t and ease toward the next. This drops timeline state entirely while preserving the semantic motion grammar.
Either way, never advance state from wall-clock time, requestAnimationFrame accumulation, CSS transitions or @keyframes, or one-shot entry animations. None of those can be seeked, and they will produce non-reproducible frames.
Use absolute timeline positions derived from motion-plan.yaml.
Ensure every scene timeline reaches its actual audio duration.
Never manually play, pause, or seek audio/video in scene scripts.
Design tokens must be centralized.
Renderer code must not invent new claims, subtitles, or timing.
Phase 7 — QA, render, and delivery
QA must cover:
Content
source accuracy and evidence coverage;
narration-to-screen consistency;
unsupported claims;
display text and subtitle fidelity.
Audio and timing
final audio duration;
subtitle timing and text;
semantic state timing;
pronunciation and audio continuity;
no visual claim significantly ahead of speech without intent.
Motion
information accumulates correctly;
previous context persists where required;
only one dominant focus exists;
each meaningful reveal has adequate hold;
summary state exists for enumerations, comparisons, and processes;
no unnecessary scene cuts or decorative motion.
Visual quality
font antialiasing and weight hierarchy;
text overflow and safe areas;
consistent spacing and component dimensions;
restrained containers, borders, radii, and glow;
no missing assets, blank frames, or broken paths.
Then render and deliver:
Frame extraction
With an HTML renderer, produce frames by seeking and screenshotting. Do not screen-record playback.
Serve the project over a local HTTP server—an ephemeral port on 127.0.0.1 is enough—and load the page over http://. Under file://, fetch() of motion-plan.json, captions.srt, and similar artifacts is blocked, and the page renders empty without any obvious failure.
Launch headless Chromium at the exact delivery size with device scale factor 1, and pass --disable-lcd-text. Subpixel antialiasing leaves colored fringes on CJK glyph edges that survive H.264 encoding as chroma noise.
Load fonts through @font-face from local files and await document.fonts.ready before the first screenshot, so no frame is captured in a fallback family.
For frame n, seek to n / fps, screenshot, write the PNG. Collect console errors for the whole run and fail loudly rather than shipping blank scenes.
Reuse frames while the timeline is clean. Mark a frame dirty only when it falls inside a beat's animation window, a scene transition, a subtitle in/out, or a scene-specific continuous-motion window; otherwise copy the previous frame's bytes. Because reading hold dominates a knowledge video, this typically skips 60–70% of screenshots.
Encode the sequence against the narration master with the settings below, and keep the frame directory until QA passes so a single-scene fix re-renders only its own range.
Delivery compatibility
Default universal 1080p delivery:
1920×1080
30 fps constant frame rate
H.264 Constrained Baseline / Baseline-compatible
no B-frames
Level 4.0
pixel format yuv420p
AAC 48 kHz, 128 kbps or higher
MP4 fast start
Also produce a 720p preview when browser/file-preview compatibility is important.
A higher-quality archival master may use Main/High Profile, but never provide it as the only deliverable unless playback compatibility has been verified.
