reelsmith
The server enables an AI agent to create, inspect, edit, validate, preview, render, and review reelsmith video projects and their assets.
Read the built-in reelsmith manual.
Create new project folders with optional title and profile.
Describe a project's canvas, safe area, duration, voice lines, tracks, clips, assets, and issues, optionally at a specific time.
Apply atomic edit batches for tracks, clips, keyframes, assets, and settings, and undo previous batches.
Validate the project and owner rules before rendering.
Inspect the component library and type-check custom components.
Render preview stills with measured layout problems, or sweep the whole film for render-blocking layout issues.
Render the final film with loudness mastering and delivery checks, then review delivered frames.
Generate narration with pace/emotion controls, caching, and budget enforcement.
Capture web-page evidence, generate images, animate images into short videos, and import local or downloaded media.
List project assets and read or append workspace notes.
Supports original picture generation via the OpenAI Codex CLI image-generation tool (draw), used as an asset source for films.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@reelsmith create a 30-second vertical video from script.md with narration and captions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A language model can write a script and invoke a renderer, but it cannot see the result: a title that runs off the
frame, a caption over a face, a cut that lands mid-word. reelsmith gives the agent an editor rather than a pipeline.
The agent assembles the film clip by clip from footage, pictures, narration and React components. reelsmith keeps
every edit valid and undoable, anchors each clip to what it follows, measures the text on rendered frames, masters
the loudness and enforces the delivery rules. There are no templates: the agent decides the story, the cut, the
sound and the look, and project.json remains editable by hand.
Visual verification
preview returns stills at the requested moments, with the safe area outlined and the layout measured on those
frames. render applies the same measurement to the whole film before encoding and refuses a film that fails; the
previous delivery is kept.
[error] n1 @ 24.2s: text "of salt in every litre o" is cut by the canvas edge (right, 66 px): move it in or make it smaller
NOT DELIVERED (stopped at layout): words sit where the viewer cannot read them (listed in layout): fix and render againRelated MCP server: levea-mcp-server
The application
Running reelsmith in a workspace opens the application: a desktop window, or a browser tab without the app
extra. A sidebar lists every film of the workspace with its state, and requests to the agent run in several films at
once, each film showing its session, its current cut and its beats. A new film starts from a one-line description;
media are added from the file dialog or by dropping files on a film; the Library shows the workspace's components,
notes, rules and fonts, and Settings holds the engine, the budgets and the keys. The interface is available in eight
languages, runs locally, and uses the engine already installed (Claude Agent SDK, Codex, DeepSeek Harness or any
OpenAI-compatible API). See docs/app.md.
reelsmith chat holds the same conversation in the terminal. See docs/terminal.md.
pip install -e ".[app]" # the desktop window; without it, a browser tab
reelsmith # in a workspace, or in an empty folder to create oneInstallation
Requirements: Python 3.10+, Node.js 20+ and ffmpeg on PATH.
git clone https://github.com/wangkant/reelsmith && cd reelsmith
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[capture,web]"
cd renderer && npm ci && cd ..
reelsmith doctor # verifies the machine and reports what each optional tool needsAttach reelsmith to a coding agent, in the folder where the agent runs:
reelsmith setup claude-code # or: codex, dsh, cursor, generic (--print shows what it would write)reelsmith reads its manual and renderer from the checkout, so the editable install must be kept. Example requests: "Cut ~/videos/talk.mp4 to its best 90 seconds, remove the pauses, add English captions and a title card." or "Make a 60-second vertical explainer on why tea leaves curl."
Installation by a coding agent
Paste the following into Claude Code, Codex, Cursor or another coding agent:
Read https://raw.githubusercontent.com/wangkant/reelsmith/main/docs/setup-for-agents.md and set up reelsmith for me.The agent asks where to install and before installing any system tool, verifies the machine with reelsmith doctor,
attaches itself with reelsmith setup <agent> and renders a test film without a paid call.
Capabilities
Area | What the agent can do |
Timeline | Visual, audio and caption tracks; image, video, text, shape, evidence and component clips; keyframes, transitions, filters and blend modes. Edits are atomic batches, validated and undoable. |
Footage | Probe recordings, find cuts and silences, obtain word-level transcripts; ripple edits, reframing for a vertical canvas, speed curves, freeze frames, reverse, ducking under the voice. |
Captions and chapters | Captions from narration or a transcript, by phrase or by word, burned in and delivered as |
Timing | Times anchor on narration lines, clips, markers or source seconds ( |
Inspection |
|
Assets | Narration (text-to-speech, cached per line), generated pictures, web-page evidence with the proving sentence boxed, image-to-video clips, imports of local or downloaded media; a workspace stock of poses, sets and props drawn once in one look and reused by every film. |
Canvas and language |
|
Platform playbooks | Each platform profile (YouTube and Shorts, Douyin, TikTok, Instagram Reels, Bilibili, Xiaohongshu, WeChat Channels) carries a sourced playbook that the agent reads with the manual. |
Delivery checks | Text outside the safe area, cut, too small, overlapping or low in contrast; loudness; black or frozen stretches; length, size and workspace rules. A refused render names the clips and times to fix. |
Spend control | Paid calls pass through a ledger with a per-project budget and an account balance floor. |
Built-in scene components
Fifteen React components are built in; twelve are shown above. Each lands its parts at the times the agent gives
and sizes itself to its box on any canvas. The agent can also write its own: a component is a .tsx file and a
JSON schema in the workspace library, built on a documented kit (docs/kit.md), type-checked and
import-guarded. It can equip itself further: add_package brings npm libraries into the workspace for its
components, and run_script runs a Node script of its own under Node's permission model to make textures, paths or
baked data (Bring your own tools).
For films made entirely in code, the kit's stage acts each narration line out in drawn-pose animation: a character drawn in key poses, with a closed-mouth twin and a blink for each, anticipates, snaps to the next pose and settles, its mouth moving with the voice, on a set drawn in the same style, with hard cuts on the words it plays under (docs/kit.md). Sets, paper, ink and drawn objects are built in; examples/performance is a film made with them.
Supported agents
Agent | Setup |
Claude Code |
|
Codex |
|
DeepSeek Harness | the plugin in integrations/dsh, or |
Cursor |
|
Any MCP client |
|
No client |
|
Every agent receives the same tools and the reelsmith skill (skills/reelsmith/SKILL.md). See docs/agents.md.
Workspaces and projects
A workspace is a folder for one creator or channel. Its projects share settings, rules, keys, a component library and the agent's notes:
studio/
workspace.json profile, locale, theme, providers, budget, runner defaults (all optional)
rules.json hard rules (block delivery) and advice (information only)
.env provider keys; never shown to the agent
library/ NOTES.md, the agent's components/, fonts/
projects/<film>/ project.json, assets/, voice/, build/ (previews), out/ (film, subtitles, chapters, covers)examples/workspace is a starter, and examples holds the project of the film
shown above. Every agent tool is also a command (reelsmith --help).
Optional services
Editing, previews, checks and rendering run locally at no cost. The following tools require more:
Tool | Requirement |
| the |
| the Codex CLI, signed in |
| an OpenRouter key (English is read by an ElevenLabs voice, Chinese by a Qwen voice), or any OpenAI-compatible speech endpoint |
| an OpenRouter key |
| any OpenAI-compatible transcription endpoint, or the |
| a model API key, or Codex or DeepSeek Harness installed; the |
Paid calls are estimated first and refused above budget.per_project_usd (default $1) or below the account floor
budget.min_balance_usd (default $5). The film shown above cost about $0.55.
Documentation
docs/manual.md: the agent's manual, as returned by the
manualtool.docs/platforms/: the platform playbooks.
docs/editor-spec.md: the full reference (project format, edit operations, providers, checks, profiles, the runner).
docs/agents.md: attaching coding agents and running them headless.
docs/app.md: the application.
docs/terminal.md: the terminal session.
docs/watch.md: the window on a single film.
docs/kit.md:
@reelsmith/kit, for writing components.
Development
pip install -e ".[dev]" && pytest
cd renderer && npm run typecheck && node test/selftest.mjs && node test/stage.test.mjs && cd ..
cd integrations/dsh && npm ci && npm test && cd ../..
python integrations/sync_skills.py --check # the plugin's copy of the skillLicense
reelsmith is source-available under the PolyForm Noncommercial License 1.0.0: it may be used, modified and shared for noncommercial purposes. Commercial use requires a separate license from the author; open an issue to enquire. Releases published before 10 November 2026 were made under the MIT license.
The renderer depends on Remotion, which has its own license: free for individuals and small teams, with a company license required for larger organisations (https://www.remotion.dev/license). The bundled Smiley Sans font is under the SIL Open Font License (renderer/src/fonts/SmileySans-OFL.txt).
Available Tools
19 toolsanimateA
Turn image asset image_asset into a short silent video asset id (2-12 s) in which motion happens
(what moves in the picture). camera: push, pull, pan_left, pan_right, rise or still (default push).
Paid: estimates first and refuses over budget; a submitted job is resumed, never bought twice.
Inputs: id (required), motion (required), project (required), image_asset (required), +2 more.
assetsC
The project's assets with kinds, sizes and durations.
Inputs: project (required).
captureA
Screenshot a web page at phone width as evidence asset id (assets/.png), boxing the sentence that
contains match (a short exact phrase from the page, 8-20 characters is safest; empty boxes the title).
Inputs: id (required), url (required), project (required), match.
checkA
Validate the project and apply the owner's rules. Errors block render; warnings and advice are information. Run it after a batch of edits and before render.
Inputs: project (required).
describeB
The editor's window as text: canvas, safe area, duration, voice lines, tracks bottom to top with their clips,
assets and the latest issues. With at (seconds or a Time like "line:4"; "clip:c2.end" = c2's last frame),
only what is on screen then.
Inputs: project (required), at.
drawB
Generate an original image asset id from prompt (optionally in the style of an image asset). size: an
aspect "9:16" (default, 1080x1920), "2:3", "3:4", "4:5", "1:1", "4:3", "3:2", "16:9", or pixels "WxH" with
sides 256-4096. Paid or rate-limited depending on the provider; slow (minutes).
Inputs: id (required), prompt (required), project (required), size, +1 more.
editA
Apply a batch of edit ops atomically: all apply and validate, or nothing changes. Ops: add_track, update_track, remove_track, add_clip, update_clip, remove_clip, move_clip, split_clip, set_keyframes, add_asset (an existing id is replaced), update_asset ({"op": "update_asset", "id", "set": {...}}: deep merge, null removes a key), remove_asset, set (see the manual). Every applied batch can be undone.
Inputs: ops (required), project (required).
import_assetA
Copy a local file, or download an http(s) image/video/audio (size-capped), into assets/ and register it as
asset id (an existing id of the same kind is replaced). kind image, video, audio or evidence (a page
screenshot you have: its box is the whole picture until you set one with the update_asset edit op); empty
detects it from the file. This is also how music gets in: import a file you are allowed to use.
Inputs: id (required), source (required), project (required), kind.
libraryB
The components a component clip can use (built-in presets and your own library): name, source, what it is
and its prop names. With name, one component in full: props schema, example props and the source file to read
as a model. Also gives the path of the @reelsmith/kit reference (docs/kit.md).
Inputs: project (required), name.
manualA
The reelsmith manual: how the editor works, the project format, Times, every tool, edit ops, components and what blocks delivery. Read it once before your first edit.
Inputs: no named parameters.
new_projectA
Create a project folder with an empty project.json (no tracks yet), assets/, voice/ and script.md. Put it in /projects/ to get the workspace's library, rules and keys.
Inputs: project (required), title, profile.
noteA
Append a dated note at the end of the workspace's library/NOTES.md for future work (a lesson, a preference, a fix). Keep it short and specific. To put it under a heading or reword old notes, edit NOTES.md with your file tools.
Inputs: text (required), project (required).
notesB
Your own notes for this workspace (library/NOTES.md): what worked, what to avoid. Read them when you start.
Inputs: project (required).
previewA
Render stills at the given moments straight from the project (no full render): seconds or Times like "line:3", "clip:c2+0.5", "end-1" ("clip:c2.end" = c2's last frame). Up to 24 per call. Returns PNG paths (look at them with Read), a contact sheet with the platform's UI bands darkened and the safe area outlined, and measured layout problems. sweep=true also measures a still every second of the whole film, as render does before it encodes (no film is made): every layout problem that would stop render shows now, with stills of the flagged moments.
Inputs: project (required), sweep, times.
renderA
Render the whole film to out/film.mp4: refuses on check errors; measures text layout every second (the same pass as preview sweep=true); renders, masters loudness and runs the delivery checks. Anything failing keeps the previous film and says what to fix; a transient renderer failure is retried once and said to be one. Takes minutes: preview first.
Inputs: project (required).
reviewB
Evenly spaced frames (2-24) from the delivered out/film.mp4 and a contact sheet, to judge the film as a phone viewer would.
Inputs: project (required), n.
speakA
Narrate: one item per voice line, a string or {"text", "pace"?, "emotion"?}. pace: "slower", "normal", "faster" or a speed factor 0.5-2 relative to normal (1.0 normal, 0.9 a little slower, 1.1 a little faster). emotion: a word or two (at most 20 characters, e.g. "惊讶", "平静", "surprised") passed to the voice as an instruction; how much it changes depends on the voice model. gap_s: silence between lines. Writes voice/voice.wav and voice/voice.json (line times), sets the project's voice if unset. Only changed lines cost money (cached). Paid: estimates first and refuses over budget.
Inputs: lines (required), project (required), gap_s.
typecheckB
Type-check your own components (library/components/*.tsx) with the renderer's TypeScript, before a preview bundles them. Lists errors in your files; errors elsewhere are counted, not shown.
Inputs: project (required).
undoB
Undo the last steps edit batches: project.json goes back to the snapshot taken before them.
Inputs: project (required), steps.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools target clearly distinct stages of the reel workflow (edit → check → preview → render → review), and descriptions make the differences explicit. A few pairs are close enough to invite misselection: preview vs review (stills from the project vs frames from the delivered mp4), check vs typecheck, and note vs notes (append vs read).
The set mixes bare verbs (render, preview, draw, speak, capture, edit), bare nouns (manual, library, assets, notes), and only two snake_case compounds (new_project, import_asset). Singular/plural siblings note/notes add to the inconsistency, though every name remains readable and guessable.
19 tools is on the heavy side of the ideal 3-15 band, but the domain is genuinely broad (project setup, editing, validation, rendering, voice, generated/imported assets, components, notes). Almost every tool maps to a real workflow step; only the doc/note trio (manual, notes, note) feels auxiliary.
The surface covers the full lifecycle: create project, edit atomically, undo, validate, preview, render, and review the delivered film, plus asset acquisition (import, capture, draw, animate) and voice narration. Minor gaps: no project listing/deletion or script-editing tool, and clipping/caption or audio-track authoring is only implied through edit ops and file tools.
Maintenance
Related MCP Connectors
Agentic AI video editor: edit a real timeline, generate clips, music and voice, then render.
AI video editor your agent can drive: plan scenes, edit a multi-track timeline, and render MP4s.
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
AI video agent: edit timelines, captions, voice, music, images and ads, then render MP4s.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to autonomously edit videos into publish-ready vertical short-form content, including silence removal, subtitle generation, voiceover synthesis, color grading, and composite pipeline creation.MIT
- AlicenseBqualityBmaintenanceEnables AI agents to turn natural-language creative direction, transcripts, and source media into fully structured, editable video projects, then verify and render delivery files.255MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to edit talking-head videos locally by transcribing footage, applying validated edit operations like cutting fillers and silences, adding zooms, captions, looks and branding, and checking results with rendered previews. Agents can also read pinned editor feedback notes with annotated frames, resolve them, and export MP4, SRT or OTIO while the user watches changes live.52 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to build and edit a real video timeline — cuts, text, shapes, keyframes, captions and music — in a live studio the user can watch and edit alongside, rendering actual frames so the agent can verify its own work instead of guessing. Finishes by exporting an MP4 or carrying the timeline into DaVinci Resolve, Premiere Pro, CapCut or Remotion.2MIT