/open-edit

name: open-edit
description: Video work with VEED's hosted services and a CLI toolkit — word-timed transcription, cutting, background removal, AI presenters, lipsync, any fal model, sound mixing, and a Chrome renderer for HTML compositions that re-renders only what changed. Captions, edits, motion graphics, or pieces with no footage at all; hands a finished piece to VEED's editor as an editable project, and takes projects back from it. Use when the user wants video made, edited, or captioned by an agent.

open-edit

You author the piece yourself, as an HTML page, and render it with `render`. OpenEdit supplies what a bare shell does not: VEED's hosted services on one login, measured tools for cutting and sound, and a renderer that re-renders only the stretch you changed. `openedit` below is short for `npx @veedstudio/openedit-cli`; every command explains its flags with `--help`.

Setup

Once per workspace, before the first command. WORKSPACE is the current project root, or the current directory outside a project.

npx --yes @veedstudio/openedit-cli init --dry --workspace "$WORKSPACE"
npx --yes @veedstudio/openedit-cli init --workspace "$WORKSPACE"

Read the final `preflight:` line, not the exit code: `ready — OPEN_EDIT_ROOT=…` means go, and `runs/` and the recorded preferences live under that root. If init prints `APPROVAL REQUIRED`, tell the user every exact action and wait for an explicit yes, then run it again with `--auto-approve`. When the final line says the user runs the install commands, `--auto-approve` cannot run them: give the user those commands and run init again once they are done. Never install anything machine-global without that yes, and never infer it from the render request. When a command prints `update available`, tell the user once; run the `init --update` command it names only after they say yes, and if they decline, carry on without asking again.

One folder per piece

Keep everything a piece is made of under `runs/<key>/`: the page, its assets, renders, audio. The code is the edit: that folder is how the user comes back later to change one scene or reuse the piece for another video, so nothing it needs lives anywhere else. When the user states a length, where the piece is posted or wording for it, run `openedit brief runs/<key>` with `--length <sec>`, `--platform <zone>` (the app they name, or the shape when they name none or several) or `--words "<their words>"`.

The footage's look

HDR footage (HLG or PQ, as phones record it) is converted to SDR on the way in, keeping its look and rolling its highlights off: `apply-edl`, `render`, `frames` and `concat-videos` convert it where they read it, `background-removal`, `lipsync` and `veed-project` send a converted copy, and each prints a line when it does. Keep the source's look: no tone-map, grade or colour correction of your own unless the user asks for one, and then grade in `apply-edl` (`CUT.md`). When HDR was converted, tell the user in one plain sentence.

Tools

| Need | Command | | --- | --- | | A transcript with real per-word times | `transcribe <video> [...]` runs the provider recorded in `$OPEN_EDIT_ROOT/.open-edit-prefs.json`. None recorded (the command refuses and says so), "No VEED login found", or a failed run: read `TRANSCRIPTION.md` first | | A transcript as timed lines | `words <transcript>`: a line per word with its start and end (`--cues` a line per cue, `--from`/`--to` in seconds), from a `transcript.json` or a speech-to-text JSON as it came | | Remove, reorder or join takes, whatever their frame rates and levels; slow motion, a speed change or a grade on footage | read `CUT.md` (`speech-probe`, `apply-edl`) | | Join whole clips | `concat-videos --canvas WxH <out> <in...>` re-encodes them to one canvas at 30 fps (without `--canvas`, the largest clip as shown, the first of equals) and cuts each clip of another shape to it as `reframe` does: around its faces when `faces` has run on that clip, else from the middle, and a line per clip says which. `--fit letterbox` keeps each clip whole and pads it instead | | Look at a video, a page or a pile of images | `frames <video> --at <sec,...> --sheet` (one sheet of those moments; `--images` for a folder of references), `render --stills` | | Make it like a reference video | `shots <reference>`: every shot's start and length, what is said in it, its shot size, and storyboard sheets of a few labelled frames of every shot (its first, middle and last, or the middle of a shot under a second; a reference with too many shots for three frames each on four sheets shows every shot's middle alone). Look at the sheets with the list before planning from it. Its speech is the reference's transcript, so transcribe the reference first if it talks; on VEED that spends transcription credits on a video that is not the deliverable, so ask before. It finds hard cuts and fades through black: a dissolve reads as one longer shot, and so does about one jump cut in three. Effects that flicker can read as extra cuts; `--threshold 0.2` drops those, and most jump cuts with them. Each shot's size (close-up, medium, wide or no face) comes from the boxes `faces` wrote for the reference, so run that first; a face the frame cuts through, in shadow or very small often reads as no face, one in profile now and then a size off, and a title or an effect now and then as a face; a letterboxed reference is measured inside its black bars, where a wide shot can read medium, unless a full-frame title or text in the bars keeps them in, and then every size reads wider. So check the sizes the plan leans on against the sheets. On-screen text is not read; the sheets (paths printed, and in the JSON) show it at those frames | | Where the faces and burned-in graphics are, shot by shot | `faces <video>` writes `faces.json` and `faces.js` to `runs/<key>/faces-<hash>/`, a folder of that clip's own, and prints the path; load the `faces.js` it printed. It runs MediaPipe, which `install-med