Skip to main content
Glama

TrueMotion

CI License: MIT

An open, harness-agnostic core for authoring and rendering motion-graphics video scenes.

Six scenes from the pro demo

The finished 25-second demo and its state file are in this repository. Regenerate them with npm run demo:pro.

This project was recovered by reverse engineering OpenMotion 1.1.0 (/Applications/OpenMotion.app, an Electron + React app signed by "Meta Dots", updater anovius/openmotion). The original ships its tools through an embedded MCP server wired to the Claude Agent SDK and Codex SDK. TrueMotion keeps the useful part, the tool contract, the scene format, and the motion-design references, and drops everything that ties it to one vendor: no Electron UI, no account, no license gate, no model SDK. The result is a plain stdio MCP server that any coding agent can drive, plus a renderer you can run yourself.

What you get

  • Eight MCP tools: get_scenes, read_scene, update_scene, patch_scene, add_scene, read_skill, view_sketch, review_timeline.

  • Scene format: one self-contained HTML document per scene with a single paused GSAP timeline on window.__SCENE_TIMELINE__. Injection tokens {{GSAP}}, {{FONTS_CSS}}, {{W}}, {{H}}, {{ICON:...}}, {{ASSET:...}} and the OMTyping runtime are resolved locally.

  • Contract validation (including a static seek-safety lint that rejects from(), external scripts or URLs, timers, requestAnimationFrame, CSS keyframes and transitions), evolve/digest reads, and rendered frame feedback after each write. Feedback is measured, not decorative: pixel-diff ratios for static slides and dead holds, duration/timeline mismatches, external requests, script errors, clipped actors and text under 18px. Evolved scenes get measured actor exit states, and a visible jump at an evolved cut is rejected with the two frames attached.

  • Rendering: Playwright seeks the timeline frame-by-frame, ffmpeg encodes the frames to MP4. No cloud service involved. Seeks fire GSAP onUpdate callbacks, so proxy-driven counters and typed text export correctly on a cold seek.

Related MCP server: Cleya

Install

cd truemotion
npm install
npx playwright install chromium   # only if Chromium is not already cached

You need ffmpeg on PATH only for render (preview frames during MCP writes do not use it).

If Chrome or Chromium is already installed, TrueMotion can use it directly and you can skip the Playwright browser download:

export TRUEMOTION_CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
# or pass --chrome <path> to render/serve
truemotion doctor   # reports which browser will be used

Use with any harness

Create a state file, then point your harness at the stdio server:

node bin/truemotion.mjs init truemotion-state.json --aspect 16:9

MCP configuration (the exact file name differs by harness):

{
  "mcpServers": {
    "truemotion": {
      "command": "node",
      "args": ["/absolute/path/to/truemotion/bin/truemotion.mjs", "serve",
               "--state", "/absolute/path/to/truemotion-state.json"]
    }
  }
}

That is all that is required: stdio MCP is supported by Claude Code, Codex, Cursor, OpenCode, and most other agents. No API keys, no vendor SDK, no Electron process.

Optional flags for serve:

  • --skill <dir>: use a different motion-skill directory.

  • --assets <dir>: where {{ASSET:...}} files and sketch PNGs live (defaults to assets/ beside the state file).

  • --no-preview: skip rendered frame feedback (faster, but the agent cannot see its own scenes).

Skill installation

The agent needs the motion-design references. Either let the agent call read_skill through MCP, or copy the skill into your harness's skill folder:

node bin/truemotion.mjs install-skill ~/.claude/skills/truemotion
node bin/truemotion.mjs install-skill ~/.agents/skills/truemotion

Render a video

node bin/truemotion.mjs render --state truemotion-state.json --out video.mp4 --fps 30 --crf 18
# fast draft at half resolution
node bin/truemotion.mjs render --state truemotion-state.json --out draft.mp4 --resolution 540p --fps 15
# optional music bed, looped and faded in/out around the video
node bin/truemotion.mjs render --state truemotion-state.json --out video.mp4 --audio music.mp3

