---
title: Timeline edit operations
description: Every edit_timeline operation by job, with its required fields, the time unit rules, and runnable operations lists.
---
Your agent edits a timeline with one tool, `edit_timeline`. It sends a list of operations, and each operation is an `op` and its fields. The CLI sends the same list with `invideo edit change`. This is the full MCP `edit_timeline` call:

```json
{
  "url": "https://invideo.io/@acme/launch-reel/tree/main/seq-9.1",
  "timeline_id": "T1",
  "expected_state_token": "<state_token from get_timeline>",
  "dry_run": true,
  "operations": [
    { "op": "split_clip", "clip": "c7", "at_f": 90 }
  ]
}
```

## How an edit works

An edit is a read, then a list of operations, then a check. These rules hold for every op on this page.

- **Read first.** `get_timeline` returns the ids (`T1` a timeline, `V2` a track, `c7` a clip, `m3` media in the bin) and a `state_token`. Pass ids as they are. An object without a short id, like a keyframe, has a UUID.
- **Send the latest token.** Every edit needs `expected_state_token` from your latest read or edit. A newer edit by anyone makes it stale, and the edit is refused as a conflict. Read again and rebuild the change.
- **All or none.** The operations in one call land together or not at all. Put a whole change in one call: a cut and its gap close, or every marker for a song.
- **Check with `dry_run`.** `dry_run: true` checks the operations without applying them.
- **Look up the fields.** Call `timeline_catalog` with `ops` naming the ops you are about to use, for their exact fields. Call it with `effects`, `audio_effects` or `transitions` for their settings. Unknown ops and fields are refused, and a renamed op says its new name.
- **Retry the same request.** After a timeout or `completion_unknown`, send the identical request with the same token. If the first one landed, the retry is refused as a conflict and a read shows the change. Never re-read and resend because a call timed out.
- **Use a new object in a second call.** An op cannot always use an object made earlier in the same call. `set_keyframes` on a text clip made in that call is refused, and so is the whole call. Ops that change an effect, a transition or an audio effect take its id from `get_timeline`. Make the object, read the timeline, then send the second call.
- **Explicit values only.** Your agent decides the edits and sends exact values. There is no natural-language editing.

### Time units

Fields ending in `_f` are frames at the timeline's rate, and may be fractional. Fields ending in `_seconds`, and `at_seconds`, are seconds. Ranges include their start and exclude their end, so a clip from frame 0 to frame 90 ends before frame 90. Reads give rational times as `{value, rate}`, which is `value / rate` seconds.

At 30 frames a second, two seconds is `60` frames. Convert seconds from a transcript or a beat list with the timeline's own rate from `get_timeline`.

### From the CLI

The CLI takes the same operations list from a file. Read the edit for its token, check with `--dry-run`, then apply. `ops.json` holds a bare JSON list, `[ {...} ]`, with no `operations` wrapper and none of the other MCP fields.

```bash
invideo edit show <edit-url>
invideo edit catalog <edit-url> --ops split_clip,delete_clip
invideo edit change <edit-url> --timeline T1 --token … \
  --operations @ops.json --dry-run
invideo edit change <edit-url> --timeline T1 --token … \
  --operations @ops.json
```

`<edit-url>` comes from `invideo edit new`. The `--token` value is the `state_token` that `invideo edit show` prints; each change returns a fresh one. On a branch, use the `branch_url` that `invideo branch new` returns, and a token from `invideo edit show <branch-url>`.

## Operations by job

Each table gives the op, what it does, and the fields it needs. Most ops take more optional fields; `timeline_catalog` lists them all.

### Placement and media

These ops put media on the timeline, move and transform clips, and keep the media bin in order. An `asset` is a bin id like `m3`, or a sequence URL from `read`, which goes into the bin first.

