The cut is the negative. Open Edit prints it.
The cut is the negative. Open Edit prints it.
Open Edit is an AI-native video editor whose editor is an external agent. Your MCP host drives a stdio server; Open Edit owns everything underneath: a content-addressed media store, word-level transcription, an append-only IR edit graph, a melt + ffmpeg render pipeline, a deterministic QC gate. You edit with ops, not pixels: every change, add a clip, trim, cut silence gaps, set gain, drop an overlay, is an append-only IR op in the SQLite edit graph. Ops revert and supersede; the timeline is always derived. There is no cloud editor and no proprietary timeline format: your project is a directory on disk.
The product surface is a local stdio MCP server with six tools: query_project, edit_project, run_script, trigger_render, get_render_job, cancel_render_job. The agent owns the loop; Open Edit executes. The web UI is for human review.
Media lands in a SHA-256 content-addressed store; edit history is an append-only IR edit graph in SQLite (WAL). Rendering runs on your hardware. No account, no upload. Media files never leave your machine.
Renders are durable jobs with a deterministic QC gate: the full 10-check battery (duration, audio sync, black/frozen frames, silence, overlays burned, thumbnail) runs on final and overlay exports; proxy artifacts run lighter structural checks; warm cache hits skip QC entirely. A failed QC names the check and the reason.
Five stages from raw media to a QC-passed deliverable.
Drop files into a project folder. ingest_local copies each file into the SHA-256 content-addressed store and probes it with ffprobe.
faster-whisper (CPU, int8) produces word-level timestamps. Transcripts are packed into silence-aware Markdown the agent can read via get_transcript_packed.
Every edit lands on the append-only IR edit graph: add_clip, trim_clip, set_audio_gain, and more (28 IR op kinds in all). Higher-level ops like apply_silence_gaps and add_hyperframes_overlay expand into several IR ops. Ops can be reverted or superseded; the timeline is derived by replaying applied ops.
The emitter writes the MLT XML; melt renders it, and ffmpeg composites overlays and encodes. GPU mode auto-probes NVENC/AMF/QSV/VAAPI; CPU mode uses libx264.
A deterministic QC gate checks durable renders: the full 10-check battery on final/overlay exports, lighter structural checks on proxy artifacts. A 640x360 review artifact lets a human scrub the full cut, copy timecodes, and leave notes before the final export.
The agent drives through MCP: query_project reads state, edit_project mutates, run_script runs sandboxed multi-step IR edits, trigger_render enqueues renders, get_render_job polls them, cancel_render_job stops them. With --review-only the UI is a pure review surface: preview, timeline, notes. Run serve without it and the same UI hosts a chat loop with selectable LLM providers.
One Python package, hard layering, no magic.
ir is a pure domain: no network I/O, no project state. Storage and render persist and produce; qc gates deliverables; agent/kernel route tools and run the sandbox; mcp, serve, and cli are thin entry points over one dispatcher. Layering is enforced by tests, not by convention.
Step-by-step, with tabs: Linux | Windows
Fastest: the one-command installers — curl -fsSL https://github.com/AH64-dll/OpenEdit/releases/download/v1.3.1/install.sh | bash (Linux/macOS) or irm https://github.com/AH64-dll/OpenEdit/releases/download/v1.3.1/install.ps1 | iex (Windows). They clone, install Python deps, provision Node 22+ and the HyperFrames overlay engine (npm install), check ffmpeg/melt/Chrome, and print a runtime-readiness summary — no sudo, everything under your home.
Paste this into your coding agent (Cursor, Claude Code, OpenCode, Gemini CLI). The agent installs Open Edit itself, verifies the result, and reports the exact paths it created. It will not touch anything outside the clone and the new project folder.
You are installing Open Edit, a local AI video editor that runs as an MCP server. Do the entire install yourself, then verify it end to end.
1. Detect the operating system: Linux or macOS, or Windows.
2. Confirm prerequisites are on PATH: git, and Python 3.11+ (python3 on Linux/macOS, python on Windows). If either is missing, stop and tell the user what to install.
3. Clone the repository and enter it:
git clone https://github.com/AH64-dll/OpenEdit.git
cd OpenEdit
4. Create a virtual environment and install the package:
Linux / macOS:
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ".[mcp]"
Windows (PowerShell):
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -e ".[mcp]"
If PowerShell blocks activation, first run: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
If your shell does not keep the venv active between commands, call the venv binaries directly: .venv/bin/open_edit and .venv/bin/open-edit-mcp on Linux/macOS, or .\.venv\Scripts\open_edit.exe and .\.venv\Scripts\open-edit-mcp.exe on Windows.
5. Install the optional extras (review UI and local transcription):
pip install -e ".[mcp,serve]"
pip install -e ".[mcp,whisper]"
6. Provision the render stack (Node.js 22+ and the HyperFrames overlay engine):
- Check for Node.js 22+: node --version. If missing or older than 22, install Node.js LTS (Linux/macOS: user-local tarball from nodejs.org or your package manager; Windows: winget install OpenJS.NodeJS.LTS or the nodejs.org installer).
- Install the pinned JS dependencies and verify the engine:
npm install --no-audit --no-fund
Linux/macOS: node_modules/.bin/hyperframes --version (must print 0.7.65)
Windows: .\node_modules\.bin\hyperframes.cmd --version
- Check the render binaries are on PATH: ffmpeg and ffprobe, and melt (Linux/macOS; on Windows melt is optional — overlay-only renders do not need it). If any are missing, install them (Linux/macOS package manager, Windows winget for ffmpeg) and note it in your report.
7. Verify the MCP server entry point runs:
Linux / macOS: .venv/bin/open-edit-mcp --help
Windows: .\.venv\Scripts\open-edit-mcp.exe --help
It must print usage with a --project option. If it errors, fix the cause before continuing.
8. Create an edit project. The folder must exist before init:
Linux / macOS:
mkdir -p ~/OpenEditProjects/my-talk
open_edit init ~/OpenEditProjects/my-talk
Windows:
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\OpenEditProjects\my-talk"
open_edit init "$env:USERPROFILE\OpenEditProjects\my-talk"
9. Report back: the absolute clone path, the venv path, the absolute project path (the folder that contains .open_edit/), the hyperframes version from step 6, and confirmation that steps 7 and 8 succeeded. Do not skip or fake the verification. Do not modify anything outside the clone and the new project folder.| Prerequisite | Required | Why |
|---|---|---|
Git | yes | clone the repository |
Python 3.11+ | yes | runs the MCP server, CLI, and tool kernel |
ffmpeg / ffprobe | yes | media probing, HyperFrames overlay burn-in, QC detectors, final encode |
melt (MLT) | recommended | renders the proxy and final timeline; needed for video-clip timelines (overlay-only renders work without it) |
Node.js 22+ | yes | runs the HyperFrames motion-graphics engine — the installers auto-install Node and run npm install (pinned hyperframes 0.7.65) |
$ git clone https://github.com/AH64-dll/OpenEdit.git
$ cd OpenEdit
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -U pip
$ pip install -e ".[mcp]"
$ npm install --no-audit --no-fund # HyperFrames overlay engine (Node 22+)$ pip install -e ".[mcp,serve]" # review UI
$ pip install -e ".[mcp,whisper]" # local transcription$ .venv/bin/open-edit-mcp --helpPS> git clone https://github.com/AH64-dll/OpenEdit.git C:\OpenEdit
PS> cd C:\OpenEdit
PS> python -m venv .venv
PS> .\.venv\Scripts\Activate.ps1
PS> python -m pip install -U pip
PS> pip install -e ".[mcp]"PS> pip install -e ".[mcp,serve]" # review UI
PS> pip install -e ".[mcp,whisper]" # local transcriptionPS> .\.venv\Scripts\open-edit-mcp.exe --helpThe project folder must exist before init: it is never created for you. init writes .open_edit/ inside it and ingests top-level media files (mp4, mkv, mov, webm, mp3, wav, aac, flac, jpg, jpeg, png, webp).
$ mkdir -p ~/OpenEditProjects/my-talk
$ open_edit init ~/OpenEditProjects/my-talkPS> New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\OpenEditProjects\my-talk"
PS> open_edit init "$env:USERPROFILE\OpenEditProjects\my-talk"Projects under OPEN_EDIT_PROJECTS_ROOT (default ~/OpenEditProjects) are the ones the review UI can list.
Point Cursor, OpenCode, or Claude Code at the server. The project path is pinned at startup and is never a model input.
File location: ~/.cursor/mcp.json on Linux/macOS, %USERPROFILE%\.cursor\mcp.json on Windows.
Paste this into your coding agent after the install is done. The agent resolves the real paths on your machine, registers the MCP server in your host's config, and verifies the server starts.
Open Edit is installed and an edit project exists (the folder that contains .open_edit/). Configure your MCP host to launch Open Edit as an MCP server. Do it yourself, then verify.
1. Detect the host you are running in: Cursor, Claude Code, OpenCode, or another MCP client.
2. Resolve the absolute path to the Open Edit MCP binary:
Linux / macOS: <clone>/.venv/bin/open-edit-mcp
Windows: <clone>\.venv\Scripts\open-edit-mcp.exe
Substitute the real clone path from the install step.
3. Resolve the absolute path to the edit project folder (the one containing .open_edit/).
4. Register the server:
- Cursor: edit ~/.cursor/mcp.json (Linux/macOS) or %USERPROFILE%\.cursor\mcp.json (Windows). If the file exists, back it up, then merge the new server into its mcpServers object without removing other servers.
- Claude Code: the same mcpServers shape goes into the project's .mcp.json.
- OpenCode: use OpenCode's own MCP config format (a per-server object with type and command). Do not paste the Cursor shape into OpenCode's config.
The entry to add (Cursor and Claude Code), with real absolute paths substituted:
{
"mcpServers": {
"open-edit": {
"command": "<absolute path to open-edit-mcp>",
"args": ["--project", "<absolute path to the edit project>"],
"env": { "OPEN_EDIT_RENDER_BACKEND": "cpu" }
}
}
}
On Windows, JSON strings escape backslashes, so the command value looks like: C:\\OpenEdit\\.venv\\Scripts\\open-edit-mcp.exe
5. Verify: run the configured command once (open-edit-mcp --project "<project>") and confirm it speaks MCP on stdio, or reload the host's MCP list and confirm the open-edit server appears with its six tools: query_project, edit_project, run_script, trigger_render, get_render_job, cancel_render_job.
6. Tell the user to reload MCP servers in their host (Cursor: Cmd/Ctrl+Shift+P, then "Reload MCP Servers"). Report exactly which file you wrote, the absolute command path, and the pinned project path.{
"mcpServers": {
"open-edit": {
"command": "/ABSOLUTE/PATH/TO/OpenEdit/.venv/bin/open-edit-mcp",
"args": ["--project", "/home/YOU/OpenEditProjects/my-talk"],
"env": {
"OPEN_EDIT_RENDER_BACKEND": "cpu"
}
}
}
}{
"mcpServers": {
"open-edit": {
"command": "C:\\OpenEdit\\.venv\\Scripts\\open-edit-mcp.exe",
"args": ["--project", "C:\\Users\\YOU\\OpenEditProjects\\my-talk"],
"env": {
"OPEN_EDIT_RENDER_BACKEND": "cpu"
}
}
}
}.mcp.json. OpenCode uses its own mcp config format (per-server type/command); see OpenCode's docs. The server itself is host-agnostic.query_project, edit_project, run_script, trigger_render, get_render_job, cancel_render_job.query_project
All reads: assets, timeline view, packed transcript, silence gaps, pending notes, style profile, narrative analysis, asset search
edit_project
Mutations and creative generation: ingest, clip edits, overlays, generate kinds, commit generated ops
run_script
Sandboxed Python for multi-step IR edits the pillar ops cannot express
trigger_render
Enqueue durable render jobs: proxy, final, overlay, preview-chunks
get_render_job
Poll a durable job: progress, diagnostics, QC report
cancel_render_job
Cancel a queued or running job
The human review surface: preview, timeline, renders, notes, style.
It is a readout of the server-derived IR, served by a local FastAPI web app. You preview the cut, scrub the timeline, inspect the edit graph, render review artifacts, leave timecoded notes, trigger the final export. The agent drives; the Studio watches.
$ pip install -e ".[mcp,serve]"$ open_edit serve --review-only --port 8000Open http://127.0.0.1:8000 and select your project (it must live under OPEN_EDIT_PROJECTS_ROOT, default ~/OpenEditProjects).
Three columns (Assets + Edit graph | Preview | Renders + Notes + Style) above a bottom timeline panel with track labels, ruler, playhead, clip blocks, and edit/note markers. Key microcopy: "Render review artifact (640x360)" to bake the proxy, "Copy time" to copy a [MM:SS.ms] timecode, "Note here" to leave a pending note the agent reads via get_pending_notes, "Render final (1080p)" when the cut is approved.
--review-only disables the built-in chat entirely: the WebSocket closes with code 4404. The external agent owns the conversation; the Studio stays a review surface.
From empty folder to QC-passed final, in six steps.
open_edit init ~/OpenEditProjects/my-talk (folder must pre-exist).
Use the mcp.json block from the Configure section; reload MCP.
It calls ops like ingest_local, add_clip, trim_clip, apply_silence_gaps, set_audio_gain, and add_hyperframes_overlay.
Render the proxy, scrub, copy timecodes, drop notes.
The agent reads pending notes and applies the next round of ops; repeat.
Trigger final once the proxy passes review and QC.
| Tool | Responsibility |
|---|---|
query_project | All reads: assets, timeline view, packed transcript, silence gaps, pending notes, style profile, narrative analysis, asset search |
edit_project | Mutations and creative generation: ingest, clip edits, overlays, generate kinds, commit generated ops |
run_script | Sandboxed Python for multi-step IR edits the pillar ops cannot express |
trigger_render | Enqueue durable render jobs: proxy, final, overlay, preview-chunks |
get_render_job | Poll a durable job: progress, diagnostics, QC report |
cancel_render_job | Cancel a queued or running job |
| Mode | What you get |
|---|---|
proxy | One complete whole-file 640x360 review-artifact MP4 for the full timeline: the human review artifact |
final | Full-quality export read from canonical original sources |
overlay | Legacy HyperFrames composite mode (new motion graphics use add_hyperframes_overlay) |
preview-chunks | Dirty-range cache: independent video/audio planes plus a muxed playback artifact, manifest-backed |
| Command | Purpose |
|---|---|
open_edit init [folder] | Create a project (.open_edit/) and ingest top-level media |
open_edit list | List edit-graph ops for the nearest project |
open_edit summary | Derived timeline: tracks and clips |
open_edit undo | Revert the most recent applied op |
open_edit render | Render to MP4 + QC gate: --mode proxy|final, --encoder gpu|cpu |
open_edit asset-proxy | Drain the per-asset source-proxy job queue |
open_edit preview-chunks --job-id ID | Run the durable preview-chunks worker |
open_edit free-form CODE_FILE PROJECT_DIR | Run a Python script in the sandbox; append produced ops |
open_edit notes <list|add|dismiss> | Review notes lifecycle (notes.db) |
open_edit serve | FastAPI review UI: --host, --port, --token, --review-only |
open_edit mcp | stdio MCP server: --project |
Everything is a plain environment variable or a JSON file. No hidden state.
| Variable | Default | What it does |
|---|---|---|
OPEN_EDIT_PROJECT | — | Project path for the MCP server (fallback when --project is omitted) |
OPEN_EDIT_PROJECTS_ROOT | ~/OpenEditProjects | Root scanned by open_edit serve; projects must be subdirectories |
OPEN_EDIT_RENDER_BACKEND | see note | gpu = probe GPU encoders; cpu = software encode |
OPEN_EDIT_NODE_BIN | node | Node executable for the HyperFrames overlay engine (>= 22; legacy Remotion uses it too). HyperFrames resolves its own hyperframes binary via PATH or OPEN_EDIT_HYPERFRAMES_BIN |
OPEN_EDIT_WHISPER_MODEL | base | faster-whisper model size |
OPEN_EDIT_WHISPER_LANGUAGE | auto-detect | faster-whisper language code (e.g. ar) |
OPEN_EDIT_SANDBOX_BACKEND | bwrap (Linux) / dev (Windows) | run_script isolation; dev runs unsandboxed |
OPEN_EDIT_TOKEN | — | Bearer token for serve (enforced when the client is not localhost) |
OPEN_EDIT_SERVE_HOST / OPEN_EDIT_SERVE_PORT | 127.0.0.1 / 8000 | Review UI bind address and port |
The full list (QC policy knobs, cache budgets, asset-proxy concurrency) is in .env.example in the repo root.
| Provider | Key | Notes |
|---|---|---|
anthropic (default) | ANTHROPIC_API_KEY | default model claude-sonnet-4-5; included in the base install |
openai | OPENAI_API_KEY | requires the .[openai] extra |
pi | PI_API_KEY | via the pi CLI binary |
opencode | OPENCODE_API_KEY | via the opencode CLI binary |
antigravity | ANTIGRAVITY_API_KEY | via the agy/antigravity CLI binary |
No. GPU mode auto-probes NVENC/AMF/QSV/VAAPI and falls back to libx264 when nothing probes. Set OPEN_EDIT_RENDER_BACKEND=cpu to always use software encoding: slower, but zero GPU required.
run_script executes Python in a bwrap + seccomp jail on Linux, fail-closed by default. On Windows it defaults to dev (unsandboxed, run as a plain subprocess), and an explicit OPEN_EDIT_SANDBOX_BACKEND=bwrap is rejected: the host harness owns isolation there.
Required for motion graphics. Node.js 22+ runs the HyperFrames overlay engine (HTML/CSS/JS, pinned hyperframes 0.7.65). The one-command installers auto-install Node (user-local, no sudo) and run npm install. Point at a specific binary with OPEN_EDIT_NODE_BIN; without Node you lose motion-graphics overlays — everything else works. Remotion is legacy.
Overlays with transparency land on ProRes 4444 (.mov) on Windows, because WebM/VP8 alpha is unreliable there. The choice is probe-driven: auto verifies VP8 alpha with a real encode round-trip and uses prores when that fails. Linux/macOS use WebM/VP8 (libvpx).
The moviepy generate_visual_for_segment generation op (it needs the Linux render-sandbox binary) and same-pass frame feeding to melt (POSIX inherited descriptors). Everything else, ingest, IR edits, Remotion/HyperFrames, proxy/final render, works.
Install the whisper extra: pip install -e ".[mcp,whisper]". faster-whisper runs on CPU with int8 quantization and word-level timestamps. Tune it with OPEN_EDIT_WHISPER_MODEL (default base) and OPEN_EDIT_WHISPER_LANGUAGE (unset = auto-detect; small is recommended for Arabic).
Open Edit itself is free. If you use Remotion compositions, Remotion may require a company license: see docs/REMOTION_LICENSE.md. Native HyperFrames (HTML/CSS/JS) motion graphics carry no such dependency.
Inside the project directory under .open_edit/: media in a SHA-256 content-addressed store, the edit graph in SQLite (WAL), renders and caches alongside. No external service ever sees your media files.