video-merger

name	video-merger
description	Concatenate a directory of numbered MP4 segments (1_*.mp4, 2_*.mp4, ...) into one MP4 with optional fade transitions, unified resolution/fps/codec. Pure ffmpeg wrapper, no LLM. Trigger when a workflow has produced several short clips that need stitching into a final reel.
provenance	{"origin":"clawhub-mit0","license":"MIT-0","upstream_url":"https://clawhub.ai/machunlin/video-merger","upstream_version":"1.1.0","maintained_by":"AgentOS"}
metadata	{"agentos":{"risk":"medium","capabilities":["filesystem-write","process-control"],"requires":{"bins":["ffmpeg","ffprobe"],"anyBins":["python","python3"]}}}
entrypoint	{"command":"python {baseDir}/scripts/merge.py","args":["--input","{{ with.input_dir }}","--output","{{ with.output_path }}","--mode","{{ with.mode | default('full') }}","--transition","{{ with.transition | default(0.5) }}","--fps","{{ with.fps | default(24) }}","--crf","{{ with.crf | default(22) }}","--preset","{{ with.preset | default('medium') }}"],"parse":"text","timeout":600}

video-merger — numbered-segment MP4 concatenator

Combines 1_*.mp4, 2_*.mp4, ... in numeric order into one MP4 (or multiple ~60s chunks), with optional fade transitions, codec/resolution/ fps normalisation.

Inputs (with:)

key	required	default	notes
input_dir	yes	—	Directory containing \d+_*.mp4 segments.
output_path	yes	—	.mp4 path (full mode) or directory (chunk mode).
mode	no	full	full or chunk.
transition	no	0.5	Fade duration in seconds. 0 disables.
fps	no	24	Target frame rate.
crf	no	22	x264 CRF (0-51, lower = better).
preset	no	medium	x264 preset.

For chunk mode, pass chunk_duration directly to the script — the meta engine entrypoint above does not template it; use a direct shell call when chunking is needed.

Dependencies

• ffmpeg ≥ 5.0
• ffprobe
• Python 3.8+
• No Python packages required beyond stdlib.

Install hints (or just run the bundled installer):

OS	One-liner installer	Manual
Windows (PowerShell)	pwsh -ExecutionPolicy Bypass -File install.ps1	winget install Gyan.FFmpeg / choco install ffmpeg / scoop install ffmpeg
macOS	bash install.sh	brew install ffmpeg
Debian/Ubuntu	bash install.sh	sudo apt install ffmpeg

The Windows installer (install.ps1) defaults to winget but accepts $env:AGENTOS_FFMPEG_INSTALLER="choco"|"scoop"|"skip" to switch backends. It prints the absolute ffmpeg/ffprobe paths after install so you can pass them to merge.py via --ffmpeg-path / --ffprobe-path when subprocess PATH inheritance is unreliable.

Filename ordering contract

The script picks files matching ^\d+_.*\.mp4$ and sorts by the leading integer. Producers must save segments as 1_shot.mp4, 2_shot.mp4, 3_shot.mp4, etc. The meta-short-drama workflow already follows this.

Output

Stdout: progress lines and the final output path. Non-zero exit on ffmpeg failure.

Failure modes

• 未找到ffmpeg → install ffmpeg, ensure ffmpeg on PATH or pass --ffmpeg-path directly.
• 未找到符合命名规则...的MP4文件 → ensure segments are \d+_*.mp4.
• Mixed resolutions / fps: handled automatically when --resolution is set; otherwise ffmpeg preserves originals (no normalisation).