| Op | What it does | Required fields |
| --- | --- | --- |
| `insert_media` | Places a whole media file on one track. On a video track it places the picture alone. | `asset`, `track`, `at_f`, `ripple` |
| `place_media` | Places part of a file, from one source time to another, with or without its sound. | `asset`, `track`, `at_f`, `source_start_seconds`, `source_end_seconds`, `mode`, `linked_audio` |
| `move_clip` | Moves one clip to a track and frame. Linked clips stay unless you move them too. | `clip`, `track`, `at_f`, `mode` |
| `reorder_clip` | Puts a clip right after another clip in a track's order. | `clip`, `track` |
| `duplicate_clip` | Copies a clip and puts the copy right after it. | `clip` |
| `link_clips` | Links clips into one group that moves, trims, splits and deletes together. | `clips` |
| `unlink_clips` | Takes clips out of their link groups. | `clips` |
| `set_position` | Moves a visual clip, in canvas pixels from the center. | `clip`, `x`, `y` |
| `set_zoom` | Zooms a visual clip. `1` fits the canvas. Give `x` and `y` the same value. | `clip`, `x`, `y` |
| `set_rotation` | Sets a visual clip's rotation in degrees. | `clip`, `degrees` |
| `set_anchor` | Sets the point a clip rotates and zooms around. | `clip`, `x`, `y` |
| `set_opacity` | Sets the opacity of a visual clip or a video track. | `target`, `opacity` |
| `set_blend_mode` | Sets how a clip or a video track blends with what is below it. | `target`, `mode` |
| `fit_frame` | Zooms a clip so the whole picture fits the canvas, with bars. | `clip` |
| `fill_frame` | Zooms a clip so the picture covers the canvas, cropping the overflow. | `clip` |
| `paste_attributes` | Copies transform, composite, crop, playback or effects from one clip onto others. | `from`, `to`, `attributes` |
| `set_clip_enabled` | Turns a clip off or on. A clip that is off is skipped in playback and exports. | `clip`, `enabled` |
| `set_name` | Renames a media clip, track, marker, folder or other named object. | `target`, `name` |
| `create_folder` | Makes a folder in the media bin. | `name` |
| `move_bin_items` | Moves bin folders and assets into a folder. | `folders`, `assets` |
| `delete_bin_items` | Deletes bin folders and assets. | `folders`, `assets` |

### Cutting and trimming

These ops cut clips, move their edges, and open or close time. `from_f` on a trim or a roll must match the edge as you last read it.

| Op | What it does | Required fields |
| --- | --- | --- |
| `split_clip` | Cuts a clip in two at a frame. The right half is a new clip; the left half keeps the id. | `clip`, `at_f` |
| `trim_clip` | Moves the head or tail of a clip. | `clip`, `edge`, `from_f`, `to_f`, `mode`, `linked` |
| `slip_clip` | Changes which part of its media a clip plays, without moving it. | `clip`, `from_src_f`, `to_src_f` |
| `roll` | Moves the cut between two touching clips. One gets longer, the other shorter. | `left_clip`, `right_clip`, `from_f`, `to_f` |
| `delete_clip` | Removes a clip, and leaves a gap (`leave_gap`) or closes it (`close_gap`). | `clip`, `mode`, `linked` |
| `clear_track` | Empties a track, or one span of it, and keeps the track. | `track` |
| `edit_gap` | Closes, resizes or opens a gap on a track. | `kind` |
| `edit_time_range` | Inserts time, or removes a span, on every unlocked track at once. | `timeline`, `start_f`, `end_f`, `mode` |
| `retime` | Changes speed inside one video clip: ramp, freeze, reverse, section, points or reset. | `clip`, `kind` |

### Tracks

These ops add, order, hide and lock tracks.

| Op | What it does | Required fields |
| --- | --- | --- |
| `add_track` | Adds an empty video or audio track. | `name`, `kind` |
| `delete_track` | Deletes a track and everything on it. | `track` |
| `move_track` | Moves a track above another track of the same kind. | `track` |
| `set_track_hidden` | Hides or shows a video track. | `track`, `hidden` |
| `set_track_locked` | Locks or unlocks a track. Edits on a locked track are refused. | `track`, `locked` |
| `add_adjustment` | Adds an adjustment clip. Its effects and grades apply to everything below it. | `track`, `start_f`, `end_f` |

### Text and captions

Text clips hold one block of words. Caption clips hold slides, each a line of text with a start and an end, and optional timed words that light up as they are spoken.

