vidcut

The AI-native video editor — your AI cuts through MCP, you supervise in the browser.

繁體中文 · usevidcut.com

What is vidcut?

vidcut is a local-first timeline editor for short-form video — four canvas presets (portrait 1080×1920 by default, plus landscape 16:9, square 1:1 and portrait 4:5) — built around one idea: the AI and the human edit the same timeline, at the same time.

It is not a prompt-to-video generator. An AI agent (Claude Code, or any MCP client) edits the project through 39 MCP tools — importing footage, cutting, captioning, mixing audio, rendering. Every change appears live in your browser over WebSocket. You drag a caption, trim a clip, leave a review note — and the AI reads your adjustments back and keeps working. A human-in-the-loop editing loop, not a black box.

• 🖥️ Local & private — a single Node process on 127.0.0.1:3845. Your footage never leaves your machine.

• 🤝 Built for supervision — the AI can call request_review; you annotate in the browser; it reads your feedback and continues.

• 🔍 WYSIWYG captions & overlays — preview and export render from the same rasterized text card (byte-identical PNGs), guarded by a pixel-level regression suite.

• 🎬 Real render pipeline — ffmpeg composes the final video from project.json at the project's canvas size, with progress reporting.

Related MCP server: mcpCut

How it works

┌──────────────┐   MCP  /mcp    ┌───────────────────────────┐   WebSocket  /ws   ┌───────────────┐
│ Claude Code  │ ─────────────▶ │   vidcut server  :3845    │ ◀────────────────▶ │  Browser UI   │
│ (or any MCP  │                │  ProjectStore · commands  │                    │  timeline ·   │
│  client)     │ ◀───────────── │  ffmpeg · whisper · cards │                    │  A/B preview ·│
└──────────────┘  review loop   └────────────┬──────────────┘                    │  inspector    │
                                             │                                   └───────────────┘
                                        project.json
                                     (single source of truth)

One process, one port, four kinds of traffic: static UI, /media (native Range for <video>), /mcp, and /ws. Every state change — from the AI or from you — goes through the same serialized command path and is broadcast to the browser as immer patches.

Features

• ✂️ Timeline editing — split / delete-left / delete-right / freeze-frame at the playhead, trim by dragging, reorder, magnetic track, cursor-anchored zoom, snapping with guide lines, undo/redo

• 📺 Seamless preview — A/B dual-<video> player for gapless playback across cuts

• 🗣️ Auto captions — whisper.cpp transcription with word-level timestamps, automatic sentence segmentation, one call from audio to styled captions (auto_caption)

• 🎤 Karaoke highlight — per-word color reveal, rendered deterministically (one card per word) so export geometry is exact

• 📝 WYSIWYG text cards — captions and text overlays are rasterized by one Pillow pipeline shared by preview and export; CJK-aware auto-wrapping (per-character CJK, word-boundary Latin, forbidden-punctuation rules)

• 🖼️ Overlays — text or image, drag directly on the canvas with center/safe-margin snap guides

• 🔊 Audio — extract audio from clips, voiceover/BGM tracks, volume & fades, auto-ducking under speech

• 🌫️ Blur fill — when the source aspect ratio does not match the canvas, the gaps get a blurred copy of the frame instead of black bars

• 📤 Export options — output scale (0.67× / 1× / 2× of the project canvas), quality (CRF), 24/30/60 fps, H.264/HEVC; subtitles as burn / embed / sidecar (.srt) / off

• 🖼️ Cover frame — pick any moment as the cover, extracted from the rendered output when available

• 🔁 Review loop — request_review pauses writes, you approve or annotate in the UI, the AI reads get_feedback and continues

Quick start

1. Install prerequisites — Node.js 20+, ffmpeg (with ffprobe), Python 3 + Pillow. whisper.cpp is optional (auto captions only). (The server itself runs on Node ≥18; the UI build in step 2 needs Vite's floor, 20.19+ or 22.12+.)

macOS:

brew install ffmpeg
pip3 install pillow
brew install whisper-cpp   # optional

Debian / Ubuntu:

sudo apt install ffmpeg python3-pil fonts-noto-cjk   # fonts-noto-cjk: CJK text cards
# whisper.cpp (optional): build from https://github.com/ggerganov/whisper.cpp

Windows is untested — the text-card rasterizer spawns python3 directly, so run vidcut under WSL.

2. Run it

git clone https://github.com/mao-data/vidcut.git
cd vidcut
npm install
npm run build -w @vidcut/ui   # builds ui/dist, which the server serves — skip this and :3845 404s
npm run demo                   # scaffolds the demo project and starts the server

Open http://127.0.0.1:3845. No footage needed to try it — npm run demo synthesizes five vertical clips with ffmpeg (one deliberately silent), a title overlay, and two captions.

Your own footage goes in either way. The right panel's Media tab has three zones: Project media (what's already in this project — add to timeline, save to library), Library (search, upload, import, retag, delete — the cross-project asset library at ~/.vidcut/library/, for stuff you reuse across projects like intros or BGM), and Source folder (scan a directory, check files, batch-import). Or point your agent at a folder and it calls import_media, which references files in place without copying them — same asset library on the AI side via list_library / add_to_library / import_from_library. Note: the Source folder zone only lists video/audio (its extension whitelist excludes images); images go in through the Library zone's upload button or the AI's add_to_library, and import into a project as an overlay rather than a timeline clip.

