gifhorse

# GifHorse - Dialogue Search & GIF Creator

Create reaction GIFs from your video library by searching dialogue and adding timed subtitles.

## What GifHorse Does

1. **Transcribe videos** - Extract dialogue with timestamps by downloading subtitles, using local .srt files, or Whisper AI
2. **Search dialogue** - Find quotes across your entire video library instantly
3. **Preview clips** - See exactly what will be captured before creating the GIF
4. **Create GIFs** - Generate GIFs with perfectly timed subtitles and optional watermarks

## Setup

### First Time Setup

1. Install gifhorse (via install button above)
2. Install FFmpeg-full for subtitle rendering (via install button above)
3. Transcribe your video library (downloads subtitles automatically):

```bash
cd ~/gifhorse && source venv/bin/activate
gifhorse transcribe ~/Movies
```

The gifhorse command must be run from within its virtual environment. You can activate it with:

```bash
cd ~/gifhorse && source venv/bin/activate
```

Or use the activation helper:

```bash
source ~/gifhorse/activate.sh
```

## Available Commands

### Transcribe Videos

Extract dialogue from your videos (one-time per video):

```bash
# Default: downloads subtitles from online providers (fast, recommended)
gifhorse transcribe /path/to/videos

# Use only local .srt files (no downloading, no Whisper)
gifhorse transcribe /path/to/videos --use-subtitles

# Use Whisper AI (slow but works for any video)
gifhorse transcribe /path/to/video.mp4 --use-whisper
```

### Download Subtitles Only

Download .srt files without storing in the database:

```bash
gifhorse fetch-subtitles /path/to/videos
gifhorse fetch-subtitles /path/to/videos --skip-existing
```

### Search Dialogue

Find quotes across your entire library:

```bash
# Basic search
gifhorse search "memorable quote"

# Search with surrounding context
gifhorse search "memorable quote" --context 2
```

### Preview Before Creating

See exactly what will be captured:

```bash
gifhorse preview "memorable quote" 1
gifhorse preview "quote" 1 --include-before 1 --include-after 1
```

### Create GIF

Generate the GIF with subtitles:

```bash
# Basic GIF
gifhorse create "memorable quote" 1 --output reaction.gif

# High quality for social media
gifhorse create "quote" 1 --width 720 --fps 24 --quality high

# Include conversation context
gifhorse create "quote" 1 --include-before 2 --include-after 1
```

### Check Status

```bash
# See transcription stats
gifhorse stats

# List all transcribed videos
gifhorse list
```

## Timing Options

Control exactly what gets captured:

- `--include-before N` - Include N dialogue segments before the match
- `--include-after N` - Include N dialogue segments after the match
- `--padding-before SECS` - Add buffer seconds before dialogue starts (default: 1.0)
- `--padding-after SECS` - Add buffer seconds after dialogue ends (default: 1.0)
- `--start-offset SECS` - Manual adjustment to start time (can be negative)
- `--end-offset SECS` - Manual adjustment to end time (can be negative)

**Important:** For reactions after dialogue, use `--padding-after` instead of `--include-after`. The include-after option captures ALL time until the next dialogue segment (could be 30+ seconds!).

## Quality Options

- `--quality low|medium|high` - Color palette quality (affects file size)
- `--fps N` - Frames per second (default: 15, use 24 for smooth)
- `--width N` - Width in pixels (default: 480, use 720 for HD)
- `--no-subtitles` - Create GIF without subtitle overlay

**Note:** All GIFs automatically include a subtle "gifhorse" watermark in the bottom-right corner.

## Common Workflows

### Quick Reaction GIF

```bash
gifhorse search "perfect"
gifhorse create "perfect" 1 --padding-after 2.0 --output perfect.gif
```

### Full Conversation Exchange

```bash
gifhorse search "key phrase"
gifhorse preview "key phrase" 1 --include-before 2 --include-after 1
gifhorse create "key phrase" 1 --include-before 2 --include-after 1
```

### High Quality for Twitter/X

```bash
gifhorse create "quote" 1 --width 720 --fps 24 --quality high --output tweet.gif
```

### Scene with Reaction After Dialogue

```bash
gifhorse create "memorable line" 1 --padding-after 3.0
```

## Tips & Tricks

1. **Always preview first** - Use `preview` to verify timing before creating
2. **Default downloads subtitles** - Just run `gifhorse transcribe` and subtitles are fetched automatically
3. **Watch file sizes** - High quality + long duration = large files (20s can be 20+ MB)
4. **Padding vs Include** - For reactions, use `--padding-after` not `--include-after`
5. **Search with context** - Add `--context 2` to see surrounding dialogue

## File Size Guide

- **Low quality, 10s, 360p:** ~1-2 MB
- **Medium quality, 10s, 480p:** ~3-5 MB
- **High quality, 20s, 720p:** ~20+ MB

## Troubleshooting

### "command not found: gifhorse"

Activate the virtual environment:

```bash
cd ~/gifhorse && source venv/bin/activate
```

### Subtitle rendering errors

Make sure FFmpeg-full is installed:

```bash
brew install ffmpeg-full
```

### Video file not found

The database stores absolute paths. If you moved videos after transcription, re-transcribe in the new location.

## Network Share Support

GifHorse works with network-mounted videos:

```bash
# Mount network share (macOS)
open "smb://server-ip/share-name"

# Transcribe from network
gifhorse transcribe "/Volumes/server-ip/Movies"
```

## When to Use This Skill

Invoke gifhorse when the user wants to:
- Search for dialogue or quotes in their video library
- Create a reaction GIF from a movie or TV show
- Add subtitles to a video clip
- Transcribe videos for searchable dialogue
- Preview what a GIF will look like before creating it
- Add watermarks to GIFs for social media

## Learn More

- **GitHub:** https://github.com/Coyote-git/gifhorse
- **Usage Guide:** https://github.com/Coyote-git/gifhorse/blob/main/USAGE_GUIDE.md
- **Roadmap:** https://github.com/Coyote-git/gifhorse/blob/main/ROADMAP.md

## License

MIT