██╗   ██╗ ██████╗ ██╗  ██╗██╗
██║   ██║██╔═══██╗╚██╗██╔╝██║
██║   ██║██║   ██║ ╚███╔╝ ██║
╚██╗ ██╔╝██║   ██║ ██╔██╗ ██║
 ╚████╔╝ ╚██████╔╝██╔╝ ██╗██║
    ╚═══╝   ╚═════╝ ╚═╝  ╚═╝╚═╝                
  

🚀 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)

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)

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)

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

🎮 Usage

Interactive mode

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

Direct mode

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):

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):

{
  "mcpServers": {
    "voxi": {
      "command": "python",
      "args": ["-m", "voxi_transcriber.mcp_server"]
    }
  }
}

Step 3 — Restart Claude Desktop. Done! 🎉

Two tools are exposed to the AI:

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

💸 vs Cloud APIs

🛠 Commands

⚙️ Configuration

Edit voxi_transcriber/config.py:

🌐 Platform Support

❓ FAQ

pip install faster-whisper

yt-dlp --cookies-from-browser firefox --cookies cookies.txt "https://www.instagram.com/"

sudo apt install ffmpeg  # Ubuntu/Debian
brew install ffmpeg      # macOS

📁 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 © 2026 royalashu4u