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 storyboard and a narration script, generates the narration (Gemini TTS) and BGM that fits the theme (Lyria), builds the animation with Claude Motion, and renders it to an MP4 on your machine.
Note
Claude Motion is in beta and available only on Team and Enterprise plans (as of October 2026). motion-render needs an account on one of those plans.
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)
- 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
| What | Notes |
|---|---|
| Claude Code | An account that can use Claude Motion (beta, Team and Enterprise plans only). Claude Code only: other agents such as Codex or Cursor have no Motion |
| 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.
Plugin skills are prefixed with the plugin name, so you call it as /motion-render:motion-render <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 🎧: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 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 …)
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") - 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
Each video uses one work directory (<work>). Its layout and the script.json format are in SKILL.md.
| Command | What it does |
|---|---|
motion-render narrate <work> |
Generates narration from script.json and writes scene lengths to timing.json |
motion-render bgm <work> |
Generates the BGM from the bgm prompt in script.json |
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 |
Expands a Motion film's data into a directory it can render |
motion-render stills <filmDir> <outDir> 0,5,12 |
Writes still frames for checking |
motion-render build <work> [out.mp4] |
Mixes narration, BGM and sound effects and renders the MP4 (stops if any is missing) |
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 |
| 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 |
| Japanese glyphs or line breaks differ slightly from the Motion page | Text is drawn with your OS fonts |
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 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, 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/motion-render/ # The skill (read by both the skills CLI and the plugin)
SKILL.md # Instructions for Claude (setup, storyboard, script and BGM choices)
package.json # The motion-render command and pinned dependencies (playwright-core, ffmpeg-static)
scripts/cli.ts # The motion-render command
scripts/audio.ts # Narration and BGM generation, audio mixing
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 in the browser
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 and a stub player)
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 } }