Metadata-Version: 2.5
Name: gifboom
Version: 0.1.4
Summary: Search, download, convert and process GIFs — CLI & AI skill
Project-URL: Homepage, https://github.com/MIt9/gifboom
Project-URL: Repository, https://github.com/MIt9/gifboom
Project-URL: Bug Tracker, https://github.com/MIt9/gifboom/issues
Author: GifBoom Contributors
License: MIT
License-File: LICENSE
Keywords: ai,cli,convert,gif,giphy,mcp,tenor,video
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: anyio>=4
Requires-Dist: diskcache>=5.6
Requires-Dist: httpx>=0.27
Requires-Dist: imageio[ffmpeg]>=2.34
Requires-Dist: moviepy>=1.0.3
Requires-Dist: pillow>=10
Requires-Dist: pydantic-settings>=2
Requires-Dist: pydantic>=2
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: tui
Requires-Dist: textual>=0.70; extra == 'tui'
Description-Content-Type: text/markdown

<div align="center">

# 🎬 gifboom

### *The ultimate open-source GIF engine for Humans & AI Agents*

[![PyPI Version](https://img.shields.io/pypi/v/gifboom?style=for-the-badge&color=ff4757)](https://pypi.org/project/gifboom/)
[![Python Version](https://img.shields.io/pypi/pyversions/gifboom?style=for-the-badge&color=2ed573)](https://pypi.org/project/gifboom/)
[![License: MIT](https://img.shields.io/badge/License-MIT-70a1ff?style=for-the-badge)](LICENSE)
[![CI Status](https://img.shields.io/github/actions/workflow/status/MIt9/gifboom/ci.yml?branch=main&style=for-the-badge)](https://github.com/MIt9/gifboom/actions)

<br/>

![gifboom hero](https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif)

*"Why spend 20 minutes finding and converting a GIF when `gifboom` can do it in 2 seconds?"*

</div>

---

## 📦 Installation

```bash
pip install gifboom        # pip
uv add gifboom             # uv (recommended)
pipx install gifboom       # pipx — isolated global CLI
```

> **FFmpeg** is required for video/GIF conversion:
> ```bash
> brew install ffmpeg        # macOS
> sudo apt install ffmpeg    # Ubuntu / Debian
> ```

**Optional extras:**
```bash
pip install 'gifboom[mcp]'   # MCP server for Claude Desktop / LobeChat
pip install 'gifboom[tui]'   # Interactive terminal UI
pip install 'gifboom[dev]'   # Dev tools (pytest, ruff, mypy)
```

---

## 🌟 Why gifboom?

We loved tools like [gifgrep](https://github.com/steipete/gifgrep) for searching GIFs right from the terminal. But we kept asking:

> *"Where is the MP4 conversion? Where is video-to-GIF? What about trimming? And why can't my Claude / Cursor AI agent search and send GIFs for me??"* 🤔

So we built **gifboom** — an open-source, lightning-fast Python CLI + MCP Server that does it all:

* 🔍 **Multi-Provider Search** — GIPHY, Tenor, KLIPY, and local folders in one command
* 🎬 **GIF ↔ Video Conversion** — Turn heavy 30MB GIFs into silky 2MB MP4s (or vice versa)
* 🖼️ **Stills & Contact Sheets** — Grab single PNG frames or full 3×3 video grids
* ✂️ **Trim & Shrink** — Slice out the funny 2 seconds and optimize color palettes
* 🤖 **AI-Native** — Give your AI assistant GIF superpowers via CLI Skill or MCP Server

---

## 🍿 Feature Tour

### 1. 🔍 Instant GIF Search
Find the perfect reaction without leaving your terminal (or let your script get JSON results).

![Cat Searching](https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExODp1dndxZXFqazBwZnd2dHc4cjR1NjlzbjBqa3J0dXp6emtyOXFiYjAmZXA9djFfaW50ZXJuYWxfZ2lmX2J5X2lkJmN0PWc/3oKIPnAiaMCws8nOsE/giphy.gif)

```bash
# Pretty table format
gifboom search "excited reaction" --format table

# Pure JSON for scripts & AI
gifboom search "mind blown" --format json --limit 5

# Specific provider
gifboom search "fireworks" --provider tenor
```

---

### 2. 🎬 GIF ↔ Video Alchemy
Convert giant animated GIFs into lightweight MP4/WebM videos for Twitter, Discord, or web apps. Or turn video clips into crisp GIFs!

![Transformation Magic](https://media.giphy.com/media/12NUbkX6p4xOO4/giphy.gif)

```bash
# Shrink 40MB GIF → 2MB MP4 (huge bandwidth saver!)
gifboom convert gif2video cat.gif -o cat.mp4

# Convert video clip to high-quality GIF
gifboom convert video2gif movie.mp4 -o clip.gif --start 00:01:20 --end 00:01:25

# Batch convert a whole folder of GIFs
gifboom convert batch ./my_gifs/ --format mp4 --out-dir ./my_videos/
```

---

### 3. 🖼️ Frame Extractor & Contact Sheets
Need a quick PNG snapshot or a grid breakdown of every keyframe?

![Freeze Frame](https://media.giphy.com/media/3o7TKSjRrfIPjeiVyM/giphy.gif)

```bash
# Extract single frame at 1.5 seconds
gifboom still dance.gif --at 1.5 -o frame.png

# Generate a 3×3 grid breakdown of 9 frames
gifboom sheet dance.gif --frames 9 --cols 3 -o grid.png
```

---

### 4. 🤖 AI Superpowers — Two Flows
Teach your AI agents (Claude Desktop, Cursor, Antigravity, LobeHub) how to handle GIFs autonomously!

![Robot AI](https://media.giphy.com/media/26n6WywJyh39n1pBu/giphy.gif)

#### Flow A — CLI + Agent Skill *(shell-based)*

Best for: **Antigravity, Cursor, Windsurf, Claude Code** — any agent with terminal access.

```
AI Agent
   ├─ reads skills/gifboom/SKILL.md   ← knows every command & flag
   └─ runs gifboom CLI via shell      ← gifboom search / convert / download …
```

```bash
pip install gifboom

# Copy the skill to your agent's skills folder:
cp -r skills/gifboom ~/.agents/skills/gifboom
# or for Antigravity:
cp -r skills/gifboom ~/.gemini/config/skills/gifboom
```

#### Flow B — MCP Server *(native tool calls)*

Best for: **Claude Desktop, LobeChat, LibreChat** — clients without shell access.

```
AI Agent
   └─ calls MCP tools directly   ← search_gifs() / gif_to_video() / …
         └─ gifboom MCP server   ← no shell needed, structured JSON
```

```bash
pip install 'gifboom[mcp]'
```

`claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "gifboom": {
      "command": "gifboom",
      "args": ["mcp"]
    }
  }
}
```

| | Flow A — CLI + Skill | Flow B — MCP |
|---|---|---|
| Requires shell | ✅ | ❌ |
| Claude Desktop | ❌ | ✅ |
| Cursor / Antigravity | ✅ | ✅ |
| Extra install | none | `gifboom[mcp]` |

> 💡 Both flows can be used simultaneously — install once, integrate both ways.

---

## 🚀 Quick Start

### Step 1: Install
```bash
pip install gifboom
brew install ffmpeg   # Required for video magic ✨
```

### Step 2: Get Free API Keys in 1-Click 🔑
Don't have API keys yet? No problem! `gifboom` will launch the developer portals for you:

```bash
# Open developer portals directly in your web browser:
gifboom keys giphy    # Opens GIPHY Developer Dashboard
gifboom keys tenor    # Opens Tenor / Google Cloud Console

# Save your key locally:
gifboom config set GIPHY_API_KEY=your_secret_key_here
```

### Step 3: Boom! 💥
```bash
# Download the top "happy cat" GIF directly
gifboom download "q:happy cat" -o ~/Downloads/happy_cat.gif

# Convert to MP4
gifboom convert gif2video ~/Downloads/happy_cat.gif -o ~/Downloads/happy_cat.mp4

# Batch convert a whole folder of GIFs
gifboom convert batch ./my_gifs/ --format mp4 --out-dir ./my_videos/
```

---

## ⚡ Cheat Sheet & Recipes

| Task | Command |
|---|---|
| **Quick search & copy URL** | `gifboom search "party parrot"` |
| **Download specific URL** | `gifboom download https://media.giphy.com/... -o meme.gif` |
| **Discord Emoji Optimizer** | `gifboom convert optimize emote.gif --colors 64 -o emote_small.gif` |
| **Trim awkward start/end** | `gifboom convert trim laugh.gif --start 0.5 --end 2.5 -o clean_laugh.gif` |
| **WebM for websites** | `gifboom convert gif2video hero.gif -o hero.webm --crf 28` |
| **Check cache size** | `gifboom cache stats` |

---

## 🌐 Provider Support

| Provider | Free Tier | Setup Command | Env Variable |
|---|---|---|---|
| **GIPHY** | 100 req/hr (dev key) | `gifboom keys giphy` | `GIPHY_API_KEY` |
| **Tenor** | Generous (Google Cloud) | `gifboom keys tenor` | `TENOR_API_KEY` |
| **KLIPY** | Free beta | `gifboom keys klipy` | `KLIPY_API_KEY` |
| **Local** | Unlimited 💾 | *No key needed* | — |

---

## 🤝 Contributing

We love pull requests! Whether it's adding new GIF providers, improving conversion speed, or writing documentation:

```bash
git clone https://github.com/MIt9/gifboom.git
cd gifboom
pip install -e ".[dev]"
pytest tests/ -v
```

Check out our [CONTRIBUTING.md](CONTRIBUTING.md) for details.

---

<div align="center">

Made with ❤️ and lots of 🍿 by the Open Source Community.

[License: MIT](LICENSE) • [Report Issue](https://github.com/MIt9/gifboom/issues) • [Star on GitHub ⭐](https://github.com/MIt9/gifboom)

</div>