| Op | What it does | Required fields |
| --- | --- | --- |
| `add_text` | Adds a text clip. It never covers or pushes other clips. | `track`, `start_f`, `end_f`, `text` |
| `set_text` | Replaces the words of a text clip, or of a caption clip with one slide. | `clip`, `text` |
| `set_text_style` | Restyles a whole text or caption clip. Only the keys you send change. | `clip`, `style` |
| `style_text_range` | Styles some characters of a text clip. | `target`, `range`, `style` |
| `add_captions` | Adds a caption clip from a list of slides, with optional words. | `track`, `slides` |
| `set_caption_slide_text` | Replaces the text of one caption slide. | `clip`, `slide_index`, `text` |
| `append_caption_slide` | Adds a slide at the end of a caption clip. | `clip`, `text`, `duration_seconds` |
| `delete_caption_slide` | Removes one slide, as a blank gap or with the rest moving up. | `clip`, `slide`, `ripple` |
| `move_caption_slide` | Moves one slide later or earlier inside its caption clip. | `clip`, `slide`, `delta_seconds` |
| `trim_caption_slide` | Moves the left or right edge of one slide. | `clip`, `slide`, `delta_seconds`, `edge`, `ripple` |
| `split_caption_fragment` | Splits one timed word of a slide in two. | `clip`, `slide`, `fragment_index`, `character_offset` |
| `merge_caption_fragment` | Joins one timed word with the next. | `clip`, `slide`, `fragment_index` |

### Shapes

A shape clip holds paths: rectangles, ellipses, stars or drawn outlines. Each path has fills and strokes, called paint.

| Op | What it does | Required fields |
| --- | --- | --- |
| `add_shape` | Adds a shape clip from a preset, with its box and center in canvas pixels. | `track`, `at_f`, `duration_f`, `preset`, `width`, `height`, `x`, `y` |
| `add_shape_path` | Adds a rectangle, ellipse or star to a shape clip. | `clip`, `preset`, `size` |
| `remove_shape_path` | Removes one path. | `clip`, `path` |
| `reorder_shape_path` | Moves a path in the drawing order. | `clip`, `path`, `index` |
| `rename_shape_path` | Renames a path. | `clip`, `path`, `name` |
| `set_shape_path_visible` | Shows or hides a path. | `clip`, `path`, `visible` |
| `set_shape_path_geometry` | Makes a path a rectangle, ellipse or star with a size and position. | `clip`, `path`, `geometry` |
| `convert_shape_path_to_points` | Turns a preset path into points you can move one by one. | `clip`, `path`, `at_seconds` |
| `set_shape_path_points` | Sets every point of a drawn path at one time. | `clip`, `path`, `at_seconds`, `closed`, `vertices` |
| `transform_shape_path` | Moves, scales, rotates or fades one path at one time. | `clip`, `path`, `at_seconds`, `values` |
| `trim_shape_path` | Draws only part of a path's outline, for a line that draws itself on. | `clip`, `path`, `at_seconds`, `enabled` |
| `add_shape_paint` | Adds a fill or a stroke to a path. | `clip`, `path`, `kind` |
| `remove_shape_paint` | Removes a fill or a stroke. | `clip`, `path`, `layer` |
| `reorder_shape_paint` | Moves a fill or a stroke in the paint order. | `clip`, `path`, `layer`, `index` |
| `set_shape_paint` | Changes a fill's or a stroke's settings at one time. | `clip`, `path`, `layer`, `at_seconds`, `values` |
| `animate_shape_path` | Starts animating a drawn path's outline. | `clip`, `path`, `at_seconds` |
| `stop_animating_shape_path` | Stops the outline animation and keeps the outline at one time. | `clip`, `path`, `at_seconds` |
| `delete_shape_path_keyframe` | Removes the outline keyframe at one time. | `clip`, `path`, `at_seconds` |
| `move_shape_path_keyframe` | Moves an outline keyframe to another time. | `clip`, `path`, `from_seconds`, `to_seconds` |
| `set_shape_path_keyframe_easing` | Sets the easing from one outline keyframe to the next. | `clip`, `path`, `at_seconds`, `in_handle`, `out_handle` |
| `create_shape_keyframe_lane` | Starts animating one setting of a path, like `transform.rotation`. | `clip`, `parameter`, `path` |

### Effects

Effects go on a video or image clip, or on a whole video track. Call `timeline_catalog` with `effects` for each effect's settings and ranges.

| Op | What it does | Required fields |
| --- | --- | --- |
| `add_effect` | Adds an effect to the end of a clip's effects. | `clip`, `effect` |
| `remove_effect` | Removes one effect or grade from a clip. | `clip`, `effect` |
| `set_effect_parameter` | Sets one setting of an effect on a clip. | `clip`, `effect`, `parameter`, `value` |
| `set_visual_effect_enabled` | Turns one effect off or on without removing it. | `target`, `effect`, `enabled` |
| `move_visual_effect` | Reorders one effect in its stack. | `target`, `effect` |
| `add_track_effect` | Adds an effect to a video track, for everything on it. | `track`, `effect` |
| `remove_track_effect` | Removes one effect from a video track. | `track`, `effect` |
| `set_track_effect_parameter` | Sets one setting of an effect on a video track. | `track`, `effect`, `parameter`, `value` |
| `set_matte_source` | Sets the track a `track_matte_key` takes its shape from. | `target`, `effect` |
| `apply_effect_asset` | Adds an effect asset from the media bin to a clip. | `clip`, `asset` |

