Merge Videos

Merge multiple MP4 videos into a single grid-layout video with optional labels.

Permanent Script

The merge tool is the permanent CLI script next to this file:

<this skill directory>\merge_videos.py

After syncing to Claude with codex2claude, use the copied script in Claude's merge skill directory. Do not use hardcoded stale paths such as .claude-key3.

Do not generate temporary merge scripts. Always call this permanent script directly with python.

Templates

Auto-detect template when -t is omitted:

• 2 videos -> 2x1
• 3 videos -> 3x1
• 4 videos -> 2x2
• 6 videos -> 3x2

For any other count, pass -t, for example -t 8x4 for 32 videos.

Workflow

1. Find video paths from user arguments, globbing a directory when needed.
2. Determine the template from the user request or by auto-detect.
3. Auto-generate labels from filenames unless custom labels or --no-labels are requested.
4. Use --loop-to-longest when the user wants the longest video to define the full episode and shorter videos to replay.
5. Use --stream for large grids or long videos so encoded frames are written incrementally instead of held in memory.
6. Run the permanent script directly:

python "<this skill directory>\merge_videos.py" <video_paths> -t <template> --labels <labels...> -o <output>

7. Report output path, frame count, duration, resolution, and file size.

CLI Parameters

python merge_videos.py VIDEO [VIDEO ...] [-t TEMPLATE] [--labels LABEL [LABEL ...]]
                       [-o OUTPUT] [--gap N] [--fps N] [--font-size N] [--no-labels]
                       [--loop-to-longest] [--stream]
                       [--cell-width N] [--cell-height N]

Examples

2x2 grid:

python "<this skill directory>\merge_videos.py" `
  "dir\v1.mp4" "dir\v2.mp4" "dir\v3.mp4" "dir\v4.mp4" `
  -t 2x2 --labels "iter 1700" "iter 3000" "iter 5000" "iter 7000" `
  -o "dir\merge_2x2.mp4"

3x1 vertical:

python "<this skill directory>\merge_videos.py" `
  "dir\v1.mp4" "dir\v2.mp4" "dir\v3.mp4" `
  -t 3x1 --labels "IsaacLab" "MuJoCo Humanoid" "MuJoCo Manual"

Large 8x4 grid, longest video defines duration, shorter videos loop:

python "<this skill directory>\merge_videos.py" <32 videos> `
  -t 8x4 --loop-to-longest --stream --fps 50 `
  --cell-width 320 --cell-height 180 `
  -o "merge_8x4_loop_longest.mp4"

Notes

• The script supports arbitrary NxM templates via auto-parsing.
• All videos are resized to the smallest common resolution unless --cell-width or --cell-height caps the cell size.
• Without --loop-to-longest, videos are cropped to the shortest input duration.
• With --loop-to-longest, the output frame count equals the longest input frame count and shorter videos repeat.
• For high video counts, always prefer --stream.

Prerequisites

Python packages:

pip install opencv-python imageio imageio-ffmpeg av Pillow numpy