geneva

geneva [--format human|json] subcommand [options]geneva trim input -o file [--from time] [--to time | --duration time] [encode-options]geneva concat input... -o file [--crossfade time | --fade time] [encode-options]geneva convert input -o file [size-options] [encode-options]geneva render timeline.json -o file|dir [encode-options]geneva probe file

geneva is a command-line video editor. Everyday verbs (`trim`, `concat`, `convert`, and the rest) are compiled into a JSON timeline and rendered through the same path as geneva render. Titles and graphics are HTML and CSS, drawn by geneva's own layout engine — no browser, Playwright, or filtergraph.A document names the format version in `"geneva"` (current 1.1; a `"1.0"` document is read as it is). Assets are media files or HTML. Layers hold clips; clips can be video, audio, HTML, captions, or colour. Each frame is computed from its timestamp, so a render is deterministic. HDR sources are tone-mapped to SDR unless --keep-hdr.The planner picks the cheapest output mode: copy (packets copied), copy-picture, smart (H.264 bytes copied where the picture is untouched), direct (decode to encode without the compositor), or render (full composite). Errors are reported before rendering, with a code and a JSON path, for example `error[E200]: unknown asset "crad"`. geneva explain E302 prints what a code means.Codecs come from FFmpeg's libraries, bundled in the binary. H.264 uses a hardware encoder when one is allowed, else the system's x264, else bundled OpenH264. Smart cut and smaller H.264 files need x264 on the system (`libx264` on Debian/Ubuntu, `brew install x264` on macOS, or `GENEVA_X264` / a `libx264-*.dll` beside `geneva.exe` on Windows). H.265 is hardware-only.Markup supports flexbox and block layout, absolute positioning, gradients, `box-shadow`, `filter: blur()`, `clip-path: polygon()`, `mix-blend-mode`, `background-clip: text`, web fonts shipped as assets, and CSS `@keyframes` played as written. Not supported: CSS grid, floats, transitions, static `transform` (transforms come from animations), and JavaScript. An unsupported declaration is reported by name and skipped.`--format json` works on every command. Exit 0 on success, 1 if the timeline is invalid, 2 for a usage error, 3 if rendering or encoding failed.

--format human|json

Global. json prints one JSON document on stdout. In human mode diagnostics go to stderr. Default human

Cut a range. --from starts the keep (default: beginning). --to or --duration ends it (default: end of the file). Copied by default, with the cut moved back to a keyframe; --exact for the exact frame

Join two or more inputs back to back. Identical stream parameters are copied; anything else is rendered. --crossfade TIME dissolves (constant-power audio). --fade TIME dips through --fade-color (black default)

Re-encode, optionally changing container, codec, size, or rate. --width / --height (one keeps the aspect, rounded even). --fps. --fit `contain`|`cover`|`fill`. --crop `X,Y,WxH` or centred `WxH` (pixels or percentages). --speed FACTOR (`2` twice as fast; pitch follows)

convert with --width or --height required (or --crop)

Image or video (without its audio) over the input. --at `top-right` (default), `top-left`, `bottom-left`, `bottom-right`, `center`. --margin (default 24 px). --scale. --opacity 0–1. --start / --duration

One of --extract (audio file; --speech writes 16 kHz mono), --mute, --replace FILE, or --mix FILE [--gain DB]

One of --add FILE (repeatable, with --language codes in order), --burn FILE (`.srt`, `.vtt`, or word-timed `.json`; --position, --style JSON, --highlight COLOR, --fit), or --extract [--track N]

Render a JSON document. The container comes from the extension unless the document sets it. With an `outputs` map, -o is a directory

One PNG or JPEG. --at TIME or --frame N. --width / --height. Default output `frame.png`

Parse and check. --probe also opens media assets. --assets DIR is the asset root (default: the timeline's directory)

Container, duration, streams, sizes, rates, rotation, and colour tags

Print the JSON Schema of the current timeline format

Print the --for table (device and platform encode presets)

Built-in manual. No topic: the agent guide. Topics: `agents`, `timeline`, `cli`, `errors`, `color`, `architecture`

What a diagnostic code means (any case). --list prints every code

Output path. The extension selects the container

Constant quality; lower is better. Useful range about 18–30 for H.264/H.265. Forces a re-encode

Encoder preset, `ultrafast` to `veryslow`. Forces a re-encode

`h264`, `h265`, `vp9`, `av1`, `prores`, `dnxhd`, `png`, `mjpeg`. Default: the container's usual codec

Encode for a destination: `phone`, `tablet`, `desktop`, `tv`, `web`, `youtube`, `instagram`, `tiktok`, `podcast`, `x`, `linkedin`, `email`. --quality `best`|`good`|`eco` (default good). --budget SIZE (for example `25MB`)

Frame-accurate cuts. With H.264 and system x264, a smart cut copies untouched GOPs and re-encodes only around cuts and overlays

Who composites frames. auto (default) uses a hardware GPU if one is present, else the CPU. Copied streams are copied either way

Print the compiled JSON document instead of rendering

Write no audio track

This geneva is geneva-render's video editor, not Georgetown's network-evasion toolkit of the same name.No GUI and no hosted service. One binary for Linux (x64, arm64), macOS (Apple silicon), and Windows (x64). The install script is a curl-to-shell download of a GitHub release.OpenH264 is bundled because x264 is GPL; without x264, smart cut is off and H.264 files are larger. VideoToolbox and NVENC at constant quality, and bundled OpenH264 always, ignore --max-bitrate; the report says so. `--budget` puts VideoToolbox in bitrate mode.There is no fixed average bitrate, CBR, or two-pass encode: video is constant quality under an optional ceiling.

Written by Francesco Benetti. MIT licensed. First public release 1.0.0 (2026-09-25); current 1.1.0 (2026-09-28), timeline format 1.1.

ffmpeg(1), ffprobe(1), melt(1), handbrakecli(1), whisper(1)

Source code · Homepage · Documentation