### Transitions

Transitions sit on the cut between two touching clips, or at a clip's head or tail, from or to black. `in_f` is how far a transition reaches into the left clip and `out_f` into the right clip.

| Op | What it does | Required fields |
| --- | --- | --- |
| `add_transition` | Adds a transition at the cut between two touching clips. | `left_clip`, `right_clip`, `type`, `in_f`, `out_f` |
| `add_edge_transition` | Adds a transition at a clip's head or tail, from or to black. | `clip`, `edge`, `type`, `in_f`, `out_f` |
| `remove_transition` | Removes a transition by its id. | `transition` |
| `set_transition_parameter` | Sets one setting of a transition. | `transition`, `parameter`, `value` |
| `resize_transition` | Changes how far a transition reaches into each clip. | `transition`, `in_f`, `out_f` |
| `apply_transition_asset` | Places a custom transition from the media bin on a cut. | `left_clip`, `right_clip`, `asset`, `in_f`, `out_f` |

### Color

A grade is a stack of color controls on a clip. Masks limit a grade to part of the picture.

| Op | What it does | Required fields |
| --- | --- | --- |
| `edit_grade` | Adds, removes or reorders a grade on a clip. | `clip`, `kind` |
| `set_grade_parameter` | Sets one control of a grade, like `exposure` or `saturation`. | `clip`, `grade`, `parameter`, `value` |
| `set_grade_curve` | Replaces one whole curve of a grade. | `clip`, `grade`, `which`, `points` |
| `edit_grade_mask` | Adds or removes a mask on a grade. | `clip`, `grade`, `kind` |
| `set_grade_mask_parameter` | Sets one setting of a grade mask, like its center or feather. | `clip`, `grade`, `mask`, `parameter`, `value` |
| `apply_lut` | Applies a LUT from the media bin to a clip's grade. Bring the `.cube` or PNG LUT file in with `add_media` on the timeline URL first. | `clip`, `lut` |
| `set_media_color_profile` | Says which color profile a bin file was shot in, such as a log profile. | `asset`, `profile` |
| `set_timeline_working_space` | Sets the color space a timeline is mixed in. | `timeline`, `working_space` |

### Audio and buses

A video's sound is a separate audio clip linked to it, so target that clip. Call `timeline_catalog` with `audio_effects` for each audio effect's settings.

| Op | What it does | Required fields |
| --- | --- | --- |
| `set_audio_gain` | Sets the volume of an audio clip or track, in dB. | `target`, `gain_db` |
| `set_audio_muted` | Mutes or unmutes an audio clip or track. | `target`, `muted` |
| `set_audio_solo` | Solos or unsolos an audio track. | `track`, `solo` |
| `set_audio_pan` | Sets the stereo pan of an audio track. | `track`, `pan` |
| `set_audio_fades` | Sets both fades of an audio clip, in frames. | `clip`, `fade_in_f`, `fade_out_f` |
| `set_audio_fade` | Sets one fade of an audio clip, in seconds, and its curve. | `clip`, `direction`, `curve` |
| `set_audio_speed` | Sets an audio clip's playback speed. | `clip`, `speed` |
| `set_audio_pitch_preserved` | Chooses whether an audio clip keeps its pitch when its speed changes. | `clip`, `maintain_pitch` |
| `apply_audio_crossfade` | Crossfades two touching audio clips. | `outgoing`, `incoming`, `curve`, `duration_seconds`, `alignment`, `trim_to_fit` |
| `remove_audio_crossfade` | Removes a crossfade between two audio clips. | `outgoing`, `incoming` |
| `add_audio_effect` | Adds an audio effect to a clip, a track, a bus or the timeline's chain. | `target`, `target_kind`, `effect` |
| `remove_audio_effect` | Removes one audio effect. | `effect` |
| `set_audio_effect_enabled` | Turns one audio effect off or on. | `effect`, `enabled` |
| `move_audio_effect` | Reorders one audio effect in its chain. | `effect` |
| `set_audio_effect_parameter` | Sets one setting of an audio effect. | `effect`, `parameter`, `value` |
| `create_audio_bus` | Makes a submix bus that feeds the main output. | `timeline`, `name` |
| `set_audio_routing` | Sends a track's or a bus's output to a bus. | `target` |
| `create_audio_send` | Sends a copy of a track's or a bus's sound to another bus. | `target`, `bus`, `level`, `pre_fader` |
| `set_audio_send_level` | Changes a send's level. | `send`, `level` |
| `delete_audio_send` | Removes one send. | `send` |
| `set_audio_bus_controls` | Changes a bus's volume, pan, mute, solo, name or effect switch. | `bus`, `values` |
| `set_main_output` | Changes the main audio output, the last stage before export. | `values` |
| `set_timeline_audio` | Sets the volume of a timeline's whole mix, or mutes it. | `timeline` |
| `set_sidechain_source` | Picks the track, usually the voice, that `ducker` effects react to. A new timeline already uses `A1`; set it only when the voice is on another track. | `timeline` |

