whisper-windows-mcp 1.1.0 → 1.4.0

package/FUNDING.yml

@@ -0,0 +1,3 @@
+github: eviscerations
+ko_fi: 
+patreon: 

package/README.md

@@ -1,9 +1,9 @@
 # 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/ggerganov/whisper.cpp) — no internet connection required, no data sent to the cloud.
+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 local transcription functionality in Claude Desktop.
+> 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.
 
 ---
 
@@ -12,8 +12,9 @@ A Windows-native MCP (Model Context Protocol) server that lets Claude Desktop tr
 Once installed, you can say things like this directly in Claude Desktop:
 
 - *"Transcribe C:\Users\Me\Downloads\meeting.mp3"*
-- *"Transcribe this recording and summarise the key points"*
+- *"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.
 
@@ -21,61 +22,93 @@ Everything runs on your own machine. No audio ever leaves your computer.
 
 ## Requirements
 
-You need the following installed before proceeding. Each one is free.
+Before installing this package, you need three things set up on your Windows machine:
 
-| Requirement | Purpose |
-|---|---|
-| [Node.js 18+](https://nodejs.org/en/download) | Runs the MCP server |
-| [whisper.cpp](https://github.com/ggerganov/whisper.cpp/releases/latest) | The transcription engine |
-| A Whisper model file | The AI model (downloaded in Step 2) |
+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
+## 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):
 
-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
+**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).
 
-✅ You should now have **`C:\whisper\Release\whisper-cli.exe`**
+```
+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\`.
 
-> **Why this path?** You can install whisper.cpp anywhere, but `C:\whisper\Release\` matches the default config below and means less to edit later.
+> **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
 
-The model is the AI that does the actual transcription. Click a link below to download directly:
+Models are downloaded from Hugging Face. Choose one based on your needs:
 
-| Model | Download | Size | Speed | Best for |
+| Model | File size | Speed | Accuracy | Recommended 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 |
+| `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 |
 
-Save the downloaded `.bin` file to **`C:\whisper\models\`** — create this folder if it doesn't exist.
+**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.
 
-✅ You should now have something like **`C:\whisper\models\ggml-base.en.bin`**
+Download your chosen model from:
 
----
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin
+```
 
-## Step 3 — Install Node.js
+Save it to `C:\whisper\models\` — create that folder if it doesn't exist.
 
-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
+## Step 3 — Install this MCP server
 
-✅ To verify, open Command Prompt and run `node --version` — you should see something like `v20.x.x`
+```
+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 → **Settings → Developer → Edit Config**
-2. Add the following (or merge the `mcpServers` block if you already have other servers):
+1. Open Claude Desktop
+2. Go to **Settings → Developer → Edit Config**
+3. Add the whisper-windows-mcp entry:
 
 ```json
 {
@@ -92,11 +125,10 @@ If you don't already have Node.js:
 }
 ```
 
-> ⚠️ **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.
+> **Important:** If your `claude_desktop_config.json` already has other content, add the `"mcpServers"` block inside the existing `{}` — don't replace the whole file.
 
-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
+4. Save the file and fully restart Claude Desktop.
+5. Go to **Settings → Developer** — you should see **whisper** listed with a green **running** badge.
 
 ---
 
@@ -106,65 +138,40 @@ In Claude Desktop, type:
 
 > *"Can you check your whisper config?"*
 
-Claude will verify that `whisper-cli.exe` and your model file are both found. Then try:
+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"*
 
 ---
 
-## Converting video files to audio
-
-Whisper processes audio. If you have a video file (MP4, MKV, etc.) you may want to extract the audio first — audio-only files are much smaller and faster to process.
+## GPU acceleration
 
-> **Tip:** whisper.cpp may handle MP4 files directly if FFmpeg is installed. Try transcribing an MP4 first before converting.
+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.
 
-**Using VLC Media Player** (free, recommended for beginners):
+**Confirmed working:** AMD Radeon RX Vega 56 (GCN 5th gen), and any GPU with Vulkan 1.0+ support.
 
-1. Download [VLC](https://www.videolan.org/vlc/) if you don't have it
-2. Open VLC → **Media → Convert / Save**
-3. Click **Add**, select your video, then click **Convert / Save**
-4. Under **Profile**, choose **Audio - MP3**
-5. Set a destination filename and click **Start**
+**Performance comparison with medium.en model:**
 
-A 1-hour MP4 that might be 2–4 GB typically becomes a 50–100 MB MP3.
+| Hardware | ~5 min audio file |
+|---|---|
+| CPU only (Ryzen 7 2700x) | ~8–12 minutes |
+| GPU (Vega 56 via Vulkan) | ~20–40 seconds |
 
-**Using FFmpeg** (command line, for advanced users):
-```
-ffmpeg -i "C:\path\to\video.mp4" -vn -ac 1 -ar 16000 "C:\path\to\output.wav"
-```
+GPU utilization during transcription is typically 15–30% — efficient bursts, not sustained load.
 
 ---
 
 ## 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"* |
-
----
-
-## 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 |
-
-> **GPU acceleration** for AMD (ROCm) and NVIDIA (CUDA) on Windows is planned for a future update.
+- **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
 
-If you have other MCP servers already configured:
-
 ```json
 {
   "preferences": {
@@ -176,26 +183,25 @@ If you have other MCP servers already configured:
       "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_MODEL": "C:\\whisper\\models\\ggml-medium.en.bin"
       }
     }
   }
 }
 ```
 
-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**
+Config file location: `C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json`
 
 ---
 
-## Tested on
+## Optional environment variables
 
-- Windows 10 Pro (10.0.19045)
-- Windows 11 — untested, feedback welcome via [Issues](../../issues)
+| 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 |
 
 ---
 
@@ -204,23 +210,11 @@ C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
 See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions.
 
 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
-
----
-
-## Roadmap
-
-- [ ] SRT subtitle output
-- [ ] Direct MP4/video file support via FFmpeg
-- [ ] Translation to English from other languages
-- [ ] AMD GPU acceleration (ROCm)
-- [ ] NVIDIA GPU acceleration (CUDA)
-- [ ] Speaker diarization (automatic speaker identification)
+- 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
 
 ---
 
@@ -232,4 +226,4 @@ MIT — free to use, modify, and distribute.
 
 ## Contributing
 
-Pull requests welcome. GPU acceleration solutions for AMD or NVIDIA especially appreciated. Windows 11 feedback welcome via Issues.
+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.