--start 4 --end 8 renders only that global time range, which is useful for debugging one beat. --concurrency N renders frames on N browser pages in parallel and is the main speed control (default 2). Frame order is preserved exactly; content is seek-deterministic, though subpixel antialiasing can vary marginally with the number of concurrent pages. --crf defaults to 18 (higher quality than ffmpeg's default). --audio loops the file, fades it in and out, and cuts it to the video length.

For frame-accurate QA without ffmpeg, export a single PNG:

node bin/truemotion.mjs still --state truemotion-state.json --out frame.png --scene 2 --time 1.5

Call review_timeline through MCP before finishing a video. It audits every scene and returns a short note plus one contact sheet of middle frames, so the connected model can fix its own work with a small image payload. Pass contactSheet: false to receive full-size frames instead.

Example

examples/intro-demo.mjs authors a three-scene, 12-second intro entirely through the MCP tools (title reveal, capability assembly with an evolved matched cut, outro lockup) and renders it. Run it to see the tool contract in action:

node examples/intro-demo.mjs

The generated state and MP4 land in examples/out/ (gitignored).

For a larger, art-directed piece, run node examples/pro-demo.mjs. It authors six scenes (kinetic wordmark, manifesto typography, prompt-to-film pipeline with typing, frame/count-up data visual, measured-continuity panels, outro lockup) through the same MCP tools, runs review_timeline, and renders a 25-second 1080p H.264 film with a generated stereo ambient score into examples/pro-out/. The score is produced by examples/ambient.py (Python 3 with numpy): an Am-F-C-G-Am pad with sub layer, detuned voices, soft plucked arpeggio, breathing air texture, short feedback delays and fades, encoded to AAC. Every scene in it passes the motion audit with measured build and resolve change.

State file

Plain JSON, so it is easy to inspect or version:

{
  "projectId": "default",
  "aspect": "16:9",
  "scenes": [
    { "id": "uuid", "name": "Opening", "durationSec": 6, "html": "<!doctype html>..." }
  ],
  "sketchRefs": [],
  "skillReadCache": {},
  "stats": { "readSkillCalls": 0, "writeSceneCalls": 0 }
}

This is intentionally compatible with OpenMotion's scene tool state, so a project authored there can be opened here and vice versa.

Scope and limits

  • Supported injection tokens are listed above. Advanced original-only tokens ({{THREE}}, {{SHADERS}}, {{ROUGH}}, {{FX}}, {{BRAND:*}}, {{COMPONENT:*}}) are rejected with a clear error rather than silently mis-rendered.

  • There is no GUI, brand-kit scraper or in-app sound editor. The CLI can mux a single audio bed with --audio, but there is no timeline-level mixing.

  • Frame-by-frame seeking is deterministic but slow for long videos; use a lower --fps for drafts.

Documentation

Full documentation lives in docs/dox/: getting-started, architecture, reference, contributing.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup and ideas, NOTICE.md for provenance and third-party licenses, and CHANGELOG.md for the release history. The most useful help is a scene that breaks a measurement, or a better measurement with a test.

Licensing note

The source code in src/ and bin/ is MIT licensed (see LICENSE). Dependencies keep their own licenses; see NOTICE.md. The files in skill/ are reference documentation recovered from OpenMotion 1.1.0; their copyright holder has not published a license for them. Confirm your right to redistribute those files before publishing a fork. They are kept separate from the MIT-licensed code for exactly that reason. Bundle versions of GSAP, fonts and Simple Icons are read from the installed npm packages at render time, not copied into this repo.

Verification

npm test
npm pack --dry-run

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A local-first MCP server that captures rendered web evidence including screenshots, motion, pixel diffs, and CSS animation metadata for coding agents.
      7
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server for creative generation and video production, letting AI agents author declarative animations, render deterministic frames, and measure output quality with perception instruments for brand and accessibility conformance.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to drive a local explanatory-video lab over stdio: inspecting and patching declarative scenes and a multilayer timeline (clips, titles, captions, voice, music), querying media and frames, rendering previews, running recoverable jobs, and exporting bundles. It also handles Kdenlive round-trip sync plus checkpoints, undo and restore, all offline with JSON responses.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      A local MCP server that lets AI coding agents turn a folder of raw video clips into a finished montage from a single natural-language prompt, handling clip analysis, shot selection, beat-synced cuts, music matching, subtitles, transitions, and picture-in-picture. Each turn returns a reviewable timeline digest and contact sheet so nothing is rendered until the user approves the plan.
      -