### Keyframes

A keyframe lane animates one property of a clip or a track. Keyframe times are in seconds: from the clip's start for a clip lane, and from the timeline's start for a track lane.

| Op | What it does | Required fields |
| --- | --- | --- |
| `set_keyframes` | Replaces a clip's whole opacity or rotation animation, in frames. | `clip`, `property`, `points` |
| `add_keyframe_lane` | Starts animating one property of a clip or track. | `parent`, `parent_kind`, `property`, `default_value` |
| `create_effect_keyframe_lane` | Starts animating one number setting of an effect. | `clip`, `parameter`, `effect` |
| `add_keyframe` | Adds a point to a lane. | `lane`, `time_seconds`, `value` |
| `add_keyframes` | Adds many points to one lane at once. | `lane`, `points` |
| `move_keyframe` | Moves a keyframe and gives it a new value. | `keyframe`, `time_seconds`, `value` |
| `delete_keyframe` | Deletes one keyframe. | `keyframe` |
| `remove_keyframe_lane` | Removes a lane and stops that animation. | `lane` |
| `set_keyframe_interpolation` | Sets the easing from one keyframe to the next. | `keyframe`, `bezier_in`, `bezier_out`, `hold` |

### Markers and guides

Markers sit on the timeline at a frame. Guides are lines on the canvas, placed as a fraction of its width or height.

| Op | What it does | Required fields |
| --- | --- | --- |
| `add_marker` | Adds a marker at a frame, or over a range with `duration_f`. | `at_f` |
| `set_marker` | Changes a marker's frame, length, name, note or color. | `marker` |
| `delete_marker` | Removes a marker. | `marker` |
| `create_guide` | Adds a guide line to the canvas. | `timeline`, `orientation`, `position`, `locked` |
| `set_guide` | Sets a guide's position and lock. | `guide`, `position`, `locked` |
| `update_guide` | Changes any of a guide's position, orientation, lock or color. | `guide` |
| `delete_guide` | Deletes one guide. | `guide` |
| `set_timeline_guides_locked` | Locks or unlocks all guides at once. | `timeline`, `locked` |
| `clear_timeline_guides` | Removes all guides, or only the horizontal or vertical ones. | `timeline` |

### Nesting

A nested clip shows another timeline inside this one.

| Op | What it does | Required fields |
| --- | --- | --- |
| `nest_timeline` | Places another timeline as a nested clip. | `timeline`, `track`, `start_f`, `end_f` |
| `nest_clips` | Copies chosen clips into a new timeline, and can replace them with one nested clip. | `video_clips`, `audio_clips`, `name`, `mode` |
| `unnest_clip` | Replaces a nested clip with copies of the clips it shows. | `clip` |
| `make_nested_clip_unique` | Gives one nested clip its own copy of its timeline. | `clip` |

### Timelines and settings

These ops make timelines and change their size, rate and work area. Branches and checkpoints are not ops: the `timeline_history` tool keeps them, and the CLI `branch` commands do the same.

| Op | What it does | Required fields |
| --- | --- | --- |
| `create_timeline` | Makes a new timeline with empty video and audio tracks. Edit it in a later call. | `width`, `height`, `fps` |
| `duplicate_timeline` | Copies a whole timeline into a new one that shares nothing with it. | `timeline`, `name` |
| `set_timeline_settings` | Sets a timeline's canvas size and frame rate together. | `timeline`, `width`, `height`, `fps` |
| `set_timeline_work_area` | Marks the part of a timeline to work on. | `timeline`, `start_seconds`, `end_seconds` |
| `clear_timeline_work_area` | Clears the work area, so the whole timeline is used. | `timeline` |

