Skip to content
Back to search

truemotion

Open, harness-agnostic motion-graphics MCP server and renderer for coding agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/instax-dutta/truemotion with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/instax-dutta/truemotion'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/instax-dutta--truemotion/badge.svg)](/listings/instax-dutta--truemotion)

HTML

<a href="/listings/instax-dutta--truemotion"><img src="/api/listings/instax-dutta--truemotion/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

cd truemotion
npm install

TrueMotion uses `playwright-core` and does **not** download a browser. Install Chrome or Chromium on the host, or point it at an existing binary:

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

If no browser is found, rendering fails with a clear message rather than silently downloading one. You also need `ffmpeg` on `PATH` for `render` (preview frames during MCP writes do not use it).

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.

README.md · README · 215 lines
  1. # TrueMotion
  2. [![CI](https://github.com/instax-dutta/truemotion/actions/workflows/ci.yml/badge.svg)](https://github.com/instax-dutta/truemotion/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. An open, harness-agnostic core for authoring and rendering motion-graphics video scenes.
  5. ![Six scenes from the pro demo](docs/demo-contact-sheet.png)
  6. The [finished 29-second demo](examples/pro-out/pro-demo.mp4) and its
  7. [state file](examples/pro-out/state.json) are in this repository. Regenerate them with
  8. `npm run demo:pro`. Its sixth scene ("The toolkit") deliberately exercises every
  9. local helper in one shot: `{{BRAND:*}}`, `{{COMPONENT:*}}`, `{{ROUGH}}`, `{{FX}}`,
  10. `{{SHADERS}}` and `{{THREE}}`.
  11. 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.
  12. ## What you get
  13. - Eleven MCP tools: `get_scenes`, `read_scene`, `update_scene`, `patch_scene`, `add_scene`, `read_skill`, `list_skills`, `view_sketch`, `review_timeline`, `render_video`, `optimize_assets`. An agent can author, audit, optimise assets and render a film without shell access.
  14. - 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:...}}`, `{{ROUGH}}`, `{{FX}}`, `{{SHADERS}}`, `{{THREE}}`, `{{BRAND:*}}`, `{{COMPONENT:*}}` and the `OMTyping` runtime are resolved locally.
  15. - 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.
  16. - Rendering: Playwright seeks the timeline frame-by-frame, then PNG frames are piped straight into ffmpeg in bounded batches. No full-frame staging directory and no cloud service. Memory stays flat for long videos; 240 frames at 540p peaked at 78 MiB. Seeks fire GSAP `onUpdate` callbacks, so proxy-driven counters and typed text export correctly on a cold seek.
  17. ## Install
  18. ```bash
  19. cd truemotion
  20. npm install
  21. ```
  22. TrueMotion uses `playwright-core` and does **not** download a browser. Install
  23. Chrome or Chromium on the host, or point it at an existing binary:
  24. ```bash
  25. export TRUEMOTION_CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  26. # or pass --chrome <path> to render/serve
  27. truemotion doctor # reports which browser will be used
  28. ```
  29. If no browser is found, rendering fails with a clear message rather than
  30. silently downloading one. You also need `ffmpeg` on `PATH` for `render`
  31. (preview frames during MCP writes do not use it).
  32. ## Use with any harness
  33. Create a state file, then point your harness at the stdio server:
  34. ```bash
  35. node bin/truemotion.mjs init truemotion-state.json --aspect 16:9
  36. ```
  37. MCP configuration (the exact file name differs by harness):
  38. ```json
  39. {
  40. "mcpServers": {
  41. "truemotion": {
  42. "command": "node",
  43. "args": ["/absolute/path/to/truemotion/bin/truemotion.mjs", "serve",
  44. "--state", "/absolute/path/to/truemotion-state.json"]
  45. }
  46. }
  47. }
  48. ```
  49. 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.
  50. Optional flags for `serve`:
  51. - `--skill <dir>`: use a different motion-skill directory.
  52. - `--assets <dir>`: where `{{ASSET:...}}` files and sketch PNGs live (defaults to `assets/` beside the state file).
  53. - `--no-preview`: skip rendered frame feedback (faster, but the agent cannot see its own scenes).
  54. ### Skill installation
  55. 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:
  56. ```bash
  57. node bin/truemotion.mjs install-skill ~/.claude/skills/truemotion
  58. node bin/truemotion.mjs install-skill ~/.agents/skills/truemotion
  59. ```
  60. ## Render a video
  61. ```bash
  62. node bin/truemotion.mjs render --state truemotion-state.json --out video.mp4 --fps 30 --crf 18
  63. # fast draft at half resolution
  64. node bin/truemotion.mjs render --state truemotion-state.json --out draft.mp4 --resolution 540p --fps 15
  65. # optional music bed, looped and faded in/out around the video
  66. node bin/truemotion.mjs render --state truemotion-state.json --out video.mp4 --audio music.mp3
  67. ```
  68. `--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). `--batch-size N` controls the streaming batch (default 30); lower it to reduce peak memory on long videos or small machines. 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.
  69. Large project assets can be downscaled and recompressed locally. Filenames are
  70. preserved so `{{ASSET:...}}` tokens keep working:
  71. ```bash
  72. node bin/truemotion.mjs optimize-assets ./assets --max-dimension 2200
  73. ```
  74. The same operation is available to agents as the `optimize_assets` MCP tool.
  75. It is a standalone ffmpeg implementation; no Electron or cloud service is involved.
  76. For frame-accurate QA without ffmpeg, export a single PNG:
  77. ```bash
  78. node bin/truemotion.mjs still --state truemotion-state.json --out frame.png --scene 2 --time 1.5
  79. ```
  80. 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.
  81. ## Example
  82. `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:
  83. ```bash
  84. node examples/intro-demo.mjs
  85. ```
  86. The generated state and MP4 land in `examples/out/` (gitignored).
  87. For a larger, art-directed piece, run `node examples/pro-demo.mjs`. It authors seven scenes (kinetic wordmark, manifesto typography, prompt-to-film pipeline with typing, frame/count-up data visual, measured-continuity panels, an all-token toolkit scene, and an outro lockup) through the same MCP tools, runs `review_timeline`, and renders a 29-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.
  88. ## State file
  89. Plain JSON, so it is easy to inspect or version:
  90. ```json
  91. {
  92. "schemaVersion": 1,
  93. "projectId": "default",
  94. "aspect": "16:9",
  95. "resolution": "1080p",
  96. "brand": { "primary": "#F5A524", "background": "#0B0E14", "text": "#F3EFE9", "logo": "" },
  97. "components": {},
  98. "scenes": [
  99. { "id": "uuid", "name": "Opening", "durationSec": 6, "html": "<!doctype html>..." }
  100. ],
  101. "sketchRefs": [],
  102. "skillReadCache": {},
  103. "stats": { "readSkillCalls": 0, "writeSceneCalls": 0 }
  104. }
  105. ```
  106. This is intentionally compatible with OpenMotion's scene tool state. Files without `schemaVersion` are treated as legacy v0, migrated to v1 and reported on stderr; files written by a newer schema are rejected rather than silently misread. Save the file after a migration to persist the version.
  107. ## Scope and limits
  108. - Supported injection tokens are listed above. `{{ROUGH}}`, `{{FX}}` and `{{SHADERS}}` are small local deterministic helpers (`OMRough`, `OMFX`, `OMShaders`) with no third-party dependency. `{{BRAND:*}}` values come from the state file's `brand` object, `{{COMPONENT:*}}` expands built-in or state-defined snippets, and `{{THREE}}` is a CSS-3D stage helper rather than a WebGL bundle. All documented authoring tokens are supported locally.
  109. - 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.
  110. - Frame-by-frame seeking is deterministic but slow for long videos; use a lower `--fps` for drafts.
  111. ## Documentation
  112. Full documentation lives in [`docs/dox/`](docs/dox/): getting-started, architecture, reference, contributing.
  113. ## Contributing
  114. The formal reverse-engineering audit, including rejected findings and their
  115. rationale, is in [docs/reverse-engineering/audit.md](docs/reverse-engineering/audit.md).
  116. Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and
  117. ideas, [NOTICE.md](NOTICE.md) for provenance and third-party licenses, and
  118. [CHANGELOG.md](CHANGELOG.md) for the release history. The most useful help is a
  119. scene that breaks a measurement, or a better measurement with a test.
  120. ## Licensing note
  121. All source in `src/`, `bin/` and `test/`, and all reference documents in `skill/`, are MIT licensed (see `LICENSE`). Dependencies keep their own licenses; see [NOTICE.md](NOTICE.md). The original OpenMotion documentation that early versions carried has been replaced with original MIT-licensed material, so the repository is free to redistribute in full. Bundle versions of GSAP, fonts and Simple Icons are read from the installed npm packages at render time, not copied into this repo.
  122. ## Verification
  123. ```bash
  124. npm test
  125. npm run test:e2e
  126. npm run test:crash
  127. npm run test:audio-resume
  128. npm run test:csp
  129. npm run test:mcp-schema
  130. npm run selftest
  131. npm pack --dry-run
  132. npm run benchmark -- --write # records docs/benchmarks/latest.md
  133. npm run goldens # regenerate pinned golden frames after renderer changes
  134. npm run test:e2e # authors the all-token scene through MCP and renders it
  135. ```
  136. CI runs a pinned-Chromium golden-frame regression job. The fixtures are
  137. font-free geometric scenes rendered at 540p, so they stay stable across hosts;
  138. set `TRUEMOTION_GOLDEN=1` to run that test locally.
  139. Measured footprint and frame rates on one machine are recorded in
  140. [docs/benchmarks/latest.md](docs/benchmarks/latest.md). The organisation-scale
  141. run is in [docs/benchmarks/longform.md](docs/benchmarks/longform.md): the current
  142. page-pool renderer completed a 2-minute 1080p timeline (1200 frames, 30 scenes)
  143. in 177.7 s at 6.8 frames/s with a 1278 MiB process-tree peak, 2.6x faster than
  144. before the page-pool change with byte-comparable output. Memory stays bounded by
  145. the batch and browser pool rather than video length; `--concurrency 1` reduced
  146. peak RSS to 977 MiB at 400 frames. Run `npm run bench:longform` to reproduce it.
  147. The npm package itself does not include the rendered demo film.
  148. Audio alignment was measured over a two-minute render with a looping bed:
  149. 23 ms drift and a confirmed tail fade, detailed in
  150. [docs/benchmarks/av-drift.md](docs/benchmarks/av-drift.md) (`npm run bench:av`).
  151. Skill references are cached by SHA-256 content hash, so same-size edits are
  152. still detected.
  153. Long renders can be split across invocations with `--segment-size` and
  154. `--max-segments`, then finished with `--resume`. Completed segments are
  155. checkpointed as MPEG-TS files with a byte-verified manifest, so an interrupted
  156. render never loses work. The manifest also stores a digest of scenes, brand,
  157. components and `{{ASSET:...}}` file contents, so editing the state file or an
  158. asset between a partial render and a resume is rejected rather than producing a
  159. mismatched film. The same options are available on the MCP `render_video` tool.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.