# Recipes: cut, caption, export

> Five complete command sequences an agent can copy: import, cut, caption and export; recover from a conflict; fill a template; captions from a transcript; remove silences.

Source: https://alexgalhardo.github.io/vukem-video/docs/agents/recipes/

## The idea

Each recipe is a sequence of CLI commands that works as written. The same operations exist as MCP tools; the batches are the same JSON. Replace the identifiers with the ones your commands print, or pass your own with `--id` and `--asset-id` as below.

## Import, cut, caption and export

```bash
vukem-video project:create --name "Teaser" --id prj_7k2m9x4q1b
vukem-video media:import clip.mp4 --project prj_7k2m9x4q1b --asset-id ast_3c5v8n2w6d
vukem-video edit --project prj_7k2m9x4q1b --ops - <<'EOF'
[{"op":"track.add","args":{"kind":"visual","name":"Video","id":"trk_f6g7h8j9k0"}},
 {"op":"track.add","args":{"kind":"visual","name":"Captions","id":"trk_a1b2c3d4e5"}},
 {"op":"clip.add","args":{"track_id":"trk_f6g7h8j9k0","asset_id":"ast_3c5v8n2w6d","start":"0s","duration":"2s","id":"itm_m1n2p3q4r5"}}]
EOF
vukem-video edit --project prj_7k2m9x4q1b --ops - <<'EOF'
[{"op":"item.split","args":{"item_id":"itm_m1n2p3q4r5","at":"1s","new_id":"itm_c3d4e5f6g7"}},
 {"op":"item.delete","args":{"item_ids":["itm_c3d4e5f6g7"]}}]
EOF
vukem-video edit --project prj_7k2m9x4q1b --ops - <<'EOF'
[{"op":"caption.add","args":{"track_id":"trk_a1b2c3d4e5","start":"0.1s","linked_item":"itm_m1n2p3q4r5","id":"itm_s6t7v8w9x0","words":[{"text":"Meet","start":"0s","duration":"0.3s"},{"text":"us.","start":"0.3s","duration":"0.3s"}]}}]
EOF
vukem-video lint --project prj_7k2m9x4q1b
vukem-video export --project prj_7k2m9x4q1b
```

`lint` before `export` catches what would block the export. `export` waits for the job and prints the verified result.

To caption speech instead of typing the words, see "Captions from a transcript" below.

## Recover from a conflict

When another actor changed the project after your plan, an edit with a stale `--base` fails with `E_REVISION_CONFLICT` and exit code `2`. Here the project is at revision 1 and another actor changes the track first, which moves it to revision 2.

```bash
vukem-video edit --project prj_7k2m9x4q1b --actor other track.update track_id=trk_f6g7h8j9k0 name=Theirs
vukem-video edit --project prj_7k2m9x4q1b --base 1 track.update track_id=trk_f6g7h8j9k0 name=Mine
# exit 2: E_REVISION_CONFLICT, details.diff lists what changed since revision 1
vukem-video project:show prj_7k2m9x4q1b
vukem-video edit --project prj_7k2m9x4q1b --base 2 track.update track_id=trk_f6g7h8j9k0 name=Mine
```

Read `details.diff`, plan again against the current revision and send the batch again. The batch that failed changed nothing.

## Fill a template

The project must have a text item marked as a slot (here `headline`) before it is saved as a template.

```bash
vukem-video edit --project prj_7k2m9x4q1b --base 1 slot.mark item_id=itm_t1t2t3t4t5 name=headline
vukem-video template:save --project prj_7k2m9x4q1b --name "Spring sale"
vukem-video template:new <template id> --name "Spring sale" --id prj_6t4y2w8j1m --fill - <<'EOF'
{"headline":{"text":"Spring sale"}}
EOF
vukem-video export --project prj_6t4y2w8j1m
```

A required slot that is missing returns an error that names the slot in `path`; fix the fill and run the command again.

## Captions from a transcript

`transcribe` needs the transcription helper, installed once by a person with `vukem-video tools:install whisper`. The project has a clip `itm_m1n2p3q4r5` on a video track and an empty track `trk_a1b2c3d4e5` for the captions.

```bash
vukem-video transcribe --project prj_7k2m9x4q1b --asset ast_3c5v8n2w6d --language en --wait
vukem-video edit --project prj_7k2m9x4q1b caption.from_transcript clip_item_id=itm_m1n2p3q4r5 track_id=trk_a1b2c3d4e5 new_ids:='["itm_c1c2c3c4c5","itm_c6c7c8c9c0"]'
```

Pass one new id per caption line.

## Remove silences

With the transcript of the asset in place, cut the silent parts out of a clip.

```bash
vukem-video edit --project prj_7k2m9x4q1b clip.remove_silences item_id=itm_m1n2p3q4r5 new_ids:='["itm_s1s2s3s4s5","itm_s6s7s8s9s0"]'
```

Pass one new id per piece left; `vukem-video media:inspect --sections silences` lists them.

## Common mistakes

- Planning from a stale revision. Read the project again after any conflict.
- Skipping `lint`. The export gate refuses a project with lint errors.

## Next steps

- [Safety: undo, trash and limits](/docs/agents/safety)
- [The agent skill](/docs/agents/skill)
- [CLI reference](/docs/reference/cli)
