VANTRUE Dashcam Video Stitcher

This script is designed to process and combine dual-channel video files from a VANTRUE dashcam into a single, picture-in-picture (PiP) video. It automates the process of finding front and rear/cabin video pairs, grouping them into recording sessions, and using ffmpeg to create a final stitched video.

Overview

The stitch.py script can:

• Scan a directory for VANTRUE video files (.MP4).
• Identify front (_A.MP4) and cabin (_B.MP4) video pairs based on their timestamped filenames.
• Group continuous recordings into "sessions," correctly handling sessions that span across midnight.
• Filter videos to process only a specific day, week, or month.
• Use ffmpeg to create a picture-in-picture video, overlaying the cabin view on the main front camera view.
• Concatenate all clips from a session into a single output file.

Prerequisites

• Python 3: The script is written in Python 3.
• FFmpeg: The script relies on the ffmpeg command-line tool for all video manipulation. You must have ffmpeg installed and available in your system’s PATH.

Install and Setup (macOS example)

1. Install dependencies:

brew install ffmpeg

1. Check out the repo into the root of the VANTRUE SD card or folder:

cd /Volumes/<VANTRUE_VOLUME_NAME>
git clone https://github.com/SteveClement/vantrue-dashcam-stitcher.git VANTRUE
mv VANTRUE/.git VANTRUE/.gitignore VANTRUE/* . && rm -r VANTRUE

This keeps paths like Normal/, Event/, and GPS/ in the expected locations.

Directory Structure

• Normal/: Contains the continuous loop recordings. These are designated with _N_ in the filename.
• Event/: Contains video files recorded when the G-sensor is triggered. These are designated with _E_ in the filename.
• Normal/processed/: After processing, the original video files from Normal/ are moved here.
• Event/processed/: After processing, the original video files from Event/ are moved here.
• stitched_videos/: The default output directory where the processed, stitched videos are saved.

Usage

The script is run from the command line and offers several arguments to customize its behavior.

Basic Command

To process videos, run a command like the following:

python3 stitch.py --video_dir Normal --file_type N

This command will:

1. Find all Normal videos in the Normal/ directory.
2. Group them into "sessions" (a session ends when there is a time gap of more than 5 minutes between clips).
3. For each session, create a single stitched video with the rear camera as a picture-in-picture overlay.
4. Save the stitched videos to the stitched_videos/ directory.
5. Move the original source files to Normal/processed/.

You can filter which videos to process by date:

# Process videos from a specific day
python3 stitch.py --date 2023-10-27

# Process videos from a specific week
python3 stitch.py --week 2023-W43

# Process videos from a specific month
python3 stitch.py --month 2023-10

Use the --dry-run flag to see what the script would do without actually processing any files.

For a full list of options, run:

python3 stitch.py --help

Cleanup Script

After running stitch.py, the original files are moved to a processed folder (e.g., Normal/processed). The cleanup_processed.sh script can be used to safely delete the original files from the root Normal or Event directory. It works by comparing the checksum of the original file with the processed copy to ensure it was moved correctly before deleting it.

# Do a dry run to see which files would be deleted from 'Normal'
./cleanup_processed.sh -n Normal

# Delete the verified original files from 'Normal'
./cleanup_processed.sh Normal

Development Conventions

The script relies on the specific filename convention of the VANTRUE dashcam to pair front and rear videos. The expected format is YYYYMMDD_HHMMSS_####_[N|E]_[A|B].MP4.

Note: Future updates may add support for the rear camera (*_C.MP4) as well.