editorvideo-ai

<p align="center"><img src="https://raw.githubusercontent.com/metiutek/editorvideo-ai/main/docs/logo/logo.png" alt="vedit logo" width="120"/></p> <h1 align="center">vedit — tell an AI to edit your video, and watch it happen</h1> <p align="center"> <strong>A normal video editor — timeline, clips, cuts, transitions — except an AI can use it for you.</strong><br/> You say what you want in plain words. It does the editing while you watch the clips move, and you can grab the mouse and fix anything at any point. </p> <p align="center"> <a href="https://github.com/metiutek/editorvideo-ai/actions/workflows/ci.yml"><img src="https://github.com/metiutek/editorvideo-ai/actions/workflows/ci.yml/badge.svg" alt="CI"/></a> <a href="https://pypi.org/project/vedit-mcp/"><img src="https://img.shields.io/pypi/v/vedit-mcp.svg?style=flat-square" alt="PyPI"/></a> <a href="https://pypi.org/project/vedit-mcp/"><img src="https://img.shields.io/pypi/pyversions/vedit-mcp.svg?style=flat-square" alt="Python versions"/></a> <img src="https://img.shields.io/badge/AI%20tools-92-blueviolet?style=flat-square" alt="92 AI tools"/> <img src="https://img.shields.io/badge/runs-100%25%20local-brightgreen?style=flat-square" alt="Runs locally"/> <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"/> </p> <p align="center"> <img src="https://raw.githubusercontent.com/metiutek/editorvideo-ai/main/docs/vedit-promo.gif" alt="vedit promo — you say what you want, the agent edits the timeline, checks its own work, and you stay in control with Ctrl+Z" width="820"/> </p>

🇮🇹 Italiano: README.it.md

Install — 3 steps

1. Install uv (it installs Python apps for you). Then close and reopen the terminal.

| Windows (PowerShell) | macOS | Linux | |---|---|---| | winget install astral-sh.uv | brew install uv | curl -LsSf https://astral.sh/uv/install.sh \| sh |

2. Install vedit and ffmpeg

uv tool install vedit-mcp
vedit install-ffmpeg

If the terminal says vedit is not recognized, run uv tool update-shell, then close and reopen the terminal.

3. Open the editor

vedit ui

The editor opens in your browser at http://127.0.0.1:8760. That's it.

Optional — let Claude Code edit for you: claude mcp add vedit -- vedit-mcp. This only connects Claude Code to vedit; it does not install anything, so do step 2 first.

Something wrong? vedit doctor tells you what is missing and how to fix it.

---

What it is

vedit is a video editor. The ordinary kind: a timeline, video and audio tracks, clips you drag, cut, speed up, colour-grade and fade into each other.

The difference is that everything you can do with the mouse, an AI can also do on command — because the buttons and the AI call the exact same 86 operations. Nothing is AI-only, nothing is mouse-only.

So instead of half an hour of trimming, you type:

"Cut the first 40 seconds, remove the pauses where I say nothing, speed the screen recording up 2×, cut the b-roll on the beat of the music, and burn in subtitles."

and the clips rearrange themselves on the timeline in front of you. If it puts a cut in the wrong place, you drag that one clip and keep going. It is not a black box that hands you a finished file you cannot touch — it is your editing software, with a second pair of hands.

Who it is for

• Anyone who edits talking-head, tutorial or gameplay video and is tired of spending two hours on decisions that were never creative: finding the good take, cutting dead air, matching cuts to music, redoing the same volume curve.
• People who already work with Claude Code, Cursor or Codex. One line of setup and your coding agent can edit video, the same way it edits files.
• Developers who want video editing in a script or a pipeline — the whole project is a JSON document, so it can be generated, diffed and version-controlled like source code.

Why use it instead of the alternatives

| | | |---|---| | vs. "AI video generators" | They give you a finished clip you cannot fix. vedit gives you the project, every clip, every knob — and the AI only moves the same controls you would have moved. | | vs. Premiere / DaVinci / CapCut | Those give you every control and none of your time back. Here the boring 80 % is delegated and the last 20 % stays in your hands. | | vs. an ffmpeg script | Same speed and precision, but you can actually see what happened, scrub it, and undo it. | | Cost and privacy | Runs on your machine. No subscription, no upload, no watermark, no render queue. MIT licensed. |

Code, comments and UI messages are in Italian — that is the project convention.

---

What makes it work

An AI that cannot see the edit produces garbage. These are the parts that make the difference between a demo and something you would actually cut a video with:

| | | |---|---| | An agent can actually edit | 92 MCP tools that are the same operations as the buttons: cut, split, speed, keyframes, effects, transitions, render. Nothing is agent-only, nothing is UI-only. | | The agent can see what it did | preview_frame returns the real rendered frame, preview_grid the whole edit as a contact sheet. An agent that guesses produces garbage; this one looks. | | It cuts on the beat, for real | music_beats returns BPM, beat and bar length, first-beat offset and an energy profile, so cuts land on the music instead of near it. | | It picks the takes | plan_edit splits shots longer than 12s into their own segments and scores them individually — three minutes of continuous footage becomes dozens of candidates with a real in-point. | | Same project, same file | The render is deterministic. No hidden state, no "works in the preview, breaks on export". | | You keep the timeline | Whatever the agent does shows up in the web UI, on the same in-memory project, and undoes with one Ctrl+Z. |

