git:20260827.d6a00ab to git:20260827.d2b68b3

---

name: video-merge

description: >-

Merges multiple videos from a folder (sorted by filename) into one clip with a

random xfade transition (0.5s) between each pair; freeze-pads so total duration

equals the sum of sources. Exports 3840×2160 60fps H.265 Main10 40Mbps + AAC

320kbps. Use when the user wants video merge, concatenate videos, 视频拼接,

过场动画, xfade, join clips, or batch stitch clips with transitions.

disable-model-invocation: true

---

# Video Merge

Concatenate every video in a folder (filename sort) into **one** high-quality MP4. Between each pair, pick a **random** FFmpeg `xfade` transition (0.5s). Audio uses matching `acrossfade`.

**Duration is preserved:** each cut freeze-pads the outgoing clip by 0.5s (last frame + silence) before the overlap, so output length equals the sum of source clip durations (not shortened by transitions).

## Rules

- Run `merge.py` through **`.dependency/python/python.exe`**. Never use host `python` / `ffmpeg`.

- **Never overwrite sources.** Outputs go under `video-merge/`.

## Quick Start

```bash

.dependency/python/python .ai/video-merge/merge.py --folder path/to/clips

```

Example:

```

assets/shots/

01.mp4

02.mp4

03.mp4

```

## Output Spec (fixed)

| Setting | Value |

|---------|-------|

| Resolution | 3840×2160 (scale + letterbox pad) |

| Frame rate | 60 fps |

| Video | H.265 Main10 (`libx265`, `yuv420p10le`) @ **40 Mbps** |

| Audio | AAC **320 kbps**, 48 kHz stereo |

| Transition | **0.5 s**, random from the pool below (freeze-pad; duration preserved) |

| Container | `.mp4` (`hvc1` tag) |

## Transition Pool (random per cut)

`fade` · `dissolve` · `wipeleft` · `wiperight` · `wipeup` · `wipedown` · `slideleft` · `slideright` · `circlecrop` · `pixelize` · `distance` · `radial` · `smoothleft` · `smoothright` · `circleopen` · `circleclose` · `diagtl` · `diagtr` · `hblur` · `zoomin`

Each cut independently samples one transition. Printed in the run log.

## Common Flags

`--folder` · `-o` / `--output`

```bash

.dependency/python/python .ai/video-merge/merge.py --folder clips

.dependency/python/python .ai/video-merge/merge.py --folder clips -o out/final.mp4

```

**Never overwrite source files.** Input must be a folder (`--folder`), not a single video file. Only top-level videos in the folder (no recurse). Supported: `.mp4`, `.mkv`, `.mov`, `.avi`, `.webm`, `.wmv`, `.flv`, `.m4v`, `.mpeg`, `.mpg`, `.ts`, `.mts`, `.m2ts`, `.3gp`, `.ogv`.

## Agent Notes

3. Every clip **except the first** must be **longer than 0.5s** (incoming side of `xfade`).

5. Many clips (4K10) auto-chunk (max 4 inputs per filtergraph) to avoid OOM; transitions stay correct across chunk boundaries.

7. FFmpeg filter details: [reference.md](reference.md)

## Tests

From repo root:

```bash

.dependency/python/python .ai/video-merge/test_merge.py

```