TimeCraker/video-motion

video-motion — Overlay Motion Effects on Video Base (Remotion)

Design as Code: All coordinates, timings and text are declared in src/cues.ts (data contract, fields must not be changed); fx components have zero hardcoding. Change the cues and re-run one command to regenerate the entire video. Three-layer motion effects: SubtitleTrack / DataBars / Spotlight (circle / arrow / box).

Technical diagrams, process/data screens, Lottie, 3D, maps, or Studio parameter editing follow the relevant branches as per Specialized Visual Production. The director provides content and visual direction; the production module delivers actual project assets/code and render evidence. Current components, types, and locked engine interfaces take priority.

Series videos follow Series Consistency by applying column conventions to project tokens, fonts, scenes, subtitles, covers, and actual audio tracks. Reuse actual input versions and render comparisons with current episode content; do not assume changing one theme value unifies the entire video. For product demos, overlay annotations on actual recorded/captured footage; any post-production mouse cursors or spotlights must correspond to real actions and results.

Step 1 · Script Design (Look at the Footage, Don't Guess the Screen)

1. Extract frames to review footage: npx remotion still remotion/index.ts FootageOverlay <output>/f-<n>.png --frame=<n>, select frames based on shots and key changes; read images using the absolute path of the actual generated image.
2. Write the motion script in src/cues.ts:
   • Subtitles explain the scene: Describe what the viewer is seeing at that moment, segmented according to semantics and reading speed.
   • Spotlights point to real objects: circle / arrow / box pointing to elements that actually exist in the frame and are noteworthy; first verify the position of coordinates using extracted frames.
   • Data must have a source: Data bar values must come from a real source (on-screen HUD / results panel / backend data); if unobtainable, clearly mark as "demo data" in the subtitle.
3. Interpretations must relate to the target context: HUD, chat, prompts, and actions can serve as evidence, but only mark the content needed for explanation; do not fill the entire video just to achieve cue density.

Step 2 · Engineering & Specifications (Adapt to the Footage)

1. Copy templates/remotion-app/ to the working directory, run npm install (all Remotion sub-packages must be installed together with the same command; versions are strictly coupled). After installation, run npm run typecheck (esbuild tolerance does not equal type cleanliness; only tsc passing reveals issues; the template includes typescript as a devDependency, runnable anytime after installation).
2. Native specifications: Run node scripts/probe-footage.mjs <footage path> to use ffprobe and generate src/footage-params.ts — output resolution / frame rate follow the footage, not hardcoded; re-run this script if the footage changes.
3. Footage does not go into the skill: Render with --public-dir <footage directory> (staticFile reads directly from the project footage library); only copy footage as public/footage.mp4 when passing parameters is inconvenient.
4. Cues are written for 1080p design coordinates; FootageOverlay has built-in transformOrigin: "top left" for overall scaling to fit any canvas — no need to modify cues when resolution changes, motion effect positions do not drift.

Step 3 · Render (One Command)

Run validation before rendering: node scripts/verify-cues.mjs (for deck subtitles, use src/deck-cues.ts parameters). Errors must be zero before rendering; total duration warnings are informational and do not block.

cd <remotion-app>
npx remotion render remotion/index.ts FootageOverlay <repo>/products/<project name>/demo.mp4 --crf=16 --public-dir <footage directory>

Output goes to the repository's products/<project name>/ (directory rule: the skill is a pure tool, output does not fall inside the skill; when used across repositories, place it in the project root output/<skill name>/). --crf=16 ensures high quality. Large footage rendering runs in the background (approx 10 minutes for 1440p60 × 30s). Verify using exit code + ffprobe; do not rely on progress bars.

Step 4 · Three-Level Verification (Mandatory, Cannot Skip)

① Programmatic: Render exit code 0; npx remotion compositions remotion/index.ts output durationInFrames / width / height / fps match the footage metadata. Use npx remotion still to select representative frames based on key subtitles, data changes, and transitions — for each subtitle at start+0.3s / end-0.3s, data bars at t-0.3s / t+1.5s, spotlights at t+0.5s / t+ttl+0.3s (convert to frame numbers using the actual fps from compositions output).

② Image Inspection: Read the actual PNG frames to check frame-by-frame: appearance / disappearance timing and text, data bar height ratio and value labels, spotlight type and position, base footage without artifacts or stretching, no garbled characters in any frame (Chinese uses Microsoft YaHei fallback). If issues are found, fix the corresponding source file, re-render, and check the original issue and adjacent transitions; if a blocking issue cannot be determined or fixed, report it clearly.

③ Continuous Playback & Audio Review: Extracted frames cannot prove timing and synchronization; use the audio-visual methods from media-qc to check the actual clip and audio track, and record the inspection scope. The user performs the final review of the finished video.

Step 5 · Delivery

Report: Finished video path and size / resolution and frame rate (= native footage) / three-level verification conclusions (including the extracted frame checklist) / cues.ts location (re-runnable). Outputs and mp4 files are never committed to git.

PPT Page-by-Page Video (DeckVideo, Second Output Type)

One engine, two output types: The steps above are "Overlay Motion Effects on Video Base"; this section is "PPT Page-by-Page" — pptx slide images + per-page voiceover directly output as a video. Page duration follows the actual voiceover length; subtitles appear according to the segmented script timeline.

1. pptx & Segmented Script: The ppt skill output is a pptx file. Write the narration segmented script script.json, with ref set to "page N" (N = page number). First run python skills/narration/templates/verify_narration.py <script.json> until it passes all checks. Each segment should be ≤20 characters after stripping (the single-line subtitle pill directly displays the segment text). Within a page, multiple segments are connected with periods to form the page's narration.
2. Page Images: Run python scripts/extract_pages.py <in.pptx> public/deck/pages — CONVERT the COM to PDF, then use fitz to render at 200dpi, outputting p-<N>.png (2667×1500, canvas contain to fill).
3. Voiceover: For testing, run powershell -File scripts/make_deck_audio.ps1 <script.json> public/deck/audio (SAPI Huihui generates page-N.wav per page). For the official workflow, manually voiceover each page in 剪映 (CapCut), export the same page-N.wav, and place it in the same directory; downstream is unaffected.
4. Wiring & Render: Run node scripts/build-deck-params.mjs <script.json> public/deck to generate src/deck-params.ts + src/deck-cues.ts (page start points / total duration / subtitle time distribution are all derived values; do not manually edit) → npx remotion render remotion/index.ts DeckVideo <repo>/products/<project name>/deck.mp4 --crf=16.
5. Three-Level Verification: Same as Step 4 three-level (Programmatic: ffprobe / compositions reconciliation + Extracted Frame Image Inspection + User Viewing). L2 extraction points: for each page's first frame+0.3s to check page order; for overlap midpoint, use next page's start+0.25s (overlap tail is at the page window tail, 0.5s cross dissolve); subtitle start+0.3s / end+0.3s to check text and exit. At page first frame+0.3s, if the spring fade-in is not complete and the entire frame is slightly gray, this is a transition intermediate state, not a defect.

Page images and voiceover are stored in public/deck/ (covered by .gitignore, not committed); canvas is 1920×1080@30 constant at the top of build-deck-params.mjs; changing two lines achieves 4K.

Scene-Based Output v2→v3 Quality Craftsmanship (scene-kit Direct Rendering, Third Output Type)

An upgrade line from PPT page-by-page video: The visual subject changes from "PPT slide images" to Remotion components that directly render motion scenes (src/scene-kit/ 24 components). Page duration/audio/subtitle mechanisms follow the deck-params derivable chain. Judge "plain" or "low quality" by referencing docs/2026-08-30-motion-grammar.md; this section covers the hard rules for quality craftsmanship.

Quality Baseline

Select the acceptance method based on the content type in docs/2026-08-30-motion-grammar.md. Preserve tokens and brand continuity; visuals should center on the real subject and readable information; motion should explain changes. Whitespace, stillness, and the amount of supporting information per shot are judged based on the shot's goal, without applying fixed quotas or a static PPT rejection rule.

First, the content-director provides factual sources, storyboards, and art briefs; then review representative frames and short samples. Structure diagrams should prioritize SVG, real interfaces use screenshots/recordings; when illustrations are needed, use available imagegen tools and register assets. New ArtLayers and more motion effects do not automatically mean art quality is approved.

Scene Design Method (General, No Preset Answer)

First, check the assets/patterns.md page solution library — if a similar scenario already has a validated PAT entry, adapt it by changing parameters (scenario → layout → components → pitfalls → reference frames are all in the entry). If none exists, design from scratch. For each page's copy, first determine the content type (narrative pain point / feature demo / data persuasion / process explanation / concept / call to action — six types). Then, follow three rules: "the subject is determined by the copy content, the same visual solution is not repeated across multiple pages of the same type, and the background family serves the content's emotion" to decide the subject form and component combination. Before starting work, produce a design table (per page: copy summary → content type → subject form → background family → component combination → rationale → information package with sources for each item → subject annotation). The design table must be reviewed and approved before writing code; each piece of supporting information must cite its source (narration script / project documentation / content visible in the footage).

Three Hard Lessons (Written as Rules)

1. Allow reading pauses in the finished state: Use existing components when chat, charts, or processes need to show state changes; judge static shots based on information and rhythm; do not force decorative motion effects just for the sake of checking.
2. Wrapper components must explicitly pass width: When a new container wraps an old component, losing width causes block-level elements to fill the parent container (illustration covering the title, phone case expanding to 700px wide — two instances of the same root cause). Always use style={{ width, ...style }} in wrapper containers.
3. Check whitespace ratio before deciding on a long screenshot: Upon receiving a long screenshot, first calculate the std/blank ratio line-by-line (a short PIL script). "Long empty images" where lazy loading hasn't rendered content into the screenshot will die in the air when scrolling — first crop close-ups, fix the footage, then switch back to scrolling.

MG Arsenal (S0-S6, Main Ammunition for Output Quality)

The template comes with a full weapon set. Detailed per-component usage is in assets/component-catalog.md (scene-kit 24 components / entrance-kit nine verbs / vendor community picks / fonts). Only the ironclad rules are recorded here:

• Version Iron Rule: All @remotion/* packages must be exactly the same version (e.g., 4.0.533, no ^) — version mismatch is a hard Remotion error, not a warning. When adding new packages, first align with the existing version (check-docs assertion 3.7 monitors this; drifting will turn red).
• 4.0.533 API Facts (may differ from docs/memory; verified via testing; 4.0.518→4.0.533 upgrade confirmed via still baseline PSNR all inf, API shape unchanged): evolvePath returns dash properties for non-clipping paths; interpolatePath(value, from, to) takes three independent parameters; fitText only accepts withinWidth and returns {fontSize} object; Chinese multi-line cannot use fitTextOnNLines (it splits by space); parseSrt accepts {input} object (bare string throws undefined.split) and returns {captions:[{text,startMs,endMs}]} in milliseconds.
• Transform Wrapper Pitfall (S6 double-pit record): Wrapper verbs with transforms (CameraPush/SlideGroup/TextBreath/BlurTrail) must not directly wrap a position:absolute subtree — a transform element is the containing block for absolute descendants; the flow-in height collapses to 0, and content overflows at the top. Components are already self-sufficient (CameraPush root inset: 0, BlurTrail main layer in flow); still avoid bare wrapping inside a dimension-less absolute parent.
• Official <Trail> / TransitionSeries Semantics: The Trail root is an AbsoluteFill (page-level overlay semantics); element-level afterimages use BlurTrail from scene-kit (already relativized). TransitionSeries transition eats adjacent page duration; the output engine defaults to zero transitions (Series hard cut) + intra-page verbs.
• Vendor Discipline: Copy-paste into a local source file, not an npm dependency; upgrading = re-pull and re-do intake; four discipline rules are in the template src/vendor/README.md.
• Lottie Asset Flow: Free commercial JSON goes into assets/lottie/ (README three-field registration) → copy into project public/ when used → LottieLayer src references it; intake prohibits JSON with expressions (render uncertainty).
• Complex Effect Budget: ShutterBlur's samples and BlurTrail's layers increase render cost; ThreeStage varies by scene and machine. First render representative frames/shorts, then decide on scale; do not set fixed shot quotas for the entire video.

Verification Process (Four Levels)

L1 Programmatic (render exit code with full log, no piping tail; ffprobe = compositions frame count reconciliation); L2 Image Inspection (select representative frames based on risk — entry/stable wide shot/information close-up/transition and subtitle key frames, check actual images; zooming is only for inspecting details, no fixed number of frames per page); L2.5 Silent Test (answer the subject of each page blind); L3 Report (including technical scope, key frame evidence, items pending manual review, and before/after comparisons when needed). If components, tokens, or layouts are confirmed to have general value, backport them to the template/registry according to the Asset Backflow Convention. Project-specific content stays within the project; do not create additional tickets if no new lessons were learned. The render command is the same as DeckVideo (the composition is replaced with the scene-based component, e.g., DeckVideoV2). For covers, use npx remotion still to output an image (still frame number must account for entry spring duration).

Cover Image Output (Cover, Fourth Output Type)

Output a single frame instead of a video: one command produces a 1920×1080 cover PNG, used as an accompanying image when publishing the video.

1. Props: products/<project name>/cover-<name>.json should contain { title, subtitle?, badge?, bg?, preset }. preset can be photo (bg image fills the screen + bottom 55% black gradient overlay for contrast) / dark (dark gradient, default) / clean (light background + top thin line). bg is a relative path under the remotion-app public/ directory. If subtitle is omitted, it is not rendered; if badge is omitted, it falls back to the ASTERFORGE brand logo.
2. Render: npx remotion still src/cover-index.ts Cover <output>.png --props=<json file path> (independent entry point, does not go through Root.tsx; works in parallel with DeckVideo without conflicts).
3. Verification: Read the image to check that the title is complete and not truncated, text is readable under the photo overlay, and there are no garbled character boxes. Use the actual absolute path of the output to re-check the current version or hash. Adjust the number of title lines based on the target canvas dimensions and reading needs.

Boundaries & Pitfalls

• Use the absolute path of the actual output to read images; re-check the current file version or hash; only convert paths when a specific tool genuinely requires a path limit.
• GBK Console: print entirely in English.
• The first npx remotion browser ensure for Chrome Headless Shell downloads from Google's source (hundreds of MB); may time out on Chinese networks — report failure immediately; do not repeatedly retry large file downloads.
• Large media, dependencies, and caches are not committed to Git; production recipes, covers, subtitles, publication config, and acceptance metadata are retained according to archiving rules.

Current Process & Technical References

Use node scripts/studio.mjs init --id <name> --line b to bootstrap the template; the deps/typecheck in job.json can be re-run. This project's params/render/QC commands are added to job.json after the scene and actual audio track are determined. Call media-qc after rendering; technical reports and user final reviews are recorded separately. Clear caches after passing archiving checks.

Official remotion-best-practices are installed to the project cache via python scripts/install-upstream-skills.py, then mounted by setup-skills. The source is in references/upstream.json; it is a technical reference, not a replacement for this repository's workflow. Official reference version 4.0.538 is managed separately from the current engine version 4.0.533; before using new APIs, verify against local types and actual rendering; do not automatically upgrade.