vid-to-gif-with-subs/README.md

Video Subtitle to GIF Generator

A Python tool that searches video subtitles for text matches and generates GIF clips with burned-in subtitles for each occurrence.

Features

• Multiple subtitle formats: Supports SRT, ASS/SSA, and WebVTT formats
• Flexible subtitle sources: Works with both external subtitle files and embedded subtitles
• Case-insensitive search: Find text regardless of capitalization
• Multiple matches: Automatically creates separate GIF files for each match
• High-quality output: Uses FFmpeg's palette generation for optimal GIF quality
• Configurable parameters: Customize GIF size, framerate, and timing

Requirements

• Python 3.9+
• FFmpeg 7.0+ (with subtitle support)
• pipx for installation (recommended)

Python Dependencies

Required:

• srt - For SRT subtitle parsing
• webvtt-py - For WebVTT subtitle parsing

Optional:

• colorama - For colored terminal output (enhances readability and looks pretty)

Installation

Using pipx (Recommended)

pipx install -e .

This creates an isolated environment and installs the video-subtitle-gif command globally.

Manual Installation

# Install required dependencies
pip install srt webvtt-py

# Install optional dependencies for better experience
pip install colorama

# Run the script
python video_subtitle_gif.py [options]

Usage

Basic Usage

video-subtitle-gif video.mp4 "search text"

This will:

1. Search for subtitles (external file or embedded)
2. Find all occurrences of "search text" (case-insensitive)
3. Create GIF files named output_1.gif, output_2.gif, etc.

Advanced Usage

video-subtitle-gif video.mp4 "search text" \
  --output-prefix myclip \
  --fps 15 \
  --width 720 \
  --context 1.0

Command-Line Options

• video_path: Path to the video file (required)
• search_text: Text to search for in subtitles (required)
• --output-prefix PREFIX: Prefix for output files (default: output)
• --fps FPS: GIF framerate in frames per second (default: 10, range: 1-60)
• --width WIDTH: GIF width in pixels, height auto-calculated (default: 480)
• --context-before SECONDS: Extra seconds before subtitle start (default: 0, can be negative to trim)
• --context-after SECONDS: Extra seconds after subtitle end (default: 0, can be negative to trim)
• --include-surrounding-subtitles: Include subtitles from surrounding lines in the output (optional flag)

Examples

Search for a quote and create a GIF

video-subtitle-gif movie.mp4 "hello world"

Output:

Found external subtitle: movie.srt

Found 2 matching subtitle(s):
  1. [00:01:23.456 - 00:01:26.789]: Hello world, this is a test...
  2. [00:05:42.123 - 00:05:44.567]: Hello world again...

Generating GIFs...

Generating output_1.gif...
  Time range: 00:01:22.956 - 00:01:27.289
  Created: output_1.gif (2.34 MB)

Generating output_2.gif...
  Time range: 00:05:41.623 - 00:05:45.067
  Created: output_2.gif (1.89 MB)

Successfully created 2 GIF(s)

High-quality GIF with custom settings

video-subtitle-gif video.mp4 "important quote" \
  --output-prefix quote \
  --fps 20 \
  --width 1280 \

This creates higher quality GIFs with:

• 20 fps (smoother animation)
• 1280px width (larger size)

Using with embedded subtitles

video-subtitle-gif movie.mkv "dialogue"

The script automatically extracts embedded subtitles if no external file is found.

Subtitle File Discovery

The script searches for subtitles in this order:

1. External files in the same directory as the video:

   • {video_name}.srt
   • {video_name}.ass
   • {video_name}.vtt

2. Embedded subtitles in the video container:

   • Automatically extracted using FFmpeg
   • Saved as {video_name}.srt

Supported Formats

Video Formats

Any format supported by FFmpeg (MP4, MKV, AVI, WebM, etc.)

Subtitle Formats

• SRT (SubRip): Most common format
• ASS/SSA (Advanced SubStation): Anime and styled subtitles
• VTT (WebVTT): Web-based subtitle format

Troubleshooting

"No subtitles found"

• Ensure subtitle file exists in the same directory as the video
• Check that embedded subtitles exist: ffprobe -v error -select_streams s input.mp4

"Library not installed" errors

• Install missing dependencies: pip install srt webvtt-py
• For colored output: pip install colorama
• Or reinstall with pipx: pipx reinstall video-subtitle-gif

Poor GIF quality

• Increase --fps (e.g., 15 or 20)
• Increase --width (e.g., 720 or 1280)
• Note: Larger values = bigger file sizes

Large file sizes

• Decrease --fps (e.g., 8 or 10)
• Decrease --width (e.g., 320 or 480)