vean

vean

vean studio — Video Editor, Agent Native · vean.studio

The agent-native video editing core. A typed document, edit algebra, and diagnostics layer for video editing on top of MLT — a language server for video.

Status: active development. The headless core, action runtime, React/Remotion viewer, and local Tauri app are implemented behind verification gates. Package, release, and remaining breadth work is tracked in ROADMAP.md.

Why

Video editors maintain timeline validity implicitly, inside carefully-written command code, and never tell anyone why an edit is or isn't valid. That's fine for a human dragging clips; it's hostile to an agent — and to anyone who wants to build a different UI on top.

vean inverts that. It is a frame-exact, rationally-timed model of a timeline that an agent (or a UI, or a human) mutates through a closed set of operations, each of which reports its consequences before a single frame renders:

• a typed IR for an MLT timeline — multi-track, audio, keyframes, filters, transitions — that round-trips losslessly to .mlt XML (the format Shotcut and Kdenlive read/write);
• a pure edit algebra — op(state) → {state', consequences, inverse} — so every edit is legible, reversible, and identical whether a human or an agent issues it;
• a diagnostics layer (the "LSP"): gaps/overlaps, out-of-bounds keyframes, A/V-sync hazards, dial-range violations, plus go-to-definition (resolve a param's value at a frame, through clip → track → tractor → transition) and find-references (what uses this source, what ripples if I move this).

vean's core is not a renderer, a motion-graphics engine, or a GUI. It delegates:

• Render → melt (MLT/FFmpeg), driven as a separate process. The CLI/source install uses system deps; the Mac app can bundle pinned renderer sidecars.
• Motion graphics → Remotion, as a producer (pre-rendered alpha clips for export; @remotion/player for live preview).
• UI → the local Tauri Mac app in app/, built on this core. The website is for download/docs, not a web editor.

The timeline core is stateless: files in, files out. Product coordination state is local-only: CLI/LSP/MCP/app metadata lives in gitignored .vean/vean.db and never replaces committed timeline files.

Architecture

Four layers:

1. Core (headless) — the typed document + serialize/parse + keyframes + edit algebra + diagnostics + the melt/ffmpeg driver.
2. Action runtime — one typed registry for product behaviors, projected to Commander CLI, MCP tools, deterministic LSP code actions, and the Tauri app. Every public action is available through ergonomic commands or vean action run <id> --input-json ....
3. Agent bridge — vean-lsp for ambient diagnostics/navigation/code actions, plus CLI/MCP tools for domain actions (apply-op, preview-op, undo, render, still, resolve-value-at-frame, find-references) + skills. diagnose remains a debug/CI command, not the normal agent safety loop.
4. Local Mac app — a Tauri app for project selection, media catalog, timeline/preview, render/still review, jobs, and agent orchestration with git-worktree exploration. It uses the same action runtime and local state as the CLI.

Human gestures and agent actions are the same operations — both update the same document, both get undo, and vean-lsp pushes diagnostics as ambient feedback the way coding agents expect from TypeScript/Pyright/rust-analyzer.

Relationship to MLT, Shotcut, and Remotion

• MLT is the engine — we depend on it (LGPL framework + the GPL melt CLI), driven at arm's length via the public .mlt format. We do not link it.
• Shotcut (GPL) is the spec, not a dependency — its edit-command semantics and per-filter dial metadata are the answer key we reimplement in a typed, Qt-free shape.
• Remotion is a producer, not a co-renderer. The MLT timeline is the spine; Remotion graphics are alpha clips on it.

Status & roadmap

Building in phases, each behind a gate — see ROADMAP.md. Move 0 is the document core (round-trip + render-faithfulness); the spine reaches a usable agent-editing loop by Move 2; Move 3 hardens the action registry, Commander CLI, and project/media ergonomics; Move 4 is the local Mac app.

Requirements

• Bun
• mlt (provides melt) and ffmpeg — brew install mlt ffmpeg / apt install melt ffmpeg
• Rust/Cargo for native Tauri app builds — macOS: brew install rust

Claude Code / Agent Setup

This repo is also a Claude Code plugin root: