Video Overlay Automation

Batch-overlays main/text video clips onto matching background videos using FFmpeg, with luma-key transparency, resolution scaling, background loop extension, audio/video fades, and hardware-accelerated GPU rendering.

Drop your clips in the background/ and main/ folders, run run.sh, and find the composited results in final/.

flowchart LR
    A["Background Clips\n(background/)"] --> C["FFmpeg Compositor"]
    B["Main / Overlay Clips\n(main/)"] --> C
    C --> D{"Hardware Probe\n(/dev/dri)"}
    D -->|"VAAPI Available"| E["⚡ GPU Transcode\n(h264_vaapi)"]
    D -->|"CPU Fallback"| F["CPU Software\n(libx264)"]
    E --> G["🚀 Composited Video\n(final/)"]
    F --> G

• Sequential index pairing — alphabetically sorted backgrounds are matched to the same-index main clip (names can differ; order matters).
• Luma-key compositing — screens out pure-black (#000000) backgrounds on the overlay using the lumakey filter.
• Background looping — backgrounds are streamed infinitely so the main clip always has a backdrop for its full duration.
• Resolution scaling — the overlay is scaled to match the background automatically.
• Video & audio fades — configurable fade-in / fade-out durations applied to both streams.
• GPU acceleration — when available, automatically probes for /dev/dri/renderD* to utilize h264_vaapi hardware encoding (AMD and Intel GPUs). Fallback to CPU software encoding (libx264) is automatic and transparent.
• Configurable CRF / preset — tune quality/size trade-offs in config.json.
• Error resilience — on render failure, source files are moved to failed/ so nothing is lost.

video-processing-pipeline/
├── background/        # Place background clips here
├── main/              # Place main/text overlay clips here
├── final/             # Composited results land here
├── failed/            # Source files moved here on error
├── video_processor.py # Main automation script
├── config.json        # Tunable parameters
├── run.sh             # One-shot batch trigger
└── README.md

git clone https://github.com/lZXGl/video-processing-pipeline.git
cd video-processing-pipeline

# FFmpeg and ffprobe are required
sudo apt install ffmpeg

# Python 3 is the only runtime dependency
python3 --version

1. Place matching background and main clips in background/ and main/.
2. Run:

./run.sh

or:

python3 video_processor.py

3. Results appear in final/; source files are removed automatically.

python3 video_processor.py --bg path/to/bg.mp4 --text path/to/text.mp4 --out path/to/output.mp4

Edit config.json — all paths are relative to the project directory:

• Short description: Batch video overlay pipeline: luma-key compositing, GPU-accelerated FFmpeg, sequential background+foreground pairing.
• Suggested topics: ffmpeg, video, vaapi, gpu-acceleration, automation, overlay, luma-key, python, linux
• License recommendation: MIT.
• Security note: .gitignore covers final/, failed/, output/ and logs/ so media outputs never reach the repository.