### Custom shaders

When no effect or transition in the catalog fits, write a GLSL shader. Read `timeline_catalog` with `guides: ["custom_shader"]` once first. The shader is compiled and checked before it lands; a refusal lists the compiler's errors.

| Op | What it does | Required fields |
| --- | --- | --- |
| `add_custom_effect` | Puts a GLSL effect you write on a video or image clip, with its parameters as controls. | `clip`, `name`, `source`, `params` |
| `update_custom_effect` | Replaces a custom effect's shader. It needs the hash from `inspect_objects`. | `clip`, `effect_id`, `expected_effect_hash`, `source`, `params` |
| `add_custom_transition` | Puts a GLSL transition you write on a cut, or at a clip's head or tail. | `name`, `source`, `params`, `in_f`, `out_f` |
| `update_custom_transition` | Replaces a custom transition's shader. It needs the hash from `inspect_objects`. | `transition_id`, `expected_transition_hash`, `source`, `params` |

## Effect, audio effect and transition names

These are the names that `add_effect`, `add_track_effect`, `add_audio_effect`, `add_transition` and `add_edge_transition` take. Call `timeline_catalog` with the name for its settings and ranges.

### Effects

Effects go on a video or image clip with `add_effect`, or on a video track with `add_track_effect`.

| Name | What it does |
| --- | --- |
| `aurora` | Adds moving bands of rainbow aurora light over the picture. |
| `beat_rock` | Splits the picture's color channels apart in short, regular bursts, like a beat hitting. |
| `drop_shadow` | Puts a soft shadow of the clip's shape behind it. |
| `tint` | Recolors the picture with two colors: one for the darks and one for the lights. |
| `dynamic_zoom` | Zooms and pans smoothly over the clip's length, from a start framing to an end framing. |
| `dynamic_anchor_zoom` | Zooms smoothly around the clip's anchor point over its length, from a start framing to an end framing. |
| `edge_roundness` | Rounds the clip's corners. |
| `8bit` | Turns the picture into blocky pixel art with a small retro game palette. |
| `fast_chroma_key` | Removes a solid background color, like a green screen, so the tracks below show through. |
| `fit_with_blur` | Fits the whole clip in the frame and fills the empty bars with a blurred, enlarged copy of it. |
| `flashback` | Flickers the picture with bright, tinted overexposure in bursts, like a memory. |
| `focus_blur` | Keeps the center sharp and blurs toward the edges, with slight color fringing. |
| `gaussian_blur` | Blurs the picture evenly. |
| `invert` | Inverts the colors, like a film negative. |
| `kaleidoscope` | Folds the picture into a moving kaleidoscope pattern. |
| `lens_flare` | Adds a lens flare glow over the picture. |
| `multi_mirror` | Mirrors one part of the picture onto the rest. |
| `pixel_glitch` | Flashes shifted blocks of the picture with noisy grain, like a digital glitch. |
| `16bit` | Turns the picture into blocky pixel art with fewer color levels, keeping its own colors. |
| `tritone` | Recolors the picture with three colors: one each for the darks, midtones and lights. |
| `wiggle` | Shakes the picture randomly, zoomed in slightly so the edges stay hidden. |
| `zoom_out` | Shrinks the picture and repeats it in tiles to fill the frame. |
| `crop` | Cuts the clip down to a rectangle, with optional soft edges and rounded corners. |
| `track_matte_key` | Shows the clip only where another video track has picture, using that track as a mask. |

### Audio effects

Audio effects go on an audio clip, an audio track, a bus or the timeline's own chain with `add_audio_effect`.

| Name | What it does |
| --- | --- |
| `compressor` | Evens out a performance: loud parts quieter, quiet parts louder. |
| `de_esser` | Softens harsh s and sh sounds in a voice. |
| `click_remover` | Removes lip smacks and mouth clicks from a voice. |
| `ducker` | Pulls music down under a voice, and back up after it. |
| `eq` | An 8-band equalizer. |
| `limiter` | Holds the level under a ceiling, for delivery. |
| `pitch_shift` | Moves a voice up or down without changing its timing. |
| `plate_reverb` | A classic plate reverb. |
| `voice_eq` | Cleans up a recorded voice: less rumble, more clarity. |
| `voice_reverb` | A one-knob plate reverb for voice. |

### Transitions

Transitions go on a cut with `add_transition`, or at a clip's head or tail with `add_edge_transition`.

