whisper-windows-mcp 1.7.0 → 1.9.0

package/README.md

@@ -1,229 +1,338 @@
-# 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.
+# 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/ggml-org/whisper.cpp) — with GPU acceleration, multilingual support, and batch processing. No internet connection required. No audio ever leaves your machine.
+
+> **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 local AI transcription integrated with 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 this folder of recordings and save each as a text file"*
+- *"Generate Japanese and English subtitles for this video"*
+- *"Start a batch transcription of everything in this folder"*
+- *"How long will it take to transcribe these files?"*
+- *"Check if GPU acceleration is working"*
+
+---
+
+## Requirements
+
+1. **Node.js 18 or later** — [nodejs.org](https://nodejs.org)
+2. **whisper.cpp binaries with Vulkan GPU support** — see Step 1
+3. **A Whisper model file** — see Step 2
+4. **FFmpeg** — required for video files and non-WAV/MP3 audio
+
+---
+
+## 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/tag/v1.4.0).
+
+This is a custom-compiled build with **Vulkan GPU acceleration** enabled. Works with AMD, NVIDIA, and Intel GPUs — no vendor-specific SDK required.
+
+Extract to `C:\whisper\Release\`. You should end up with:
+
+```
+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 — no additional configuration needed.
+
+### Option B — Build from source
+
+Requires: 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 binaries from `build\bin\Release\` to `C:\whisper\Release\`.
+
+> **Note:** The official whisper.cpp Windows releases on GitHub do not include a Vulkan build. You must use the pre-built release above or compile from source with `-DGGML_VULKAN=ON`.
+
+---
+
+## Step 2 — Download a Whisper model
+
+| Model | Size | Speed | Accuracy | Best for |
+|---|---|---|---|---|
+| `ggml-tiny.en.bin` | 75 MB | Very fast | Basic | Quick tests |
+| `ggml-base.en.bin` | 142 MB | Fast | Good | Everyday English |
+| `ggml-small.en.bin` | 466 MB | Moderate | Better | Important recordings |
+| `ggml-medium.en.bin` | 1.5 GB | Fast on GPU | Very good | Best quality English |
+| `ggml-large-v3.bin` | 2.9 GB | Fast on GPU | Excellent | Multilingual, best accuracy |
+
+For **English-only** use: `base.en` or `medium.en` are the best starting points.
+For **multilingual** use (auto-detect, foreign language, translation): use `large-v3` for best results.
+
+Download from Hugging Face:
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.en.bin
+```
+
+Save to `C:\whisper\models\`.
+
+---
+
+## Step 3 — Install FFmpeg
+
+FFmpeg is required for video files and non-native audio formats.
+
+Install via winget:
+```
+winget install ffmpeg
+```
+
+Or download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to your PATH.
+
+Verify:
+```
+ffmpeg -version
+```
+
+---
+
+## Step 4 — Install this MCP server
+
+```
+npm install -g whisper-windows-mcp
+```
+
+---
+
+## Step 5 — Configure Claude Desktop
+
+Open Claude Desktop → Settings → Developer → Edit Config.
+
+Add the `whisper` 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-medium.en.bin"
+      }
+    }
+  }
+}
+```
+
+Config file location: `C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json`
+
+> Use **double backslashes** in all paths.
+
+Save and **fully restart** Claude Desktop. You should see **whisper** listed with a green running badge in Settings → Developer.
+
+---
+
+## Step 6 — Verify your setup
+
+In Claude Desktop, ask:
+
+> *"Check your whisper config"*
+
+Then:
+
+> *"Check your system hardware"*
+
+This confirms your GPU is detected and Vulkan acceleration is active.
+
+---
+
+## Available tools
+
+### `transcribe_audio`
+Transcribe a single file. Supports blocking (default) or background mode for long files.
+
+| Parameter | Description |
+|---|---|
+| `file_path` | Absolute path to the file (required) |
+| `language` | Language code (`en`, `ja`, `es`, etc.) or `auto` to detect. Default: `en` |
+| `output_format` | `text` (default), `timestamps`, `json`, or `srt` |
+| `save_to_file` | Save transcript as .txt next to the source file |
+| `background` | Run as detached job — returns a job ID immediately. Use `check_progress` to monitor. Recommended for files over 10 minutes. |
+| `threads` | CPU thread override |
+
+---
+
+### `check_progress`
+Monitor a background transcription job started with `transcribe_audio` (background=true).
+
+Returns elapsed time, last processed timestamp, percentage, and the full transcript when complete.
+
+| Parameter | Description |
+|---|---|
+| `job_id` | Job ID returned by `transcribe_audio` |
+
+---
+
+### `start_batch`
+Automated sequential batch transcription of all untranscribed files in a folder. Sorts by duration (shortest first), processes one at a time as background jobs, validates each output.
+
+| Parameter | Description |
+|---|---|
+| `folder_path` | Path to folder (required) |
+| `language` | Language code. Default: `en` |
+| `threads` | CPU thread override |
+
+---
+
+### `check_batch_progress`
+Monitor a running batch. Automatically advances to the next file when the current one finishes. Returns overall progress, current file with timestamp, ETA, and any failed files.
+
+| Parameter | Description |
+|---|---|
+| `batch_id` | Batch ID returned by `start_batch` |
+
+---
+
+### `transcribe_batch` (interactive)
+Process files one at a time with a preview and confirmation before each. Useful when you want to review as you go.
+
+| Parameter | Description |
+|---|---|
+| `folder_path` | Path to folder (required) |
+| `file_index` | Which file to process (1-based). Omit to list files first. |
+| `language` | Language code. Default: `en` |
+| `recursive` | Include subfolders |
+
+---
+
+### `generate_subtitles`
+Generate SRT subtitle files. Supports automatic language detection and English translation output.
+
+| Parameter | Description |
+|---|---|
+| `file_path` | Path to file (required) |
+| `language` | Language code or `auto` to detect. Default: `en` |
+| `translate_to_english` | Also generate an English translation `.en.srt`. Only applies when source is not English. |
+| `threads` | CPU thread override |
+
+When both native and translation are requested, two files are saved next to the source:
+- `filename.ja.srt` — original language
+- `filename.en.srt` — English translation
+
+> Whisper's built-in translation only translates **to English**. For other target languages, translate the .srt file contents separately.
+
+---
+
+### `analyze_media`
+Analyze files before committing to transcription. Returns duration, size, codec, and estimated transcription time on CPU and GPU. For folders, shows all files in a sortable table with transcription status.
+
+| Parameter | Description |
+|---|---|
+| `path` | Path to a single file or folder (required) |
+| `sort_by` | For folders: `duration` (default), `name`, or `size` |
+
+---
+
+### `check_config`
+Verify whisper-cli.exe, the model file, and FFmpeg are all accessible. Run this first if anything is failing.
+
+---
+
+### `check_system`
+Detect GPU hardware and verify Vulkan acceleration is available. Reports GPU name, VRAM, whether `ggml-vulkan.dll` is present, and recommends the best model size for your hardware.
+
+---
+
+## Supported formats
+
+| Type | Formats |
+|---|---|
+| Native (no conversion) | `mp3`, `wav` |
+| Video (auto-converted via FFmpeg) | `mp4`, `mkv`, `avi`, `mov`, `webm`, `flv`, `wmv`, `m4v`, `ts`, `3gp` |
+| Audio (auto-converted via FFmpeg) | `m4a`, `ogg`, `flac` |
+
+---
+
+## GPU acceleration
+
+The pre-built Vulkan release enables GPU acceleration automatically. Tested on AMD Radeon RX Vega 56 (GCN 5th gen). Any GPU with Vulkan 1.0+ support should work, including NVIDIA and Intel Arc.
+
+**Performance comparison (medium.en model, ~5 minute audio file):**
+
+| Hardware | Time |
+|---|---|
+| CPU only (Ryzen 7 2700x, 8 threads) | 8–12 minutes |
+| GPU (Vega 56 via Vulkan) | 20–40 seconds |
+
+GPU utilization during transcription is typically 15–20%, dropping back to idle between files. CPU stays around 15%.
+
+---
+
+## Multilingual support
+
+Whisper can auto-detect the spoken language and transcribe in that language. The built-in translation model translates **to English only**.
+
+For best multilingual accuracy, use the `large-v3` model. English-specific models (`*.en.bin`) cannot detect or transcribe other languages.
+
+**Example — foreign language video with subtitles:**
+1. Ask Claude to generate subtitles with `language=auto` and `translate_to_english=true`
+2. Whisper detects the language and generates a native-language SRT
+3. A second pass generates an English translation SRT
+4. Load either file in VLC via Subtitle → Add Subtitle File
+
+---
+
+## Designed for free-tier users
+
+This tool is built to minimize Claude API interactions. The entire transcription workflow — scan, analyze, queue, run, validate — is designed to require as few Claude interactions as possible. Heavy lifting is done locally on your machine.
+
+---
+
+## 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 configured path
+- Model `.bin` file exists at the configured path
+- FFmpeg is installed and in PATH (`ffmpeg -version` works)
+- Claude Desktop was fully restarted after editing config
+- Whisper shows **running** in Settings → Developer
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+Pull requests welcome. See [ROADMAP.md](ROADMAP.md) for planned features.
+
+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.

package/dist/index.js

@@ -25,7 +25,7 @@ const WHISPER_THREADS = parseInt(process.env.WHISPER_THREADS ?? String(DEFAULT_T
 const SUPPORTED_EXTENSIONS = [
     ".mp3", ".wav",
     ".mp4", ".mkv", ".avi", ".mov", ".webm", ".flv", ".wmv", ".m4v",
-    ".m4a", ".ogg", ".flac",
+    ".m4a", ".ogg", ".flac", ".3gp", ".ts",
 ];
 const NATIVE_EXTENSIONS = [".mp3", ".wav"];
 // ---------------------------------------------------------------------------
@@ -186,6 +186,123 @@ async function readJobProgress(jobId) {
         `${progressLine}\n\n` +
         `Call check_progress with this job ID to get an update.`);
 }
+function validateTranscript(txtPath, durationSec) {
+    if (!existsSync(txtPath))
+        return { valid: false, reason: "output file missing" };
+    const content = readFileSync(txtPath, "utf8").trim();
+    if (!content)
+        return { valid: false, reason: "output file is empty" };
+    const lines = content.split(/\n/).filter(l => l.trim()).length;
+    const minExpected = Math.max(1, Math.floor(durationSec / 30));
+    if (lines < minExpected) {
+        return { valid: false, reason: `only ${lines} line(s) for ${Math.round(durationSec)}s audio (expected ≥${minExpected})` };
+    }
+    return { valid: true };
+}
+async function spawnNextBatchJob(state) {
+    for (let i = state.currentIndex; i < state.files.length; i++) {
+        if (state.files[i].status === "pending") {
+            state.currentIndex = i;
+            state.files[i].status = "running";
+            const f = state.files[i];
+            const { jobId } = await spawnDetached(f.filePath, state.model, state.language, state.threads);
+            state.files[i].jobId = jobId;
+            writeFileSync(state.batchPath, JSON.stringify(state, null, 2), "utf8");
+            return;
+        }
+    }
+    // Nothing left to run
+    state.status = "complete";
+    writeFileSync(state.batchPath, JSON.stringify(state, null, 2), "utf8");
+}
+async function readBatchProgress(batchId) {
+    const batchPath = join(JOBS_DIR, `${batchId}.batch.json`);
+    if (!existsSync(batchPath)) {
+        return `❌ Batch not found: ${batchId}\n\nThe batch file may have been deleted or the ID is incorrect.`;
+    }
+    const state = JSON.parse(readFileSync(batchPath, "utf8"));
+    // Check current running job
+    const running = state.files.find(f => f.status === "running");
+    if (running && running.jobId) {
+        const jobPath = join(JOBS_DIR, `${running.jobId}.json`);
+        if (existsSync(jobPath)) {
+            const job = JSON.parse(readFileSync(jobPath, "utf8"));
+            const isRunning = await isPidRunning(job.pid);
+            const outputExists = existsSync(job.outputPath);
+            if (!isRunning) {
+                // Job finished — validate and advance
+                const validation = validateTranscript(job.outputPath, running.durationSec);
+                if (outputExists && validation.valid) {
+                    running.status = "complete";
+                }
+                else {
+                    running.status = "failed";
+                    running.failReason = validation.reason ?? "no output file";
+                }
+                // Advance to next
+                state.currentIndex = state.files.indexOf(running) + 1;
+                if (state.files.some(f => f.status === "pending")) {
+                    await spawnNextBatchJob(state);
+                }
+                else {
+                    state.status = "complete";
+                    writeFileSync(batchPath, JSON.stringify(state, null, 2), "utf8");
+                }
+            }
+            else {
+                // Still running — update state file without advancing
+                writeFileSync(batchPath, JSON.stringify(state, null, 2), "utf8");
+            }
+        }
+    }
+    else if (state.status !== "complete" && state.files.some(f => f.status === "pending")) {
+        // No running job but pending files exist — advance
+        await spawnNextBatchJob(state);
+    }
+    // Build status report
+    const done = state.files.filter(f => f.status === "complete").length;
+    const failed = state.files.filter(f => f.status === "failed");
+    const pending = state.files.filter(f => f.status === "pending").length;
+    const currentRunning = state.files.find(f => f.status === "running");
+    const total = state.files.length;
+    const elapsed = Math.round((Date.now() - new Date(state.startTime).getTime()) / 1000);
+    let report = `Batch: ${batchId}\n`;
+    report += `Folder: ${state.folder}\n`;
+    report += `${"─".repeat(50)}\n`;
+    report += `Progress: ${done}/${total} complete`;
+    if (failed.length > 0)
+        report += ` | ${failed.length} failed`;
+    if (pending > 0)
+        report += ` | ${pending} remaining`;
+    report += `\nElapsed: ${formatDuration(elapsed)}\n`;
+    if (currentRunning) {
+        report += `\nCurrently processing: ${currentRunning.fileName}`;
+        if (currentRunning.jobId) {
+            const jobPath = join(JOBS_DIR, `${currentRunning.jobId}.json`);
+            if (existsSync(jobPath)) {
+                const job = JSON.parse(readFileSync(jobPath, "utf8"));
+                const logContent = existsSync(job.logPath) ? readFileSync(job.logPath, "utf8") : "";
+                const lastSec = parseLastTimestamp(logContent);
+                if (lastSec > 0)
+                    report += ` (${formatDuration(lastSec)} / ${formatDuration(currentRunning.durationSec)})`;
+            }
+        }
+    }
+    if (failed.length > 0) {
+        report += `\n\n⚠️  Failed files:\n`;
+        for (const f of failed) {
+            report += `  ❌ ${f.fileName} — ${f.failReason ?? "unknown reason"}\n`;
+        }
+        report += `\nRe-run failed files with transcribe_audio individually.`;
+    }
+    if (state.status === "complete") {
+        report = `✅ Batch complete!\n\n` + report;
+    }
+    else {
+        report += `\n\nCall check_batch_progress again to update.`;
+    }
+    return report;
+}
 async function detectGpus() {
     try {
         const { stdout } = await execFileAsync("wmic", ["path", "win32_VideoController", "get", "name,AdapterRAM", "/format:csv"], { windowsHide: true });
@@ -296,8 +413,11 @@ async function convertToWav(inputPath) {
     ], { windowsHide: true });
     return tmpFile;
 }
-function buildArgs(filePath, model, language, outputFormat, threads) {
-    const args = ["-m", model, "-f", filePath, "-l", language, "-t", String(threads)];
+function buildArgs(filePath, model, language, outputFormat, threads, translate = false) {
+    const lang = language === "auto" ? "auto" : language;
+    const args = ["-m", model, "-f", filePath, "-l", lang, "-t", String(threads)];
+    if (translate)
+        args.push("--translate");
     if (outputFormat === "srt") {
         args.push("-osrt", "-of", filePath.replace(/\.[^.]+$/, ""));
     }
@@ -309,6 +429,49 @@ function buildArgs(filePath, model, language, outputFormat, threads) {
     }
     return args;
 }
+/**
+ * Detect the language of a file by running a short whisper probe.
+ * Runs whisper on the first 30 seconds only (--duration 30000ms).
+ * Returns the detected language code (e.g. "ja", "en") or null on failure.
+ */
+async function detectLanguage(wavPath, model, threads) {
+    try {
+        const { stdout, stderr } = await execFileAsync(WHISPER_CLI_PATH, [
+            "-m", model, "-f", wavPath,
+            "-l", "auto",
+            "-t", String(threads),
+            "--no-timestamps",
+            "--duration", "30000",
+        ], { maxBuffer: 10 * 1024 * 1024, windowsHide: true });
+        const output = stdout + stderr;
+        // whisper outputs: "auto-detected language: ja (p = 0.98)"
+        const m = output.match(/auto-detected language:\s*([a-z]{2,3})/i);
+        return m ? m[1].toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run a single whisper SRT pass and move the output to destSrt.
+ * Returns the destSrt path.
+ */
+async function runSrtPass(transcribeFrom, destSrt, model, language, threads, translate = false) {
+    const args = buildArgs(transcribeFrom, model, language, "srt", threads, translate);
+    await execFileAsync(WHISPER_CLI_PATH, args, {
+        maxBuffer: 100 * 1024 * 1024,
+        windowsHide: true,
+    });
+    const tmpSrt = transcribeFrom.replace(/\.[^.]+$/, ".srt");
+    if (existsSync(tmpSrt)) {
+        writeFileSync(destSrt, readFileSync(tmpSrt, "utf8"));
+        try {
+            unlinkSync(tmpSrt);
+        }
+        catch { }
+    }
+    return destSrt;
+}
 async function transcribeSingle(filePath, model, language, outputFormat, threads, saveToFile = false) {
     // ---- Priority 2: Process lock ----
     // Never spawn a second whisper-cli.exe while one is already running.
@@ -373,7 +536,7 @@ function getFiles(dir, recursive) {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "whisper-windows-mcp", version: "1.7.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "whisper-windows-mcp", version: "1.9.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
@@ -389,7 +552,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 properties: {
                     file_path: { type: "string", description: "Absolute Windows path, e.g. C:\\Users\\You\\Downloads\\recording.mp4" },
                     model: { type: "string", description: "Override model path. Leave blank to use WHISPER_MODEL." },
-                    language: { type: "string", description: "Language code, e.g. en, es, fr. Defaults to en.", default: "en" },
+                    language: { type: "string", description: "Language code (e.g. en, ja, es, fr) or 'auto' to detect automatically. Defaults to en.", default: "en" },
                     output_format: {
                         type: "string", enum: ["text", "timestamps", "json", "srt"],
                         description: "text = plain (default), timestamps = with time codes, json = structured, srt = subtitle file saved next to source.",
@@ -441,14 +604,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "generate_subtitles",
-            description: "Generate an SRT subtitle file for an audio or video file. " +
-                "Saved next to the source file. Load in VLC via Subtitle → Add Subtitle File. " +
-                "Supports all the same formats as transcribe_audio.",
+            description: "Generate subtitle files for an audio or video file using whisper.cpp. " +
+                "Set language='auto' to detect the spoken language automatically. " +
+                "Set translate_to_english=true to also generate an English translation subtitle file. " +
+                "When both are requested, two .srt files are saved: one in the original language (e.g. film.ja.srt) " +
+                "and one English translation (film.en.srt). " +
+                "Load in VLC via Subtitle → Add Subtitle File. " +
+                "Supports all standard formats plus .3gp and .ts.",
             inputSchema: {
                 type: "object",
                 properties: {
                     file_path: { type: "string", description: "Absolute Windows path to the file." },
-                    language: { type: "string", description: "Language code. Defaults to en.", default: "en" },
+                    language: {
+                        type: "string",
+                        description: "Language code (e.g. ja, es, fr, de) or 'auto' to detect automatically. Defaults to en.",
+                        default: "en",
+                    },
+                    translate_to_english: {
+                        type: "boolean",
+                        description: "Also generate an English translation .srt alongside the native language .srt. Only applies when language is not 'en'.",
+                        default: false,
+                    },
                     threads: { type: "number", description: `CPU threads. Defaults to ${WHISPER_THREADS} of ${SYSTEM_THREADS}.` },
                 },
                 required: ["file_path"],
@@ -459,6 +635,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "Verify whisper-cli.exe, model, and FFmpeg are all available. Run this first if anything fails.",
             inputSchema: { type: "object", properties: {} },
         },
+        {
+            name: "start_batch",
+            description: "Start an automated sequential batch transcription of all untranscribed files in a folder. " +
+                "Scans for files without a matching .txt, sorts by duration (shortest first), " +
+                "and processes them one at a time as background jobs. " +
+                "Each file is validated after completion — empty or suspiciously short outputs are flagged. " +
+                "Returns a batch ID to use with check_batch_progress.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    folder_path: { type: "string", description: "Absolute Windows path to the folder." },
+                    language: { type: "string", description: "Language code. Defaults to en.", default: "en" },
+                    threads: { type: "number", description: `CPU threads. Defaults to ${WHISPER_THREADS} of ${SYSTEM_THREADS}.` },
+                },
+                required: ["folder_path"],
+            },
+        },
+        {
+            name: "check_batch_progress",
+            description: "Check the status of a batch started with start_batch. " +
+                "Automatically advances to the next file when the current one finishes. " +
+                "Returns overall progress, current file, failed files, and elapsed time. " +
+                "Call repeatedly until the batch shows as complete.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    batch_id: { type: "string", description: "Batch ID returned by start_batch." },
+                },
+                required: ["batch_id"],
+            },
+        },
         {
             name: "analyze_media",
             description: "Analyze one or more media files using FFprobe before transcribing. " +
@@ -720,11 +927,94 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
     }
     // -------------------------------------------------------------------------
+    // start_batch
+    // -------------------------------------------------------------------------
+    if (name === "start_batch") {
+        const folderPath = args?.folder_path;
+        const language = args?.language || "en";
+        const threads = Math.min(SYSTEM_THREADS, Math.max(1, Math.round(args?.threads || WHISPER_THREADS)));
+        if (!folderPath)
+            return { content: [{ type: "text", text: "folder_path is required." }], isError: true };
+        if (!existsSync(folderPath))
+            return { content: [{ type: "text", text: `Folder not found: ${folderPath}` }], isError: true };
+        const configError = validatePaths();
+        if (configError)
+            return { content: [{ type: "text", text: configError }], isError: true };
+        if (await isWhisperRunning()) {
+            return { content: [{ type: "text", text: "A transcription is already running. Wait for it to finish before starting a batch." }], isError: true };
+        }
+        // Scan for untranscribed files
+        const allFiles = getFiles(folderPath, false);
+        const untranscribed = allFiles.filter(f => !existsSync(f.replace(/\.[^.]+$/, ".txt")));
+        if (untranscribed.length === 0) {
+            return { content: [{ type: "text", text: `✅ All files in ${folderPath} are already transcribed. Nothing to do.` }] };
+        }
+        // Probe durations for sorting
+        const batchFiles = [];
+        for (const f of untranscribed) {
+            const info = await probeFile(f);
+            batchFiles.push({
+                filePath: f,
+                fileName: basename(f),
+                durationSec: info?.durationSec ?? 0,
+                status: "pending",
+            });
+        }
+        batchFiles.sort((a, b) => a.durationSec - b.durationSec);
+        ensureJobsDir();
+        const batchId = `batch_${Date.now()}`;
+        const batchPath = join(JOBS_DIR, `${batchId}.batch.json`);
+        const state = {
+            batchId,
+            batchPath,
+            folder: folderPath,
+            startTime: new Date().toISOString(),
+            files: batchFiles,
+            currentIndex: 0,
+            status: "running",
+            model: WHISPER_MODEL,
+            language,
+            threads,
+        };
+        writeFileSync(batchPath, JSON.stringify(state, null, 2), "utf8");
+        await spawnNextBatchJob(state);
+        const totalDuration = batchFiles.reduce((acc, f) => acc + f.durationSec, 0);
+        return {
+            content: [{
+                    type: "text",
+                    text: `⏳ Batch started!\n\n` +
+                        `Batch ID: ${batchId}\n` +
+                        `Folder: ${folderPath}\n` +
+                        `Files to process: ${batchFiles.length}\n` +
+                        `Total audio: ${formatDuration(totalDuration)}\n` +
+                        `Est. GPU time: ${estimateTime(totalDuration, hasVulkanDll())}\n\n` +
+                        `First file: ${batchFiles[0].fileName}\n\n` +
+                        `Call check_batch_progress with batch_id="${batchId}" to monitor.`,
+                }],
+        };
+    }
+    // -------------------------------------------------------------------------
+    // check_batch_progress
+    // -------------------------------------------------------------------------
+    if (name === "check_batch_progress") {
+        const batchId = args?.batch_id;
+        if (!batchId)
+            return { content: [{ type: "text", text: "batch_id is required." }], isError: true };
+        try {
+            const result = await readBatchProgress(batchId);
+            return { content: [{ type: "text", text: result }] };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Error reading batch progress:\n\n${err?.message || String(err)}` }], isError: true };
+        }
+    }
+    // -------------------------------------------------------------------------
     // generate_subtitles
     // -------------------------------------------------------------------------
     if (name === "generate_subtitles") {
         const filePath = args?.file_path;
         const language = args?.language || "en";
+        const translateToEnglish = args?.translate_to_english || false;
         const threads = Math.min(SYSTEM_THREADS, Math.max(1, Math.round(args?.threads || WHISPER_THREADS)));
         if (!filePath)
             return { content: [{ type: "text", text: "file_path is required." }], isError: true };
@@ -733,15 +1023,56 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const configError = validatePaths();
         if (configError)
             return { content: [{ type: "text", text: configError }], isError: true };
+        if (await isWhisperRunning()) {
+            return { content: [{ type: "text", text: "Transcription already in progress. Wait for it to finish first." }], isError: true };
+        }
         try {
-            const result = await transcribeSingle(filePath, WHISPER_MODEL, language, "srt", threads, false);
+            // Convert to WAV if needed
+            let transcribeFrom = filePath;
+            let tmpFile = null;
+            if (needsConversion(filePath)) {
+                tmpFile = await convertToWav(filePath);
+                transcribeFrom = tmpFile;
+            }
+            const baseNoExt = filePath.replace(/\.[^.]+$/, "");
+            // Auto-detect language if requested
+            let detectedLang = language;
+            if (language === "auto") {
+                const detected = await detectLanguage(transcribeFrom, WHISPER_MODEL, threads);
+                detectedLang = detected ?? "en";
+            }
+            const results = [];
+            // Pass 1 — native language SRT
+            const nativeSrt = language === "en" || detectedLang === "en"
+                ? `${baseNoExt}.srt`
+                : `${baseNoExt}.${detectedLang}.srt`;
+            await runSrtPass(transcribeFrom, nativeSrt, WHISPER_MODEL, detectedLang, threads, false);
+            results.push(`✅ Native (${detectedLang}): ${nativeSrt}`);
+            // Pass 2 — English translation SRT (only if language isn't already English)
+            if (translateToEnglish && detectedLang !== "en") {
+                const englishSrt = `${baseNoExt}.en.srt`;
+                await runSrtPass(transcribeFrom, englishSrt, WHISPER_MODEL, detectedLang, threads, true);
+                results.push(`✅ English translation: ${englishSrt}`);
+            }
+            // Clean up temp WAV
+            if (tmpFile && existsSync(tmpFile))
+                try {
+                    unlinkSync(tmpFile);
+                }
+                catch { }
+            const langNote = language === "auto"
+                ? `Auto-detected language: ${detectedLang}\n\n`
+                : "";
             return {
                 content: [{
                         type: "text",
-                        text: `✅ Subtitle file generated!\n\n` +
-                            `Saved to: ${result.srtPath}\n\n` +
+                        text: `✅ Subtitle file(s) generated!\n\n` +
+                            langNote +
+                            results.join("\n") + "\n\n" +
                             `To use in VLC: Subtitle → Add Subtitle File → select the .srt file.\n` +
-                            `Works in any video player that supports external subtitles.`,
+                            `Works in any video player that supports external subtitles.\n\n` +
+                            `Note: whisper's built-in translation only translates to English. ` +
+                            `For other target languages, translate the .srt file contents separately.`,
                     }],
             };
         }
@@ -834,7 +1165,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`whisper-windows-mcp v1.7.0 running | threads: ${WHISPER_THREADS}/${SYSTEM_THREADS}`);
+    console.error(`whisper-windows-mcp v1.9.0 running | threads: ${WHISPER_THREADS}/${SYSTEM_THREADS}`);
 }
 main().catch((err) => {
     console.error("Fatal error:", err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whisper-windows-mcp",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Windows-native MCP server for local audio transcription using whisper.cpp with Vulkan GPU acceleration",
   "main": "dist/index.js",
   "bin": {