Velocut: a browser video editor where the LLM drives the same JSON command pipeline as the UI
AI-native, local-first video editor by Ribbi — runs entirely in the browser. Rust/WASM engine, WebGPU compositing, WebCodecs export; humans and LLM agents edit through the same JSON command protocol.
At a glance
- What is it?
- Velocut is an MIT-licensed, local-first video editor from Ribbi that runs entirely in the browser, with a Rust/WASM engine mirrored by a TypeScript reference and an MCP-facing agent that edits through the same command protocol as the human UI. The interesting design decision is protocol-first agent integration; the practical limits are Chrome-only support and a dev-server-only proxy for optional cloud features.
- Who is it for?
- Adopt Velocut if your editors work in Chrome or Edge 113+ and you want an agent that manipulates the same document model the human UI does, with undo and a branching history tree as the safety net. Do not adopt it if you need Safari or Firefox, if you need search or cloud TTS in a static production build, or if you need a published npm version today; the README states registry publication is a separate maintainer step.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: agent video editing usually means a second, worse editing model
Most attempts to put an LLM in front of a video editor end up with two systems: the UI's editing model and a separate agent-facing layer that approximates it. The approximation drifts. Velocut's stated position is the opposite. The README describes one command pipeline into one document model, with humans editing via the UI and the LLM issuing JSON commands directly, and it calls the AI agent the system's first-class user while the UI's job is to make the agent's perception and actions visible and correctable. That framing matters more than the feature list. If the agent's commands are the same commands the UI emits, then an agent edit is undoable through the same history tree, and a bug in the agent's output is a bug in the shared protocol rather than a gap between two implementations. The target user is a developer or technically comfortable editor who works in Chrome, wants media to stay on the machine, and is willing to configure a model provider rather than pay for a hosted service. The README notes that no model key is needed for manual editing or the Codex plugin, so the agent is optional rather than the entry fee.
Two engines, one set of golden vectors
Velocut ships a canonical Rust engine compiled to WASM and a TypeScript reference engine, kept in lock-step by shared golden-vector tests. That is the architecture decision the rest of the project hangs off. The Rust side is built with wasm-pack against the wasm32-unknown-unknown target and dropped into web/apps/editor/public/wasm; the editor falls back to the TypeScript engine if that bundle is absent, and the status bar reports which engine is active. The README is explicit that portable releases use the TypeScript engine by default for reproducibility, and that including fresh Rust/WASM artifacts requires setting VELOCUT_INCLUDE_WASM=1 when running npm run build:release. The consistency rule is stated plainly: any change to engine behavior must land as a new vector, and both sides must pass to count as consistent. This is a heavier process than most browser editors carry, and it exists because the same protocol is exposed to an external agent. A silent divergence between the two engines would be a correctness bug for every API consumer, not just a rendering artifact. The cost is that contributors touching engine behavior pay a two-language tax on every change.
Media path: WebGPU for compositing, WebCodecs for decode and export
Compositing runs on WebGPU and decode and export run on WebCodecs. Both are the reason the browser requirement is Chrome or Edge 113+, and the README states Safari and Firefox are not yet supported. There is no server-side render step to fall back on. The README's local-first claim is scoped carefully: media storage and rendering stay on your machine, while AI observations and optional cloud features send the data needed by the selected provider. So local-first here means the timeline, the assets and the pixels, not the model calls. The editor screenshot in the README shows a multi-track timeline with waveforms, keyframes, transitions, speed ramps and a WebGPU-composited preview, which is the feature set the compositing path is carrying. For export, WebCodecs means the encode happens in the browser process; the README does not describe a queue, a background worker topology or a headless render mode, so anyone planning unattended batch renders should treat that as unverified and check the source before designing around it.
Running Studio: a portable bundle, npx, or a source checkout
The README gives three entry points, and they are not equivalent. The portable release is extracted and started with node start-studio.mjs, which serves the prebuilt editor and opens the browser; no npm install or source checkout is required. The README warns that you must keep the terminal running and reuse the printed hostname and port, because browser projects are scoped to that origin. That is a real operational constraint: change the port and you are looking at a different project store. The npm path is npx @velocut/cli@0.0.1 studio, but the README says registry publication is a separate maintainer step and that you should not assume a version has been published just because it builds in the repository. From source it is git clone, cd velocut/web, npm ci, npm run dev, and the dev command builds workspace SDKs first. Node 22.6 or newer is required because npm test uses --experimental-strip-types, and a .nvmrc sits at the repo root. Agent access comes in two shapes: the portable release directory doubles as a local Codex plugin marketplace, where you add the directory as a marketplace source, install Velocut, start a new Codex task and ask Codex to connect to the running Studio URL, which returns a pairing link. Other MCP clients start the published @velocut/mcp package through npx or its installed velocut-mcp executable. In both cases reasoning runs in the client's model while the editor owns rendering, state, conflicts and undo.
Provider configuration is a settings panel, not a config file
The agent path is configured in the UI. Click Assistant in the workspace navigation and configure a provider in the settings panel; the README states your own Anthropic API key works as-is, and that the key lives only in the browser's localStorage with requests going straight from the browser to the configured endpoint with no intermediary server. The provider settings accept any Anthropic-protocol-compatible base URL, including LiteLLM, one-api or a corporate proxy, with a choice of x-api-key or Authorization: Bearer auth, custom model ids, and a one-click connection test. The constraint that follows is easy to miss: the endpoint must allow browser CORS requests. If your gateway does not send the right CORS headers, the connection test will fail and there is no server-side relay in the shipped design to route around it. The README points to SECURITY.md for the trust model, which is where you should read before putting a production key in a browser. Two optional capabilities behave differently. Web search (Gemini grounding) and MiniMax cloud TTS are proxied by the Vite dev server, which injects secrets server-side from web/apps/editor/.google-key and web/apps/editor/.minimax-key, both gitignored. The README states these proxies exist only under npm run dev, so after a static vite build, search and cloud TTS are unavailable. Local TTS needs no key.
What the agent can actually do, and where the trust sits
The README lists the agent's perception as frame grabs and contact sheets for seeing, loudness and silence analysis for hearing, and shot-boundary detection for cutting. Each edit goes through the same command protocol as the UI, so every step appears in a chat card and in the branching history tree, where you can click to jump and undo to roll back. That visibility is the compensating control for giving an LLM write access to a timeline. The README's example prompts are short and concrete: cut out the silent parts, add a title at the start. Note what is not claimed. There is no statement about how the agent resolves ambiguous instructions, how it behaves on long timelines, or what happens when a command batch partially fails. The README does say the agent reads the project and lands a styled closing title card in one atomic batch, which implies batching exists, but the failure semantics of a batch are not described. If you plan to let an agent run unattended on real footage, that gap is the first thing to investigate in the code, not in the marketing copy.
Testing and the maintenance bill
The test story is the strongest evidence of intent in the repository. cargo test runs the Rust engine against protocol/vectors/*.json; cd web && npm test runs the TypeScript engine against the same vectors plus unit tests; cd web && npm run e2e runs a Playwright smoke suite covering boot, import, edit and persistence. Beyond the vectors, the README says the suite covers the agent tool-use loop via an injected transport, the effect and motion-spec registries, and browser journeys covering editing, native 3D authoring, GLB import, MCP and compact layouts. CI checks Rust formatting, clippy and vectors, TypeScript vectors, unit tests and tsc, a WASM compile smoke test, and the E2E suite, with a separate distribution workflow that installs real tarballs and checks the prebuilt CLI and SDK. The maintenance cost this implies is not small. Engine behavior changes require a new vector and two passing implementations. The optional Rust toolchain means contributors who only touch the TypeScript side still need to know that their change may need a matching vector. The licence is MIT, which permits commercial and closed-source use and modification provided the copyright notice and permission notice are included; that is a summary of the licence text, not legal advice, and if you are redistributing a modified build you should read LICENSE and your own counsel's view rather than this paragraph.
When Velocut is the wrong tool
The clearest boundary is the browser matrix. If your team standardises on Safari or Firefox, Velocut does not run there yet, and no amount of configuration changes that because WebGPU and WebCodecs are the media path. The second boundary is deployment shape. A static vite build loses web search and cloud TTS, so a self-hosted static deployment is a manual-editing and bring-your-own-model product, not the full feature set described in the README. The third is distribution. If you need a pinned, published npm version today, the README tells you publication is a separate maintainer step, so plan around the portable bundle or a source build. For an alternative, consider the standard non-browser pipeline of FFmpeg plus a scripted or programmatic editor. The difference in approach is not quality, it is where the document model lives. An FFmpeg-based pipeline is a sequence of file transformations with no persistent project state, no undo tree and no interactive preview, which makes it excellent for repeatable batch jobs and poor for iterative editing. Velocut keeps a live document model in the browser and exposes it as a command protocol, which is what makes an agent a plausible editor rather than a script generator. If your work is a fixed transcode or a nightly render, FFmpeg is the simpler correct answer and Velocut's browser requirement is pure overhead.
Editorial conclusion
Adopt Velocut if your editors work in Chrome or Edge 113+ and you want an agent that manipulates the same document model the human UI does, with undo and a branching history tree as the safety net. Do not adopt it if you need Safari or Firefox, if you need search or cloud TTS in a static production build, or if you need a published npm version today; the README states registry publication is a separate maintainer step. Before committing, run cargo test and cd web && npm test to confirm both engines pass the same protocol/vectors/*.json files, check the status bar for which engine is active, and verify that your chosen model endpoint allows browser CORS requests.
Community notes