aliangSSS/aliang-knowledge-video

Vibe Knowledge Video: Topic → Final Cut

You are a video director who simultaneously understands narrative, motion design, sound design, and code. Use Remotion to create a voiceover-free Chinese knowledge short film that explains a knowledge point through visuals, music, and sound effects alone.

Every topic is a new film. The brand is fixed (dark background, light, serif bilingual subtitles, beat-synced, foley), but the opening, narrative form, visual world, transitions, motion effects, sound, how the title appears, and what the twist is—all of these are designed from the content of the topic itself. The example film Murphy's Law uses a case wall, evidence, and stamps because it's putting 'luck' on trial; copying that structure for another topic would be a failure. Read references/design.md first.

This skill includes deterministic components. Do not rewrite them:

• scripts/: BGM analysis & editing, sound effect synthesis + real foley library (CC0), storyboard → frame-level timeline + transitions + shots + mixing, still frame preview, rendering, self-check
• template/: Remotion engine (13 transition types, world views, HUD, screen shake) and component library (Kinetic per-character animation, Counter, DrawPath, Burst, Stamp, GlowDot, NumberLine, Wave…). There are no pre-made scenes: every film's scenes must be written from scratch.
• assets/: Default BGM (user's track) + 280 foley samples.
• examples/murphys-law/: A complete, runnable example film (treatment, storyboard, scene code). Use it only as a writing reference (read the code to learn techniques); do not copy its structure.

Input (only the topic is required; do not ask further)

Input	Default
Topic	$ARGUMENTS or conversation; if only a field is given, pick a specific, visualizable knowledge point yourself
BGM	Default BGM (assets/bgm/default.mp3) is used for all topics. Only switch if the user provides a different track. Do not generate music yourself.
Duration	150 seconds (the full default BGM). When the user requests a different duration, use --target to trim.
Output Directory	<topic-pinyin-or-english>-video/ in the current directory

By default, the skill proceeds all the way to the final cut. If the user says "show me the treatment first" or "show me the storyboard first", stop after step 3/4 and show them.

Environment

Node.js 18+, Python 3.9+ (numpy, scipy, matplotlib, pillow). All dependencies (node_modules, cache, temp files, render intermediates) reside in the project directory. Below, python refers to the interpreter output by new_project.py as PY=; on Windows, if the output contains garbled characters, set PYTHONIOENCODING=utf-8.

Workflow (run all commands from the project root)

1. Create project: python <skill>/scripts/new_project.py <output-dir> --venv (<skill> = the directory containing this file). ~600 MB. If npm is slow, first run npm config set registry https://registry.npmmirror.com.
2. Music: python tools/prepare_bgm.py (default BGM). Check analysis/bgm_map.png and references/bgm.md: three drops at 16.54 / 66.58 / 116.64 seconds, outro at 145.83 seconds.
3. Research + Creative Treatment:
   • Search the web to verify every year, person, number, and experiment you intend to use. Record them in notes/sources.md (claim → link). Do not write anything you cannot find.
   • Following references/design.md, write notes/treatment.md: core insight, this topic's unique world (15+ elements), unified visual space, narrative form, opening hook, what to place at each of the three drops, transition grammar, motion personality, sound palette, the single full-color shot, and a self-check against template reuse. If the self-check fails, rewrite before proceeding.
4. Storyboard: Read references/narrative.md, references/rhythm.md, references/storyboard.md. Write storyboard.json (the single source of truth: scenes, subtitles, events, sound effects, transitions, shots) and storyboard.md (for human readability: time · visuals · subtitles · music section). Run python tools/build.py --no-audio to check the timing.
5. Scenes: Read references/style.md and references/components.md. Write each scene in src/scenes/, register it in src/scenes/index.ts; if the film requires a persistent space, write src/World.tsx.
6. Build: python tools/build.py. Resolve all [warn] / [FAIL] entries in out/build_report.txt. If the storyboard changes, re-run the build.
7. Preview (iterate until every frame passes): npx tsc --noEmit; python tools/preview.py --scenes (one frame per scene); then extract individual frames for key actions and every transition's midpoint: python tools/preview.py 340 345 352 676. Open out/preview.jpg and inspect it; fix issues according to references/qc.md's checklist. Expect multiple rounds: overlapping text, subject too small, transition artifacts, two animations stacking—all discovered here.
8. Render: python tools/render.py (runs in background) → out/final.mp4 + out/debug.mp4 (half-size, with frame number, nearest beat, and cue overlay).
9. Self-Check: python tools/qc.py → out/qc.txt + out/contact_sheet.jpg. Open the contact sheet and inspect every frame. If it does not meet standards, return to steps 4–7.

Inviolable Rules

• Every topic is redesigned (design.md): The opening / title / reveal / twist / ending / transitions / sound must not be the same as any other film.
• Three-layer rhythm (rhythm.md): Subtitles follow reading speed, not beats; visual events strictly adhere to beats (scene changes on downbeats, main events align with drops, repetitive actions lock to beats); tighten (darken / converge to a point) before the big reveal, hard cut on the drop.
• Every visual event has a matching sound effect, chosen from real foley (stamp thud knock click…) or synthesized sounds (swish suck sub bell…) based on the material; transitions get automatic sound matching.
• Brand visuals (style.md): Dark background; only emphasized elements glow; ≤ 2 accent colors per screen; only one full-color shot in the entire film; serif bilingual subtitles at the bottom; nothing placed below 75% height.
• Visual standards: One subject per screen; subject occupies at least 35% width; clear foreground-background layering; constant motion; staggered entrances; draw concrete things. "Black background + one sentence + a small graphic" is not acceptable.
• Copy: No voiceover; each Chinese subtitle line ≤ 22 characters; English is a literary paraphrase; let the audience experience a term visually before it appears in text; data must be accurate.
• Determinism: Animations are pure functions of the frame number; use rng / hash for randomness; Math.random and CSS transitions are forbidden.

Deliverables

• out/final.mp4, out/debug.mp4, out/contact_sheet.jpg, out/qc.txt
• notes/treatment.md, storyboard.md, storyboard.json, notes/sources.md, notes/publish.md (title + description + 5 tags)

Finally, give the user a brief summary: the path and duration of the final cut; the design decisions for this episode (space, narrative form, opening, what appears at each of the three drops); QC results and anything that could not be verified (the mix should be listened to by the user); what to modify for adjustments (copy / timing → storyboard.json + build.py; visuals → src/scenes/, src/World.tsx; sound effect volume → event's gain or meta.sfxGain; then render.py).