video_stitch
Combine finished video clips into one ordered file with hard cuts, preserving each clip's audio. Optionally add voiceover, background music, or subtitles to assemble a longer video from separate clips.
Instructions
Join finished video clips into one file, in the order given, with a hard cut between each and each clip's audio kept — this assembles existing clips, it does not generate new video. Use it to build a video longer than a single model clip: generate the shots with video_generate, then stitch them. Do NOT use it for a single clip, or for a batch of clips meant to stay separate. Three optional layers, each its own parameter: lay a voiceover over the picture (pass narration — ONE take per clip, in clip order, NOT one joined track; each take is aligned to its own clip so nothing drifts), lay a background-music track under the whole thing (pass music), or burn in subtitles from an SRT file (pass subtitles); clips of different sizes are scaled to a common frame. Returns the output file path with its duration, resolution, and size, or a structured error with a hint. Requires ffmpeg on the system. Set dry_run=true to preview the plan without running anything.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| clips | Yes | The clips to join, in play order — local file paths (e.g. the `path` a video_generate result returns) or direct http(s) video URLs. At least two. | |
| music | No | Optional audio file (a local path or a URL) laid under the whole video as background music, mixed below the clips' own audio. | |
| output | No | Optional output file path. Omit to write a default filename into the media output directory. | |
| dry_run | No | If true, return the planned output path and inputs; run no ffmpeg. | |
| narration | No | Optional voiceover — ONE audio take per clip, in the same order and the same count as `clips`. Each take is padded with silence to its clip's length, so take N is heard over clip N with no timecodes to keep in sync. The narration sits at full level and the clips' own audio is ducked beneath it. A take longer than the clip it belongs to is an error naming that clip, never a truncation — shorten the line and re-voice that one take. | |
| subtitles | No | Optional SRT subtitle file (a local path or a URL) burned into the video. |