motion-educator
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.
Badge for your README
Markdown
[](/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
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
- ---
- name: motion-educator
- 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.
- ---
- # Motion Educator
- You make short educational films (20 to 120 seconds, landscape explainers or portrait shorts) that look expensive
- and teach one thing well. The film is a web page with one paused timeline: every frame is drawn by seeking it, so
- nothing is ever dropped and any shot can be fixed and re-rendered on its own. The kit in this skill is that engine.
- `examples/` holds finished films made by following this skill, each with its storyboard, source, cue sheet and
- narration: `langit-biru` (captions only, the most reviewed) and `petir-guntur` (a narrated short) are the ones to
- read first.
- ## The flow, as the person sees it
- **Their prompt → your research (the topic, the blueprints, the narration) → the storyboard, sent to them → their yes
- → the finished film.** The storyboard is the only stop. Everything they might want to weigh in on goes into it: the
- script, the voice, the length, the real version of each object and the drawings it is built from. After their yes
- you build, check, review and fix on your own and deliver the best film you can make, without asking again.
- - **Decide; do not hand the person choices.** When sources disagree or a detail is open, choose what is most
- faithful to the real thing the viewer knows and to the drawings (`references/detail.md` says how), write the
- choice and its reason in the delivery note, and carry on. Ask only when the film cannot be made without them
- (a missing drawing or photo that changes what the film shows), and ask it with the storyboard, not after.
- - **Quality is checked by you and by a fresh reviewer, not by the person.** The model against every blueprint, the
- stills against the board, the render against the five detail checks, the independent review, the fixes: all of
- it happens before delivery. The person sees the board once and the finished film once.
- Read only the reference your current step needs.
- | Step | Read |
- | --- | --- |
- | Deciding what to teach and in what order | `references/pedagogy.md` |
- | Writing and drawing the storyboard (the gate) | `references/storyboard.md` |
- | Choosing the look, the accent, the stage light, 3D | `references/look.md` |
- | Building real things in detail; directing the camera | `references/detail.md` |
- | Building the film with the kit | `references/engine.md`, then `references/motion.md` |
- | Writing the narration: talk, not captions; Indonesian and English register | `references/narration.md` |
- | The voice: choosing it, performing one take with ElevenLabs, cutting the film to it | `references/voice.md` |
- | Music, sound effects, the mix | `references/sound.md` |
- | Checking the render, independent review | `references/review.md` |
- ## What never bends
- 1. **Storyboard first, and it is drawn.** No film file is written until `storyboard.json` passes
- `kit/tools/storyboard.mjs` with zero errors and the person has seen the board. Every shot has drawn frames (how
- it starts, what happens, how it ends), sketched in the real frame's coordinates, so the build can be cut
- straight from them. If the person asked for an unattended run, send the board and keep going; otherwise wait for
- their yes. That yes is the last thing you wait for: from there to the finished film, you decide.
- 2. **True, with sources.** Every number and every claim on screen is in the storyboard's fact sheet with where it
- comes from. If you cannot source it, do not say it. What is drawn agrees with what is written: a bar, a meter
- or a path that stands for a number is computed from that number, a diagram that is not to scale says so on
- screen, and a number appears at its value (no counting up through values that are false).
- 3. **It explains itself on mute.** The picture and the words on screen carry the explanation; the voice and the
- 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
- (what goes in, what it meets, what comes out, where it ends up), never left to the caption alone.
- 4. **One clock.** Every animated value is a function of the timeline's time. No CSS animations, no
- `requestAnimationFrame` loops, no `Date.now()`, no unseeded randomness.
- 5. **The storyboard is the source of time.** The film reads shot starts and ends from `storyboard.json`; captions
- and the chapter rail are generated from it. Change the plan there, never by hand in the film. In a film that
- speaks, the recorded take writes those times (`voice.mjs`).
- 6. **You do not grade your own work.** Stills of every shot are looked at before a full render, measurements are
- run on the render, and a fresh reviewer who did not build it judges the result (`references/review.md`).
- 7. **A film that speaks is written as talk and performed as one take.** The script is written whole and said
- aloud before any shot exists; it is performed once, start to finish, and the picture is cut to the voice. Never
- one sentence a shot, never one recording a sentence, never a pause trimmed to fit a plan.
- 8. **Real things are built, not symbolised, and the camera is directed.** A device, an organ, a plant, a machine
- the film explains is a replica: the version the viewer knows where they live, researched from photographs and
- 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
- camera move, and when the voice names a part the camera goes to it (`references/detail.md`).
- 9. **Say what was not checked.** You cannot hear. Say that the mix was set by measurement, name what a person
- should listen for, and deliver a music-only version beside the full mix.
- ## Workflow
- ### 0. A workspace
- The kit is copied into the person's project, never used from the skill's own folder.
- ```sh
- node <skill>/kit/tools/new.mjs <workspace> <film-name> # copies kit/ and package.json if missing, scaffolds films/<film-name>/
- cd <workspace> && npm install # three.js, GSAP, the fonts
- bash kit/audio/fetch.sh # the sound library (not committed: licence)
- ```
- Needs Node 20+, Playwright with Chromium, FFmpeg, and Python 3 with numpy for the mix. `node kit/tools/doctor.mjs`
- checks all of it and says what to install. Add `--portrait` to `new.mjs` for a 1080x1920 short.
- ### 1. Brief (a few lines, in the storyboard's head)
- Who is watching, what they already know, and the **promise**: the one sentence they can say after watching. One
- film, one promise. If the topic needs two promises, it is two films. Pick the language the audience reads, the
- format (landscape for a lesson, portrait for a short) and whether the film speaks or explains with captions alone.
- ### 2. Research and the fact sheet
- List every claim the film will make, each with its source, as `facts` in `storyboard.json`. Prefer primary and
- institutional sources. Do the arithmetic yourself and show it (a number like "5,9x" is written with what it is
- computed from). Write down what you are simplifying, and decide how the film will be honest about it.
- Research does not stop at the first closed door. When a page will not open, try the other routes before you call
- it unavailable: the same document elsewhere (Google Patents for patents, with its drawings on
- patentimages.storage.googleapis.com; Wikimedia Commons for photographs; the manufacturer's PDF catalogue; an archived
- copy), a direct download with `curl`, a different search. Read images by downloading them and looking at them. Say
- exactly which address failed and how, and only then ask the person for what is still missing. A mechanism or a
- real object is never filled in from memory because a search was hard (`references/detail.md`).
- ### 3. The script, if the film speaks
- Follow `references/narration.md`: one question, written as continuous talk in the audience's own register, said
- aloud and timed, before there is a shot list. Then cut it into shots: each speaking shot's `voice` is its run of
- the script.
- ### 4. The storyboard: the gate
- Follow `references/storyboard.md`. In short: acts, then shots (a new picture about every three seconds), each shot
- with what it teaches, its caption, what is on screen, the motion, what carries into the next shot, the transition,
- the sound, what to check, the facts it cites, and **two or three drawn frames**. Cut on the music's beat.
- ```sh
- node kit/tools/storyboard.mjs films/NAME --png # zero errors, then show films/NAME/storyboard/*.png
- ```
- Send the pages to the person. The contact sheets (the whole film in frames) go first.
- ### 5. The take, if the film speaks
- Follow `references/voice.md`: choose a voice native to the language (let the person hear two or three if you can),
- perform the whole script as one take, and cut the film to it. The storyboard's times are the take's from here on.
- ```sh
- node kit/audio/voice.mjs films/NAME --script # the take to perform
- node kit/audio/voice.mjs films/NAME --generate # with an API key: the take and its word times
- node kit/audio/voice.mjs films/NAME --take AUDIO --words WORDS # with a speech connector: hand both back
- node kit/audio/voice.mjs films/NAME # every shot's time, and the words to listen to
- ```
- ### 5b. The models, before the shots
- Follow `references/detail.md`: for each real object the film explains, find its blueprints first (technical and
- dimensional drawings, exploded views, parts lists, patent figures) and write the model sheet (the drawings, every
- part they show, real sizes) into the storyboard's `models` before drawing the board, so the board shows the real
- parts; build it with `kit/engine/parts3d.js`, render a turnaround (four angles and a
- close-up) and fix it until it passes the crop test. Only then build shots around it.
- ### 6. Build, one shot at a time
- Follow `references/engine.md`. Give each shot a `<section class="scene">` and animate it between
- `s.sNN.start` and `s.sNN.end`. Build in storyboard order and look at a still of each shot as you finish it:
- ```sh
- node kit/tools/render.mjs films/NAME --stills 1.5,4.2,7.9 # finished frames, a few seconds of work
- ```
- Compare each still with its drawn frame. What the frame placed at (x, y) is at (x, y).
- ### 7. Render
- ```sh
- node kit/tools/render.mjs films/NAME # out/picture.mp4, in four-second segments
- node kit/tools/render.mjs films/NAME --only 12-16 # after a fix: only the segments that changed
- ```
- 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
- sheet meanwhile.
- ### 8. Sound
- Follow `references/sound.md`: one music bed whose beat the cuts already sit on, and small clean effects on real
- events, written as `films/NAME/cues.json`. A bed composed for the film (`kit/audio/music.mjs`) fits better than a library track
- when the film will be published.
- ```sh
- python3 kit/audio/mix.py films/NAME # out/NAME.mp4, loudness measured on the finished file
- python3 kit/audio/mix.py films/NAME --no-sfx --out films/NAME/out/NAME-music-only.mp4
- ```
- `node kit/tools/make.mjs films/NAME` runs the commands of steps 4 to 9 in order (check, voice, render, mix, measure, a
- share copy) and stops at the first that fails. It does not replace looking at stills while you build.
- ### 9. Review, fix, verify
- Follow `references/review.md`: `node kit/tools/check.mjs films/NAME` (contact sheets, frozen time, loudness), then a
- fresh reviewer with the film, the storyboard and the person's own words. Fix the largest gaps, re-render only what
- changed, and have a new reviewer verify the list. Stop at the quality bar or when the gains turn cosmetic. When a
- fix changes what a shot shows, change the storyboard to say so and redraw the board: the plan and the film never
- disagree.
- ### 10. Deliver
- The MP4 (H.264, 1080p60, about -14 LUFS, true peak under -1 dBFS), a lighter copy for sharing, the music-only
- version, the storyboard pages, and a short honest note: what was measured, what was only looked at, what nobody has
- listened to, and what you would do next.
- ## The files of a film
- ```
- films/NAME/
- storyboard.json the plan: facts, acts, shots, drawn frames. The film reads its times from here
- storyboard.html the board (generated), storyboard/*.png its pages
- index.html one <section class="scene"> per shot or group of shots
- film.css this film's pieces, on top of kit/css/film.css
- film.js the timeline, built with kit/engine/motion.js
- cues.json the music bed and every sound, on the film's clock
- voice/ the narration: take.mp3, the time of every word, the cut (voice.json), subtitles.srt
- out/ renders (never committed)
- ```
- ## Working style
- - Plan where the person can see it (the board), then build to the finished film without asking about any step.
- - When work runs long, say in one line what you are doing.
- - Show the work: the board, stills, contact sheets, measured numbers, the reviewer's verdict.
README.md · README · 380 lines
- <div align="center">
- <img src="docs/media/hero.jpg" alt="Motion Educator: three frames from a film made with it" width="100%" />
- # Motion Educator
- **Educational films that look expensive, built in code, storyboard first.**
- An agent skill and the film engine behind it. You ask for an explainer; it draws the storyboard, waits for your yes,
- then renders a 1080p60 film frame by frame: detailed 3D replicas of real things shot by a directed camera, a lit
- stage, glass, metal type, diagrams, captions, narration, music and sound effects.
- [](https://github.com/zeative/motion-educator/actions/workflows/test.yml)
- 
- 
- 
- 
- [](LICENSE)
- [Quick start](#quick-start) · [How it works](#how-it-works) · [Gallery](#gallery) · [The kit](#the-kit) · [Docs](#docs)
- <br />
- <img src="docs/media/demo.webp" alt="Moments from films made with the skill" width="100%" />
- <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>
- </div>
- <br />
- ## Why
- Most explainer videos made by an agent are slides with a voice. This one is held to a different standard:
- - **It is planned before it is built.** Nothing is rendered until an illustrated storyboard passes a checker and
- you have seen it.
- - **It is true.** Every number on screen sits in a fact sheet with its source and its arithmetic. A bar that
- stands for 5.9× is 5.9 times as tall.
- - **It shows the real thing.** A device, an organ or a machine is built in 3D as a replica of the one the viewer
- knows, from reference photographs and teardowns, and filmed like a product: orbits, push-ins, macro close-ups,
- parts lifting apart, labels riding on the parts.
- - **It explains itself on mute.** Captions carry the lesson; narration and sound make it land.
- - **It is graded by someone else.** A reviewer that did not build the film judges the render, and the fixes are
- re-rendered a segment at a time.
- ## What you get
- <table>
- <tr>
- <td width="33%" valign="top">
- ### 🎬 A film engine
- One paused timeline is the only clock, so any frame can be drawn by seeking to it. No dropped frames, no
- flicker, a fix re-renders four seconds, not the film, and the drawing runs on the GPU (or on every CPU core).
- </td>
- <td width="33%" valign="top">
- ### ✏️ A storyboard gate
- Pencil frames for every shot, drawn in the real frame's coordinates, with what each shot teaches, shows, moves,
- carries over and cites. A validator enforces the standard.
- </td>
- <td width="33%" valign="top">
- ### 🔊 Sound by measurement
- Narration through ElevenLabs, a music bed whose beat the cuts sit on, effects on real events, mastered to
- −14 LUFS and measured on the encoded file.
- </td>
- </tr>
- <tr>
- <td valign="top">
- ### 📐 Two formats
- `1920x1080` for lessons, `1080x1920` for shorts, from one field in the storyboard. A short gets safe areas for app
- chrome, captions lit word by word, and an ending that loops back into its start.
- </td>
- <td valign="top">
- ### 🎥 Real objects, a directed camera
- 3D replicas built from a model sheet (reference, parts, real sizes) with a parts kit and materials that have
- surface; a camera that orbits, pushes in and racks focus; exploded views, cutaways, pinned labels.
- </td>
- <td valign="top">
- ### 🔍 A review loop
- Stills while building, contact sheets and frozen-time checks after rendering, then independent critics with
- ready-made briefs. Their lessons are written back into the skill.
- </td>
- </tr>
- </table>
- ## Storyboard first
- The storyboard is not a sketch of intentions. It is the source of time for the film: shot starts and ends, captions
- and the chapter rail are read from it, and the frames are drawn where the pixels will be.
- <img src="docs/media/board-to-film.jpg" alt="Storyboard frames above, the rendered frames below" width="100%" />
- <sub>Top: frames from the storyboard. Bottom: the same moments in the render.</sub>
- The checker refuses a storyboard that has too few pictures (one about every 3.2 s), a shot drawn only once, a
- caption nobody could finish reading, a number with no fact behind it, a spoken line that will not fit its shot,
- three shots of the same kind in a row, a 3D object with no model sheet (which real version, from which reference,
- 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).
- ## Quick start
- ### As a skill
- ```sh
- 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
- ```sh
- 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
- ```
- ```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).
- ## Rendering
- Every frame is drawn by seeking the timeline in headless Chromium, so nothing is ever dropped, and the picture is
- cut into four-second segments so a fix re-renders only the seconds it touches. There is one renderer and it takes
- the fastest drawing the machine has, with nothing to configure: **the GPU** when there is one (any Mac or Windows
- machine, Linux with a GPU), otherwise **Mesa's lavapipe**, software Vulkan that spreads each frame over every CPU
- core. It prints which one it got.
- Measured on one heavy portrait frame (1080x1920, PBR materials, soft shadows, depth of field), on a CPU:
- | | Time per frame | Quality |
- | --- | --- | --- |
- | Before: Chromium's own software renderer, `page.screenshot` | 7.1 s | the reference |
- | Now: Mesa lavapipe, frames captured through the DevTools protocol | 1.1 s | PSNR 44.7 dB, SSIM 0.995 against the reference |
- | 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 |
- On a CPU about nine tenths of a frame is the 3D drawing itself, and it scales with cores. So the kit can also
- **render on a bigger machine**: a render worker runs in Docker anywhere you have room (a VPS, a home server, a
- Dokploy or Coolify host), capped in CPUs and memory and waiting before each job until the host has memory to spare,
- so the machine's other services keep theirs.
- ```sh
- # on the bigger machine: run kit/farm/compose.yml (set FARM_TOKEN; FARM_CPUS caps the cores), expose port 8080
- # then, from your workspace:
- FARM_URL=https://your-host/farm FARM_TOKEN=... node kit/tools/farm.mjs films/moon-face --segment 1
- ```
- It packs the kit and the film (with the segments already finished), sends them, follows the worker's log, and
- brings `out/picture.mp4` back; later fixes with `--only` render only what changed there too. Measured: a 4 s,
- 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
- film at 60 fps, a GPU is still the way to minutes; a short at 30 fps renders in minutes on a worker.
- ## How it works
- ```mermaid
- flowchart LR
- A([Brief]) --> B[Fact sheet]
- B --> S[Script<br/>written as talk]
- S --> C[Storyboard<br/>drawn frames]
- C --> D{Check<br/>+ your yes}
- D -- no --> C
- D -- yes --> V[One take<br/>the cut follows the voice]
- V --> E[Build<br/>one shot at a time]
- E --> F[Render<br/>4 s segments]
- F --> G[Mix<br/>voice · music · SFX]
- G --> H[Measure]
- H --> I{Independent<br/>review}
- I -- fixes --> E
- I -- ship --> J([MP4])
- ```
- A film is a web page with one paused [GSAP](https://gsap.com) timeline. The renderer opens it in headless Chromium
- (WebGL on the GPU, or Mesa lavapipe without one), seeks the timeline to every frame in turn, captures it, and pipes
- the frames to FFmpeg, which adds bloom and grain. Four browsers render four-second segments in parallel; each
- segment is its own file, so changing one shot re-renders only the segments it touches. A render worker on a bigger
- machine can take the segments instead ([Rendering](#rendering)).
- Anything GSAP cannot hold exactly (a canvas, a shader, typed text, a dash offset) keeps its state in a plain object
- that the timeline tweens and a per-frame job draws. Nothing reads the wall clock, which is what makes every frame
- reproducible.
- ## Gallery
- <!-- gallery:start -->
- **Explainers** (16:9)
- <table>
- <tr>
- <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>
- <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>
- </tr>
- <tr>
- <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>
- <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>
- </tr>
- </table>
- **Shorts** (9:16)
- <table>
- <tr>
- <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>
- <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>
- <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>
- <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>
- </tr>
- <tr>
- <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>
- <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>
- </tr>
- </table>
- <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>
- <!-- gallery:end -->
- ## Narration
- A film can explain with captions alone, or speak. When it speaks, it is written as one piece of talk, performed as
- one continuous take with [ElevenLabs](https://elevenlabs.io), and the picture is cut to the voice: a shot starts
- just before its first word, and the performer's own pauses are kept. The take's word times drive captions that
- light up as each word is said, and the mixer runs the voice through a de-esser and compression and pulls the music
- down under it.
- ```json
- {
- "voice": { "voice_id": "…", "name": "Jefri", "model": "eleven_v4", "language": "id", "direction": "[warmly]" },
- "shots": [
- { "id": "s01", "voice": "Kenapa sih kilat selalu kelihatan duluan, baru gunturnya nyusul?" },
- { "id": "s02", "voice": "Padahal dua-duanya muncul barengan, lho.", "caption": "muncul *barengan*" }
- ]
- }
- ```
- A short loops: its last line is the first half of a sentence its first line finishes, its last frame is its first
- shot's picture a moment early, and the music runs on across the seam, so a replay feels like the same film going
- on. The mixer measures the pause at the seam and the checker compares the two frames.
- The storyboard check reads the script as a listener would: sentences too long for the ear, clipped sentences in a
- row, digits in a spoken line, textbook Indonesian ("tidak", "hanya", "oleh karena itu") and phrases that give a
- machine away. How to write it: [`references/narration.md`](references/narration.md). How to perform and cut it:
- [`references/voice.md`](references/voice.md).
- ## The kit
- | File | What it is |
- | --- | --- |
- | [`kit/engine/motion.js`](kit/engine/motion.js) | the film engine: one timeline, scenes, type, captions, chapters, whips, hits |
- | [`kit/engine/stage.js`](kit/engine/stage.js) | the stage: one fragment shader of flowing light, a floor, dust, shock rings |
- | [`kit/engine/stage3d.js`](kit/engine/stage3d.js) | the 3D layer: a directed camera, depth of field, soft shadows, pinned labels, exploded views, cutaways |
- | [`kit/engine/parts3d.js`](kit/engine/parts3d.js) | materials with real surface and ready-made parts: boards, chips, drivers, mics, screws, a desk set |
- | [`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 |
- | [`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 |
- | [`kit/css/film.css`](kit/css/film.css) | the look: tokens, glass, metal type, captions, panels, safe areas |
- | [`kit/tools/storyboard.mjs`](kit/tools/storyboard.mjs), [`sketch.mjs`](kit/tools/sketch.mjs) | the storyboard check and the pencil board |
- | [`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 |
- | [`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 |
- | [`kit/audio/voice.mjs`](kit/audio/voice.mjs) | narration: one take, matched to the script word by word, and the film cut to it |
- | [`kit/audio/music.mjs`](kit/audio/music.mjs) | a music bed composed for the film's length with ElevenLabs Music, and its status |
- | [`kit/audio/mix.py`](kit/audio/mix.py) | the mixer: voice, music, effects, ducking, mastering, the loop seam, measurement |
- | [`kit/tools/check.mjs`](kit/tools/check.mjs) | contact sheets, frozen time, loudness, the loop seam |
- | [`kit/tools/make.mjs`](kit/tools/make.mjs) | the whole pipeline in one command |
- | [`kit/tools/doctor.mjs`](kit/tools/doctor.mjs), [`test.mjs`](kit/tools/test.mjs) | environment check and a smoke test of everything above |
- ```
- motion-educator/
- ├── SKILL.md the skill: what never bends, and the workflow
- ├── references/ how to teach on screen, storyboard, look, detail and camera, engine, motion, narration, voice, sound, review
- ├── kit/ the engine and its tools (copied into each workspace)
- ├── templates/film/ what a new film starts from
- └── examples/ finished films with their storyboards, source and cue sheets
- ```
- ## Docs
- | When you are… | Read |
- | --- | --- |
- | deciding what to teach and in what order | [`references/pedagogy.md`](references/pedagogy.md) |
- | writing and drawing the storyboard | [`references/storyboard.md`](references/storyboard.md) |
- | choosing the look, or making a portrait short | [`references/look.md`](references/look.md) |
- | building a film with the kit, and rendering it fast | [`references/engine.md`](references/engine.md), [`references/motion.md`](references/motion.md) |
- | building real objects in 3D and directing the camera | [`references/detail.md`](references/detail.md) |
- | writing narration that sounds like talk | [`references/narration.md`](references/narration.md) |
- | choosing a voice, performing the take, cutting to it | [`references/voice.md`](references/voice.md) |
- | choosing music and placing sounds | [`references/sound.md`](references/sound.md) |
- | checking a render and briefing a reviewer | [`references/review.md`](references/review.md) |
- ## Honest limits
- - **Nobody has heard the films.** The agent that makes them cannot listen: sound is chosen by description and set
- by measurement, and each delivery says what a person should listen for.
- - **Rendering is slow without a GPU.** On a CPU, heavy 3D draws at about one frame a second per four cores, so a
- minute of 1080p60 takes the better part of an hour on a small machine. A GPU, or a render worker on a machine
- with more cores ([Rendering](#rendering)), is the way to minutes.
- - **The sound library is not in the repository.** Music and effects come from [Mixkit](https://mixkit.co), whose
- licence allows them inside a video but not passed on as files; `kit/audio/fetch.sh` downloads them.
- - **Narration and composed music cost credits** on your ElevenLabs account.
- - **A replica is only as good as its references.** When good photographs of the real object cannot be found, the
- agent asks you for some; without them, it says what it could not match.
- ## Licence
- [MIT](LICENSE). The films you make with it are yours: the licence covers this repository's code, documents and
- examples, not what you render.
- What is not ours to license, and how it is handled:
- | Thing | Its terms | In this repository |
- | --- | --- | --- |
- | [GSAP](https://gsap.com) | GSAP's own no-charge licence (not MIT) | a dependency installed from npm, not redistributed |
- | [three.js](https://threejs.org) | MIT | a dependency installed from npm |
- | Sora, Inter, JetBrains Mono, Instrument Serif, Patrick Hand | SIL Open Font License | installed from npm |
- | 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 |
- | 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 |
- | Earth maps in the examples | NASA imagery, not copyrighted | included, with [sources](examples/langit-biru/assets/SOURCES.md) |
- ## Credits
- - [GSAP](https://gsap.com) and [three.js](https://threejs.org) do the animating and the 3D.
- - Fonts: Sora, Inter, JetBrains Mono, Instrument Serif and Patrick Hand (SIL Open Font License), from npm.
- - The Earth in the worked example uses NASA's Blue Marble and Earth at Night maps, which are not copyrighted
- ([sources](examples/langit-biru/assets/SOURCES.md)).
- - The composition shape (a fixed-size root and one paused timeline at `window.__timelines.root`) follows
- [Null Motion](https://github.com/blixvip/NullMotion)'s HyperFrames convention.
- <div align="center">
- <br />
- <sub>Built storyboard first.</sub>
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.