⚠️ npm run demo regenerates projects/demo every time. To serve an existing project without touching it:

npx tsx server/src/index.ts projects/demo

3. Auto captions (optional)

auto_caption needs a whisper.cpp model on disk. vidcut looks in ~/.cache/whisper.cpp/, then the Homebrew share/whisper.cpp/models dirs, and picks the most accurate model it finds:

mkdir -p ~/.cache/whisper.cpp
curl -L -o ~/.cache/whisper.cpp/ggml-large-v3-turbo-q5_0.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin

That file is ~547 MB. Smaller models (medium, small, base, tiny) work too — same URL pattern, lower accuracy. Or point VIDCUT_WHISPER_MODEL at any .bin.

Why Pillow is not optional: it rasterizes every text card. Without it captions still write fine (the preview falls back to a rough DOM approximation), but render with subtitles=burn fails outright once the project has captions, and adding or editing a text overlay (image overlays are unaffected) is rejected outright.

Troubleshooting

Hosted version

Everything above runs on your own machine, for free, under the AGPL — that is the whole product, not a time-limited trial.

If you would rather not run it yourself, usevidcut.com hosts the same editor, with cloud rendering and storage and a larger tool surface. The current tool table for the hosted build is at usevidcut.com/mcp.

Connect your AI

vidcut speaks Model Context Protocol over HTTP. With the server running:

Claude Code

claude mcp add --transport http vidcut http://127.0.0.1:3845/mcp

or in your project's .mcp.json:

{
  "mcpServers": {
    "vidcut": {
      "type": "http",
      "url": "http://127.0.0.1:3845/mcp"
    }
  }
}

Then just talk to your agent:

“Import the clips in ~/footage/cats, keep the best 20 seconds, auto-caption it with karaoke highlight, duck the BGM under my voiceover, and send it to me for review before rendering.”

Any other MCP client works the same way — point it at http://127.0.0.1:3845/mcp.

MCP tools

39 tools, grouped by what they touch:

Tool descriptions in the server are the authoritative, always-current reference — MCP clients see them automatically.

Development

shared/   @vidcut/shared   types + pure functions (used by both sides)
server/   @vidcut/server   ProjectStore, commands, ffmpeg, whisper, MCP, WS, render
ui/       @vidcut/ui       React + Vite: timeline, A/B player, inspector, panels

Note: the server serves ui/dist (the build output). After changing UI source, run npm run build -w @vidcut/ui — only the dev:ui path skips this.

npm install currently reports advisories in transitive dependencies (npm audit for details; --omit=dev narrows it to what actually ships at runtime). They are known, not ignored — bash scripts/gauntlet.sh prints the audit on every full run.

Known limitations

Honesty over marketing:

• Karaoke preview ≠ export, slightly. Exported karaoke captions are correct (one card per word, single layer). The preview composites two cards with a clip-path, which makes text strokes look marginally thicker (~1% of pixels differ; invisible in practice). Non-karaoke captions and all overlays are byte-identical between preview and export.

• Very short audio (≲4 s) gets unreliable word timestamps from whisper.cpp; vidcut normalizes them, but expect less precision.

• The Media panel's Source folder zone doesn't list images. Its extension whitelist covers video/audio only (folder scan and import_media are clip-track oriented); bring images in through the Library zone's upload button or the AI's add_to_library instead — they import as overlays, not timeline clips.

• SVG library assets can't be placed as overlays. They can still be uploaded to and kept in the library, but importing one into a project is refused — ffmpeg can't rasterize svg, so while the browser preview would render it fine, export would fail.

• Single project, single user, localhost — by design, for now.

Roadmap

Next up (see docs/ROADMAP.md): detection tools for AI decision-making (detect_silence / detect_scenes / detect_beats), templates + batch rendering, and transcript-driven long-to-short editing.

Contributing & docs

• CLAUDE.md — agent-facing project rules (also a good map of the codebase's sharp edges)

• HANDOFF.md — current state, how everything is verified, known trade-offs

• docs/superpowers/specs/ — design decisions; docs/superpowers/plans/ — implementation plans

Issues and PRs welcome — see CONTRIBUTING.md (contributions require a lightweight CLA).

License

AGPL-3.0-only. You can use, modify, and self-host vidcut freely; if you offer a modified version as a network service, the AGPL requires you to share your modifications' source with its users.