| Name | What it does |
| --- | --- |
| `back_flip` | The next clip flips over in 3D from one side and lands on top of the current one. |
| `barrel` | The picture bulges or pinches like a fisheye lens while it crossfades to the next clip. |
| `big_reveal` | The current clip shrinks and slides away while the next one slides in, zooming down from close up. |
| `blink` | The picture flickers between the two clips and settles on the next one. |
| `block_displacement` | The picture breaks into rectangular blocks that slide away to show the next clip. |
| `blur` | Both clips blur to a peak in the middle while they crossfade. |
| `bold_and_powerful` | The next clip slides in enlarged over the current one, then settles back to its normal size. |
| `bounce_back` | The next clip slides in with a springy bounce. |
| `cross_zoom` | A zoom blur sweeps across the frame while the clips crossfade. |
| `cross_zoom_blur` | The current clip zooms in and blurs as the next one zooms down into place. |
| `cube_3d_rotation` | The two clips turn like neighboring faces of a cube. |
| `curl_in` | The next clip pushes the current one out in stop-start steps. |
| `curtain_call` | The current clip shrinks as it is pushed out and the next one grows into place. |
| `cut` | The frame splits in half and the halves slide apart to show the next clip. |
| `dot_glitch` | A digital glitch of noise blocks and dots that switches to the next clip at its peak. |
| `dots` | The current clip dissolves into a grid of halftone dots that resolves into the next one. |
| `fade` | A plain crossfade; at the start or end of a clip, a fade from or to black. |
| `film_roll_in` | The frame scrolls quickly through a strip of frames, like a film reel, and lands on the next clip. |
| `flash` | A flash of color hides the change to the next clip. |
| `flippin` | The whole frame flips over like a card, with the next clip on the back. |
| `light_leak` | A glow of colored light with dust and soft light spots washes over a crossfade. |
| `light_leak_bokeh` | Drifting, out-of-focus spots of light pass over a crossfade. |
| `light_leak_flicker` | A flickering burst of colored light covers the middle of a crossfade. |
| `light_leak_flow` | Both clips smear along one direction as a band of light flows across. |
| `glitch` | The color channels wave apart while the clips crossfade. |
| `glitch_displace` | The picture breaks into noisy, washed-out fragments that resolve into the next clip. |
| `glitch_slide` | Strips of the picture slide out of place with a color split while the clips crossfade. |
| `granularity` | Both clips break into large pixel blocks at the middle while they crossfade. |
| `hinge` | The next clip swings into place around a corner, like a door on a hinge. |
| `hole` | A round opening grows from the center as one clip zooms through it into the other. |
| `impact` | The next clip snaps in close up, then punches back out to its normal size in steps. |
| `lens_distortion` | The picture bulges like a lens with color fringing, then settles into the next clip. |
| `lens_flare` | A lens flare sweeps over a soft crossfade. |
| `mirror_zoom` | The current clip shrinks into mirrored tiles while the next one grows out of them. |
| `pixelate_zoom` | The current clip zooms in while it pixelates, and the next one sharpens into place. |
| `radial_blur` | A zoom blur toward the center while the clips crossfade. |
| `rewind` | Frames scroll past quickly, snap back and land on the next clip, like a rewind. |
| `roll` | The frame rolls past repeated copies of itself and lands on the next clip. |
| `roll_3d` | Like roll, with the frame bulging like a cylinder and, if set, turning as it rolls. |
| `rotation` | The current clip spins away with motion blur as the next one spins in. |
| `rotation_zoom` | The current clip spins and zooms away while the next one spins in from small. |
| `showtime` | A hard-edged wipe shows the next clip in stop-start steps. |
| `shake_flash` | A camera shake around the change, hidden by a flash of color. |
| `shake_slide` | The next clip pushes in with a camera shake and a color split. |
| `shake_zoom` | A zoom between the clips with a camera shake and a color split. |
| `slide` | The next clip pushes the current one out of the frame. |
| `slide_blur` | The clips slide with motion blur along a straight or curved path. |
| `slide_cube` | The current clip squeezes toward one edge as the next one expands from the other. |
| `slide_fade` | The clips slide past each other while they crossfade. |
| `slide_stretch` | The clips slide with a heavy stretch and blur along the motion. |
| `slide_warp` | The clips slide with motion blur, the leading edge bending as it moves. |
| `slit_scan` | The edge of the picture smears across the frame, then unsmears into the next clip. |
| `stack` | The next clip slides in over the current one, which stays still. |
| `threshold` | The picture gives way by brightness, through a solid color, to the next clip. |
| `twirl` | The picture swirls around the center while the clips crossfade. |
| `wave` | Sideways ripples run through the picture while the clips crossfade. |
| `wipe` | A hard edge wipes across the frame to show the next clip. |
| `wiper` | The frame zooms in and spins with blur, changes to the next clip and unwinds. |
| `wobble_slide` | Strips of the picture wobble out of place with blur and color blocks while the clips crossfade. |
| `zoom` | One clip zooms in or out of the other, with a fade. |
| `zoom_twirl_rgb` | The current clip zooms away with a twirl and a color split as the next one grows into place. |

