Video Clip Extractor

A Python tool that processes CSV files containing timestamps and generates FFmpeg commands to extract video clips based on START/STOP markers.

Features

• Processes CSV files with timestamp data
• Generates FFmpeg commands for video clip extraction
• Creates executable shell scripts
• Handles errors gracefully
• Configurable output directory
• One-command execution with progress feedback

Prerequisites

• Python 3.6 or higher
• FFmpeg installed on your system
• Required Python packages (install using requirements.txt)

Installation

1. Clone this repository:

git clone <repository-url>
cd timestamp-clipper

2. Create and activate a virtual environment:

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
# .\venv\Scripts\activate

3. Install the required Python packages:

python3 -m pip install -r requirements.txt

4. Ensure FFmpeg is installed on your system:

# On macOS (using Homebrew)
brew install ffmpeg

# On Ubuntu/Debian
sudo apt-get install ffmpeg

# On Windows (using Chocolatey)
choco install ffmpeg

5. Make the wrapper script executable:

chmod +x extract_clips.sh

Usage

Quick Start (Recommended)

Use the wrapper script for a one-command solution:

./extract_clips.sh input.csv input.mp4 [output_dir]

Example:

./extract_clips.sh timestamps.csv video.mp4 clips/

The wrapper script will:

1. Generate the FFmpeg commands
2. Execute them sequentially
3. Show progress for each clip
4. Handle errors gracefully
5. Clean up temporary files

Manual Usage

Alternatively, you can run the Python script directly:

python3 video_clip_extractor.py --csv input.csv --video input.mp4 --output-dir clips/

This will generate a script with FFmpeg commands that you can execute manually.

Arguments

• csv_file: Path to the CSV file containing timestamps (required)
• video_file: Path to the input video file (required)
• output_dir: Directory where clips will be saved (default: "clips")

CSV Format

The CSV file should contain at least these columns:

• Time In: Timestamp in HH:MM:SS format
• Comment: Text containing START/STOP markers

Example CSV format:

Time In,Comment
00:00:10,START - Scene 1
00:00:20,STOP
00:00:30,START - Scene 2
00:00:40,STOP

Output

The script will:

1. Create the specified output directory if it doesn't exist
2. Generate video clips in the output directory
3. Show progress for each clip being processed
4. Provide a summary when complete

Error Handling

The script includes comprehensive error handling for:

• Missing or invalid input files
• Invalid timestamp formats
• Invalid START/STOP pairs
• File permission issues
• FFmpeg processing errors

License

[Your License Here]

Author

Kevin von James