Tweens local motion engine

Create editable animations through a CLI or an MCP client. No app window, model API key, account, or WebMCP-enabled browser is required for authoring. Rendering uses isolated headless Chromium and the same evaluator, artwork adapter, GIF encoder and MP4 encoder as the editor.

Package: [email protected], published under the MIT License. MCP Registry: io.github.sohei1l/[email protected]. The private editor repository is not relicensed by this package license. Public setup does not require access to the source documentation.

Install the pinned version with:

npm install -g [email protected]
npx playwright install chromium
tweens --version

The first command installs the tweens executable. Chromium is an explicit, separate dependency used only for PNG/GIF/MP4 rendering. tweens tools prints the authoritative schemas. Do not use an unpinned package version in automated setups.

MCP quick start

Tweens is listed in the official MCP Registry as io.github.sohei1l/tweens. A Registry-capable client can discover that name and ask you for a workspace. For clients configured manually, find the installed executable with command -v tweens, create a dedicated directory, and add:

{
  "mcpServers": {
    "tweens": {
      "command": "/absolute/path/from-command-v/tweens",
      "args": ["mcp", "--workspace", "/absolute/path/to/tweens-projects"]
    }
  }
}

Restart the client, then ask it to call list_projects. The workspace must already exist. Tweens can only address simple .tweens, PNG, GIF and MP4 basenames inside that directory; it cannot browse elsewhere, fetch URLs, run shell commands or publish files. MCP uses stdio, so do not run the mcp command in an ordinary terminal and expect an interactive prompt.

Useful first request:

Use the Tweens MCP server to create demo.tweens in the configured workspace. Build a two-state geometric animation, preserving layer IDs by duplicating the first state. Validate it, inspect PNG previews at the start, midpoint and end, repair visible issues, and export demo.gif and demo.mp4. Do not overwrite existing files.

The 20 semantic tools include project discovery/creation, bounded editor-state reads, layer creation and transforms, state duplication/deletion, transition timing/easing, atomic command batches, validation, previews and export. Tool results return stable IDs and a disk revision; mutations must use the latest revision. A success response proves the command ran, not that the design looks good—agents should inspect rendered frames.

Build and run today

Use Node.js 22 LTS or newer. From a checkout of the repository:

npm ci
npm run build --workspace tweens-cli
npx playwright install chromium
mkdir -p work/my-animation
node packages/cli/dist/cli.mjs tools
node packages/cli/dist/cli.mjs call create_project '{"file":"demo.tweens"}' --workspace work/my-animation
node packages/cli/dist/cli.mjs call get_editor_state '{"file":"demo.tweens"}' --workspace work/my-animation

Use IDs from the read result, never names or guessed IDs. Every edit needs file, revision, compositionId, and any state/layer IDs in its schema. Use the returned revision for the next edit. Inspect a particular state by passing stateId to get_editor_state; this read does not change anything.

tweens call TOOL @arguments.json --workspace DIRECTORY reads a JSON argument file (up to 1 MiB), useful for batches. --workspace=DIRECTORY is also supported. CLI results are JSON on stdout; failures set a nonzero exit code. No command executes JavaScript supplied by an agent.

Connect from a source checkout

The following alternative configuration runs an authorized source checkout. Use the installed-package quick start above for ordinary use. Your client's settings format may differ:

{
  "mcpServers": {
    "tweens": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/tweens/packages/cli/dist/cli.mjs",
        "mcp",
        "--workspace",
        "/absolute/path/to/animation-workspace"
      ]
    }
  }
}

Grant a dedicated, existing directory, not your home directory. The engine does not install itself in any client. It exposes 20 tools through tools/list, with JSON Schema validation and structured results. Stdio stdout contains only protocol messages; diagnostic logging goes to stderr. It does not start an HTTP MCP endpoint.

The authoring loop

