Initial commit

README.md

@@ -0,0 +1,173 @@
+# 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