web-video-presentation

Web Video Presentation

Skill version 2.7.0(synced from manifest.json). When starting a task, first report the version number to the user — the skills CLI does not provide update notifications, so this is the only way users can tell which version they have and whether they need to reinstall.

Sound tells the details; visuals let the audience see relationships and changes.First design "what happened to what," then arrange the text. A premium feel comes from clear hierarchy, credible material, coherent space, and precise motion; the number of animations, cards, and lines of code does not equal quality.

Which one to read first

Work	Read
Planning, SRT, facts	PLAN-FORMAT.md
Composition, shots, MG, chapter development	CRAFT.md
Audio clock, addressable animation	MOTION.md
Browser acceptance, controlled experiments	EVALUATION.md
Recording and delivery	RECORDING.md

Voiceover skill handoff

When you only have the copy and a reference recording, first use the installed voice-clone-tts to generate the final WAV, SRT, and voiceover.json. Do not regenerate the audio after web chapter development has begun.

node <本技能目录>/scripts/import-voiceover.mjs <voiceover.json> <presentation目录>

The importer validates the file, PCM duration, and subtitles, copies them to public/audio, and generates voiceover-input.json. Organize shots according to the cues in it; the same scene can span multiple cues/steps, and the importer will not invent a visual plan for you. The srt path in plan.md is relative to the plan file, and the audio path is relative to public/. Use the exact duration of the WAV in the manifest.

1. Plan with real pacing

• VO-First: If you already have a recording and SRT, use the final version; order by time, not by subtitle number. Keep the original audio intact, copy it to presentation/public/audio/, and do not modify the original.
• TTS: If you only have an article, keep article.md, and write SCRIPT-STYLE.md according to script.md. First do a small amount of voiceover to establish pacing; after the full segment is synthesized, lock in the precise animation. Don't wait until all the animation is done to discover that the audio doesn't fit. For synthesis methods, see AUDIO.md。
• First check the user's past projects, screenshots, brand assets, and preferences. The topic is only a starting point; dynamically read themes/*/theme.json; if the user asks you to choose, state your choice and move forward. For new topics, see THEMES.md。
• Write a plan.md, at the same level as presentation/ .timeline manages time and the original text; chapter notes manage shots, evidence, and shared visual conventions. The generated BRIEF and acceptance results are not a second manual plan.
• A step is a change in voiceover focus; a scene is a continuous visual space. Changes to the same object can persist across multiple steps. Cut shots only when the topic changes, the location changes, or emphasis is needed; do not change the screen for every sentence.
• The same Step can contain multiple action beats: continue advancing according to the actions, turns, and results in the voiceover, and the action score records each beat's start point, duration, and visible landing point; for detailed methods, see CRAFT. Do not turn a longer stretch of voiceover into just one entrance followed by a long freeze.
• For each shot, write clearly: the subject, initial state → action → final state, on-screen phrase, corresponding cue, and how it connects to the previous and next shots. Key causality/comparisons need to be performed; a single line like "make premium MG" is not enough to start work.
• Verify the facts and materials to be presented. When evidence is lacking, use clearly labeled mechanism illustrations or omit the item; simulated UI must not be passed off as actual screenshots.

First produce a representative 15–30 second samplepreferring the hardest explanation/comparison segment, and validate it together with the entry and exit, forming a reusable visual composition, typography, object scale, and motion language. Do not just pick titles that are easy to make look pretty. When user authorization has been obtained, proceed autonomously through the checkpoint; when the style needs the user's decision, provide a playable sample and specific differences before asking, and do not set up a fixed four-part question of theme/parallelism/anchor. Clarify separately any factual conflicts that genuinely affect the framing.

2. Build the stage, reuse the reliable parts

bash <skill>/scripts/scaffold.sh ./presentation
cd presentation
npm run dev   # 立即体验默认模板；准备好 ../plan.md 后再 npm run gen

• The default template is the 01-pipeline complete continuous scene: creator-dark theme, 6 voiceover segments, 21 action beats, including object pairing/convergence, waveform track splitting, timestamp placement, card generation, relationship transfer, focus advancement, and delivery transitions. The homepage directly interacts beat by beat,?auto=1 silent continuous playback; usage and replacement paths are in STARTER.md. The theme can be changed via --theme=<id> .
• Distinguish the two layers; they are written in opposite ways, do not conflate them：
  • Content layer — must be rewritten: the six segments of copy, the specific arrangement of the 21 beats,01-pipeline shots and materials all belong to this demo's own content; rewrite them according to your voiceover, do not copy them verbatim, and do not treat them as a fixed quota. Default illustrative waveforms/times cannot serve as actual measured evidence.
  • Visual language layer — must be inherited: object identity and handoff methods, card texture, focus advancement techniques, intra-sentence action density, transition quality. If new chapters and the template do not look like they come from the same source, it is not done.
  • When unsure about the boundary, judge by CRAFT's shot selection table :technique(how to make relationships visible) is inherited,subject matter(what is being discussed this time, what materials are used) is rewritten.
