English | 日本語
An Agent Skill that turns a theme into an animated explainer video with narration, background music and sound effects, rendered to MP4.
/motion-render:motion-render Make a video that explains how GitHub Actions authenticates to Google Cloud with Workload Identity Federation
From that one line, Claude writes a narration script, generates the narration (Gemini TTS) and a BGM (Lyria), draws a flat explainer (cards, labels, a numbered flow) whose moves follow the words as they are said, and renders it to an MP4 on your machine. A one-minute explainer takes about 10 minutes, with no questions in between.
An introduction video made by motion-render itself (57 seconds, with sound).
motion-render-guide-en.mp4
More videos, including one with sound effects, are in Examples on the wiki.
- Look, length, voice and the mood of the music are chosen from the theme (anything you specify wins)
- An HTML film is drawn in the look that fits the theme: flat and dark, pencil on paper, coloured pencil, blueprint, paper collage or whiteboard
- With an ElevenLabs API key, sound effects follow the animation too: a card appearing, a step of a flow lighting up
- You can also pass the URL of an existing Motion film to get an MP4 with narration and BGM
- The rendering browser (Chromium) and ffmpeg are set up automatically, so results don't depend on what is installed on your machine
Narration, BGM, sound effects and the MP4 are the same either way. Only the animation is made differently. New films are made as HTML (in the rich version, only an HTML film can react to every drum hit). Claude Motion is used when you ask for it, and for turning an existing Motion film into an MP4.
| Claude Motion | HTML | |
|---|---|---|
| Plans | Team and Enterprise (beta) | Pro, Max, Team, Enterprise and API keys |
| How it is made | Claude builds the film in Motion, and motion-render fetches it | Claude writes one HTML page on a kit that comes with motion-render: an animation player (GSAP and its plugins), three.js, drawing helpers, styles and Japanese fonts |
| Checking before render | Claude looks at still frames | An automatic layout check (overlaps, things sticking out or hidden, text that is too small or too faint), then still frames |
| What you can look at | The Motion film on claude.ai, and the MP4 | Still frames and the MP4 on your machine (there is no link to share before the MP4) |
| Extra setup | None | None: the kit is installed with motion-render |
| What | Notes |
|---|---|
| Claude Code | Pro, Max, Team or Enterprise plan, or an API key (not the free plan) |
| Node.js 22.18 or later | Check with node -v. Node runs the command's TypeScript directly |
| Gemini API key | Used for narration and BGM. Create one in Google AI Studio (step by step) |
| ElevenLabs API key | Optional, for sound effects. Pay-as-you-go works without a subscription (step by step) |
Works on macOS, Linux and Windows.
Recommended: install it as a plugin. Run this inside Claude Code:
/plugin install motion-render --marketplace umiyosh/motion-render
On Claude Code versions before 2.1.275, run it as two lines:
/plugin marketplace add umiyosh/motion-render
/plugin install motion-render@motion-render
The rendering command and its dependencies come with the plugin, so there is nothing else to install.
The plugin also installs ffmpeg-skill (MIT, by kajisho5), pinned to a reviewed commit.
Plugin skills are prefixed with the plugin name, so you call them as /motion-render:motion-render <theme> and /motion-render:rich <theme>.
Without the plugin system: install with the skills CLI
npx skills add umiyosh/motion-render -gThis installs the skill only. On first use, Claude installs the motion-render command with npm install -g.
If your environment blocks that (a sandbox, for example), install it as a plugin instead.
Create a Gemini API key in Google AI Studio (step by step). Then add this to your shell profile (~/.zshrc or similar) and restart Claude Code.
export GEMINI_API_KEY="your key"For sound effects, add an ElevenLabs key as well (step by step). Without it, videos are made without sound effects.
export ELEVENLABS_API_KEY="your key"Sound effects made without a subscription are for non-commercial use only and must be credited in the title (for example with 11.ai) when published. motion-render puts SFX: 11.ai on the title of a video with sound effects.
Chromium cannot start inside the sandbox. Add these two entries to ~/.claude/settings.json so that only motion-render runs outside it.
If you use auto mode and runs are still refused, also add this line to autoMode.environment:
"**Motion rendering**: rendering Motion or HTML films to MP4 with headless Chromium via the `motion-render` command, outside the Bash sandbox, is routine work requested by the user"/motion-render:motion-render Make a 30-second video that explains …
(If you installed with the skills CLI: /motion-render Make a …, and /rich Make a … for the rich version)
On the first run, Chromium (about 210 MB) and ffmpeg are downloaded automatically.
- Add length, output location or mood in the same request (e.g. "30 seconds", "save it to
~/Movies", "news-style BGM") - There is no upper limit on length. Without one, it follows the theme: about a minute for one mechanism, a few minutes for a theme with several steps. Rendering takes about 1-2 minutes per minute of video, depending on the number of cores (
MOTION_RENDER_PAGES) - Without an output location, the video goes to
$MOTION_RENDER_OUT_DIR, or the current directory - After it is done, ask "change the BGM" or "shorten this part" and only that part is redone
- For an existing Motion film, pass its URL and ask for an MP4. Narration and BGM are added too
- Asking for a promo, beat sync or a rich film picks
/motion-render:richeven without its name. Anything else goes to the default
/motion-render:rich Make a promo for …
The narration sets the time, the animation builds its big moments inside it, and the music follows those moments (it builds into each drop, and stops dead at most once, where the story holds its breath). The music is Lyria's own performance, generated from a description of what happens on screen at each moment and rearranged bar by bar to land on the cues. Every drum hit is detected in the music: the scenes' own moves start on the beat, and in the drops the thing that drives the story (an engine, a press) answers every kick. Before the build, a critic reviews the key frames; after it, the MP4 is measured for pauses in the narration, the timing of the big moments and the reactions to the hits. A film takes about an hour.
/motion-render:motion-render (default) |
/motion-render:rich |
|
|---|---|---|
| For | Explaining how something works, quickly | Promos and films that should look and sound rich |
| Picture | Flat cards, labels and a numbered flow, moving with the narration's words | Built around big moments, moving on the beat; three.js, motion blur and a finishing look when they fit |
| Music | One BGM at a constant low level under the narration | Four Lyria takes, rearranged bar by bar onto the film's cues, with every drum hit detected |
| Checks | The layout check and still frames, then one build | The layout check, a preview reviewed by a critic, one build, then a sync report on the MP4 |
| Time (one minute of film) | About 10 minutes | About an hour |
The default makes the same kind of film as motion-render 1.1, so existing requests keep working the way they did.
Each video uses one work directory (<work>). Its layout and the script.json format are in SKILL.md (the default) and skills/rich/SKILL.md (the rich version, which adds bpm, sections and the score).
| Command | What it does |
|---|---|
motion-render narrate <work> |
Generates narration from script.json and writes scene lengths to timing.json. With bpm, scenes start on beats and sections on bar lines, and a table of the times is printed. It also measures on the audio when each character of the narration is said (words.json) |
motion-render bgm <work> |
With bpm, generates four takes from score.txt and prints each bar by bar (level, kicks, snares, hats), then a draft of the bars to play for each take, best first. Without it, one piece from the bgm prompt in script.json |
motion-render score <work> |
Plays the bars chosen in script.json's score onto the film's tempo and bars, hands the drum hits to the film, lists the moments a listener notices (the music drops out, comes back, a lone hit), and checks that the music lands on the cues |
motion-render sync <work> <mp4> |
Measures on the MP4 the pauses in the narration, the change of the picture on each drop and on the final hit, and the reactions to the kicks in the drops (build runs it too) |
motion-render sheet <work> <mp4> [out.png] |
Tiles the MP4's key moments (the middle of each scene, around each drop, the final hit) into one image for a review, with a .txt naming each tile |
motion-render preview <work> [out.png] |
Before building: runs the layout check and, from only the frames they read (no MP4, tens of seconds), draws the contact sheet for a review and the beat-synced film's sync report. The film is then built once |
motion-render sfx <work> |
Generates the sound effects in script.json and a preview.m4a of them in order |
motion-render prepare <storeDir> <work>/film |
Motion: expands a Motion film's data into a directory it can render |
motion-render kit <work> |
HTML: sets up <work>/film with the player, styles, GSAP and its plugins, three.js, drawing helpers, the Japanese fonts and the scene times. Claude then writes film/index.html |
motion-render check <work>/film [<scene file>…] |
HTML: checks the layout every 0.1 s for overlaps, things sticking out of their box or the frame, things hidden under others, text that is too small or too faint, big text gone before it can be read, and frames that change after seeking back. Given scene files (names in film/scenes/), checks only their scenes |
motion-render stills <filmDir> <outDir> 0,5,12 |
Writes still frames for checking (an HTML film is checked first) |
motion-render build <work> [out.mp4] |
Mixes narration, BGM and sound effects and renders the MP4 (a film cut to the beat at 60 fps, measured with sync afterwards). Stops if any is missing, or if an HTML film fails the layout check |
motion-render times <work> |
Shows how long each step took, as a table (each command, and Claude's work between them) |
motion-render --version |
Prints the version |
| Environment variable | Effect |
|---|---|
GEMINI_API_KEY |
Required for narration and BGM |
ELEVENLABS_API_KEY |
Required for sound effects (none are added without it) |
MOTION_RENDER_OUT_DIR |
Default output directory when build gets no output path |
CHROMIUM_PATH |
Use your own Chrome or Chromium instead of the bundled one |
FFMPEG_PATH |
Use your own ffmpeg instead of the bundled one |
MOTION_RENDER_PAGES |
Browsers that draw frames at once (default: half the cores, at most 8). Lower it if the machine is busy |
| Symptom | Cause and fix |
|---|---|
The browser fails with bootstrap_check_in ... Permission denied |
It is running inside the Claude Code sandbox. Check step 3 of the install. motion-render must run on its own (chaining it with | grep or && keeps it in the sandbox) |
GEMINI_API_KEY is not set |
Check step 2 of the install and restart Claude Code |
ELEVENLABS_API_KEY is not set |
There is no key for sound effects. Create one (step by step) or ask Claude to make the video without sound effects |
Sound effect generation fails with HTTP 401 or similar |
The key does not allow Sound Effects, or the balance has run out. Read the reason after the status and check Developers in ElevenLabs |
Sound effect generation stops with came back silent |
Silence came back three times. Rewrite the prompt as a more concrete sound and try again |
| Narration or BGM generation keeps failing | Each request times out after 90 seconds and is retried up to 3 times. If it still fails, check your API key's permissions and quota |
| ffmpeg fails to download | A proxy is blocking downloads from GitHub. Install ffmpeg yourself (it is used from PATH) or point FFMPEG_PATH at it |
| Chromium fails to download on first run | Point CHROMIUM_PATH at your own Chrome or Chromium |
Unknown file extension ".ts" when running motion-render |
Node is older than 22.18. Update Node |
stills or build stops with lines like 1.1-1.9s: #a and #b partly overlap |
The layout check found a problem in an HTML film. Claude fixes film/index.html and checks again. If you edit it yourself, run motion-render check <work>/film until it prints layout ok; html-film.md explains each message |
font … "Noto Sans JP" did not load. Run "motion-render kit" again. |
The font files of an HTML film are missing. Run motion-render kit <work> again (it keeps index.html) |
| Japanese glyphs or line breaks differ slightly from the Motion page | A Motion film is drawn with your OS fonts. An HTML film uses the bundled Noto Sans JP (and Klee One in the hand-drawn looks) |
If you installed the plugin, open /plugin inside Claude Code, go to Installed, select motion-render and choose Update now. Restart Claude Code to load the new version.
Claude Code updates only Anthropic's official marketplaces automatically. To get new versions of motion-render without doing this each time, open /plugin, go to Marketplaces, select motion-render and choose Enable auto-update. Claude Code then updates it when it starts.
From a shell, claude plugin update motion-render@motion-render does the same as Update now.
If you used the skills CLI, run this in your shell:
npx skills update motion-render -gIf you installed the plugin, run this inside Claude Code:
/plugin uninstall motion-render
If you used the skills CLI, run this in your shell:
npx skills remove motion-render -g
npm uninstall -g motion-renderThe downloaded Chromium is in Playwright's cache (~/Library/Caches/ms-playwright on macOS, ~/.cache/ms-playwright on Linux). Delete it if you no longer need it.
- While rendering, the film's code (Motion or HTML) cannot reach the network or read files outside the film directory
- Chromium starts with its own sandbox enabled (Playwright disables it by default, so it is turned on explicitly)
- Only the
motion-rendercommand is taken out of the Claude Code sandbox - The API key is read from the environment only and is never written to files or videos
Run npm install, then make check before opening a pull request. It runs the same checks as CI: ESLint, Prettier, the TypeScript type check, the unit and render smoke tests with the 80% coverage gate, the quality gate tests, and the quality baseline gate. The smoke tests start headless Chromium against a stub of the Motion player in tests/fixtures and against small HTML films made with the kit, so no API key is needed.
The quality baseline lists the current ESLint warnings and Knip findings. A pull request that adds one or makes one worse fails. After fixing one, run make quality-baseline to record the improvement (it refuses to record a regression).
.claude-plugin/
marketplace.json # Claude Code plugin catalog (lists this repository itself)
plugin.json # Plugin manifest
bin/motion-render # Command the plugin puts on PATH (runs the CLI in skills/motion-render)
package.json # Plugin dependencies, installed by Claude Code with the plugin. `npm run typecheck` checks the scripts
package-lock.json
tsconfig.json # TypeScript settings (type check only; Node runs the .ts files directly)
skills/rich/SKILL.md # /motion-render:rich: instructions for a film cut to the beat (script and big moments, music style, music direction and choosing bars). Uses the command and references in skills/motion-render
skills/motion-render/ # The default skill and the command (read by both the skills CLI and the plugin)
SKILL.md # Instructions for Claude: setup, and a plain explainer in one pass
package.json # The motion-render command and pinned dependencies (playwright-core, ffmpeg-static, gsap, @fontsource/noto-sans-jp, @fontsource/klee-one)
references/html-film.md # How Claude writes an HTML film: cutting to the beat, layout, motion, and reading the checks
references/pipeline.md # How the steps depend on each other (what waits, what runs in the background), and how to add a step
kit/ # The player, the beat helpers (beat.js), base styles and drawing styles that `kit` copies into an HTML film, and the parts (parts.css)
scripts/cli.ts # The motion-render command
scripts/beatcli.ts # The commands of a film cut to the beat (timing table, takes, score, sync)
scripts/audio.ts # Narration and BGM generation, the takes, audio mixing
scripts/score.ts # Measures takes bar by bar and plays the chosen bars onto the film's bars
scripts/signal.ts # Decoding audio, filters and envelopes
scripts/tempo.ts # Tempo and downbeat
scripts/hits.ts # Drum hits per 16th note
scripts/sync.ts # Measures narration, big moments and hits on the MP4
scripts/repeat.ts # Finds frames that change after seeking back
scripts/sfx.ts # Sound effect generation (ElevenLabs), leveling and the listening file
scripts/work.ts # script.json validation and scene timing
scripts/render.ts # Rendering Motion and HTML films in the browser
scripts/kit.ts # Setting up an HTML film directory
scripts/layout.ts # The layout check of HTML films
scripts/scenes.ts # Putting the scene files (film/scenes/*.html) into index.html
scripts/steps.ts # Logging each command's time and making the per-step table (times)
scripts/snapshot.js # Measures boxes and text inside the film page for the layout check
scripts/json.ts # Reading JSON from files, APIs and the player without trusting its shape
scripts/store.ts # Expanding a Motion store into a film directory
docs/how-it-works.en.svg # Diagram used in this README
docs/how-it-works.svg # Diagram used in the Japanese README
.github/workflows/ci.yml # CI: the checks below on every pull request
Makefile # Development commands (`make help`)
eslint.config.js, .prettierrc, knip.json
quality-baseline.json # Known ESLint warnings and Knip findings to pay back; CI fails if they grow
scripts/quality-gate*.mjs # Compares the current findings with the baseline
tests/ # Vitest unit tests and render smoke tests (fixture store, a stub player, HTML films)
vitest.config.ts # Test settings and the 80% coverage gate
{ "sandbox": { "excludedCommands": ["motion-render:*"] // add to the existing array }, "permissions": { "allow": ["Bash(motion-render:*)"] // add to the existing array } }