Metadata-Version: 2.4
Name: voxi
Version: 1.1.1
Summary: Transcribe social media videos locally. No cloud, no APIs, unlimited use.
License: MIT
Project-URL: Homepage, https://github.com/royalashu4u/voxi
Project-URL: Repository, https://github.com/royalashu4u/voxi
Project-URL: Documentation, https://github.com/royalashu4u/voxi#readme
Keywords: transcription,whisper,instagram-reels,youtube-transcript,tiktok,mcp-server,cli-tool,openai-whisper,speech-to-text,voxi,local-transcription,offline-transcribe
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp
Requires-Dist: faster-whisper
Requires-Dist: textual>=0.50.0
Requires-Dist: rich
Requires-Dist: pyperclip
Provides-Extra: mcp
Requires-Dist: mcp; extra == "mcp"
Dynamic: license-file

<div align="center">
  <pre style="font-family: monospace; font-size: 1.2em; color: #00d4ff;">
██╗   ██╗ ██████╗ ██╗  ██╗██╗
██║   ██║██╔═══██╗╚██╗██╔╝██║
██║   ██║██║   ██║ ╚███╔╝ ██║
╚██╗ ██╔╝██║   ██║ ██╔██╗ ██║
 ╚████╔╝ ╚██████╔╝██╔╝ ██╗██║
    ╚═══╝   ╚═════╝ ╚═╝  ╚═╝╚═╝                
  </pre>

  <h1>Voxi</h1>

  <p><strong>Transcribe social media videos locally</strong></p>
  <p><strong>No cloud. No paid APIs. Unlimited use. 🤯</strong></p>

  <!-- Badges -->
  <p>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
    <img src="https://img.shields.io/badge/python-3.8%2B-blue" alt="Python 3.8+">
    <a href="https://github.com/royalashu4u/voxi/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs Welcome"></a>
    <img src="https://img.shields.io/badge/MCP-ready-8A2BE2" alt="MCP Ready">
    <a href="https://www.buymeacoffee.com/voxitranscriber"><img src="https://img.shields.io/badge/sponsor-buy%20me%20a%20coffee-orange" alt="Buy Me a Coffee"></a>
  </p>
</div>

---

## 🚀 What is Voxi?

A terminal tool that downloads and transcribes **any social media video** into clean text with timestamps.

Paste an Instagram Reel, YouTube video, TikTok, Twitter/X clip, or Facebook video — get back a full transcript. **All on your machine. Forever free.**

**Pipeline:**
```
YouTube/Instagram/TikTok/Twitter/X/Facebook ──► yt-dlp ──► ffmpeg ──► Whisper ──► JSON + Text
```

---

## ⚡ Quick Start

### Option A — Clone & run (30 seconds)

```bash
git clone https://github.com/royalashu4u/voxi.git
cd voxi
pip install -e .
voxi "https://www.instagram.com/reel/..."
```

### Option B — One-click setup (auto)

```bash
git clone https://github.com/royalashu4u/voxi.git
cd voxi
bash scripts/setup.sh        # Linux / macOS
powershell -File scripts/setup.ps1    # Windows
```

### Option C — pip install (from anywhere)

```bash
pip install voxi
voxi "https://www.youtube.com/watch?v=..."
```

---

## 🎮 Usage

### Interactive mode

```bash
voxi
# Paste a URL at the prompt — or type / to see command suggestions
# Try /help, /lang hi, /history, /config
```

### Direct mode

```bash
voxi "https://www.instagram.com/voxi/..."
```

---

## 🤖 MCP Integration — Use Voxi inside Claude, Cursor, Windsurf

Voxi can run as an **MCP server**, letting AI assistants transcribe videos on your behalf.
You say *"transcribe this reel"* — the AI calls Voxi locally, gets the text, and replies.

**Step 1 — Install MCP support** (Python 3.10+ required):
```bash
pip install voxi[mcp]
```

