Skip to content
Back to search

motion-educator

SkillWorks with Claude CodeGitHub

Make educational motion videos (explainers, lessons, concept films, shorts, "video edukasi") as premium films built in code - a lit shader stage, glass panels, metal type, 3D objects, diagrams, charts, captions, narration, music and sound effects - rendered frame by frame to MP4, landscape 16:9 or portrait 9:16. Always storyboard first - a detailed, illustrated storyboard with drawn frames for every shot, checked by a tool and shown to the person before anything is built. Narration is written as talk (Indonesian or English), performed as one take with ElevenLabs, and the picture is cut to the voice. Use when the user asks for an educational or explainer video, an animated lesson, a "how does X work" or "why is X" film, a science, maths, history, finance or product-concept explanation in motion, or asks to storyboard one.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zeative--motion-educator/badge.svg)](/listings/zeative--motion-educator)

HTML

<a href="/listings/zeative--motion-educator"><img src="/api/listings/zeative--motion-educator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

As a skill

git clone https://github.com/zeative/motion-educator ~/.claude/skills/motion-educator

It is a plain [Agent Skills](https://agentskills.io) folder (`SKILL.md`, `references/`, a Node kit), so any agent that reads skills can use it. Clone it into the folder yours looks in:

| Agent | For you (all projects) | For one project | | --- | --- | --- | | Claude Code | `~/.claude/skills/motion-educator` | `.claude/skills/motion-educator` | | OpenAI Codex | `~/.agents/skills/motion-educator` | `.agents/skills/motion-educator` | | Gemini CLI | `~/.gemini/skills/motion-educator` | `.gemini/skills/motion-educator` | | GitHub Copilot (CLI, cloud agent, VS Code agent mode) | `~/.copilot/skills/motion-educator` | `.github/skills/motion-educator` | | Cursor | reads `~/.claude/skills` and `~/.codex/skills` | `.cursor/skills/motion-educator` |

An agent without skill support can still follow it: clone it anywhere and tell it to read `SKILL.md` there first. What the agent needs: a shell to run Node, FFmpeg and Python, and the ability to look at images, since it checks its own stills and contact sheets. Every film in this repository was made with Claude Code; the others are untested here.

Then ask your agent for a film:

> Make a 45-second explainer on why the Moon always shows us the same face. Portrait, English, with narration.

It scaffolds a workspace in your project, writes and draws the storyboard, and stops for your approval before it builds anything.

By hand

git clone https://github.com/zeative/motion-educator && cd motion-educator
npm install && bash kit/audio/fetch.sh
node kit/tools/doctor.mjs                                # is this machine ready?

node kit/tools/new.mjs ~/films moon-face --portrait      # a workspace and films/moon-face
cd ~/films && npm install && bash kit/audio/fetch.sh
# 1. Write films/moon-face/storyboard.json, then check it and draw the board
node kit/tools/storyboard.mjs films/moon-face --png

# 2. Record the narration (optional) and let it set the shot lengths
node kit/audio/voice.mjs films/moon-face --generate      # one take, and the film cut to it (ELEVENLABS_API_KEY)

# 3. Build index.html, film.css and film.js, looking at stills as you go
node kit/tools/render.mjs films/moon-face --stills 1.5,4.2 --safe
node kit/tools/render.mjs films/moon-face --serve        # watch it live

# 4. Everything else, in order: render, mix, measure, a share copy
node kit/tools/make.mjs films/moon-face

Requirements: Node 20+, FFmpeg, Python 3 with numpy, and Playwright's Chromium (`npm i -D playwright && npx playwright install chromium`). The renderer uses the GPU when there is one; on a Linux machine without one it needs Mesa's software Vulkan (`apt install mesa-vulkan-drivers`). `node kit/tools/doctor.mjs` checks all of it. See [Rendering](#rendering).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 202 lines
  1. ---
  2. name: motion-educator
  3. description: Make educational motion videos (explainers, lessons, concept films, shorts, "video edukasi") as premium films built in code - a lit shader stage, glass panels, metal type, 3D objects, diagrams, charts, captions, narration, music and sound effects - rendered frame by frame to MP4, landscape 16:9 or portrait 9:16. Always storyboard first - a detailed, illustrated storyboard with drawn frames for every shot, checked by a tool and shown to the person before anything is built. Narration is written as talk (Indonesian or English), performed as one take with ElevenLabs, and the picture is cut to the voice. Use when the user asks for an educational or explainer video, an animated lesson, a "how does X work" or "why is X" film, a science, maths, history, finance or product-concept explanation in motion, or asks to storyboard one.
  4. ---
  5. # Motion Educator
  6. You make short educational films (20 to 120 seconds, landscape explainers or portrait shorts) that look expensive
  7. and teach one thing well. The film is a web page with one paused timeline: every frame is drawn by seeking it, so
  8. nothing is ever dropped and any shot can be fixed and re-rendered on its own. The kit in this skill is that engine.
  9. `examples/` holds finished films made by following this skill, each with its storyboard, source, cue sheet and
  10. narration: `langit-biru` (captions only, the most reviewed) and `petir-guntur` (a narrated short) are the ones to
  11. read first.
  12. ## The flow, as the person sees it
  13. **Their prompt → your research (the topic, the blueprints, the narration) → the storyboard, sent to them → their yes
  14. → the finished film.** The storyboard is the only stop. Everything they might want to weigh in on goes into it: the
  15. script, the voice, the length, the real version of each object and the drawings it is built from. After their yes
  16. you build, check, review and fix on your own and deliver the best film you can make, without asking again.
  17. - **Decide; do not hand the person choices.** When sources disagree or a detail is open, choose what is most
  18. faithful to the real thing the viewer knows and to the drawings (`references/detail.md` says how), write the
  19. choice and its reason in the delivery note, and carry on. Ask only when the film cannot be made without them
  20. (a missing drawing or photo that changes what the film shows), and ask it with the storyboard, not after.
  21. - **Quality is checked by you and by a fresh reviewer, not by the person.** The model against every blueprint, the
  22. stills against the board, the render against the five detail checks, the independent review, the fixes: all of
  23. it happens before delivery. The person sees the board once and the finished film once.
  24. Read only the reference your current step needs.
  25. | Step | Read |
  26. | --- | --- |
  27. | Deciding what to teach and in what order | `references/pedagogy.md` |
  28. | Writing and drawing the storyboard (the gate) | `references/storyboard.md` |
  29. | Choosing the look, the accent, the stage light, 3D | `references/look.md` |
  30. | Building real things in detail; directing the camera | `references/detail.md` |
  31. | Building the film with the kit | `references/engine.md`, then `references/motion.md` |
  32. | Writing the narration: talk, not captions; Indonesian and English register | `references/narration.md` |
  33. | The voice: choosing it, performing one take with ElevenLabs, cutting the film to it | `references/voice.md` |
  34. | Music, sound effects, the mix | `references/sound.md` |
  35. | Checking the render, independent review | `references/review.md` |
  36. ## What never bends
  37. 1. **Storyboard first, and it is drawn.** No film file is written until `storyboard.json` passes
  38. `kit/tools/storyboard.mjs` with zero errors and the person has seen the board. Every shot has drawn frames (how
  39. it starts, what happens, how it ends), sketched in the real frame's coordinates, so the build can be cut
  40. straight from them. If the person asked for an unattended run, send the board and keep going; otherwise wait for
  41. their yes. That yes is the last thing you wait for: from there to the finished film, you decide.
  42. 2. **True, with sources.** Every number and every claim on screen is in the storyboard's fact sheet with where it
  43. comes from. If you cannot source it, do not say it. What is drawn agrees with what is written: a bar, a meter
  44. or a path that stands for a number is computed from that number, a diagram that is not to scale says so on
  45. screen, and a number appears at its value (no counting up through values that are false).
  46. 3. **It explains itself on mute.** The picture and the words on screen carry the explanation; the voice and the
  47. sound make it land. A first-time viewer with the sound off can say what they learned. The step the whole explanation turns on is drawn as a mechanism
  48. (what goes in, what it meets, what comes out, where it ends up), never left to the caption alone.
  49. 4. **One clock.** Every animated value is a function of the timeline's time. No CSS animations, no
  50. `requestAnimationFrame` loops, no `Date.now()`, no unseeded randomness.
  51. 5. **The storyboard is the source of time.** The film reads shot starts and ends from `storyboard.json`; captions
  52. and the chapter rail are generated from it. Change the plan there, never by hand in the film. In a film that
  53. speaks, the recorded take writes those times (`voice.mjs`).
  54. 6. **You do not grade your own work.** Stills of every shot are looked at before a full render, measurements are
  55. run on the render, and a fresh reviewer who did not build it judges the result (`references/review.md`).
  56. 7. **A film that speaks is written as talk and performed as one take.** The script is written whole and said
  57. aloud before any shot exists; it is performed once, start to finish, and the picture is cut to the voice. Never
  58. one sentence a shot, never one recording a sentence, never a pause trimmed to fit a plan.
  59. 8. **Real things are built, not symbolised, and the camera is directed.** A device, an organ, a plant, a machine
  60. the film explains is a replica: the version the viewer knows where they live, researched from photographs and
  61. teardowns, built in 3D from its real parts at real proportions, in materials that read as what they are; a box, an icon or a flat shape never stands in for it. A body, a limb or an organ is never modelled from shapes: load the real anatomy (`kit/tools/anatomy.mjs`, `kit/engine/body3d.js`) or a measured scan, and build tissue and cells from a dimension sheet taken from histology. Every 3D shot has a deliberate
  62. camera move, and when the voice names a part the camera goes to it (`references/detail.md`).
  63. 9. **Say what was not checked.** You cannot hear. Say that the mix was set by measurement, name what a person
  64. should listen for, and deliver a music-only version beside the full mix.
  65. ## Workflow
  66. ### 0. A workspace
  67. The kit is copied into the person's project, never used from the skill's own folder.
  68. ```sh
  69. node <skill>/kit/tools/new.mjs <workspace> <film-name> # copies kit/ and package.json if missing, scaffolds films/<film-name>/
  70. cd <workspace> && npm install # three.js, GSAP, the fonts
  71. bash kit/audio/fetch.sh # the sound library (not committed: licence)
  72. ```
  73. Needs Node 20+, Playwright with Chromium, FFmpeg, and Python 3 with numpy for the mix. `node kit/tools/doctor.mjs`
  74. checks all of it and says what to install. Add `--portrait` to `new.mjs` for a 1080x1920 short.
  75. ### 1. Brief (a few lines, in the storyboard's head)
  76. Who is watching, what they already know, and the **promise**: the one sentence they can say after watching. One
  77. film, one promise. If the topic needs two promises, it is two films. Pick the language the audience reads, the
  78. format (landscape for a lesson, portrait for a short) and whether the film speaks or explains with captions alone.
  79. ### 2. Research and the fact sheet
  80. List every claim the film will make, each with its source, as `facts` in `storyboard.json`. Prefer primary and
  81. institutional sources. Do the arithmetic yourself and show it (a number like "5,9x" is written with what it is
  82. computed from). Write down what you are simplifying, and decide how the film will be honest about it.
  83. Research does not stop at the first closed door. When a page will not open, try the other routes before you call
  84. it unavailable: the same document elsewhere (Google Patents for patents, with its drawings on
  85. patentimages.storage.googleapis.com; Wikimedia Commons for photographs; the manufacturer's PDF catalogue; an archived
  86. copy), a direct download with `curl`, a different search. Read images by downloading them and looking at them. Say
  87. exactly which address failed and how, and only then ask the person for what is still missing. A mechanism or a
  88. real object is never filled in from memory because a search was hard (`references/detail.md`).
  89. ### 3. The script, if the film speaks
  90. Follow `references/narration.md`: one question, written as continuous talk in the audience's own register, said
  91. aloud and timed, before there is a shot list. Then cut it into shots: each speaking shot's `voice` is its run of
  92. the script.
  93. ### 4. The storyboard: the gate
  94. Follow `references/storyboard.md`. In short: acts, then shots (a new picture about every three seconds), each shot
  95. with what it teaches, its caption, what is on screen, the motion, what carries into the next shot, the transition,
  96. the sound, what to check, the facts it cites, and **two or three drawn frames**. Cut on the music's beat.
  97. ```sh
  98. node kit/tools/storyboard.mjs films/NAME --png # zero errors, then show films/NAME/storyboard/*.png
  99. ```
  100. Send the pages to the person. The contact sheets (the whole film in frames) go first.
  101. ### 5. The take, if the film speaks
  102. Follow `references/voice.md`: choose a voice native to the language (let the person hear two or three if you can),
  103. perform the whole script as one take, and cut the film to it. The storyboard's times are the take's from here on.
  104. ```sh
  105. node kit/audio/voice.mjs films/NAME --script # the take to perform
  106. node kit/audio/voice.mjs films/NAME --generate # with an API key: the take and its word times
  107. node kit/audio/voice.mjs films/NAME --take AUDIO --words WORDS # with a speech connector: hand both back
  108. node kit/audio/voice.mjs films/NAME # every shot's time, and the words to listen to
  109. ```
  110. ### 5b. The models, before the shots
  111. Follow `references/detail.md`: for each real object the film explains, find its blueprints first (technical and
  112. dimensional drawings, exploded views, parts lists, patent figures) and write the model sheet (the drawings, every
  113. part they show, real sizes) into the storyboard's `models` before drawing the board, so the board shows the real
  114. parts; build it with `kit/engine/parts3d.js`, render a turnaround (four angles and a
  115. close-up) and fix it until it passes the crop test. Only then build shots around it.
  116. ### 6. Build, one shot at a time
  117. Follow `references/engine.md`. Give each shot a `<section class="scene">` and animate it between
  118. `s.sNN.start` and `s.sNN.end`. Build in storyboard order and look at a still of each shot as you finish it:
  119. ```sh
  120. node kit/tools/render.mjs films/NAME --stills 1.5,4.2,7.9 # finished frames, a few seconds of work
  121. ```
  122. Compare each still with its drawn frame. What the frame placed at (x, y) is at (x, y).
  123. ### 7. Render
  124. ```sh
  125. node kit/tools/render.mjs films/NAME # out/picture.mp4, in four-second segments
  126. node kit/tools/render.mjs films/NAME --only 12-16 # after a fix: only the segments that changed
  127. ```
  128. A minute of film at 60 fps is about half an hour on four CPU cores. Run it in the background and write the cue
  129. sheet meanwhile.
  130. ### 8. Sound
  131. Follow `references/sound.md`: one music bed whose beat the cuts already sit on, and small clean effects on real
  132. events, written as `films/NAME/cues.json`. A bed composed for the film (`kit/audio/music.mjs`) fits better than a library track
  133. when the film will be published.
  134. ```sh
  135. python3 kit/audio/mix.py films/NAME # out/NAME.mp4, loudness measured on the finished file
  136. python3 kit/audio/mix.py films/NAME --no-sfx --out films/NAME/out/NAME-music-only.mp4
  137. ```
  138. `node kit/tools/make.mjs films/NAME` runs the commands of steps 4 to 9 in order (check, voice, render, mix, measure, a
  139. share copy) and stops at the first that fails. It does not replace looking at stills while you build.
  140. ### 9. Review, fix, verify
  141. Follow `references/review.md`: `node kit/tools/check.mjs films/NAME` (contact sheets, frozen time, loudness), then a
  142. fresh reviewer with the film, the storyboard and the person's own words. Fix the largest gaps, re-render only what
  143. changed, and have a new reviewer verify the list. Stop at the quality bar or when the gains turn cosmetic. When a
  144. fix changes what a shot shows, change the storyboard to say so and redraw the board: the plan and the film never
  145. disagree.
  146. ### 10. Deliver
  147. The MP4 (H.264, 1080p60, about -14 LUFS, true peak under -1 dBFS), a lighter copy for sharing, the music-only
  148. version, the storyboard pages, and a short honest note: what was measured, what was only looked at, what nobody has
  149. listened to, and what you would do next.
  150. ## The files of a film
  151. ```
  152. films/NAME/
  153. storyboard.json the plan: facts, acts, shots, drawn frames. The film reads its times from here
  154. storyboard.html the board (generated), storyboard/*.png its pages
  155. index.html one <section class="scene"> per shot or group of shots
  156. film.css this film's pieces, on top of kit/css/film.css
  157. film.js the timeline, built with kit/engine/motion.js
  158. cues.json the music bed and every sound, on the film's clock
  159. voice/ the narration: take.mp3, the time of every word, the cut (voice.json), subtitles.srt
  160. out/ renders (never committed)
  161. ```
  162. ## Working style
  163. - Plan where the person can see it (the board), then build to the finished film without asking about any step.
  164. - When work runs long, say in one line what you are doing.
  165. - Show the work: the board, stills, contact sheets, measured numbers, the reviewer's verdict.
README.md · README · 380 lines
  1. <div align="center">
  2. <img src="docs/media/hero.jpg" alt="Motion Educator: three frames from a film made with it" width="100%" />
  3. # Motion Educator
  4. **Educational films that look expensive, built in code, storyboard first.**
  5. An agent skill and the film engine behind it. You ask for an explainer; it draws the storyboard, waits for your yes,
  6. then renders a 1080p60 film frame by frame: detailed 3D replicas of real things shot by a directed camera, a lit
  7. stage, glass, metal type, diagrams, captions, narration, music and sound effects.
  8. [![test](https://github.com/zeative/motion-educator/actions/workflows/test.yml/badge.svg)](https://github.com/zeative/motion-educator/actions/workflows/test.yml)
  9. ![node](https://img.shields.io/badge/node-%E2%89%A5%2020-3c873a)
  10. ![output](https://img.shields.io/badge/output-1080p60%20%C2%B7%20landscape%20%2B%20portrait-4da3ff)
  11. ![voice](https://img.shields.io/badge/narration-ElevenLabs-111111)
  12. ![skill](https://img.shields.io/badge/works%20as-an%20agent%20skill-d97757)
  13. [![license](https://img.shields.io/badge/license-MIT-8a8f98)](LICENSE)
  14. [Quick start](#quick-start) · [How it works](#how-it-works) · [Gallery](#gallery) · [The kit](#the-kit) · [Docs](#docs)
  15. <br />
  16. <img src="docs/media/demo.webp" alt="Moments from films made with the skill" width="100%" />
  17. <sub>Moments from films made with the skill, each by an agent following it from the brief to the mix. Every frame is code: no stock footage, no video model.</sub>
  18. </div>
  19. <br />
  20. ## Why
  21. Most explainer videos made by an agent are slides with a voice. This one is held to a different standard:
  22. - **It is planned before it is built.** Nothing is rendered until an illustrated storyboard passes a checker and
  23. you have seen it.
  24. - **It is true.** Every number on screen sits in a fact sheet with its source and its arithmetic. A bar that
  25. stands for 5.9× is 5.9 times as tall.
  26. - **It shows the real thing.** A device, an organ or a machine is built in 3D as a replica of the one the viewer
  27. knows, from reference photographs and teardowns, and filmed like a product: orbits, push-ins, macro close-ups,
  28. parts lifting apart, labels riding on the parts.
  29. - **It explains itself on mute.** Captions carry the lesson; narration and sound make it land.
  30. - **It is graded by someone else.** A reviewer that did not build the film judges the render, and the fixes are
  31. re-rendered a segment at a time.
  32. ## What you get
  33. <table>
  34. <tr>
  35. <td width="33%" valign="top">
  36. ### 🎬 A film engine
  37. One paused timeline is the only clock, so any frame can be drawn by seeking to it. No dropped frames, no
  38. flicker, a fix re-renders four seconds, not the film, and the drawing runs on the GPU (or on every CPU core).
  39. </td>
  40. <td width="33%" valign="top">
  41. ### ✏️ A storyboard gate
  42. Pencil frames for every shot, drawn in the real frame's coordinates, with what each shot teaches, shows, moves,
  43. carries over and cites. A validator enforces the standard.
  44. </td>
  45. <td width="33%" valign="top">
  46. ### 🔊 Sound by measurement
  47. Narration through ElevenLabs, a music bed whose beat the cuts sit on, effects on real events, mastered to
  48. −14 LUFS and measured on the encoded file.
  49. </td>
  50. </tr>
  51. <tr>
  52. <td valign="top">
  53. ### 📐 Two formats
  54. `1920x1080` for lessons, `1080x1920` for shorts, from one field in the storyboard. A short gets safe areas for app
  55. chrome, captions lit word by word, and an ending that loops back into its start.
  56. </td>
  57. <td valign="top">
  58. ### 🎥 Real objects, a directed camera
  59. 3D replicas built from a model sheet (reference, parts, real sizes) with a parts kit and materials that have
  60. surface; a camera that orbits, pushes in and racks focus; exploded views, cutaways, pinned labels.
  61. </td>
  62. <td valign="top">
  63. ### 🔍 A review loop
  64. Stills while building, contact sheets and frozen-time checks after rendering, then independent critics with
  65. ready-made briefs. Their lessons are written back into the skill.
  66. </td>
  67. </tr>
  68. </table>
  69. ## Storyboard first
  70. The storyboard is not a sketch of intentions. It is the source of time for the film: shot starts and ends, captions
  71. and the chapter rail are read from it, and the frames are drawn where the pixels will be.
  72. <img src="docs/media/board-to-film.jpg" alt="Storyboard frames above, the rendered frames below" width="100%" />
  73. <sub>Top: frames from the storyboard. Bottom: the same moments in the render.</sub>
  74. The checker refuses a storyboard that has too few pictures (one about every 3.2 s), a shot drawn only once, a
  75. caption nobody could finish reading, a number with no fact behind it, a spoken line that will not fit its shot,
  76. three shots of the same kind in a row, a 3D object with no model sheet (which real version, from which reference,
  77. with which parts), a 3D shot with no camera move, or a short whose ending does not loop. Full standard: [`references/storyboard.md`](references/storyboard.md).
  78. ## Quick start
  79. ### As a skill
  80. ```sh
  81. git clone https://github.com/zeative/motion-educator ~/.claude/skills/motion-educator
  82. ```
  83. It is a plain [Agent Skills](https://agentskills.io) folder (`SKILL.md`, `references/`, a Node kit), so any agent
  84. that reads skills can use it. Clone it into the folder yours looks in:
  85. | Agent | For you (all projects) | For one project |
  86. | --- | --- | --- |
  87. | Claude Code | `~/.claude/skills/motion-educator` | `.claude/skills/motion-educator` |
  88. | OpenAI Codex | `~/.agents/skills/motion-educator` | `.agents/skills/motion-educator` |
  89. | Gemini CLI | `~/.gemini/skills/motion-educator` | `.gemini/skills/motion-educator` |
  90. | GitHub Copilot (CLI, cloud agent, VS Code agent mode) | `~/.copilot/skills/motion-educator` | `.github/skills/motion-educator` |
  91. | Cursor | reads `~/.claude/skills` and `~/.codex/skills` | `.cursor/skills/motion-educator` |
  92. An agent without skill support can still follow it: clone it anywhere and tell it to read `SKILL.md` there first.
  93. What the agent needs: a shell to run Node, FFmpeg and Python, and the ability to look at images, since it checks its
  94. own stills and contact sheets. Every film in this repository was made with Claude Code; the others are untested here.
  95. Then ask your agent for a film:
  96. > Make a 45-second explainer on why the Moon always shows us the same face. Portrait, English, with narration.
  97. It scaffolds a workspace in your project, writes and draws the storyboard, and stops for your approval before it
  98. builds anything.
  99. ### By hand
  100. ```sh
  101. git clone https://github.com/zeative/motion-educator && cd motion-educator
  102. npm install && bash kit/audio/fetch.sh
  103. node kit/tools/doctor.mjs # is this machine ready?
  104. node kit/tools/new.mjs ~/films moon-face --portrait # a workspace and films/moon-face
  105. cd ~/films && npm install && bash kit/audio/fetch.sh
  106. ```
  107. ```sh
  108. # 1. Write films/moon-face/storyboard.json, then check it and draw the board
  109. node kit/tools/storyboard.mjs films/moon-face --png
  110. # 2. Record the narration (optional) and let it set the shot lengths
  111. node kit/audio/voice.mjs films/moon-face --generate # one take, and the film cut to it (ELEVENLABS_API_KEY)
  112. # 3. Build index.html, film.css and film.js, looking at stills as you go
  113. node kit/tools/render.mjs films/moon-face --stills 1.5,4.2 --safe
  114. node kit/tools/render.mjs films/moon-face --serve # watch it live
  115. # 4. Everything else, in order: render, mix, measure, a share copy
  116. node kit/tools/make.mjs films/moon-face
  117. ```
  118. Requirements: Node 20+, FFmpeg, Python 3 with numpy, and Playwright's Chromium
  119. (`npm i -D playwright && npx playwright install chromium`). The renderer uses the GPU when there is one; on a Linux
  120. machine without one it needs Mesa's software Vulkan (`apt install mesa-vulkan-drivers`). `node kit/tools/doctor.mjs`
  121. checks all of it. See [Rendering](#rendering).
  122. ## Rendering
  123. Every frame is drawn by seeking the timeline in headless Chromium, so nothing is ever dropped, and the picture is
  124. cut into four-second segments so a fix re-renders only the seconds it touches. There is one renderer and it takes
  125. the fastest drawing the machine has, with nothing to configure: **the GPU** when there is one (any Mac or Windows
  126. machine, Linux with a GPU), otherwise **Mesa's lavapipe**, software Vulkan that spreads each frame over every CPU
  127. core. It prints which one it got.
  128. Measured on one heavy portrait frame (1080x1920, PBR materials, soft shadows, depth of field), on a CPU:
  129. | | Time per frame | Quality |
  130. | --- | --- | --- |
  131. | Before: Chromium's own software renderer, `page.screenshot` | 7.1 s | the reference |
  132. | Now: Mesa lavapipe, frames captured through the DevTools protocol | 1.1 s | PSNR 44.7 dB, SSIM 0.995 against the reference |
  133. | Now: depth of field that skips in-focus pixels and sizes its blur | the pass 245 → 125 ms | PSNR 45.4 dB, SSIM 0.997 |
  134. On a CPU about nine tenths of a frame is the 3D drawing itself, and it scales with cores. So the kit can also
  135. **render on a bigger machine**: a render worker runs in Docker anywhere you have room (a VPS, a home server, a
  136. Dokploy or Coolify host), capped in CPUs and memory and waiting before each job until the host has memory to spare,
  137. so the machine's other services keep theirs.
  138. ```sh
  139. # on the bigger machine: run kit/farm/compose.yml (set FARM_TOKEN; FARM_CPUS caps the cores), expose port 8080
  140. # then, from your workspace:
  141. FARM_URL=https://your-host/farm FARM_TOKEN=... node kit/tools/farm.mjs films/moon-face --segment 1
  142. ```
  143. It packs the kit and the film (with the segments already finished), sends them, follows the worker's log, and
  144. brings `out/picture.mp4` back; later fixes with `--only` render only what changed there too. Measured: a 4 s,
  145. 1080x1920, 60 fps 3D test took **91 s on a 10-core worker** against 320 s on a busy 4-core machine. For a long
  146. film at 60 fps, a GPU is still the way to minutes; a short at 30 fps renders in minutes on a worker.
  147. ## How it works
  148. ```mermaid
  149. flowchart LR
  150. A([Brief]) --> B[Fact sheet]
  151. B --> S[Script<br/>written as talk]
  152. S --> C[Storyboard<br/>drawn frames]
  153. C --> D{Check<br/>+ your yes}
  154. D -- no --> C
  155. D -- yes --> V[One take<br/>the cut follows the voice]
  156. V --> E[Build<br/>one shot at a time]
  157. E --> F[Render<br/>4 s segments]
  158. F --> G[Mix<br/>voice · music · SFX]
  159. G --> H[Measure]
  160. H --> I{Independent<br/>review}
  161. I -- fixes --> E
  162. I -- ship --> J([MP4])
  163. ```
  164. A film is a web page with one paused [GSAP](https://gsap.com) timeline. The renderer opens it in headless Chromium
  165. (WebGL on the GPU, or Mesa lavapipe without one), seeks the timeline to every frame in turn, captures it, and pipes
  166. the frames to FFmpeg, which adds bloom and grain. Four browsers render four-second segments in parallel; each
  167. segment is its own file, so changing one shot re-renders only the segments it touches. A render worker on a bigger
  168. machine can take the segments instead ([Rendering](#rendering)).
  169. Anything GSAP cannot hold exactly (a canvas, a shader, typed text, a dash offset) keeps its state in a plain object
  170. that the timeline tweens and a per-frame job draws. Nothing reads the wall clock, which is what makes every frame
  171. reproducible.
  172. ## Gallery
  173. <!-- gallery:start -->
  174. **Explainers** (16:9)
  175. <table>
  176. <tr>
  177. <td valign="top" align="center" width="300"><a href="docs/media/films/langit-biru.mp4"><img src="docs/media/previews/langit-biru.webp" alt="Kenapa langit berwarna biru?" width="300" /></a><br /><sub><a href="examples/langit-biru"><b>Kenapa langit berwarna biru?</b></a><br />Bahasa Indonesia · 67 s · captions · <a href="docs/media/films/langit-biru.mp4">▶ watch</a> · <a href="examples/langit-biru/storyboard">board</a></sub></td>
  178. <td valign="top" align="center" width="300"><a href="docs/media/films/how-gps-works.mp4"><img src="docs/media/previews/how-gps-works.webp" alt="How does your phone know where you are?" width="300" /></a><br /><sub><a href="examples/how-gps-works"><b>How does your phone know where you are?</b></a><br />English · 60 s · captions · <a href="docs/media/films/how-gps-works.mp4">▶ watch</a> · <a href="examples/how-gps-works/storyboard">board</a></sub></td>
  179. </tr>
  180. <tr>
  181. <td valign="top" align="center" width="300"><a href="docs/media/films/why-seasons.mp4"><img src="docs/media/previews/why-seasons.webp" alt="Why do we have seasons?" width="300" /></a><br /><sub><a href="examples/why-seasons"><b>Why do we have seasons?</b></a><br />English · 57 s · captions · <a href="docs/media/films/why-seasons.mp4">▶ watch</a> · <a href="examples/why-seasons/storyboard">board</a></sub></td>
  182. <td valign="top" align="center" width="300"><a href="docs/media/films/bunga-majemuk.mp4"><img src="docs/media/previews/bunga-majemuk.webp" alt="Kok uang bisa beranak? Gimana bunga majemuk bekerja?" width="300" /></a><br /><sub><a href="examples/bunga-majemuk"><b>Kok uang bisa beranak? Gimana bunga majemuk bekerja?</b></a><br />Bahasa Indonesia · 52 s · captions · <a href="docs/media/films/bunga-majemuk.mp4">▶ watch</a> · <a href="examples/bunga-majemuk/storyboard">board</a></sub></td>
  183. </tr>
  184. </table>
  185. **Shorts** (9:16)
  186. <table>
  187. <tr>
  188. <td valign="top" align="center" width="170"><a href="docs/media/films/luka-sembuh.mp4"><img src="docs/media/previews/luka-sembuh.webp" alt="Gimana sih luka bisa nutup sendiri?" width="170" /></a><br /><sub><a href="examples/luka-sembuh"><b>Gimana sih luka bisa nutup sendiri?</b></a><br />Bahasa Indonesia · 53 s · voice: Livna · <a href="docs/media/films/luka-sembuh.mp4">▶ watch</a> · <a href="examples/luka-sembuh/storyboard">board</a></sub></td>
  189. <td valign="top" align="center" width="170"><a href="docs/media/films/hoaks-diulang.mp4"><img src="docs/media/previews/hoaks-diulang.webp" alt="Kenapa hoaks yang diulang-ulang lama-lama terasa benar?" width="170" /></a><br /><sub><a href="examples/hoaks-diulang"><b>Kenapa hoaks yang diulang-ulang lama-lama terasa benar?</b></a><br />Bahasa Indonesia · 50 s · voice: Jefri · <a href="docs/media/films/hoaks-diulang.mp4">▶ watch</a> · <a href="examples/hoaks-diulang/storyboard">board</a></sub></td>
  190. <td valign="top" align="center" width="170"><a href="docs/media/films/hp-lemot.mp4"><img src="docs/media/previews/hp-lemot.webp" alt="Kenapa HP makin lemot pas memorinya hampir penuh?" width="170" /></a><br /><sub><a href="examples/hp-lemot"><b>Kenapa HP makin lemot pas memorinya hampir penuh?</b></a><br />Bahasa Indonesia · 45 s · voice: Rafiq · <a href="docs/media/films/hp-lemot.mp4">▶ watch</a> · <a href="examples/hp-lemot/storyboard">board</a></sub></td>
  191. <td valign="top" align="center" width="170"><a href="docs/media/films/petir-guntur.mp4"><img src="docs/media/previews/petir-guntur.webp" alt="Kenapa petir terlihat dulu, baru guntur terdengar?" width="170" /></a><br /><sub><a href="examples/petir-guntur"><b>Kenapa petir terlihat dulu, baru guntur terdengar?</b></a><br />Bahasa Indonesia · 40 s · voice: Rafiq · <a href="docs/media/films/petir-guntur.mp4">▶ watch</a> · <a href="examples/petir-guntur/storyboard">board</a></sub></td>
  192. </tr>
  193. <tr>
  194. <td valign="top" align="center" width="170"><a href="docs/media/films/float-math.mp4"><img src="docs/media/previews/float-math.webp" alt="Why does 0.1 + 0.2 not equal 0.3?" width="170" /></a><br /><sub><a href="examples/float-math"><b>Why does 0.1 + 0.2 not equal 0.3?</b></a><br />English · 35 s · captions · <a href="docs/media/films/float-math.mp4">▶ watch</a> · <a href="examples/float-math/storyboard">board</a></sub></td>
  195. <td valign="top" align="center" width="170"><a href="docs/media/films/es-mengapung.mp4"><img src="docs/media/previews/es-mengapung.webp" alt="Kenapa es malah ngapung di air?" width="170" /></a><br /><sub><a href="examples/es-mengapung"><b>Kenapa es malah ngapung di air?</b></a><br />Bahasa Indonesia · 32 s · captions · <a href="docs/media/films/es-mengapung.mp4">▶ watch</a> · <a href="examples/es-mengapung/storyboard">board</a></sub></td>
  196. </tr>
  197. </table>
  198. <sub>Every preview is a few seconds of the finished film, looping. Click one for the whole film (720p, sound on). 10 films, each made by an agent following this skill from the brief to the mix.</sub>
  199. <!-- gallery:end -->
  200. ## Narration
  201. A film can explain with captions alone, or speak. When it speaks, it is written as one piece of talk, performed as
  202. one continuous take with [ElevenLabs](https://elevenlabs.io), and the picture is cut to the voice: a shot starts
  203. just before its first word, and the performer's own pauses are kept. The take's word times drive captions that
  204. light up as each word is said, and the mixer runs the voice through a de-esser and compression and pulls the music
  205. down under it.
  206. ```json
  207. {
  208. "voice": { "voice_id": "…", "name": "Jefri", "model": "eleven_v4", "language": "id", "direction": "[warmly]" },
  209. "shots": [
  210. { "id": "s01", "voice": "Kenapa sih kilat selalu kelihatan duluan, baru gunturnya nyusul?" },
  211. { "id": "s02", "voice": "Padahal dua-duanya muncul barengan, lho.", "caption": "muncul *barengan*" }
  212. ]
  213. }
  214. ```
  215. A short loops: its last line is the first half of a sentence its first line finishes, its last frame is its first
  216. shot's picture a moment early, and the music runs on across the seam, so a replay feels like the same film going
  217. on. The mixer measures the pause at the seam and the checker compares the two frames.
  218. The storyboard check reads the script as a listener would: sentences too long for the ear, clipped sentences in a
  219. row, digits in a spoken line, textbook Indonesian ("tidak", "hanya", "oleh karena itu") and phrases that give a
  220. machine away. How to write it: [`references/narration.md`](references/narration.md). How to perform and cut it:
  221. [`references/voice.md`](references/voice.md).
  222. ## The kit
  223. | File | What it is |
  224. | --- | --- |
  225. | [`kit/engine/motion.js`](kit/engine/motion.js) | the film engine: one timeline, scenes, type, captions, chapters, whips, hits |
  226. | [`kit/engine/stage.js`](kit/engine/stage.js) | the stage: one fragment shader of flowing light, a floor, dust, shock rings |
  227. | [`kit/engine/stage3d.js`](kit/engine/stage3d.js) | the 3D layer: a directed camera, depth of field, soft shadows, pinned labels, exploded views, cutaways |
  228. | [`kit/engine/parts3d.js`](kit/engine/parts3d.js) | materials with real surface and ready-made parts: boards, chips, drivers, mics, screws, a desk set |
  229. | [`kit/tools/anatomy.mjs`](kit/tools/anatomy.mjs), [`kit/engine/body3d.js`](kit/engine/body3d.js) | real human anatomy (BodyParts3D, measured from a real body): bones, muscles with their tendons, skin; tissue materials, joints that bend, muscles that flex, skin that turns to glass |
  230. | [`kit/engine/tissue3d.js`](kit/engine/tissue3d.js) | skeletal muscle from the whole muscle down to its molecules, at measured sizes with sources: fascicles, fibres with their nuclei and satellite cells, myofibrils, sarcomeres that slide, hypertrophy |
  231. | [`kit/css/film.css`](kit/css/film.css) | the look: tokens, glass, metal type, captions, panels, safe areas |
  232. | [`kit/tools/storyboard.mjs`](kit/tools/storyboard.mjs), [`sketch.mjs`](kit/tools/sketch.mjs) | the storyboard check and the pencil board |
  233. | [`kit/tools/render.mjs`](kit/tools/render.mjs) | frame-by-frame render in segments, stills, live preview; on the GPU, or Mesa lavapipe without one |
  234. | [`kit/tools/farm.mjs`](kit/tools/farm.mjs), [`kit/farm/`](kit/farm) | render on a bigger machine: the client, and the worker with its Docker Compose file |
  235. | [`kit/audio/voice.mjs`](kit/audio/voice.mjs) | narration: one take, matched to the script word by word, and the film cut to it |
  236. | [`kit/audio/music.mjs`](kit/audio/music.mjs) | a music bed composed for the film's length with ElevenLabs Music, and its status |
  237. | [`kit/audio/mix.py`](kit/audio/mix.py) | the mixer: voice, music, effects, ducking, mastering, the loop seam, measurement |
  238. | [`kit/tools/check.mjs`](kit/tools/check.mjs) | contact sheets, frozen time, loudness, the loop seam |
  239. | [`kit/tools/make.mjs`](kit/tools/make.mjs) | the whole pipeline in one command |
  240. | [`kit/tools/doctor.mjs`](kit/tools/doctor.mjs), [`test.mjs`](kit/tools/test.mjs) | environment check and a smoke test of everything above |
  241. ```
  242. motion-educator/
  243. ├── SKILL.md the skill: what never bends, and the workflow
  244. ├── references/ how to teach on screen, storyboard, look, detail and camera, engine, motion, narration, voice, sound, review
  245. ├── kit/ the engine and its tools (copied into each workspace)
  246. ├── templates/film/ what a new film starts from
  247. └── examples/ finished films with their storyboards, source and cue sheets
  248. ```
  249. ## Docs
  250. | When you are… | Read |
  251. | --- | --- |
  252. | deciding what to teach and in what order | [`references/pedagogy.md`](references/pedagogy.md) |
  253. | writing and drawing the storyboard | [`references/storyboard.md`](references/storyboard.md) |
  254. | choosing the look, or making a portrait short | [`references/look.md`](references/look.md) |
  255. | building a film with the kit, and rendering it fast | [`references/engine.md`](references/engine.md), [`references/motion.md`](references/motion.md) |
  256. | building real objects in 3D and directing the camera | [`references/detail.md`](references/detail.md) |
  257. | writing narration that sounds like talk | [`references/narration.md`](references/narration.md) |
  258. | choosing a voice, performing the take, cutting to it | [`references/voice.md`](references/voice.md) |
  259. | choosing music and placing sounds | [`references/sound.md`](references/sound.md) |
  260. | checking a render and briefing a reviewer | [`references/review.md`](references/review.md) |
  261. ## Honest limits
  262. - **Nobody has heard the films.** The agent that makes them cannot listen: sound is chosen by description and set
  263. by measurement, and each delivery says what a person should listen for.
  264. - **Rendering is slow without a GPU.** On a CPU, heavy 3D draws at about one frame a second per four cores, so a
  265. minute of 1080p60 takes the better part of an hour on a small machine. A GPU, or a render worker on a machine
  266. with more cores ([Rendering](#rendering)), is the way to minutes.
  267. - **The sound library is not in the repository.** Music and effects come from [Mixkit](https://mixkit.co), whose
  268. licence allows them inside a video but not passed on as files; `kit/audio/fetch.sh` downloads them.
  269. - **Narration and composed music cost credits** on your ElevenLabs account.
  270. - **A replica is only as good as its references.** When good photographs of the real object cannot be found, the
  271. agent asks you for some; without them, it says what it could not match.
  272. ## Licence
  273. [MIT](LICENSE). The films you make with it are yours: the licence covers this repository's code, documents and
  274. examples, not what you render.
  275. What is not ours to license, and how it is handled:
  276. | Thing | Its terms | In this repository |
  277. | --- | --- | --- |
  278. | [GSAP](https://gsap.com) | GSAP's own no-charge licence (not MIT) | a dependency installed from npm, not redistributed |
  279. | [three.js](https://threejs.org) | MIT | a dependency installed from npm |
  280. | Sora, Inter, JetBrains Mono, Instrument Serif, Patrick Hand | SIL Open Font License | installed from npm |
  281. | Music and sound effects | [Mixkit](https://mixkit.co)'s licences: free inside a video, not to be passed on as files | not included; `kit/audio/fetch.sh` downloads them |
  282. | Narration in the example films | generated with [ElevenLabs](https://elevenlabs.io); your rights to voices you generate depend on your own plan | the examples' recordings are included so they can be re-mixed |
  283. | Earth maps in the examples | NASA imagery, not copyrighted | included, with [sources](examples/langit-biru/assets/SOURCES.md) |
  284. ## Credits
  285. - [GSAP](https://gsap.com) and [three.js](https://threejs.org) do the animating and the 3D.
  286. - Fonts: Sora, Inter, JetBrains Mono, Instrument Serif and Patrick Hand (SIL Open Font License), from npm.
  287. - The Earth in the worked example uses NASA's Blue Marble and Earth at Night maps, which are not copyrighted
  288. ([sources](examples/langit-biru/assets/SOURCES.md)).
  289. - The composition shape (a fixed-size root and one paused timeline at `window.__timelines.root`) follows
  290. [Null Motion](https://github.com/blixvip/NullMotion)'s HyperFrames convention.
  291. <div align="center">
  292. <br />
  293. <sub>Built storyboard first.</sub>
  294. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.