# 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)

## Installation

### Using pipx (Recommended)

```bash
cd /var/home/dan/Dev/Misc/VidToSub/
pipx install -e .
```

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

### Manual Installation

```bash
pip install srt webvtt-py
python video_subtitle_gif.py [options]
```

## Usage

### Basic Usage

```bash
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

```bash
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`)
- `--width WIDTH`: GIF width in pixels, height auto-calculated (default: `480`)
- `--context SECONDS`: Extra time before/after subtitle (default: `0.5`)

## Examples

### Search for a quote and create a GIF

```bash
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

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

This creates higher quality GIFs with:

- 20 fps (smoother animation)
- 1280px width (larger size)
- 2 seconds of context before/after the subtitle

### Using with embedded subtitles

```bash
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`
- Manually specify subtitle file path (feature not yet implemented)

### "Library not installed" errors

- Install missing dependencies: `pip install srt webvtt-py`
- 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`)
- Reduce `--context` to shorten clips