**Step 2 — Add to your Claude Desktop config**
(`~/.config/claude/claude_desktop_config.json` on Linux/macOS,
`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
```json
{
  "mcpServers": {
    "voxi": {
      "command": "python",
      "args": ["-m", "voxi_transcriber.mcp_server"]
    }
  }
}
```

**Step 3 — Restart Claude Desktop.** Done! 🎉

Two tools are exposed to the AI:
| Tool | Returns |
|------|---------|
| `transcribe_video(url)` | Full plain-text transcript |
| `transcribe_video_with_timestamps(url)` | `[MM:SS → MM:SS] text` per segment |

> Works with Claude Desktop, Cursor, Windsurf, Zed, and any MCP-compatible client.

---

## 💸 vs Cloud APIs

| Feature | **Voxi** | AssemblyAI | Rev.ai | Whisper API |
|---------|:---:|:---:|:---:|:---:|
| **Cost** | **$0** | $0.015/min | $0.25/min | $0.006/min |
| **Unlimited** | ✅ | ❌ | ❌ | ❌ |
| **Offline** | ✅ | ❌ | ❌ | ❌ |
| **Privacy** | ✅ | ❌ | ❌ | ❌ |
| **MCP support** | ✅ | ❌ | ❌ | ❌ |
| **Instagram** | ✅ | ❌ | ❌ | ❌ |

---

## 🛠 Commands

| Command | What it does |
|---------|-------------|
| Paste a URL | Transcribe the video |
| `/help` | Show commands |
| `/lang [code]` | Set language |
| `/history` | View transcripts |
| `/config` | Show settings |
| `/cache` | View/clear cache |
| `/clear` | Clear screen |
| `/exit` | Quit |

---

## ⚙️ Configuration

Edit `voxi_transcriber/config.py`:

| Setting | Default | Options | Description |
|---------|---------|---------|-------------|
| `MODEL_SIZE` | `base` | `tiny, base, small, medium, large-v3` | Model size |
| `DEVICE` | `auto` | `auto, cuda, cpu` | Compute device |
| `COMPUTE_TYPE` | `int8` | `int8, float16, float32` | Precision |
| `LANGUAGE` | `auto` | `auto, en, hi, es, ...` | Language |
| `USE_COOKIES` | `True` | `True, False` | Instagram cookies |
| `USE_CACHE` | `True` | `True, False` | Enable caching |

---

## 🌐 Platform Support

| Platform | Works out of the box | Needs cookies |
|----------|:---:|:---:|
| YouTube | ✅ | ❌ |
| TikTok | ✅ | ❌ |
| Twitter / X | ✅ | ❌ |
| Facebook | ✅ | Sometimes |
| Instagram | ✅ | **Always** |

---

## ❓ FAQ

<details>
<summary><strong>Missing dependencies: faster-whisper</strong></summary>

```bash
pip install faster-whisper
```
</details>

<details>
<summary><strong>"Instagram blocked the request"</strong></summary>

```bash
yt-dlp --cookies-from-browser firefox --cookies cookies.txt "https://www.instagram.com/"
```
</details>

<details>
<summary><strong>Missing ffmpeg</strong></summary>

```bash
sudo apt install ffmpeg  # Ubuntu/Debian
brew install ffmpeg      # macOS
```
</details>

---

## 📁 Folder Structure

```
voxi/
├── voxi_transcriber/         # Python package
│   ├── __init__.py
│   ├── __main__.py
│   ├── app.py                # ← Textual TUI (main entry point)
│   ├── cli.py                # Rich REPL (legacy)
│   ├── config.py             # All settings
│   ├── mcp_server.py         # MCP server for AI agents
│   ├── transcribe.py         # Core pipeline
│   ├── utils.py              # Cache, download, formatting
│   └── ui/
│       ├── header.py
│       ├── history_viewer.py
│       └── transcript_viewer.py
├── scripts/
│   ├── setup.sh              # Linux / macOS auto-setup
│   └── setup.ps1             # Windows auto-setup
├── outputs/                  # Saved transcripts (auto-created)
├── .cache/                   # Cache directory (auto-created)
├── cookies.txt               # Instagram auth (you generate this)
├── pyproject.toml
├── README.md
└── AGENTS.md
```

---

## 🤝 Contributing

Contributions welcome!

1. Fork the repo
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

---

## 📜 License

[MIT](LICENSE) © 2026 royalashu4u

---

<div align="center">
  <p>⭐ Star this repo if you find it useful! ⭐</p>
</div>