## Examples

Each example is the `operations` list of one `edit_timeline` call, or the contents of `ops.json` for `invideo edit change`. The ids are examples: take the real ones from `get_timeline`. The timeline runs at 30 frames a second.

### Place a file on the timeline

This places bin asset `m3` at the start of track `V1`, then places seconds 4 to 10 of `m4`, with its sound, right after it.

```json
[
  {
    "op": "insert_media",
    "asset": "m3",
    "track": "V1",
    "at_f": 0,
    "ripple": false
  },
  {
    "op": "place_media",
    "asset": "m4",
    "track": "V1",
    "at_f": 150,
    "source_start_seconds": 4,
    "source_end_seconds": 10,
    "mode": "overwrite",
    "linked_audio": true
  }
]
```

### Cut the first three seconds

This splits clip `c7` at frame 90. The left half keeps the id `c7`, so the delete removes it and closes the gap. Its linked sound goes with it.

```json
[
  { "op": "split_clip", "clip": "c7", "at_f": 90 },
  {
    "op": "delete_clip",
    "clip": "c7",
    "mode": "close_gap",
    "linked": true
  }
]
```

### Add a title and match an existing one

This adds a white, bold title for the first three seconds, then restyles text clip `c12` to match.

```json
[
  {
    "op": "add_text",
    "track": "V2",
    "start_f": 0,
    "end_f": 90,
    "text": "Summer in Lisbon",
    "style": {
      "font_size": 96,
      "font_weight": 700,
      "color": "#ffffff",
      "align": "center",
      "shadow": true
    }
  },
  {
    "op": "set_text_style",
    "clip": "c12",
    "style": { "font_weight": 700, "color": "#ffffff", "shadow": true }
  }
]
```

### Add a crossfade and a fade to black

This crossfades the cut between `c7` and `c8` over 24 frames, then fades the tail of `c8` to black over one second.

```json
[
  {
    "op": "add_transition",
    "left_clip": "c7",
    "right_clip": "c8",
    "type": "fade",
    "in_f": 12,
    "out_f": 12
  },
  {
    "op": "add_edge_transition",
    "clip": "c8",
    "edge": "tail",
    "type": "fade",
    "in_f": 0,
    "out_f": 30
  }
]
```

### Add word-by-word captions

This adds two caption slides with timed words. The words build up as they are spoken. The times come from a transcript (`media` with `audio.transcript`), turned into frames.

```json
[
  {
    "op": "add_captions",
    "track": "V3",
    "slides": [
      {
        "text": "Welcome back",
        "start_f": 0,
        "end_f": 30,
        "words": [
          { "text": "Welcome", "start_f": 0, "end_f": 15 },
          { "text": "back", "start_f": 15, "end_f": 30 }
        ]
      },
      {
        "text": "to the channel",
        "start_f": 30,
        "end_f": 66,
        "words": [
          { "text": "to", "start_f": 30, "end_f": 38 },
          { "text": "the", "start_f": 38, "end_f": 46 },
          { "text": "channel", "start_f": 46, "end_f": 66 }
        ]
      }
    ],
    "style": {
      "font_size": 64,
      "color": "#ffffff",
      "stroke": true,
      "stroke_color": "#000000",
      "stroke_width": 4
    }
  }
]
```

## After an edit

Check the result before you call it done. `capture` renders frames of the timeline at the seconds you name. `check_timeline` reports structural problems, like a clip that points at something deleted. It does not judge the edit. On the CLI, the same checks are `invideo edit capture` and `invideo edit check`.

## Related

- [MCP tools](/reference/mcp-tools)
- [CLI commands and flags](/reference/cli)
- [Check your video before you say it is done](/how-to/check-your-video)
- [Add word-by-word captions](/how-to/creators/word-by-word-captions)
- [Cut ums, pauses and retakes](/how-to/creators/cut-ums-and-retakes)