169 lines
4.1 KiB
Markdown
169 lines
4.1 KiB
Markdown
# 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
|
|
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-before SECONDS`: Tweak the start time of the output GIF (default: `0`)
|
|
- `--context-after SECONDS`: Tweak the end time of the output GIF (default: `0`)
|
|
|
|
## 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 \
|
|
```
|
|
|
|
This creates higher quality GIFs with:
|
|
|
|
- 20 fps (smoother animation)
|
|
- 1280px width (larger size)
|
|
|
|
### 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`
|
|
|
|
### "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`)
|