• 01-pipeline/ Keep it as a visual reference, do not delete the directory. Just sync src/registry/chapters.ts to register the new chapter and remove previewTiming — what is removed is the registration, not this implementation. It is the only same-source reference; if deleted, there is no second copy to compare against. For specifics on how to inherit, see STARTER.md（notread through chapter.tsx and copy by hand).
• Check the version first for old projects: old gen does not recognize srt/scene/screen, and old App does not pass time either; follow MOTION's old project migration to upgrade in a copy before using the new fields.
• gen By default reads ../plan.md; generates timeline, chapter narrations, BRIEF. When srt: is present, also generate accurate cue data timing.ts, no longer copying times repeatedly for each chapter.
• narrations.ts If it already exists, it will be preserved; changing the step count requires syncing the file or backing up and regenerating. Do not assume rerunning gen will overwrite it.
• In App.tsx set AVATAR_CORNER and SUBTITLE_SAFE, and write the configuration into the planned whole-film conventions.
• Prefer reusing src/motion/ 's time sampling functions and native SVG/CSS; introduce libraries only when complex deformation genuinely pays off. Put shared components in src/components/, do not import from other chapters.
• Card texture goes through shared primitives, do not redraw：src/styles/base.css already has .card primitive (--surface-2 / --bw-1 solid var(--rule) / --r-card / --card-shadow), globally imported by App.tsx — usable directly in any chapter, no import needed, and not subject to the two conventions of "chapter CSS has a prefix" and "no cross-chapter import"（check.mjs prefix checks and cross-chapter checks do not scan src/components and base primitives). New chapters' cards reuse it plus theme tokens.
• Use tokens, not pixel values: each theme's --r-card ranges from 4px to 32px; hardcoding border-radius:16px breaks when the theme changes. Cards that recur should then be abstracted by the main thread into src/components/。01-pipeline itself is not yet connected to .card(hardcoded 16px), which is legacy;do not copy its literal value。

3. Complete chapters shot by shot

Each chapter's input = BRIEF (including the generated FACTS.md link) + CRAFT + current theme tokens; when using time sampling, also read MOTION.

1. First build the key visual and the final readable state, and check the safe area, recognizability when scaled down on mobile, and source correspondence.
2. Then connect cues and motion, keeping the subject continuous; cards take on clear responsibilities such as comparison, containment, flip reveal, and ordering.
3. Check the start state, action midpoint, information landing point, and the next shot's entry. Only the last frame being pretty does not count as complete.

Decide whether to parallelize based on user authorization and available tools; when parallelizing, first freeze shared components/themes/interfaces, one agent per chapter, writing only in that chapter's directory. The main thread handles shared code and registration.Token consistency cannot be a fallback for composition and motion style; the sample clip is the contract. If there are no sub-agents, complete sequentially; the process does not depend on multiple agents.

Design goals (diagnostic lines, not mechanical quotas):

• One screen usually has 1 main proposition and 2–4 necessary labels; first try to stay within 40 Chinese-equivalent characters. Quotes/code/evidence images may be exceptions, providing local focus and reading time; do not meet the bar by shrinking text, cropping evidence, or deleting framing.
• Explanatory chapters should let objects, diagrams, and real materials carry most of the time; when three consecutive shots are only title + text cards, re-examine the shot selection.
• Every important action can answer "what did it help understand". Entrances, light sweeps, and background breathing do not count as mechanism demonstrations.
• Richness comes from the combination of object changes, data comparisons, local zoom-ins, connect/disconnect, flips, mask handoffs, and timely hard cuts. Conclusions can rest quietly; the whole piece does not need to keep moving.

4. Deliver after acceptance

1. npm run check: real TypeScript project checks, timeline/step count/red lines. SKIP does not mean the item has been verified.
2. According to EVALUATION.md use the user-specified or locally available real browser skill (such as ego-browser, agent-browser, or another browser tool), not bound to a platform or brand. Review each shot's start/middle/end frames and transitions; new clock shots can be precisely reproduced with ?review=1&t=<绝对秒>&mute=1 .
3. ?auto=1&mute=1 Play continuously by part, confirming the audio clock advances, cue landing points, and no black frames/misalignment/truncation. Static frame verification cannot replace playback.
4. Recheck on-screen facts, missing materials, and the safe area. Fix the smallest shot, then recheck its adjacent transitions.
5. Deliver a runnable directory, playback link, and measured evidence. Remove mute=1from the user's viewing copy. Preview page top-right export Optional 1K / 2K / 4K, rendered frame by frame on the same timeline, with voiceover processed in chunks and MP4 written to a temporary file; keep the page open. Standalone CSS/Web Animation, embedded video, and iframes must first be converted to deterministic frames or recorded RECORDING.md with screen recording software. Do not state speed/rework improvements as conclusions unless they have been measured.

Engineering bottom lines to keep

Fixed 1920×1080 stage, adapted to the viewport with transform; sections do not use vw/vh; colors and fonts use theme tokens; section CSS is prefixed; no cross-section imports. The number of steps matches the number of voiceover entries. The entire original audio is driven by audio.currentTime; sections do not use independent timers to create a second timeline. Terminology, data definitions, and real asset sources are unified.

Manual, Auto, and Review all preserve the stage outer margin and the 16:9 framing boundary. The picture area is a right-angled rectangle; the border, corner marks, and control bar are outside the picture; switching playback modes must not change the rectangle size. Screenshots/recordings are cropped according to .stage-frame the real boundary, and the outer margin is not zeroed out just to get a full-screen screenshot.

EXAMPLES The old text/checklist examples in are for structural reference only; new projects start by default from the scaffold's continuous scene examples,real SRT MG examples, and representative sample clips.