Uerdong/remotion-explainer-video

Chinese Educational Animation (Remotion Full Pipeline)

Execute the ten steps in order. Each step's output is the input for the next; skipping steps and backfilling is prohibited.

Ten Iron Rules

1. Duration is determined by dubbing, not by script. The reference script is just intent. First estimate the total length based on the measured speaking rate (Chinese TTS ≈ 3.3 characters/second). If it exceeds the target duration, compress the text and convert to spoken language, then synthesize and measure the real duration segment by segment.
2. BPM must be measured empirically; never trust user- or reference-provided numbers. librosa often reports 104 BPM as 51.7 (halved). Use autocorrelation or alternative onset parameters for independent verification, and select the value that matches the listening experience.
3. All cut points snap to beats. Segment boundary = the end time of that segment's dubbing snapped upward to the nearest beat. Frame number = round(beat * (60/BPM) * FPS), hardcoded into the source; never computed at runtime.
4. Deterministic rendering. Prohibit Date.now() and Math.random(); derive all oscillations using Math.sin(frame). Any given frame must render identically across any number of renders.
5. Single source of truth for the timeline. Segment boundaries, frame numbers, dubbing offsets, and SFX anchor frames exist in exactly one timeline.ts. Changing script word count → re-run the generation script → synchronize TS; never manually edit two places.
6. Subtitle line breaks by punctuation into boxes. First split clauses by ，；：。, then box them. Use a fixed pixel container for line width (e.g., width: 1460 + whiteSpace: "pre"); do not let maxWidth let content determine the container.
7. Three-layer audio separation: BGM, voice, and SFX each have independent levels. Voice starts at 0.8, BGM at 0.24. After rendering, measure the peak; > 0.95 indicates clipping risk.
8. Self-check each shot with a still frame. Use npx remotion still to review composition frame by frame. Rendering the full video without checking stills is equivalent to rework.
9. Three hard constraints on Windows: --props must pass a file (e.g., --props=props-nobgm.json); inline JSON will have quotes stripped by the shell. For ffmpeg 9, use -fps_mode passthrough instead of -vsync. If style changes in TSX do not take effect, first delete node_modules\.cache.
10. Deliver first, then evaluate. Present already-rendered videos and generated images to the user as-is. Record issues and explain them clearly; do not re-generate without authorization.

Ten-Step Pipeline

#	Step	Key Actions	Output
1	Topic Decomposition	Define the knowledge chain, target duration, aspect ratio, audience tone	One-sentence topic + duration/aspect ratio agreement
2	Narration Script	Compress to target word count following "Hook → Model → Deduction → Conclusion → Implication", convert to spoken language	Segmented script (≈6 segments, 50–70 characters each)
3	Dubbing	Synthesize each segment independently with same voice and parameters; measure real duration and f0 per segment	s1..sn.wav + segment duration table
4	Subtitles	Generate SRT from segment durations, same source as scene cuts	subtitles.srt
5	BGM	Select or self-compose a track, measure BPM and beat table; replace if unsuitable	bgm.wav + bgm.json (beats_sec)
6	Timeline Repositioning	Snap segment boundaries to beats, calculate total frame count	timeline.json + timeline.ts
7	Sound Effects	Assign a sound to each key action, code-compose, pin to beats	sfx/*.wav + anchor frame table
8	Visual Engineering	Theme / components / timeline + per-segment scene components	Remotion project
9	Self-Check Rendering	Still frames per segment → full video → measure peaks	out/*.mp4, QA stills
10	Release Materials	Cover art (code-rendered or design tool), title, description, topics	Cover image + release-copy.md

Conflict Resolution Decisions

Conflict	Resolution
Script word count vs. target duration conflict	Compress the script, do not change the duration. If compression ratio > 1.3, convert to short spoken sentences while preserving all knowledge points.
User-provided BPM/duration differs from measured values	Use measured values and proactively inform the user of the discrepancy (e.g., "Spec says 110 BPM / 58s, measured 104 BPM / 53.65s"), and additionally offer a "re-align to spec" option.
User-specified track style mismatches	First measure the track's BPM/spectrum/peak, provide the data, then self-compose a replacement. Disclose the deviation reason upon delivery.
Reference visual style conflicts with cover/platform style	Keep them separate: body follows the user's visual style; cover follows the cover platform's distribution logic. Explain the trade-off.

Delivery Checklist

• Dual-version final video: with BGM / without BGM (for platform native music libraries); identical frame count and duration
• SRT subtitles (external, consistent with embedded
• Delivery notes: final video table, BPM and beat methodology, segment boundary table, beat-aligned point table, script, SFX table, mix levels, project structure, run commands
• Cover (landscape + target-platform portrait), multiple title options, multiple description versions, topic tags

Reference Files

• Commands, parameters, verification methods, and output paths for each step: references/pipeline.md
• Models suitable for each stage and selection rationale: references/models.md
• Project skeleton, theme/components/timeline conventions, snapping formula, rendering pitfalls: references/remotion-conventions.md
• Restyling existing videos (white flat → dark cinematic, etc.): references/restyle-playbook.md