video-merger
GitHub将编号MP4片段按顺序拼接为完整视频，支持淡入淡出过渡及分辨率、帧率统一。适用于工作流生成的多个短片需合并为最终成片的场景。
Trigger Scenarios
Install
npx skills add opensquilla/opensquilla --skill video-merger -g -y
SKILL.md
Frontmatter
{
"name": "video-merger",
"metadata": {
"opensquilla": {
"risk": "medium",
"requires": {
"bins": [
"ffmpeg",
"ffprobe"
],
"anyBins": [
"python",
"python3"
]
},
"capabilities": [
"filesystem-write",
"process-control"
]
}
},
"entrypoint": {
"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",
"command": "python {baseDir}\/scripts\/merge.py",
"timeout": 600
},
"provenance": {
"origin": "clawhub-mit0",
"license": "MIT-0",
"upstream_url": "https:\/\/clawhub.ai\/machunlin\/video-merger",
"maintained_by": "OpenSquilla",
"upstream_version": "1.1.0"
},
"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."
}
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.0ffprobe- 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:OPENSQUILLA_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, ensureffmpegon PATH or pass--ffmpeg-pathdirectly.未找到符合命名规则...的MP4文件→ ensure segments are\d+_*.mp4.- Mixed resolutions / fps: handled automatically when
--resolutionis set; otherwise ffmpeg preserves originals (no normalisation).
Version History
- 7f72a32 Current 2026-07-05 18:40
