# Local Faster-Whisper MCP Server

A high-performance, fully local Model Context Protocol (MCP) server powered by **faster-whisper** (CTranslate2 INT8 engine) and **yt-dlp**. Built specifically for content creators, YouTube strategists, and autonomous AI agents, it transcribes local audio/video files, automatically downloads and transcribes YouTube competitor URLs, generates production-ready subtitles (SRT / WebVTT), and audits script pacing and audience retention risk.

## 🚀 Key Features

1. **whisper_transcribe_file**
   - Transcribes any local video or audio format (`.mp4`, `.mp3`, `.wav`, `.m4a`, `.mkv`, etc.).
   - Optimized for CPU execution using CTranslate2 INT8 quantization (fast inference with minimal memory footprint).
   - Supports all standard Whisper models (`tiny`, `base`, `small`, `medium`, `large-v3`).
   - Word-level timestamps, automatic language detection, and segment-level probability scores.

2. **whisper_generate_subtitles**
   - Automatically exports formatted subtitles in **SRT** or **WebVTT** (`.vtt`) format.
   - Saves subtitle files alongside media files or returns the raw formatted string.
   - Ideal for automating video editing workflows, Premiere Pro / DaVinci Resolve caption imports, or web video players.

3. **whisper_analyze_retention_pacing**
   - Analyzes spoken pacing and cadence for YouTube audience retention optimization.
   - Computes:
     - **Words Per Minute (WPM):** Classifies speech rate (Slow, Optimal, Fast, Rushed).
     - **Dead Air & Long Pauses:** Detects silence gaps longer than a customizable threshold (default: 1.5s) that risk audience drop-off.
     - **Active Speech Ratio:** Percentage of total video runtime occupied by active voice.
     - **Actionable Script Recommendations:** Concrete feedback to improve hook speed, pacing, and retention.

4. **whisper_transcribe_youtube_url**
   - Accepts any public YouTube URL (`youtube.com/watch?v=...` or `youtu.be/...`).
   - Automatically downloads the highest-quality audio stream in the background using `yt-dlp`.
   - Transcribes content and provides both full text, segment breakdown, and spoken pacing analysis.
   - Automatically cleans up temporary media files to preserve disk space.

## 🛠️ Architecture & Tech Stack

- **Speech-to-Text Engine:** [faster-whisper](https://github.com/SYSTRAN/faster-whisper) with CTranslate2.
- **Quantization:** `int8` on CPU (or `float16` on CUDA if GPU is available).
- **Audio Extraction & FFmpeg:** Integrated statically via `imageio-ffmpeg` (zero PATH configuration needed on Windows).
- **YouTube Ingestion:** `yt-dlp`.
- **MCP Framework:** FastMCP (Python Model Context Protocol SDK).
- **100% Local & Private:** No audio leaves your machine. Zero cloud API costs.

## 📦 Installation & Setup

### Prerequisites
- Python 3.10+ (Python 3.12 recommended)
- Windows / Linux / macOS

### Installation

```bash
# Clone the repository
git clone https://github.com/ramedina-ia/faster-whisper-mcp.git
cd faster-whisper-mcp

# Install dependencies
pip install -r requirements.txt

# Run automated tests
python test/test_whisper.py

# Run MCP server
python -m src.server
```

### Antigravity & Claude Desktop Configuration

Add to your `mcp_config.json`:

```json
{
  "mcpServers": {
    "faster-whisper-mcp": {
      "command": "cmd.exe",
      "args": ["/c", "path\\to\\faster-whisper-mcp\\run.cmd"]
    }
  }
}
```

## 📄 License

MIT License. Developed by Ramiro Medina.