English | 简体中文

Velocut — AI-native video editing in the browser

Velocut, by Ribbi, is an AI-native, local-first video editor that runs entirely in the browser — no install, no upload, your footage never leaves your machine. A canonical Rust engine (compiled to WASM) is mirrored by a TypeScript reference engine and kept in lock-step by shared golden-vector tests; WebGPU handles compositing and WebCodecs handles decode/export; and an LLM agent edits through the exact same JSON command protocol a human drives from the UI.

Protocol-first, AI-native. Humans edit via the UI, the LLM issues JSON commands directly — both flow through one command pipeline into one document model. The AI agent is treated as the system's first-class user; the human UI's job is to make the agent's perception and actions visible and correctable.

Requirements

• Node ≥ 22.6 (npm test uses --experimental-strip-types; a .nvmrc is at the repo root)
• Browser: Chrome / Edge 113+ (WebGPU + WebCodecs; Safari/Firefox not yet supported)
• Optional: Rust stable + wasm-pack (only to build the canonical WASM engine)

Quick start (zero-dependency, TS engine)

cd web
npm install
npm run dev

Works out of the box: when the DI container detects the WASM bundle is absent, it falls back to the TypeScript reference engine (a badge in the top-right shows the active engine).

Enable the Rust/WASM engine (canonical implementation)

# one-time setup
rustup target add wasm32-unknown-unknown
cargo install wasm-pack

# build and drop into the app's public dir (or: just build-wasm)
wasm-pack build crates/velocut-wasm --target web --release \
  --out-dir web/apps/editor/public/wasm

cd web && npm run dev   # badge switches to "engine: Rust/WASM"

Agent quick start

Velocut's first "user" is the AI agent. Click the ⌘ Agent bubble (bottom-right), configure a provider in the settings panel (your own Anthropic API key works as-is), and edit in natural language — "cut out the silent parts", "add a title at the start".

• The key lives only in your browser's localStorage; requests go straight from the browser to the configured endpoint with no intermediary server (trust model: SECURITY.md).
• The agent can see (frame grabs / contact sheets), hear (loudness & silence analysis), and cut (shot-boundary detection). Every edit uses the same command protocol as the UI, so each step is visible in a chat card and the branching history tree — click to jump, undo to roll back.
• Relays/gateways are first-class: the ⚙ provider settings take any Anthropic-protocol-compatible base URL (LiteLLM, one-api, a corporate proxy), a choice of x-api-key or Authorization: Bearer auth, custom model ids, and a one-click connection test. The endpoint must allow browser (CORS) requests.

Optional capabilities & key convention (dev server only)

Web search (Gemini grounding) and MiniMax cloud TTS are proxied by the Vite dev server, which injects the secrets server-side so the browser never holds them:

# both optional; the files are gitignored, placed under web/apps/editor/
echo "<your Google API key>"  > web/apps/editor/.google-key    # velocut_search
echo "<your MiniMax key>"     > web/apps/editor/.minimax-key   # cloud TTS (local TTS needs no key)

Note: these proxies exist only under npm run dev; after a static vite build, search and cloud TTS are unavailable.

Testing (both engines share golden vectors)

cargo test                # the Rust engine runs protocol/vectors/*.json
cd web && npm test        # the TS engine runs the same vectors + unit tests
cd web && npm run e2e     # Playwright smoke (boot / import / edit / persistence)

Any change to engine behavior must land as a new vector, and both sides must pass to count as consistent. Beyond the vectors, the suite covers the agent tool-use loop (via an injected transport), the effect/motion-spec registries, and two end-to-end Chromium journeys. CI (.github/workflows/ci.yml) gates every PR on four jobs: Rust (fmt + clippy + vectors), TS (vectors + unit tests + tsc), a WASM compile smoke test, and the E2E suite. See CONTRIBUTING.md for the flow.

Repository layout

crates/
  velocut-core/        # canonical engine: model / commands / eval / history (pure Rust, no wasm deps)
  velocut-wasm/        # wasm-bindgen bindings (string-JSON ABI)
protocol/
  vectors/             # golden test vectors — the behavioral contract for both engines
web/
  packages/protocol/   # TS protocol types + zod validation (1:1 shape with the Rust serde model)
  packages/core-ts/    # TS reference engine (frontend fallback; runnable on Node)
  packages/render-sdk/ # WebGPU compositing / WebCodecs decode+export / workers / perception (grabs, shots, loudness)
  packages/agent-sdk/  # Anthropic-protocol tool-use loop (injectable transport)
  packages/collab-sdk/ # local-first persistence + multi-tab CRDT sync (Yjs)
  apps/editor/         # Vite + React editor (canvas timeline / branching history / agent console)

Current capabilities

1. ✅ Multi-track editing: split / drag / snap / speed / trim / track reorder, with a branching edit history (go back and edit to fork a new branch; human vs. AI actions are color-attributed).
2. ✅ Keyframe animation (linear / hold / bezier) + an effect registry (color grade, etc.) + transitions.
3. ✅ Text layers & caption styling (rasterized → composited through the same WebGPU pipeline as video).
4. ✅ Audio: mixed playback, volume keyframes (fade-in/out, ducking), TTS narration (local / MiniMax), Whisper auto-captions.
5. ✅ Agent perception: frame-grab observation / shot-boundary detection / loudness & silence analysis, surfaced as images and sparklines in chat.
6. ✅ Declarative motion graphics (motionClip): keyframed layers described by a JSON spec — persisted, and safe to author from the sandboxed script tool.
7. ✅ Export: WebCodecs encode + mp4 mux (streaming, no whole-clip memory bloat); background low-res proxy transcode for smooth preview.
8. ✅ Local-first: media in OPFS, document + history in IndexedDB, real-time multi-tab sync.
9. ✅ Multi-project management: a toolbar project switcher with fully isolated per-project storage (document, history, media, caches).

Keys: Space = play / S = split / Delete = delete / Cmd+Z = undo / Ctrl+wheel = zoom timeline / drag a clip edge to trim / right-click a track head or clip for a menu.

Programmatic entry points

• DevTools / external scripts: window.velocut.apply({type:'splitClip', clipId:'clip_2', atUs:1500000})
• Node-side engine: @velocut/core-ts (consumed inside the workspace; standalone npm publish is on the roadmap).

Command protocol → PROTOCOL.md. Architecture decisions → ARCHITECTURE.md. Security & trust model → SECURITY.md.

License

MIT © 2026 willbean