Geneva: A Command-Line Video Editor That Uses JSON, HTML, and CSS

Video editing from the terminal has always meant chaining ffmpeg filters or writing brittle scripts. Geneva changes that model. It reads edits as JSON documents, renders titles and graphics from HTML and CSS without a browser, and ships as a single binary for Linux x64 and arm64, macOS Apple silicon, and Windows x64. The codecs come from FFmpeg libraries. The planner, compositor, and layout engine are written in Rust. The project is MIT licensed.

How the Edit Model Works

Instead of a timeline interface, you describe a composition in JSON. A document specifies output resolution, frame rate, assets, and layers. Each layer contains clips that reference video or HTML assets with start times and durations. The CLI commands—trim, concat, convert, subtitles, probe—each produce a JSON document internally. The --show-timeline flag prints it. Running geneva render edit.json -o out.mp4 executes the document.

A typical document might overlay a name card on ten seconds of footage. The card is a standalone HTML file that plays identically in a browser and in Geneva's renderer. CSS animations defined with @keyframes run as written. The renderer supports flexbox and block layout, absolute positioning, gradients, box shadows, filter: blur(), clip-path: polygon(), mix-blend-mode, background-clip: text, web fonts shipped as assets, and CSS keyframe animations.

Unsupported declarations are reported by name and skipped. The list of unsupported features includes CSS grid, floats, transitions, static transforms (transforms must come from animations), and JavaScript. Errors appear before rendering with a code and document path, such as error[E200]: unknown asset "crad".

Frame Copying and Smart Encoding

When the source is H.264 and x264 is installed, frames that have nothing drawn on them are copied directly from the source. Only frames around cuts and overlays get re-encoded. The output notes this with a message like note[N600]: smart cut: 165 of 300 frames copied from the source, 135 encoded in 1 run around the cuts and overlays. Without x264, frames pass from decoder to encoder without the compositor. H.264 encoding uses the bundled OpenH264 or the system x264 when available.

Benchmark Results Against Playwright and Remotion

The project publishes benchmarks run on a machine with 4 vCPUs of an Intel Xeon at 2.1 GHz, 16 GB RAM, no GPU. All three tools encoded with x264 CRF 23 preset medium. Times are medians of three rounds.

| Job                           | geneva | Playwright + ffmpeg | Remotion |
|-------------------------------|--------|---------------------|----------|
| Social clip, 60 s, 1080x1920  | 60.8 s | 140.6 s             | 270.3 s  |
| Broadcast package, 3 min      | 52.2 s | 244.2 s             | 324.3 s  |
| Static captions, 4 min        | 95.6 s | 300.4 s             | 444.7 s  |
| Dynamic captions, 90 s        | 58.1 s | 190.9 s             | 164.7 s  |
| Opening, 13 s                 | 10.0 s | 64.2 s              | 19.1 s   |
| Intro, 14 s                   | 30.4 s | 145.0 s             | 63.4 s   |
| Kinetic typography, 16 s      | 14.2 s | 56.2 s              | 30.2 s   |

With frame copying disabled and the encoder pinned to match the other tools, the broadcast package takes 99.4 s and static captions 140.7 s. Full methodology is in docs/benchmarks.md.

Distributed Rendering With Geneva Farm

The geneva farm command splits a render into parts, distributes them to worker processes on any machines that connect over SSH, in containers, or on serverless functions, then joins the parts without re-encoding. A document that outputs multiple resolutions renders all files at once into one folder.

geneva farm talk.json -o talk.mp4 --parts 12
# on each worker machine:
geneva worker --connect http://192.168.1.20:41237 --token 3b8b6d76...

Documentation for SSH, Docker, Kubernetes, ECS, and AWS Lambda workers lives in docs/farm.md.

Automation and Agent Support

For scripts and agents, geneva guide prints the manual, geneva explain <code> interprets any diagnostic, and --format json works on every command. The document format has a published JSON schema. See docs/agents.md.

Where It Stands

Geneva is in active development. Issues and discussions are on GitHub. The team welcomes feedback from anyone using it or considering it for CI pipelines, automated social clips, broadcast graphics, or any workflow that benefits from version-controlled, code-driven video editing.