1. list_projects or create_project; then get_editor_state.
2. create_layer for rectangles, ellipses, polygons, stars or text; set_background for a solid state background.
3. create_state duplicates an existing state. Copies preserve stable identity so they animate together. Do not independently recreate matching layers by name.
4. Change the destination with move_layer, resize_layer, rotate_layer, style_layer or reorder_layer. tweens_transform combines supported transform fields.
5. Use set_transition_duration and set_easing for the motion. tweens_media_timing edits supported timing on already imported media.
6. apply_commands makes up to 64 edits atomically. Commands inherit scope and revision; omit both inside each command. Newly created IDs are returned for subsequent calls, not referenced symbolically inside that batch.
7. validate_project; render_preview at the start, midpoint and end. Look at the returned images, not just a success flag.
8. Make targeted repairs, re-render, then export_animation to GIF or MP4. Every output needs a new filename.
9. Open the .tweens file in the app for human review and finishing. Right-click the blank canvas → Open .tweens project…, or drop the file on the canvas. Save .tweens project downloads the editable document. Opening is undoable; autosave is still browser-local. The app does not live-sync the disk file.

Example prompt for a connected agent:

Use Tweens to make a 1.5-second blue geometric logo reveal with a short headline. Create a Start state, duplicate it, and use the same layer IDs in the end state. Inspect the start, midpoint and end PNGs and repair any clipping or overlap you observe. Export a GIF and MP4 plus the editable .tweens project. Ask before replacing any of my existing work.

render_preview returns inline PNG content to image-capable clients and a local file. Exports return the artifact path and dimensions. Validation checks schema, references, limits and evaluation at the requested time; it does not certify visual quality, all timestamps or every codec.

Safety and limits

• Basename-only .tweens files in the chosen directory; no recursive browsing, symlink reads, remote assets, arbitrary URLs, shell or JavaScript tools.
• Document size ≤20 MiB, ≤16 compositions, ≤1000 canonical nodes across the project, ≤100 states per composition, dimensions ≤4096px, duration ≤120 seconds per composition. Projects above these bounds remain a web-editor workflow.
• Artifact size ≤64 MiB; output ≤1280px; integer FPS 1–30; render runtime ≤2 minutes. Chromium is launched only for preview/export and closed afterward.
• Mutations use optimistic disk revisions, an exclusive cooperating-writer lock and atomic file replacement. Stale input and failed batches do not save partial edits. This is not an OS-level compare-and-swap against unrelated programs ignoring the lock.
• Existing artifact/project names are not overwritten on creation. delete_state is separate and requires confirmation; deleting the first state retains its frame but empties its contents. There is no project-file deletion tool.
• One operation at a time; serialize requests. MCP cancellation aborts before commit where possible and closes in-flight Chromium. Cancellation racing an already completed disk commit does not undo it: re-read the file to determine the outcome. Do not blindly repeat writes after an uncertain response.
• A crashed process may leave a .lock file. Confirm no writer remains before manually removing that specific lock. The engine never guesses it is stale.
• The in-memory engine supports transactional undo, but the file MCP adapter has no persistent history tool. Keep backups or use source control for important documents.
• No unattended publishing/upload, asset URL import, remote server, embedded model, or AI taste scoring. New nested compositions, vector editing, masks and advanced asset authoring are not exposed as commands yet. Existing supported document content still uses the shared renderer.
• Local fonts vary by machine. GIF is silent. MP4 requires Chromium H.264 support; sound additionally needs AAC support. Media must be embedded in the project; external network requests are blocked. TWEENS_CHROME can point to a compatible installed Chrome executable.

Verification and release

From the repository root, npm run test:agents tests a real MCP client and real PNG/GIF/MP4 exports. With TWEENS_TEST_URL set to a local development server it also tests browser import and undo/redo. Outputs stay in work/.

npm pack --workspace tweens-cli --pack-destination work builds a distributable tarball including the engine, renderer and dependency notices. Install that exact tarball to test it outside the monorepo. See the engine and distribution plan before npm/Registry publication or a Homebrew tap.