Code Animated Educational Videos
All visuals are drawn purely with code using Remotion; sound effects are synthesized with Python. First, provide three options with previews, then upon user confirmation, write a brief.md, then produce each shot individually.
Hard Rules
- Only use this Skill's approach. Do not replace any steps detailed here with workflows or methods from other projects.
- Sources must be real and include links. Open or download each one to verify. Mark anything that cannot be verified as "unverified." For second-hand interpretations, clearly state who made the interpretation. Do not invent numbers or include unsourced claims.
- Get user confirmation at every step before proceeding: Source list → three options and previews → audio levels → covers. After writing
brief.md, tell the user where it is saved. - No narration (unless requested by the user). All information is conveyed through on-screen text. Use the user's provided background music (the user must have rights to use it). Synthesize action sound effects and sync them to the beat. Do not include music files in the repository.
- Text: Ensure it does not overlap, is clearly visible, stays on screen long enough, and avoid large blocks of text. Visuals should be rich; protagonists (people, animals, or objects) should be drawn in detail and lively.
- Default specifications: Landscape 1920×1080, 30 fps; use 1080×1920 (set
styleto"vflash"inscenes.json) when the user requests portrait/Douyin/short-form video. Duration equals the length of the background music (if no music is provided, a duration and BPM can be specified).
Working Directory
<topic>/ Example: ~/videos/<topic>
demo.mp3 / demo.mp4 User-provided background music, reference video (optional)
source/ sources.md (source list), ref-notes.md (reference video analysis), raw materials
previews/ plan-a.png, plan-b.mp4, plan-c.png (previews of the three options)
brief.md Confirmed complete plan, also a reusable prompt
video/ Remotion project (generated by new_project.py or new_project.ps1)
qa/ Shot-by-shot still frames, whole-video frame extraction, review_log.md
<video_name>.mp4 Final video
covers/ cover_3by4_portrait.jpg, cover_4by3_landscape.jpg
Step 0: Create Project
python <skill>/scripts/new_project.py --project "<topic directory>"
# If no background music: ... --no-music --duration 60 --bpm 120
On Windows, use scripts/new_project.ps1. This script does the following in order:
- Check the environment (
scripts/check_env.py). Prints any missing items; ask user permission before installing. - Create the working directory.
- Copy templates.
- Copy fonts.
- Run
npm install. - Measure beats and write to
src/grid.json. - Produce the first draft mix.
The entire process takes 1–3 minutes. If running in an environment where long commands must run in the background, start it in the background and poll the output (see references/pitfalls.md).
The template contains a generic placeholder example of about 12 seconds to confirm the project can render. When changing the topic, rewrite the scenes, captions, and sound effects. For a complete multi-shot example, see examples/bait-color/ (optional reference, not the default content).
Step 1: Clarify What to Make
The user can provide any combination of the following raw materials:
- Idea: A one-sentence topic is fine.
- Original content: Article, voiceover script, product URL, code repository, data table.
- Reference video, background music.
Ask at most 3 follow-up questions, only those that would change the plan: duration, aspect ratio, whether narration is needed, specified brand colors or fonts. Use default values for anything the user does not specify, and note these in the plan so the user can change them.
Process raw materials:
- Educational, fact-based topics: Research sources according to
references/research.md, verify them, write tosource/sources.md, and present to user for confirmation. - Articles, voiceover scripts: Extract core information, target audience, and necessary facts. Facts can only come from the raw materials; do not write anything uncertain.
- Product URLs: Read the page, note the product name, features, tagline, and brand colors. Ask permission before taking screenshots.
- Code repositories: Read the README and key files, extract feature points; do not invent features.
- Reference videos:
- Ask permission before downloading links.
- Measure specifications with
ffprobe. - Find shot transitions with
ffmpeg -vf "select='gt(scene,0.3)',showinfo". - Extract 1 frame per second to create a contact sheet.
- Write shot structure, pacing, color palette, fonts, and techniques into
source/ref-notes.md. - Only learn structure and techniques; do not copy assets or text.
- Background music: The project creation script already measures beats. It prints BPM, segment boundaries, and drift. The plan and storyboard are arranged according to this.
Step 2: Provide Three Options
Write according to references/plans.md. The division of labor for the three options is fixed:
| Option | Style | Technology | Presentation Method |
|---|---|---|---|
| A | FLASH Animation Style (flat illustration) | Remotion + SVG flat illustration components | Safe: ask question → experiment/data → conclusion → remember three things |
| B | Pixel Cartridge Style (retro game console + CRT old TV) | Canvas 2D pixel canvas → WebGL CRT shader | Gamified: choosing a cartridge is choosing a level, HUD displays data, dialogue boxes present conclusions, results screen shows outcome |
| C | Suggested at the time: Pick the best fit from the candidate list in plans.md, or propose a new one that can be done with Remotion | Different from A and B | Different presentation method: one-shot, protagonist throughout, reverse chronology, one metaphor to explain everything |
Each option must include: name, one-sentence summary, style (color values and fonts), specifications, technology combination, shot-by-shot visual overview (with time ranges), audio, estimated render time, difficulties and risks, and why it suits this raw material.
The three options must be clearly distinct in style, technology, and presentation method; not just a recolor.
Step 3: Produce Previews for Each Option
- In
video/src/preview/PlanA.tsx,PlanB.tsx,PlanC.tsx, each build one shot that best represents the option. Start from time 0, length 2–4 seconds. The template has generic placeholder examples; modify as follows:- A uses SVG components from
src/art/,src/ui/. - B uses the
src/pixel/engine, drawn intoPixelStage. - C is new code, following the
PlanC.tsxpattern: visuals determined only by t, one shot built.
- A uses SVG components from
- Run:
node tools/preview.mjs --out ../previews --estimate A:2.4 B:2.5 C:3.9- By default, each option renders one keyframe; the number after the colon is the seconds at which to capture the frame.
- For options where the selling point is motion, write
B:clipto output a 3-second clip. - The script prints per-frame render time and estimated total video render time; fill this number into the option.
- Review the preview images yourself: check for text overflow, elements overlapping, empty visuals, and whether the three styles are truly distinct. Fix issues before presenting to the user.
- Present the text and preview images of the three options together to the user (embed the preview images in the reply; different assistants handle this differently). The user can choose one, request a hybrid, or request modifications; if changes are made, go back to Step 2 or 3 until the user confirms.
Step 4: Write brief.md
After user confirmation, write <topic>/brief.md according to references/brief-template.md. It consists of seven sections: <role> <inputs> <direction> <structure> <build> <gotchas> <start>. Record all confirmed details; for any default values used, note that they are defaults. After writing, tell the user the file location.
All subsequent production strictly follows the brief. To make changes midway, first modify the brief, then modify the code. The user can reuse this brief directly when switching topics or running it in another tool.
Step 5: Produce Each Shot
-
First write
src/scenes.json:- Set
styleto"flash"or"pixel"; the Root component will use this to select the visual system. - Write the scene table using time signatures; place transitions at segment boundaries.
- Set
-
For each shot, write:
- FLASH style: Write components in
src/scenes/*.tsx, then register them insrc/scenes/index.ts. - Pixel style: Write drawing functions
(c, f) => voidin thePIXEL_SCENESarray insrc/pixel/scenes.ts. - C style: Expand from the preview code in Step 3, hook into
Film.tsx, or write a separate full-video component similar toPixelFilm.tsx. - Write all text into
src/captions.jsonand all sound effects intosrc/sfx.json, all using the same time signature system.
- FLASH style: Write components in
-
After finishing each shot, run sequentially:
npm run typechecknpm run check(subtitle check, must have 0 issues)node tools/stills.mjs --out ../qa <entry time in seconds> <main action time in seconds> <exit time in seconds>
Then review each image, checking for occlusion, objects exiting frame, text overlapping faces, and text overlapping each other. Fix issues before proceeding to the next shot.
-
For videos longer than 30 seconds, after all shots are assembled, first render a low-resolution draft:
node tools/render.mjs --scale 0.5 --out out/draft.mp4. Confirm pacing and transitions are correct before refining details. -
Style rules: see
references/style-flash.mdandreferences/style-pixel.md; general rules: seereferences/craft.md.
Step 6: Audio
Rules: see references/audio.md:
- Sound effects and visual actions are written on the same time signature.
- Pixel style uses
chip_*chip sounds. - Typewriter effects use the
repfield to repeat the sound effect. - The default volume level is the final value.
- If the user says something is too loud, too quiet, or harsh, use
--music-dband--sfx-dbto generate several comparison files for the user to choose from. Only replace the audio track; do not re-render the visuals.
Step 7: Render and Review
- Render:
npm run sfx, thennpm run render. Time depends on Step 3's estimate; for a 3200-frame video, FLASH style takes approximately 1.8 minutes, pixel style about 6 minutes. - Verify resolution, frame rate, total frames, and duration using
ffprobe; measure loudness withebur128. - Generate frame extraction images:
python tools/qa_sheet.py out/film.mp4 ../qa/final(on Windows, also usetools/qa_sheet.ps1). This produces two images: a full contact sheet and a mobile-size version with each frame 360 pixels wide. - Score against the self-check list in
references/craft.md. Each of the 7 items must score 8 or above:- List the 3 most severe issues with their timecodes.
- Only re-render the problematic segments (
node tools/render.mjs --frames start-end), then composite the full video. - Record each round's scores and issues in
qa/review_log.md.
- Copy the final video to
<topic>/<video_name>.mp4.
Portrait Short-Form Video Key Points (style = vflash)
- Full-video components are in
src/vfilm/: VFilm, VOverlay, generic cards and tags, minimal covers. Register scenes invfilm/scenes.tsx'sVSCENE_MAP. - Caption safe area: x 40–1040, y 240–1640; default text stay time ≥ 3.5 seconds, short text cards ≥ 3 seconds.
- Do not overlay source information on the video. Record sources only in
source/sources.md. At most, mark the video with "illustration." - Ending suggestion: numbered review/poll + follow prompt. Text rules: see
references/publish-copy.md(title ≤ 30 characters, description ≤ 100 characters including hashtags). - Final video loudness: -16 LUFS, true peak ≤ -2 dBTP:
python tools/loudnorm.py out/film.mp4. Background music must be clearly audible. - Cut points align with the first beat of a measure:
python tools/sync_check.py. Speed curves written bybeat_grid.pyinto thesegmentsfield ofgrid.json. - Portrait covers:
npm run vcover34/npm run vcover43.
Step 8: Covers
Each style has two covers in 3:4 and 4:3 aspect ratios; the portrait style also has a set of minimal covers:
- FLASH style (landscape composition):
npm run cover34,npm run cover43 - Pixel style:
npm run pixelcover34,npm run pixelcover43 - Portrait minimal:
npm run vcover34,npm run vcover43
All exported at 2x resolution. Layout rules follow the respective style documentation and references/publish-copy.md. For short-form video covers, avoid the bottom-left area (play count region); do not use bottom color bands with stacked lists.
Delivery
Tell the user:
- Path to final video,
brief.md, and project directory. - Key creative decisions made.
- Known shortcomings.
- Render time.
- Any uncertain facts that need user verification, listed separately.
Changing Styles, Adding New Styles
- Change only this video: Modify files only within
video/for this specific video; do not modify Skill templates. For where each part is located, see "Which files contain which styles" inreferences/craft.md. First produce 4–6 representative still frames for user approval of the style, then create the full video. - Use C style for all future videos:
- Collect its code into
assets/template/src/<style name>/. - Write
references/style-<style name>.md. - Mark it as "included" in the candidate table in
plans.md. - Add a row to this file's option table.
- Collect its code into
- Unachievable styles: This workflow uses code only for vector and pixel art. Live action, photorealistic 3D, and photorealistic people cannot be done; inform the user in advance. If photorealistic people are needed, the user can generate a green-screen person clip using a video generation model, and the code will only handle the scene and text.
Reference Files (Read When Needed)
| File | Content |
|---|---|
references/plans.md | Format for three options, C option candidate table, preview rules, how to present to user |
references/brief-template.md | Seven-section template for brief.md |
references/style-flash.md | FLASH animation style: style guidelines, components, covers |
references/style-pixel.md | Pixel cartridge style: visual essentials, palette, two-layer resolution, bitmap fonts, sprites, CRT, covers |
references/craft.md | Storyboard rules, subtitle rules, shot-by-shot self-check, full-video self-check scoring, acceptance checklist, which files contain which styles |
references/remotion-kit.md | Template structure, time signature system, component APIs, common commands |
references/audio.md | Beats, sound palette (including chip sounds), final mixing levels, tuning workflow |
references/research.md | Research and source verification methods |
references/pitfalls.md | Past pitfalls (must read before starting) |
references/credits.md | Sources of inspiration and font licenses |
references/publish-copy.md | Portrait video publishing copy, voting ending, safe area, loudness |
scripts/new_project.py, new_project.ps1, check_env.py, beat_grid.py, music_rms.py, qa_sheet.py | Create project, check environment, measure beats, measure levels, extract frames |
assets/template/ | Remotion project template (includes all common components and placeholder examples for both styles) |
assets/fonts/ | Fusion Pixel 12px bitmap font (OFL) |
examples/bait-color/ | Complete multi-shot example (optional reference, not the default template) |