Video Editing

Apply local video edits with the Wonda CLI: trim, crop, merge, overlay, captions, audio mixing, and more.

Video editing is CLI-first. wonda edit video downloads inputs when needed, renders locally with ffmpeg or hyperframes, uploads the output media, and prints the resulting mediaId. There is no server-side editor job for current video edits.

The retired POST /api/v1/video/edit endpoint returns 410 Gone with a migration hint for known operations. Move scripts to the CLI commands below.

Setup

npm i -g @degausai/wonda
wonda auth login
wonda doctor

wonda doctor checks local prerequisites such as ffmpeg. Hyperframes operations such as textOverlay and animatedCaptions also need the bundled Chromium renderer.

Usage

wonda edit video --operation <operation> \
  --media <media-id-or-local-file> \
  --params '{...}' \
  --wait -o ./out.mp4

Common flags:

Flag	Description
`--operation`	Required operation name. Run `wonda operations list` to see the local registry.
`--media`	Media IDs or local file paths. Pass multiple inputs as a comma-separated value, such as `--media <base>,<overlay>`.
`--params`	Raw JSON object for operation-specific params. Run `wonda operations info <operation>` for the shape.
`--preset`	Featured preset name scoped to `--operation`. Explicit `--params` values override preset params.
`--audio-media`	Audio media ID or local audio file for `editAudio`.
`--prompt-text`	Required text for `textOverlay`.
`--caption-segments`	Raw JSON array for `animatedCaptions`. Produce timing data with `wonda alignment extract-timestamps`.
`--wait`	Accepted for compatibility. Local renders finish before output is printed.
`-o`, `--output`	Download the rendered output to a local file path. Implies `--wait`.

Video-only shortcut flags:

Flag	Applies to	Description
`--threshold`	`splitScenes`	Scene-change sensitivity from `0.01` to `0.9`.
`--min-clip-duration`	`splitScenes`	Minimum scene duration in seconds.
`--mode`	`splitScenes`	`split` for separate scene files or `omit` to remove one scene and concatenate the rest.
`--output-selection`	`splitScenes`	`first`, `last`, or a 1-indexed scene number.
`--duration-ms`	`imageToVideo`	Hold a still image for this many milliseconds, from `500` to `60000`.
`--silence-threshold-db`	`skipSilence`	Silence detection noise floor in dB.
`--min-silence-duration`	`skipSilence`	Shortest gap that counts as silence, in seconds.
`--max-silence-duration`	`skipSilence`	Silence beyond this gets cut; remaining silence is bounded to this value.

Output

Without --output, a successful local render prints:

{
  "mediaId": "019e1b70-6f9e-80fd-8c49-690bcbdaf8db",
  "status": "succeeded"
}

With --output, the CLI downloads the result and prints the local path plus mediaId:

{
  "path": "./trimmed.mp4",
  "mediaId": "019e1b70-6f9e-80fd-8c49-690bcbdaf8db"
}

splitScenes in split mode prints a scenes array because it can produce multiple media outputs.

Operations

Operation	Renderer	Inputs	Key params
`trim`	ffmpeg	One video	`trimStartMs`, `trimEndMs`
`crop`	ffmpeg	One video	`aspectRatio`, `customWidth`, `customHeight`, `cropPercent`, `cropAxis`, `position`, `paddingTop`
`merge`	ffmpeg	Multiple videos	Input order comes from `--media <id1>,<id2>,...`
`overlay`	ffmpeg	Base video plus overlay video	`position`, `resizePercent`, `resizeAxis`, `baseVideoVolume`, `overlayVideoVolume`, `overlayStartMs`, `overlayDurationMs`
`splitScreen`	ffmpeg	Two videos	`targetAspectRatio`
`speed`	ffmpeg	One video	`speed`, `preservePitch`
`volume`	ffmpeg	One video	`volume`, `muted`
`reverseVideo`	ffmpeg	One video	None
`extractFrame`	ffmpeg	One video	`timestampMs` or `timestampPercent`
`extractAudio`	ffmpeg	One video	None
`editAudio`	ffmpeg	One video plus one audio input	`videoVolume`, `audioVolume`, `audioStartMs`, `audioEndMs`, `audioOffsetMs`
`imageToVideo`	ffmpeg	One image	`durationMs`, or the `--duration-ms` shortcut
`skipSilence`	ffmpeg	One video with audio	`silenceThresholdDb`, `minSilenceDuration`, `maxSilenceDuration`
`splitScenes`	ffmpeg	One video	`mode`, `outputSelection`, `threshold`, `minClipDuration`
`textOverlay`	hyperframes	One video or image plus `--prompt-text`	Styling params such as `fontFamily`, `position`, `sizePercent`, `fontSizeScale`, `strokeWidth`
`animatedCaptions`	hyperframes	One video plus `--caption-segments`	Caption styling params such as `fontFamily`, `position`, `sizePercent`, `fontSizeScale`, `strokeWidth`, `highlightColor`

For exact parameter defaults and ranges, run:

wonda operations info trim
wonda operations info textOverlay

Examples

Trim a video:

wonda edit video --operation trim --media 019e1b70-6f9e-80fd-8c49-690bcbdaf8db \
  --params '{"trimStartMs":3000,"trimEndMs":10000}' \
  --wait -o ./trimmed.mp4

Merge videos locally:

wonda edit video --operation merge \
  --media 019e1b70-6f9e-80fd-8c49-690bcbdaf8db,019e1b72-0742-8bae-bb93-b569036d05af \
  --wait -o ./merged.mp4

Add a static text overlay:

wonda edit video --operation textOverlay --media 019e1b70-6f9e-80fd-8c49-690bcbdaf8db \
  --prompt-text "Launch day" \
  --params '{"fontFamily":"TikTok Sans SemiCondensed","position":"top-center","sizePercent":66,"fontSizeScale":0.5,"strokeWidth":4.5}' \
  --wait -o ./with-text.mp4

Render animated captions:

wonda edit video --operation animatedCaptions --media 019e1b70-6f9e-80fd-8c49-690bcbdaf8db \
  --caption-segments '[{"text":"Launch","startS":0},{"text":"day","startS":0.4}]' \
  --params '{"fontFamily":"TikTok Sans SemiCondensed","position":"bottom-center","sizePercent":80}' \
  --wait -o ./captioned.mp4

Replace or mix audio:

wonda edit video --operation editAudio \
  --media 019e1b70-6f9e-80fd-8c49-690bcbdaf8db \
  --audio-media 019e1b73-32a4-8c9e-8bbf-3661a14a5716 \
  --params '{"videoVolume":30,"audioVolume":80,"audioOffsetMs":2000}' \
  --wait -o ./with-audio.mp4