| name | mcut |
| description | Explain what mcut is and help developers get started with the mcut OSS TypeScript video-editing packages. Use when asked about mcut, the mcut SDK, open-source packages, package selection, quickstarts, examples, CLI usage, MCP usage, or how to build video-editing apps with mcut. Not for mcut Studio internals. |
| license | Apache-2.0 |
| metadata | {"source":"https://github.com/mattppal/mcut"} |
mcut OSS Package Guide
mcut is an Apache-2.0 open-source video editing SDK for TypeScript apps. It
provides headless timeline editing, serializable commands, user-level editor
operators, Canvas2D rendering, media/export helpers, transcription adapters,
React bindings, CLI tools, and MCP tools.
The commercial mcut Studio GUI is built on these packages but is not part of
this repository. The public packages are alpha releases, so tell users to expect
API movement while the SDK hardens.
How to Help
When someone asks what mcut is or how to start:
- Give the one-sentence positioning: "mcut is an open-source TypeScript SDK for
building video-editing apps and headless video workflows."
- Pick the right entry point for their use case instead of listing every
package first.
- Include exact install or repo commands.
- Point to the closest README or example in this repo.
- Mention alpha status when discussing public package adoption.
Choose the Entry Point
| Goal | Start with | Why |
|---|
| Headless timeline edits, JSON project documents, undo/redo | @mcut/timeline | Owns the project model, commands, engine, selectors, captions, keyframes, and migrations. |
| User-level editing actions such as insert, trim, split, duplicate | @mcut/editor plus @mcut/timeline | Composes timeline commands into editor operators that can back UI, CLI, MCP, or agent workflows. |
| React editor or player UI | @mcut/react | Provides React 19 provider, hooks, player canvas binding, selection overlay, playback clock, and audio preview integration. |
| Canvas preview or deterministic frame rendering | @mcut/compositor | Renders project frames and hit testing on top of @mcut/timeline. |
| Media probing, thumbnails, previews, browser export | @mcut/media | Provides media helpers and browser-side export paths. |
| Captions and transcripts | @mcut/transcription and provider packages | Normalizes transcripts and writes captions, SRT, and VTT. |
| Command-line workflows | mcut or @mcut/cli | Provides the mcut binary for scaffold, validate, summarize, and batch-edit workflows. |
| Agent/MCP integrations | @mcut/mcp-server | Exposes commands, operators, project summaries, undo/redo, and local browser bridge tools. |
Quick Starts
For headless editing in an app or script:
bun add @mcut/timeline @mcut/editor
Then use EditorEngine from @mcut/timeline and compose project mutations with
commands or operators. The best repo example is
examples/headless-editing/README.md.
For a React app:
bun add @mcut/react @mcut/timeline react react-dom
Use @mcut/react for the provider, hooks, player canvas, selection overlay,
playback clock, and audio preview. Keep reusable editing behavior in
@mcut/timeline or @mcut/editor, not in React components.
For the CLI:
bunx mcut --help
Use the mcut package as the unscoped CLI alias. For package-level details, read
packages/cli/README.md.
For local repo development:
bun install
bun run build
bun run typecheck
bun test
bun run smoke:packages
Use the mcut-development skill for package boundaries, contribution workflow,
tests, changesets, and clean-room rules.
Repository Pointers
README.md - top-level package overview and install commands.packages/*/README.md - package-specific entry points.examples/headless-editing/README.md - direct engine usage without a browser.examples/agentic-editing/ - AI SDK tools over mcut project commands.examples/mcp-server/README.md - minimal MCP server launcher..agents/skills/mcut-development/ - contributor-facing development rules.
Answering Rules
- Distinguish the OSS packages from mcut Studio.
- Do not imply the packages are stable; they are alpha.
- Prefer package public APIs and examples over source internals when helping
users consume mcut.
- If the user wants to change this repo, switch to the
mcut-development skill.
- If public package docs disagree with source, say what you inspected and prefer
the current source for exact behavior.