---

Table of contents

• Install — 3 steps
• Install, in detail
• Quick start
• Driving it from an agent (MCP)
• The web interface, panel by panel
• Keyboard shortcuts
• Command line
• What it can do
• Keyframes
• How it works
• Tests
• Known limits
• FAQ
• Contributing
• License

---

Install

Just to use it — nothing to clone

The three steps are at the top of this page. Details:

• The package on PyPI is vedit-mcp (the name vedit was taken; the commands are still vedit and vedit-mcp). The compiled web interface ships inside it: no build step.
• claude mcp add only registers the server with Claude Code, it installs nothing. Without step 2 the vedit command does not exist.
• No permanent install? uvx --from vedit-mcp vedit ui downloads and runs it on the spot.
• Prefer pipx? pipx install vedit-mcp does the same as uv tool install.

Same JSON for every other client (Cursor .cursor/mcp.json, Codex, VS Code):

{ "mcpServers": { "vedit": { "command": "vedit-mcp", "args": [] } } }

ffmpeg is the one thing pip cannot bring along — it is a program, not a Python package. If it is missing, don't go hunting: vedit install-ffmpeg downloads a static build of ffmpeg and ffprobe into ~/.vedit/bin. No administrator rights, no system changes, uninstalled by deleting the folder. The agent has the same thing as the install_ffmpeg tool. If ffmpeg is already on your PATH, that one wins — it usually has more hardware encoders.

To hack on it — one command

git clone https://github.com/metiutek/editorvideo-ai.git
cd editorvideo-ai
python scripts/setup.py

The script does everything: Python dependencies, compiled web interface, MCP server registered, then vedit doctor and the fast tests as verification. It prints one line per step and ends by telling you what is still missing and how to fix it. Re-running it is safe — anything already in place is skipped.

python scripts/setup.py --venv             # dependencies in .venv instead of the current interpreter
python scripts/setup.py --install-ffmpeg   # try winget / brew / apt
python scripts/setup.py --no-frontend      # CLI and MCP only, no web interface
python scripts/setup.py --rebuild          # rebuild the UI after touching frontend/src
python scripts/setup.py --json             # machine-readable result, for scripts and agents

Then vedit ui → http://127.0.0.1:8760.

Requirements

| | | |---|---| | Python | 3.10+ | | ffmpeg + ffprobe | on PATH, downloaded with vedit install-ffmpeg, or pointed at with VEDIT_FFMPEG / VEDIT_FFPROBE | | Node.js | 18+, only to compile the interface from source the first time | | GPU | optional. NVIDIA / Intel / AMD are detected and used for rendering automatically |

Optional extras

Everything below is optional; without them the rest of the editor behaves identically and the tools that need them say what to install.

pip install -e ".[chat]"        # anthropic — Claude with an API key in the assistant (other models need nothing)
pip install -e ".[vision]"      # ultralytics — detect_subjects, track_mask, auto_reframe, remove_background, pin_to_subject (pulls torch)
pip install -e ".[transcribe]"  # faster-whisper — transcribe, make_captions, tighten_speech, censor_speech
pip install -e ".[html]"        # playwright — renders HTML clips (uses the Chrome or Edge you already have)
pip install -e ".[plugin]"      # pedalboard — VST3 / AU audio plugins (VST2 .dll are not supported)

numpy and Pillow are not extras: footage analysis, music-timed editing, preview_grid and color_scopes stand on them, and looking at your edit is rule number one.

---

Quick start

End to end, three commands:

vedit new film.json --preset 1080p
vedit import film.json shots/*.mp4 music.mp3 && vedit info film.json   # prints media ids
vedit add film.json <media_id> --duration 3 && vedit render film.json out.mp4

Or open the editor and do it by hand:

vedit ui                                     # http://127.0.0.1:8760
vedit ui --project film.json                 # opening a project directly
vedit ui --port 9000 --no-browser

The .json is the project: your video files stay where they are, nothing is copied. Format presets: 1080p, 1080p60, 4k, 720p, vertical (9:16, for reels and shorts), vertical60, square.

---

Driving it from an agent (MCP)

No VS Code needed. Someone who downloads vedit just runs vedit ui (or uvx --from vedit-mcp vedit ui) and works in the browser; the assistant inside the app can be Claude Code itself (see Assistant below). Editors and terminals are one option, not a requirement.

The running editor is an MCP server too, at http://127.0.0.1:8760/mcp/. Any client that connects there works on the project open in the browser — one project in memory, one writer, every edit visible as it happens:

claude mcp add --transport http vedit-live http://127.0.0.1:8760/mcp/

The classic stdio server is still there for agents that start without a UI:

.mcp.json is already in the repo, so opening this folder in Claude Code offers the vedit server on first launch (approve it once). Anywhere else:

claude mcp add vedit -- uvx vedit-mcp

Typical tool flow:

project_create → import_media → plan_edit (choose the material) → add_clips
   → refine (set_transition, set_speed, set_transform, add_effect, set_audio)
   → preview_grid to look at it → render_video

Times are in seconds. Every animatable parameter also accepts a keyframe block — `{"kf": [{"t": 0, "v": 0}, {"t": 2, "v": 1, "ease":