YouTube Highlights Generator

(Note: this REAME is written by Claude while the code was written by a human.)

A Python tool to automatically create highlight reels from YouTube videos. Download a video, specify timestamps in a CSV file, and generate a polished highlights video with optional slow-motion effects and title overlays.

What This Project Does

This tool streamlines the process of creating highlight videos by:

1. Downloading YouTube videos using the provided YouTube ID
2. Extracting specific clips based on timestamps from a CSV timing sheet
3. Applying effects like slow-motion to selected clips
4. Adding title overlays to the first clip (optional)
5. Joining clips together into a final highlights video

Tech Stack

• Python 3.13+ - Required Python version
• uv - Python package manager and script runner
• yt-dlp - YouTube video downloader
• ffmpeg - Video processing and manipulation k- Standard Library: argparse, csv, hashlib, subprocess, pathlib, dataclasses

Prerequisites

Before running this tool, ensure you have the following installed:

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install yt-dlp
pip install yt-dlp
# or: brew install yt-dlp

# Install ffmpeg
brew install ffmpeg
# or: apt-get install ffmpeg
# or: Download from https://ffmpeg.org/download.html

How to Run

Basic Usage

uv run yt_h.py \
  --yt_id VIDEO_ID \
  --timings_file timings.csv \
  --title "My Highlights" \
  --storage_dir ./output

View Sample Usage

To see sample command and timings file format:

uv run yt_h.py --sample

Join Videos

To join multiple video files without downloading:

uv run yt_h.py --join video1.mp4 video2.mp4 video3.mp4

This creates a Final.mp4 in the current directory.

Command Line Arguments

Argument	Description	Required
--yt_id	YouTube video ID (e.g., dQw4w9WgXcQ)	Yes*
--timings_file	Path to CSV file with clip timings	No
--title	Title text to overlay on first clip (shown for 5 seconds)	No
--storage_dir	Directory to store downloaded videos and clips	No**
--join	Join specified video files into Final.mp4	No
--sample	Display sample usage and exit	No

* Required unless using --join or --sample ** Defaults to ./storage in the script directory, or current directory if yt_id is a local file

Timings File Format

Create a CSV file with the following format:

start,end,comment
00:04,00:11,nice shot
00:15,00:22,slowmo
01:30,01:45,great play

• start: Start time in MM:SS or HH:MM:SS format
• end: End time in MM:SS or HH:MM:SS format
• comment: Description of the clip
  • If comment contains the word slowmo, the clip will be rendered at 0.5x speed (2x slower)

Output Structure

storage/
└── {yt_id}/
    ├── full_video.mp4          # Downloaded full video
    └── clips/
        ├── 0004_0011.mp4       # Individual extracted clips
        ├── 0015_0022.mp4
        └── {sha_hash}/
            ├── highlights.mp4   # Final highlights video
            └── final-video-input.txt

The SHA hash is generated from the timing sheet, so different timing configurations create separate output folders.

Features

Slow Motion Clips

Add slowmo anywhere in the comment field to generate that clip at half speed:

start,end,comment
00:15,00:22,amazing goal - slowmo

Title Overlay

Use --title to add a title overlay on the first clip:

uv run yt_h.py --yt_id dQw4w9WgXcQ --timings_file timings.csv --title "Best Goals 2024"

The title appears centered at the bottom for the first 5 seconds.

Smart Caching

• Downloads are cached in the storage directory
• Clips are extracted once and reused
• Different timing sheets create separate output folders

Examples

Create highlights from a YouTube video

uv run yt_h.py \
  --yt_id dQw4w9WgXcQ \
  --timings_file my_timings.csv \
  --title "Epic Moments" \
  --storage_dir ./highlights

Join existing videos

uv run yt_h.py --join clip1.mp4 clip2.mp4 clip3.mp4

Troubleshooting

"yt-dlp is not available"

• Install yt-dlp: pip install yt-dlp or brew install yt-dlp

"ffmpeg is not available"

• Install ffmpeg: brew install ffmpeg or download from ffmpeg.org

Video download fails

• Verify the YouTube ID is correct
• Check your internet connection
• Some videos may be restricted or unavailable

License

This is a utility script. Use responsibly and respect YouTube's Terms of Service.