whisper-windows-mcp 1.3.0 → 1.4.0

package/README.md

@@ -1,290 +1,229 @@
-# whisper-windows-mcp
-
-A Windows-native MCP (Model Context Protocol) server that lets Claude Desktop transcribe audio and video files locally using [whisper.cpp](https://github.com/ggerganov/whisper.cpp) — no internet connection required, no data sent to the cloud.
-
-> **Why does this exist?**
-> The popular `whisper-mcp` package was built for macOS and assumes a Unix environment. It does not work on Windows. This package was written specifically for Windows users who want the same local transcription functionality in Claude Desktop.
-
----
-
-## What you can do with it
-
-Once installed, you can say things like this directly in Claude Desktop:
-
-- *"Transcribe C:\Users\Me\Downloads\meeting.mp3"*
-- *"Transcribe C:\Users\Me\Videos\interview.mp4"* — video files work directly, no conversion needed
-- *"Transcribe this recording and summarise the key points"*
-- *"Transcribe with timestamps so I can find specific moments"*
-- *"Generate subtitles for C:\Users\Me\Videos\lecture.mp4"*
-- *"Transcribe all files in C:\Users\Me\Videos\clips\ one at a time"*
-
-Everything runs on your own machine. No audio ever leaves your computer.
-
----
-
-## Requirements
-
-| Requirement | Purpose | Download |
-|---|---|---|
-| Node.js 18+ | Runs the MCP server | [nodejs.org](https://nodejs.org/en/download) |
-| whisper.cpp | The transcription engine | [Latest release](https://github.com/ggerganov/whisper.cpp/releases/latest) |
-| A Whisper model file | The AI model | See Step 2 below |
-| FFmpeg | Video file support | [ffmpeg.org](https://ffmpeg.org/download.html) |
-
-> FFmpeg is optional if you only use MP3/WAV files, but required for MP4, MKV, AVI, MOV and other video formats.
-
----
-
-## Step 1 — Install whisper.cpp
-
-1. Go to the [whisper.cpp latest release](https://github.com/ggerganov/whisper.cpp/releases/latest)
-2. Download the file named **`whisper-bin-x64.zip`** (look for `win` and `x64` in the filename)
-3. Extract the ZIP and move the contents to **`C:\whisper\Release\`** — create this folder if it doesn't exist
-
-✅ You should now have **`C:\whisper\Release\whisper-cli.exe`**
-
-> **Why this path?** You can install whisper.cpp anywhere, but `C:\whisper\Release\` matches the default config below and means less to edit later.
-
----
-
-## Step 2 — Download a Whisper model
-
-Click a link below to download directly:
-
-| Model | Download | Size | Speed | Best for |
-|---|---|---|---|---|
-| tiny.en | [Download](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin) | 75 MB | Very fast | Quick tests |
-| **base.en** | [**Download**](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin) | 142 MB | Fast | **Recommended starting point** |
-| small.en | [Download](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin) | 466 MB | Moderate | Better accuracy |
-| medium.en | [Download](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.en.bin) | 1.5 GB | Slow | High accuracy |
-| large-v3 | [Download](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin) | 2.9 GB | Very slow | Maximum accuracy |
-
-Save the downloaded `.bin` file to **`C:\whisper\models\`** — create this folder if it doesn't exist.
-
-✅ You should now have something like **`C:\whisper\models\ggml-base.en.bin`**
-
----
-
-## Step 3 — Install Node.js
-
-If you don't already have Node.js:
-
-1. Go to [nodejs.org](https://nodejs.org/en/download) and download the **Windows Installer (.msi)** — choose the LTS version
-2. Run the installer and accept all defaults
-
-✅ Verify: open Command Prompt and run `node --version` — you should see something like `v20.x.x`
-
----
-
-## Step 4 — Install FFmpeg (recommended)
-
-FFmpeg is required for video files (MP4, MKV, AVI, MOV, etc.).
-
-1. Go to [ffmpeg.org/download.html](https://ffmpeg.org/download.html) and download a Windows build
-2. Extract and move the `bin` folder contents (or the whole folder) somewhere permanent, e.g. `C:\ffmpeg\bin\`
-3. Add `C:\ffmpeg\bin` to your system PATH:
-   - Press **Win + S** → search **Environment Variables** → open it
-   - Under **User Variables**, select **Path** → **Edit** → **New**
-   - Add `C:\ffmpeg\bin` → click OK on all dialogs
-
-✅ Verify: open a new Command Prompt and run `ffmpeg -version`
-
----
-
-## Step 5 — Configure Claude Desktop
-
-1. Open Claude Desktop → **Settings → Developer → Edit Config**
-2. Add the following (or merge the `mcpServers` block if you have other servers):
-
-```json
-{
-  "mcpServers": {
-    "whisper": {
-      "command": "npx",
-      "args": ["-y", "whisper-windows-mcp"],
-      "env": {
-        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
-        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-base.en.bin"
-      }
-    }
-  }
-}
-```
-
-> ⚠️ **Path format:** In the JSON config, all backslashes must be doubled (`\\`). This is a JSON requirement. When typing paths into Claude in chat, use normal single backslashes.
-
-3. If you downloaded a different model, update `ggml-base.en.bin` to match your filename
-4. Save the file, fully quit Claude Desktop, and reopen it
-5. Go to **Settings → Developer** — you should see **whisper** with a green **running** badge
-
----
-
-## Step 6 — Test it
-
-In Claude Desktop, type:
-
-> *"Can you check your whisper config?"*
-
-Claude will verify that everything is found correctly. Then try:
-
-> *"Please transcribe C:\Users\YourName\Downloads\recording.mp3"*
-
----
-
-## Available tools
-
-| Tool | What it does |
-|---|---|
-| `transcribe_audio` | Transcribe a single file — audio or video |
-| `transcribe_batch` | Transcribe all files in a folder, one at a time with preview |
-| `generate_subtitles` | Generate an `.srt` subtitle file next to the source |
-| `check_config` | Verify all paths and FFmpeg are working |
-
----
-
-## Output formats
-
-| Format | What you get | Ask Claude... |
-|---|---|---|
-| `text` (default) | Plain transcript, no timestamps | *"Transcribe this file"* |
-| `timestamps` | Transcript with `[00:00:00 --> 00:00:05]` time codes | *"Transcribe with timestamps"* |
-| `json` | Structured data | *"Transcribe as JSON"* |
-| `srt` | Subtitle file saved next to source | *"Generate subtitles for..."* |
-
----
-
-## Supported file formats
-
-**Audio (native):** MP3, WAV
-
-**Audio (via FFmpeg):** M4A, FLAC, OGG
-
-**Video (via FFmpeg):** MP4, MKV, AVI, MOV, WebM, FLV, WMV, M4V
-
-> H.264 and H.265/HEVC video both work. FFmpeg must be installed and in your PATH for any video or non-MP3 audio format.
-
----
-
-## Batch transcription
-
-To transcribe multiple files in a folder interactively:
-
-> *"Transcribe all files in C:\Users\Me\Videos\clips\"*
-
-Claude will list all detected files (with checkmarks on already-completed ones), then process them one at a time, showing you a preview of each transcript before moving to the next.
-
-**For large unattended overnight batches**, use whisper-cli directly from the command line — see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for the syntax. This is more reliable than running through Claude for very large jobs.
-
----
-
-## Transcription speed
-
-Whisper runs on CPU by default. Rough estimates for a 1-hour recording:
-
-| Model | Approximate time (CPU) |
-|---|---|
-| tiny.en | 5–10 minutes |
-| base.en | 10–20 minutes |
-| small.en | 20–35 minutes |
-| medium.en | 35–60 minutes |
-| large-v3 | 60–120 minutes |
-
-You can increase thread count by adding `"WHISPER_THREADS": "12"` to the `env` block in your config (replace `12` with however many threads you want — up to your CPU's logical core count).
-
-> **GPU acceleration** for AMD (ROCm) and NVIDIA (CUDA) on Windows is planned for a future update.
-
----
-
-## Converting video to audio (optional)
-
-whisper-windows-mcp handles video files automatically via FFmpeg, so manual conversion is no longer required. However, if you want a smaller audio-only file for any reason, VLC makes it easy:
-
-1. Open VLC → **Media → Convert / Save**
-2. Click **Add**, select your video, then **Convert / Save**
-3. Under **Profile**, choose **Audio - MP3**
-4. Set a destination filename and click **Start**
-
----
-
-## Full config example
-
-```json
-{
-  "preferences": {
-    "coworkWebSearchEnabled": true
-  },
-  "mcpServers": {
-    "whisper": {
-      "command": "npx",
-      "args": ["-y", "whisper-windows-mcp"],
-      "env": {
-        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
-        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-base.en.bin",
-        "WHISPER_THREADS": "8",
-        "FFMPEG_PATH": "ffmpeg"
-      }
-    }
-  }
-}
-```
-
-Config file location:
-```
-C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
-```
-
-> The `AppData` folder is hidden by default. To show it: File Explorer → **View → Show → Hidden items**
-
----
-
-## Tested on
-
-- Windows 10 Pro (10.0.19045)
-- Windows 11 — untested, feedback welcome via [Issues](../../issues)
-
----
-
-## Troubleshooting
-
-See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions including how to run large overnight batch jobs from the command line.
-
-Quick checklist:
-
-- [ ] Config paths use **double backslashes** (`C:\\whisper\\...`)
-- [ ] `whisper-cli.exe` exists at the path specified
-- [ ] The model `.bin` file exists at the path specified
-- [ ] Claude Desktop was **fully restarted** after editing the config
-- [ ] Whisper shows **running** in Settings → Developer
-- [ ] FFmpeg is in PATH if using video files
-
----
-
-## Roadmap
-
-- [ ] AMD GPU acceleration (ROCm)
-- [ ] NVIDIA GPU acceleration (CUDA)
-- [ ] Speaker diarization (automatic A/B speaker identification)
-- [ ] Translation to English from other languages
-- [ ] Unattended background batch processing
-
----
-
-## Support this project
-
-If this tool saved you time and you'd like to support continued development:
-
-- ⭐ **Star this repo** — it helps others find it
-- 💬 **Open an issue** if you find a bug or have a feature request
-- 💖 **Sponsor** — [GitHub Sponsors](https://github.com/sponsors/eviscerations) | [Ko-fi](https://ko-fi.com) | [Patreon](https://patreon.com)
-
----
-
-## License
-
-MIT — free to use, modify, and distribute.
-
----
-
-## Contributing
-
-Pull requests welcome. GPU acceleration for AMD or NVIDIA especially appreciated. Windows 11 feedback welcome via Issues.
+# whisper-windows-mcp
+
+A Windows-native MCP (Model Context Protocol) server that lets Claude Desktop transcribe audio files locally using [whisper.cpp](https://github.com/ggml-org/whisper.cpp) — no internet connection required, no data sent to the cloud.
+
+> **Why does this exist?**
+> The popular `whisper-mcp` package was built for macOS and assumes a Unix environment. It does not work on Windows. This package was written specifically for Windows users who want the same functionality.
+
+---
+
+## What you can do with it
+
+Once installed, you can say things like this directly in Claude Desktop:
+
+- *"Transcribe C:\Users\Me\Downloads\meeting.mp3"*
+- *"Transcribe this recording and give me a summary"*
+- *"Transcribe with timestamps so I can find specific moments"*
+- *"Generate subtitles for this video"*
+
+Everything runs on your own machine. No audio ever leaves your computer.
+
+---
+
+## Requirements
+
+Before installing this package, you need three things set up on your Windows machine:
+
+1. **Node.js 18 or later** — [download from nodejs.org](https://nodejs.org)
+2. **whisper.cpp binaries** — the actual transcription engine (see Step 1 below)
+3. **A Whisper model file** — the AI model that does the transcription (see Step 2 below)
+
+---
+
+## Step 1 — Install whisper.cpp binaries
+
+### Option A — Pre-built Vulkan release (recommended)
+
+Download `whisper-vulkan-win-x64.zip` from the [releases page](https://github.com/eviscerations/whisper-windows-mcp/releases).
+
+This is a custom-compiled build with **Vulkan GPU acceleration** enabled. It works with AMD, NVIDIA, and Intel GPUs on Windows — no vendor-specific SDK required.
+
+Extract the zip to `C:\whisper\Release\`. You should end up with these files:
+
+```
+C:\whisper\Release\whisper-cli.exe
+C:\whisper\Release\ggml-vulkan.dll
+C:\whisper\Release\ggml.dll
+C:\whisper\Release\ggml-base.dll
+C:\whisper\Release\ggml-cpu.dll
+C:\whisper\Release\whisper.dll
+```
+
+**GPU acceleration is automatic** — if a supported GPU is present, whisper.cpp will use it. No additional configuration needed.
+
+### Option B — Build from source
+
+If you prefer to compile your own binary (advanced users):
+
+**Prerequisites:** Git, CMake, Visual Studio Build Tools 2022+ with "Desktop development with C++", Vulkan SDK from [lunarg.com](https://vulkan.lunarg.com/sdk/home#windows).
+
+```
+git clone https://github.com/ggml-org/whisper.cpp
+cd whisper.cpp
+cmake -B build -DGGML_VULKAN=ON -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release --target whisper-cli
+```
+
+Copy the resulting binaries from `build\bin\Release\` to `C:\whisper\Release\`.
+
+> **Note:** The default whisper.cpp Windows release on GitHub does not include a Vulkan build. You must either use the pre-built release above or compile from source with `-DGGML_VULKAN=ON`.
+
+---
+
+## Step 2 — Download a Whisper model
+
+Models are downloaded from Hugging Face. Choose one based on your needs:
+
+| Model | File size | Speed | Accuracy | Recommended for |
+|---|---|---|---|---|
+| `ggml-tiny.en.bin` | 75 MB | Very fast | Basic | Quick tests |
+| `ggml-base.en.bin` | 142 MB | Fast | Good | Everyday use |
+| `ggml-small.en.bin` | 466 MB | Moderate | Better | Important recordings |
+| `ggml-medium.en.bin` | 1.5 GB | Fast on GPU | Very good | Best quality |
+| `ggml-large-v3.bin` | 2.9 GB | Fast on GPU | Excellent | Maximum accuracy |
+
+**For most people, `base.en` or `small.en` is the best starting point.** With GPU acceleration, `medium.en` and `large-v3` become practical for everyday use.
+
+Download your chosen model from:
+
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin
+```
+
+Save it to `C:\whisper\models\` — create that folder if it doesn't exist.
+
+---
+
+## Step 3 — Install this MCP server
+
+```
+npm install -g whisper-windows-mcp
+```
+
+Or use `npx` directly in your config (see Step 4).
+
+---
+
+## Step 4 — Configure Claude Desktop
+
+1. Open Claude Desktop
+2. Go to **Settings → Developer → Edit Config**
+3. Add the whisper-windows-mcp entry:
+
+```json
+{
+  "mcpServers": {
+    "whisper": {
+      "command": "npx",
+      "args": ["-y", "whisper-windows-mcp"],
+      "env": {
+        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
+        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-base.en.bin"
+      }
+    }
+  }
+}
+```
+
+> **Important:** If your `claude_desktop_config.json` already has other content, add the `"mcpServers"` block inside the existing `{}` — don't replace the whole file.
+
+4. Save the file and fully restart Claude Desktop.
+5. Go to **Settings → Developer** — you should see **whisper** listed with a green **running** badge.
+
+---
+
+## Step 5 — Test it
+
+In Claude Desktop, type:
+
+> *"Can you check your whisper config?"*
+
+Claude will use the `check_config` tool to verify everything is set up correctly. Then try a transcription:
+
+> *"Please transcribe C:\Users\YourName\Downloads\recording.mp3"*
+
+---
+
+## GPU acceleration
+
+The pre-built Vulkan release enables GPU acceleration automatically. No flags or configuration required — whisper.cpp detects your GPU at startup and uses it if available.
+
+**Confirmed working:** AMD Radeon RX Vega 56 (GCN 5th gen), and any GPU with Vulkan 1.0+ support.
+
+**Performance comparison with medium.en model:**
+
+| Hardware | ~5 min audio file |
+|---|---|
+| CPU only (Ryzen 7 2700x) | ~8–12 minutes |
+| GPU (Vega 56 via Vulkan) | ~20–40 seconds |
+
+GPU utilization during transcription is typically 15–30% — efficient bursts, not sustained load.
+
+---
+
+## Output formats
+
+- **text** (default) — plain transcript
+- **timestamps** — transcript with `[00:00:00 --> 00:00:05]` time codes
+- **json** — structured output
+- **srt** — subtitle file saved next to the source file
+
+---
+
+## Full config example
+
+```json
+{
+  "preferences": {
+    "coworkWebSearchEnabled": true
+  },
+  "mcpServers": {
+    "whisper": {
+      "command": "npx",
+      "args": ["-y", "whisper-windows-mcp"],
+      "env": {
+        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
+        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-medium.en.bin"
+      }
+    }
+  }
+}
+```
+
+Config file location: `C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json`
+
+---
+
+## Optional environment variables
+
+| Variable | Description |
+|---|---|
+| `WHISPER_CLI_PATH` | Path to whisper-cli.exe (required) |
+| `WHISPER_MODEL` | Path to model .bin file (required) |
+| `WHISPER_THREADS` | CPU thread count override |
+| `FFMPEG_PATH` | Path to ffmpeg if not in system PATH |
+
+---
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions.
+
+Quick checklist:
+- Paths in config use **double backslashes** (`C:\\whisper\\...`)
+- `whisper-cli.exe` exists at the path specified
+- The model `.bin` file exists at the path specified
+- Claude Desktop was fully restarted after editing config
+- The whisper server shows **running** in Settings → Developer
+
+---
+
+## License
+
+MIT — free to use, modify, and distribute.
+
+---
+
+## Contributing
+
+Pull requests welcome. See [ROADMAP.md](ROADMAP.md) for planned features.

package/ROADMAP.md

@@ -0,0 +1,129 @@
+# whisper-windows-mcp — Roadmap
+
+Current version is v1.4.0. GPU acceleration via Vulkan is now working. This document tracks what has been completed and what remains.
+
+---
+
+## Completed
+
+### ✅ Priority 1 — GPU Acceleration (v1.4.0)
+
+Compiled whisper.cpp from source with `-DGGML_VULKAN=ON` using Visual Studio Build Tools 2026 and Vulkan SDK 1.4.341.1. Pre-built Vulkan binaries are now distributed as a release asset (`whisper-vulkan-win-x64.zip`).
+
+**Results:** AMD Radeon RX Vega 56 at ~16% GPU utilization, 1.2GB VRAM, CPU at ~15% during transcription. A ~5 minute file that previously took 8–12 minutes on CPU now completes in 20–40 seconds.
+
+The official whisper.cpp Windows releases do not include a Vulkan build ([issue #3673](https://github.com/ggml-org/whisper.cpp/issues/3673)). The pre-built release in this repo fills that gap for AMD and Intel GPU users.
+
+### ✅ Priority 2 — Process Lock (v1.3.1)
+
+Added `isWhisperRunning()` check using `tasklist /FI` before any transcription spawn. If `whisper-cli.exe` is already running, returns a clear error with Task Manager instructions rather than spawning a second competing process.
+
+---
+
+## Known Issues (Remaining)
+
+### 3. 4-Minute Claude MCP Timeout
+The Claude web client cuts MCP connections after ~4 minutes. Whisper continues running in the background after the timeout fires, but Claude can't confirm completion. With GPU acceleration this is less frequently hit, but still a concern for very long files or large models.
+
+### 5. No Progress Visibility
+The user has no indicator that transcription is happening or how far along it is. whisper-cli.exe outputs segment timestamps to stderr as it processes — the MCP should pipe and expose these.
+
+### 6. Background Batch Non-Functional
+A background batch mode was attempted in a previous version but stripped due to no visible feedback. Needs a proper detached process architecture with job state files.
+
+### 7. No File Pre-Analysis
+No way to know file duration or size before processing starts.
+
+---
+
+## Roadmap
+
+### Priority 3 — File Pre-Analysis Tool
+
+New tool `analyze_media` using FFprobe:
+
+```
+ffprobe -v quiet -print_format json -show_format -show_streams <file>
+```
+
+Returns: duration, file size, codec, bitrate, estimated transcription time (CPU and GPU).
+
+---
+
+### Priority 4 — Progress Visibility
+
+whisper-cli.exe outputs segment timestamps to stderr (e.g. `[00:01:30 --> 00:01:35]`). The MCP should:
+
+1. Pipe stderr to a log file during processing
+2. Expose a `check_progress` tool returning last timestamp, percentage complete, estimated time remaining, and whether the process is still running
+
+---
+
+### Priority 5 — Timeout Workaround (Detached Process Architecture)
+
+Rearchitect transcription to use fully detached background processes:
+
+1. `transcribe_audio` → spawn whisper as detached process → write `job.json` → return immediately with job ID
+2. `check_progress` → read `job.json` → check PID → read log → return status + percentage
+3. When complete → read and return transcript
+
+This eliminates the 4-minute timeout problem entirely and unlocks Priority 6.
+
+---
+
+### Priority 6 — Sequential Batch with Validation
+
+Rebuild batch mode on top of Priority 5:
+
+1. `transcribe_batch` → runs `analyze_media` on folder → sorts by duration → processes one file at a time using detached process
+2. After each file: validate .txt exists, is non-empty, line count proportional to duration
+3. Flag suspect outputs for re-run
+4. `check_batch_progress` returns: files done, remaining, current file, ETA, any failed files
+
+---
+
+### Priority 7 — Multi-Language Support and Translation
+
+Expose `--language` and `--translate` flags properly:
+
+- `language` parameter: auto-detect (default) or specify (`ja`, `es`, `de`, etc.)
+- `translate_to_english`: boolean — uses whisper's built-in translation model
+- Dual output: two whisper passes, two output files
+
+---
+
+### Priority 8 — Filename-Based References Throughout
+
+All tool outputs must reference the full source filename at all times. Never use positional indices as the primary identifier.
+
+---
+
+### Priority 9 — System Diagnostics Tool
+
+New tool `check_system`:
+
+- GPU vendor and model (via `wmic path win32_VideoController`)
+- Whether `ggml-vulkan.dll` is present alongside `whisper-cli.exe`
+- Recommended model size for available VRAM
+- Estimated throughput based on hardware profile
+- Actionable guidance if GPU binary is missing
+
+---
+
+## Design Principles
+
+**Minimize Claude API usage.** The entire transcription workflow should require fewer than 20 Claude interactions for a 60-file batch.
+
+**One whisper instance at all times.** Never spawn a second process while one is running.
+
+**Local-first, private by default.** No audio leaves the machine. No cloud APIs required.
+
+**Works for free-tier users.** Courtroom transcription, documentary research, foreign film subtitling — the tool should serve people who can't afford cloud transcription services.
+
+---
+
+## Contributing
+
+Pull requests welcome for any of the above priorities. Check existing issues before starting work.
+
+If you've tested GPU acceleration on hardware not listed above, please open an issue with your results — GPU model, VRAM, model size, and observed throughput.