whisper-windows-mcp 1.9.0 → 2.0.0

package/README.ja.md

@@ -0,0 +1,310 @@
+# whisper-windows-mcp
+
+Windows向けのMCP（Model Context Protocol）サーバーです。[whisper.cpp](https://github.com/ggml-org/whisper.cpp)を使用して、Claude Desktopで音声・動画ファイルをローカルで文字起こしできます。GPU加速、多言語対応、バッチ処理に対応しています。インターネット接続不要。音声データは一切外部に送信されません。
+
+> **なぜこのツールが存在するか**
+> 人気のある`whisper-mcp`パッケージはmacOS向けに作られており、Unix環境を前提としています。Windowsでは動作しません。このパッケージは、Claude DesktopでローカルAI文字起こしを使いたいWindowsユーザーのために作られました。
+
+---
+
+## できること
+
+インストール後、Claude Desktopで以下のように話しかけるだけで使えます：
+
+- *「C:\Users\Me\Downloads\meeting.mp3を文字起こしして」*
+- *「このフォルダの録音ファイルをすべて文字起こしして、テキストファイルに保存して」*
+- *「この動画の日本語と英語の字幕ファイルを作って」*
+- *「このフォルダのファイルをすべてバッチ文字起こしして」*
+- *「これらのファイルの文字起こしにどれくらいかかる？」*
+- *「GPU加速が有効かどうか確認して」*
+
+---
+
+## 必要なもの
+
+1. **Node.js 18以降** — [nodejs.org](https://nodejs.org)
+2. **Vulkan GPU対応のwhisper.cppバイナリ** — ステップ1参照
+3. **Whisperモデルファイル** — ステップ2参照
+4. **FFmpeg** — 動画ファイルやWAV/MP3以外の音声形式に必要
+
+---
+
+## ステップ1 — whisper.cppバイナリのインストール
+
+### オプションA — ビルド済みVulkanリリース（推奨）
+
+[リリースページ](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0)から`whisper-vulkan-win-x64.zip`をダウンロードしてください。
+
+これは**Vulkan GPU加速**を有効にしてカスタムコンパイルされたビルドです。AMD、NVIDIA、Intel GPUで動作します。ベンダー固有のSDKは不要です。
+
+`C:\whisper\Release\`に展開してください。以下のファイルが揃っていることを確認してください：
+
+```
+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加速は自動的に有効になります。追加設定は不要です。
+
+### オプションB — ソースからビルド
+
+必要なもの：Git、CMake、「C++によるデスクトップ開発」ワークロードを含むVisual Studio Build Tools 2022以降、[lunarg.com](https://vulkan.lunarg.com/sdk/home#windows)のVulkan SDK。
+
+```
+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
+```
+
+`build\bin\Release\`のバイナリを`C:\whisper\Release\`にコピーしてください。
+
+> **注意：** GitHub上の公式whisper.cpp WindowsリリースにはVulkanビルドが含まれていません。上記のビルド済みリリースを使用するか、`-DGGML_VULKAN=ON`でソースからビルドしてください。
+
+---
+
+## ステップ2 — Whisperモデルのダウンロード
+
+| モデル | サイズ | 速度 | 精度 | 用途 |
+|---|---|---|---|---|
+| `ggml-tiny.en.bin` | 75 MB | 非常に速い | 基本 | 動作確認用 |
+| `ggml-base.en.bin` | 142 MB | 速い | 良い | 日常的な英語 |
+| `ggml-small.en.bin` | 466 MB | 普通 | より良い | 重要な録音 |
+| `ggml-medium.en.bin` | 1.5 GB | GPU使用時は速い | 非常に良い | 高品質な英語 |
+| `ggml-large-v3.bin` | 2.9 GB | GPU使用時は速い | 最高 | 多言語・最高精度 |
+
+**英語のみ**の場合：`base.en`または`medium.en`がおすすめです。
+**多言語対応**（自動検出、外国語、翻訳）の場合：最良の結果を得るには`large-v3`を使用してください。
+
+Hugging Faceからダウンロード：
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.en.bin
+```
+
+`C:\whisper\models\`に保存してください。
+
+---
+
+## ステップ3 — FFmpegのインストール
+
+動画ファイルやネイティブ以外の音声形式に必要です。
+
+wingetでインストール：
+```
+winget install ffmpeg
+```
+
+または[ffmpeg.org](https://ffmpeg.org/download.html)からダウンロードしてPATHに追加してください。
+
+確認：
+```
+ffmpeg -version
+```
+
+---
+
+## ステップ4 — MCPサーバーのインストール
+
+```
+npm install -g whisper-windows-mcp
+```
+
+---
+
+## ステップ5 — Claude Desktopの設定
+
+Claude Desktop → 設定 → 開発者 → 設定ファイルを編集 を開いてください。
+
+`whisper`エントリを追加してください：
+
+```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"
+      }
+    }
+  }
+}
+```
+
+設定ファイルの場所：`C:\Users\ユーザー名\AppData\Roaming\Claude\claude_desktop_config.json`
+
+> パスには必ず**バックスラッシュを2つ**使用してください（`C:\\whisper\\...`）。
+
+保存後、Claude Desktopを**完全に再起動**してください。設定 → 開発者に**whisper**が緑色の実行中バッジで表示されれば成功です。
+
+---
+
+## ステップ6 — 動作確認
+
+Claude Desktopで以下を入力してください：
+
+> *「whisperの設定を確認して」*
+
+次に：
+
+> *「システムのハードウェアを確認して」*
+
+GPUが検出され、Vulkan加速が有効であることを確認できます。
+
+---
+
+## 利用可能なツール
+
+### `transcribe_audio`（音声文字起こし）
+単一ファイルを文字起こしします。ブロッキング（デフォルト）またはバックグラウンドモードに対応。
+
+| パラメータ | 説明 |
+|---|---|
+| `file_path` | ファイルの絶対パス（必須） |
+| `language` | 言語コード（`en`、`ja`、`es`など）または`auto`で自動検出。デフォルト：`en` |
+| `output_format` | `text`（デフォルト）、`timestamps`、`json`、`srt` |
+| `save_to_file` | ソースファイルの隣に.txtとして保存 |
+| `background` | バックグラウンドジョブとして実行し、ジョブIDをすぐに返す。10分超のファイルに推奨。`check_progress`で監視。 |
+| `threads` | CPUスレッド数の上書き |
+
+---
+
+### `check_progress`（進捗確認）
+`transcribe_audio`（background=true）で開始したジョブを監視します。経過時間、最後に処理したタイムスタンプ、完了時の文字起こし全文を返します。
+
+---
+
+### `start_batch`（バッチ開始）
+フォルダ内の未文字起こしファイルを自動的に順次文字起こしします。時間順（短い順）にソートし、バックグラウンドジョブとして1つずつ処理し、各出力を検証します。
+
+---
+
+### `check_batch_progress`（バッチ進捗確認）
+実行中のバッチを監視します。現在のファイルが完了すると自動的に次のファイルに進みます。全体の進捗、現在のファイルとタイムスタンプ、失敗したファイルを返します。
+
+---
+
+### `transcribe_batch`（インタラクティブバッチ）
+1ファイルずつプレビューと確認を挟みながら処理します。進行状況を確認しながら作業したい場合に便利です。
+
+---
+
+### `generate_subtitles`（字幕生成）
+SRT字幕ファイルを生成します。言語自動検出と英語翻訳出力に対応。
+
+| パラメータ | 説明 |
+|---|---|
+| `file_path` | ファイルのパス（必須） |
+| `language` | 言語コードまたは`auto`で自動検出。デフォルト：`en` |
+| `translate_to_english` | 英語翻訳の`.en.srt`も生成する。ソースが英語でない場合のみ適用。 |
+| `threads` | CPUスレッド数の上書き |
+
+ネイティブと翻訳の両方を要求した場合、2つのファイルが保存されます：
+- `ファイル名.ja.srt` — 元の言語
+- `ファイル名.en.srt` — 英語翻訳
+
+> whisperの組み込み翻訳は**英語へのみ**翻訳できます。他の言語への翻訳には別途翻訳ツールが必要です。
+
+---
+
+### `analyze_media`（メディア分析）
+文字起こし前にファイルを分析します。時間、サイズ、コーデック、CPUとGPUでの推定文字起こし時間を返します。フォルダの場合は、すべてのファイルをテーブル形式で表示します。
+
+---
+
+### `check_config`（設定確認）
+whisper-cli.exe、モデルファイル、FFmpegがすべてアクセス可能かを確認します。問題が発生した場合はまずこれを実行してください。
+
+---
+
+### `check_system`（システム確認）
+GPUハードウェアを検出し、Vulkan加速が利用可能かを確認します。GPU名、VRAM、`ggml-vulkan.dll`の有無、ハードウェアに適したモデルサイズを報告します。
+
+---
+
+## 対応フォーマット
+
+| 種類 | フォーマット |
+|---|---|
+| ネイティブ（変換不要） | `mp3`、`wav` |
+| 動画（FFmpegで自動変換） | `mp4`、`mkv`、`avi`、`mov`、`webm`、`flv`、`wmv`、`m4v`、`ts`、`3gp` |
+| 音声（FFmpegで自動変換） | `m4a`、`ogg`、`flac` |
+
+---
+
+## GPU加速
+
+ビルド済みVulkanリリースにより、GPU加速が自動的に有効になります。AMD Radeon RX Vega 56（GCN第5世代）で動作確認済み。Vulkan 1.0以上をサポートするGPU（NVIDIA、Intel Arcを含む）であれば動作するはずです。
+
+**パフォーマンス比較（medium.enモデル、約5分の音声ファイル）：**
+
+| ハードウェア | 処理時間 |
+|---|---|
+| CPUのみ（Ryzen 7 2700x、8スレッド） | 8〜12分 |
+| GPU（Vega 56、Vulkan経由） | 20〜40秒 |
+
+文字起こし中のGPU使用率は約15〜20%。ファイル間はアイドル状態に戻ります。
+
+---
+
+## 多言語対応
+
+Whisperは話されている言語を自動検出し、その言語で文字起こしができます。組み込みの翻訳モデルは**英語へのみ**翻訳します。
+
+多言語コンテンツには`large-v3`が**必須**です。英語専用モデル（`*.en.bin`）は英語以外の音声に`[FOREIGN]`を出力します — いかなる状況でも他の言語を検出・文字起こしすることはできません。
+
+**外国語動画の字幕作成の例：**
+1. `language=auto`と`translate_to_english=true`で字幕生成を依頼
+2. Whisperが言語を検出し、元の言語のSRTを生成
+3. 2回目のパスで英語翻訳SRTを生成
+4. VLCで「字幕」→「字幕ファイルを追加」からどちらのファイルも読み込み可能
+
+---
+
+## フリープランユーザー向け設計
+
+このツールはClaude APIの呼び出し回数を最小限に抑えるように設計されています。スキャン、分析、キュー管理、実行、検証を含む文字起こしワークフロー全体で、60ファイルのバッチ処理に必要なClaude操作は20回以下を目標としています。
+
+---
+
+## 環境変数（オプション）
+
+| 変数 | 説明 |
+|---|---|
+| `WHISPER_CLI_PATH` | whisper-cli.exeのパス（必須） |
+| `WHISPER_MODEL` | モデル.binファイルのパス（必須） |
+| `WHISPER_THREADS` | CPUスレッド数の上書き |
+| `FFMPEG_PATH` | ffmpegがPATHにない場合のパス |
+
+---
+
+## トラブルシューティング
+
+詳細は[TROUBLESHOOTING.md](TROUBLESHOOTING.md)（英語）をご覧ください。
+
+簡易チェックリスト：
+- 設定のパスには**バックスラッシュを2つ**使用（`C:\\whisper\\...`）
+- 設定したパスに`whisper-cli.exe`が存在する
+- 設定したパスにモデル`.bin`ファイルが存在する
+- FFmpegがインストールされPATHが通っている（`ffmpeg -version`が動作する）
+- 設定変更後にClaude Desktopを完全に再起動した
+- 設定 → 開発者でwhisperが**実行中**と表示されている
+
+---
+
+## ライセンス
+
+MIT
+
+---
+
+## コントリビュート
+
+プルリクエスト歓迎です。計画中の機能については[ROADMAP.md](ROADMAP.md)をご覧ください。
+
+上記以外のハードウェアでGPU加速をテストした方は、GPU型番、VRAM、使用モデル、確認したスループットをIssueで報告してください。

package/README.md

@@ -78,7 +78,7 @@ Copy the binaries from `build\bin\Release\` to `C:\whisper\Release\`.
 | `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.
+For **multilingual** use (auto-detect, foreign language, translation): `large-v3` is **required**. English-only models (`*.en.bin`) output `[FOREIGN]` on non-English audio and cannot be used for other languages.
 
 Download from Hugging Face:
 ```

package/ROADMAP.ja.md

@@ -0,0 +1,121 @@
+# whisper-windows-mcp — ロードマップ
+
+現在のバージョン：**v1.9.0**
+
+---
+
+## 完了済み
+
+### ✅ v1.3.1 — プロセスロック
+`tasklist /FI`を使用した`isWhisperRunning()`チェックを追加。競合するプロセスを生成する代わりに、明確なエラーとTask Managerの手順を返します。
+
+### ✅ v1.4.0 — Vulkan GPU加速
+VS Build Tools 2026とVulkan SDK 1.4.341.1を使用して`-DGGML_VULKAN=ON`でwhisper.cppをコンパイル。ビルド済みVulkanバイナリを`whisper-vulkan-win-x64.zip`として配布。
+
+**AMD Radeon RX Vega 56での結果：** GPU使用率約16%。58分のファイルがGPUで約4.5分（CPU専用では約88分）で完了。
+
+### ✅ v1.5.0 — システム診断
+`check_system`ツール：`wmic`によるGPU検出、Vulkan DLL確認、VRAM報告、モデルサイズ推奨。
+
+### ✅ v1.6.0 — メディアファイル事前分析
+FFprobeを使用した`analyze_media`ツール：時間、サイズ、コーデック、文字起こし状態、CPUとGPUの推定時間。単一ファイルまたはフォルダスキャン、ソートオプション付き。
+
+### ✅ v1.7.0 — バックグラウンド文字起こし + 進捗表示
+デタッチドプロセスアーキテクチャ：`background=true`の`transcribe_audio`がwhisperをデタッチドプロセスとして起動し、即座にジョブIDを返す。`check_progress`がwhisperのstderrセグメントタイムスタンプをリアルタイムで解析。
+
+### ✅ v1.8.0 — 検証付き順次バッチ処理
+`start_batch`と`check_batch_progress`：自動順次処理、文字起こし検証（空または短すぎる出力の検出）、自動キュー進行、ファイルごとの進捗タイムスタンプ。
+
+### ✅ v1.9.0 — 多言語対応と翻訳
+`language=auto`による言語自動検出と`translate_to_english=true`によるデュアルSRT出力。`.3gp`と`.ts`フォーマットのサポートを追加。
+
+**既知の制限：** Whisperの組み込み翻訳は英語へのみ対応。英語以外の言語には`large-v3`モデルが必要 — 英語専用モデル（`*.en.bin`）は英語以外の音声に`[FOREIGN]`を出力します。
+
+---
+
+## 既知のバグ（次回リリース予定）
+
+### Unicodeおよび特殊文字のファイル名
+日本語・中国語・絵文字・括弧などのUnicode文字をファイル名に含む場合、バックグラウンド文字起こしがサイレントに失敗します — whisperは完了まで動作しますが、そのパスに出力ファイルを書き込めません。
+
+**修正予定：** ジョブIDに基づくサニタイズされた一時パスに出力を書き込み、完了後に正しい宛先に移動します。
+
+### バックグラウンドモードでSRT出力が未対応
+`spawnDetached`が`-otxt`をハードコードしています。`generate_subtitles`は同期的にブロックするため、約4分を超えるファイルでMCPタイムアウトが発生します。
+
+**修正予定：** `spawnDetached`に`outputFormat`パラメータを追加。バックグラウンドモードで`text`、`srt`、`timestamps`出力形式をサポートします。
+
+---
+
+## 予定
+
+### Priority 8 — ファイル名ベースの参照
+すべてのツール出力で、位置インデックスではなく完全なソースファイル名を参照するようにします。
+
+---
+
+### 話者識別（ダイアライゼーション）
+文字起こしでの話者の切り替えを識別します（名前を特定せず、例：`[話者A]`、`[話者B]`のようにマーク）。インタビュー、パネル討論、法廷録音に有用。
+
+**実装：** [pyannote-audio](https://github.com/pyannote/pyannote-audio)が必要 — Hugging Faceアカウントとモデルアクセストークンが必要なPythonベースのライブラリ。現在のwhisper.cppパイプラインとは別の依存関係スタック。
+
+**状況：** 別途セットアップドキュメントを用意するオプションの高度機能として計画中。メインパッケージには含めません。
+
+---
+
+### 動画プロジェクトワークフローツール（Premiere準備）
+大規模な動画編集プロジェクトを管理するユーザー向けのツール：
+
+1. 親ディレクトリのソースクリップ
+2. `./clips/`サブディレクトリの編集済みクリップ
+3. 文字起こしテキストの位置照合 — テキストのファジーマッチングによる編集済みクリップのソース内位置特定
+4. Claudeが提案するディスクリプタによる半自動リネーム（実行前に明示的なユーザー確認が必要）
+5. プロジェクトディレクトリ全体の文字起こし検索
+
+**状況：** 設計フェーズ。実際のディレクトリ例をもとに実装予定。
+
+---
+
+### 英語以外の言語への翻訳
+Whisperの`--translate`フラグは英語のみを対象としています。任意のターゲット言語（例：日本語→ドイツ語）をサポートするには、外部翻訳APIまたはローカル翻訳モデルが必要です。
+
+**状況：** ローカルファーストかAPIへの依存かの設計判断待ちで保留中。
+
+---
+
+### 文字起こしのクリーンアップと整形
+より読みやすくクリップスキャンしやすい後処理：
+- フィラーワードと言い直しの削除（オプション、ユーザー制御）
+- 自然なトピック境界での段落区切り
+- ダイアライゼーションと組み合わせた話者を考慮した整形
+
+**状況：** 計画中。
+
+---
+
+### 多言語ドキュメント
+日本語ドキュメント（`README.ja.md`、`TROUBLESHOOTING.ja.md`、`ROADMAP.ja.md`）を作成済み。他の言語へのコミュニティ貢献を歓迎します。
+
+---
+
+## 設計原則
+
+**Claude APIの使用を最小限に。** スキャン、分析、キュー管理、実行、検証を含む60ファイルのバッチ処理ワークフロー全体で、必要なClaude操作は20回以下を目標としています。フリープランユーザーもこのツールを効果的に使用できる必要があります。
+
+**常に1つのwhisperインスタンス。** 実行中に2つ目のプロセスを生成しない。
+
+**ローカルファースト、デフォルトでプライベート。** 音声はマシンから外に出ない。コア機能にクラウドAPIは不要。
+
+**モジュール型かつ組み合わせ可能。** ツールは独立しています。ユーザーは必要なものだけを使います。
+
+**明示的なユーザー制御。** サイレントな一括操作なし。破壊的または不可逆なアクションは確認が必要。
+
+**Unicodeセーフなパス処理。** すべてのファイルI/Oで、日本語、中国語、絵文字、特殊文字を含む非ASCIIファイル名を正しく処理する必要があります。
+
+---
+
+## コントリビュート
+
+プルリクエスト歓迎です。作業を開始する前に既存のIssueを確認してください。
+
+上記以外のハードウェアでGPU加速をテストした方は、GPU型番、VRAM、使用モデル、確認したスループットをIssueで報告してください。

package/TROUBLESHOOTING.ja.md

@@ -0,0 +1,209 @@
+# whisper-windows-mcp — トラブルシューティング
+
+---
+
+## 簡易チェックリスト
+
+詳しい調査の前に、以下をすべて確認してください：
+
+- `claude_desktop_config.json`のパスに**バックスラッシュを2つ**使用している（`C:\\whisper\\...`）
+- `WHISPER_CLI_PATH`に指定したパスに`whisper-cli.exe`が存在する
+- `WHISPER_MODEL`に指定したパスにモデル`.bin`ファイルが存在する
+- FFmpegがインストールされPATHが通っている（コマンドプロンプトで`ffmpeg -version`が動作する）
+- 設定ファイル編集後にClaude Desktopを**完全に再起動**した（システムトレイから終了）
+- 設定 → 開発者でwhisperが緑色の**実行中**バッジで表示されている
+
+---
+
+## 「whisperに接続できない」またはツールが表示されない
+
+**最も多い原因：** 設定ファイル編集後にClaude Desktopを完全に再起動していない。
+
+1. システムトレイのClaudeアイコンを右クリック → 終了
+2. Claude Desktopを再起動
+3. 設定 → 開発者でwhisperの緑色の**実行中**バッジを確認
+
+それでも表示されない場合：
+
+1. `claude_desktop_config.json`のJSON構文エラーを確認（カンマの漏れ、括弧の不一致など）
+2. すべてのパスでバックスラッシュを2つ使用していることを確認
+3. Claude Desktopで`check_config`（設定確認）を実行して診断情報を取得
+
+---
+
+## `check_config`がwhisper-cli.exeを見つけられない
+
+設定のパスが実際のファイルの場所と一致していません。
+
+ファイルの存在を確認：
+```
+dir C:\whisper\Release\whisper-cli.exe
+```
+
+別の場所にある場合は、設定の`WHISPER_CLI_PATH`を実際のパスに更新してください。
+
+---
+
+## `check_config`がFFmpegを見つけられない
+
+FFmpegがインストールされていないか、システムPATHに含まれていません。
+
+wingetでインストール：
+```
+winget install ffmpeg
+```
+
+または[ffmpeg.org](https://ffmpeg.org/download.html)からダウンロードして、`bin`フォルダをシステムPATHに追加してください。
+
+インストール後、新しいコマンドプロンプトで確認：
+```
+ffmpeg -version
+```
+
+FFmpegを標準以外の場所にインストールした場合は、Claude Desktop設定で`FFMPEG_PATH`環境変数を設定してください：
+```json
+"env": {
+  "FFMPEG_PATH": "C:\\ffmpeg\\bin\\ffmpeg.exe"
+}
+```
+
+---
+
+## 文字起こし結果が`[FOREIGN]`タグばかりになる
+
+**原因：** 英語専用モデル（例：`ggml-medium.en.bin`）を英語以外の音声に使用しています。英語専用モデルは他の言語を処理できず、認識できないすべてのセグメントに`[FOREIGN]`を出力します。
+
+**修正方法：** `ggml-large-v3.bin`（多言語モデル）をダウンロードして使用してください。英語以外の文字起こし、言語自動検出、翻訳にはこのモデルが必要です。
+
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin
+```
+
+`C:\whisper\models\`に保存して設定を更新：
+```json
+"WHISPER_MODEL": "C:\\whisper\\models\\ggml-large-v3.bin"
+```
+
+> **注意：** 英語専用モデル（`*.en.bin`）は英語コンテンツでは速く精度が高いですが、他の言語は一切処理できません。多言語コンテンツを扱う場合は、ハードウェアに関わらず`large-v3`が正しいモデルです。
+
+---
+
+## ファイル名にUnicodeや特殊文字が含まれる場合のバックグラウンドジョブの失敗
+
+**原因：** パスに日本語・中国語・絵文字・括弧などのUnicode文字や特殊文字が含まれる場合、whisper-cli.exeが出力ファイルを書き込めません。
+
+**現在の回避方法：** 文字起こし前にファイル名をASCII文字のみに変更してください。
+
+```
+ren "日本語ファイル名.mp4" "temp_transcribe.mp4"
+```
+
+**状況：** 既知のバグです。出力をサニタイズされた一時パスに書き込んでから正しい場所に移動する修正を計画中です。
+
+---
+
+## バックグラウンドジョブが失敗して出力がない
+
+**考えられる原因：**
+
+1. **Unicodeファイル名** — 上記参照。
+2. **モデルパスが間違っている** — `check_config`でパスを確認してください。
+3. **プロセスが強制終了された** — 処理中にwhisper-cli.exeを強制終了すると出力ファイルが存在しません。再実行してください。
+4. **VRAMが不足している** — より小さいモデルを試してください。
+
+---
+
+## バックグラウンドモードでSRT出力が作成されない
+
+**原因：** バックグラウンドモード（`transcribe_audio`の`background=true`）は現在`.txt`出力のみに対応しています。
+
+**回避方法：** 約4分未満のファイルには`generate_subtitles`をブロッキングモードで使用してください。長いファイルの場合は、先にバックグラウンドモードで`.txt`を作成してから、同じファイルで`generate_subtitles`を実行してください（再度文字起こしが行われます）。
+
+**状況：** バックグラウンドモードでのSRT対応は将来のリリースで予定されています。
+
+---
+
+## GPUが使用されていない（CPUが50%以上で高負荷）
+
+**原因：** 標準のwhisper.cppリリースに付属するCPU専用バイナリを使用しています。
+
+**修正方法：** [リリースページ](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0)からVulkan対応ビルドをダウンロードして`C:\whisper\Release\`に展開してください。
+
+GPU加速の確認方法：
+- `check_system`（システム確認）を実行
+- `✅ Vulkan binary: ggml-vulkan.dll found`が表示されることを確認
+- 文字起こし中にタスクマネージャー → パフォーマンス → GPUでGPU使用率が15〜30%に上昇することを確認
+
+---
+
+## `check_system`のVRAM表示が実際と異なる
+
+Windowsの既知の制限です。`wmic`コマンドはレジストリからVRAMを読み取りますが、多くのAMDカードでは物理VRAMの半分の値が表示されます。これは表示の問題のみで、whisperは実際の物理VRAMを完全に使用します。
+
+---
+
+## 「文字起こしが既に進行中」エラー
+
+前のジョブの`whisper-cli.exe`プロセスが実行中です。完了を待つか：
+
+1. タスクマネージャー → 詳細タブ
+2. `whisper-cli.exe`を見つける
+3. 右クリック → タスクの終了
+
+その後、再試行してください。
+
+---
+
+## 言語自動検出が間違っている
+
+Whisperの自動検出は音声の最初の30秒で行われます。ファイルの最初がコンテンツの大部分と異なる言語の場合、検出が間違う可能性があります。
+
+**修正方法：** 自動検出に頼らず、言語を明示的に指定してください（例：`language=ja`）。
+
+---
+
+## 字幕生成が全編「（外国語で話しています）」になる
+
+Whisperが音声を検出したが文字起こしできていません。最も多い原因：
+
+1. **間違ったモデル** — 英語専用モデルを英語以外の音声に使用。`large-v3`を使用してください。
+2. **音声品質** — 雑音のある環境（厨房、群衆、反響）はmediumモデルでは難しい場合があります。`large-v3`を試してください。
+3. **混合言語** — 2つの言語が交互に話されるファイルは、単一言語設定では少数派の言語がプレースホルダーになります。
+
+---
+
+## 字幕翻訳が英語にしか対応していない
+
+これは仕様です。Whisperの組み込み`--translate`フラグは**英語へのみ**翻訳します。他の言語への翻訳は、生成された`.srt`ファイルを別途翻訳ツールで処理してください。
+
+---
+
+## 設定ファイルの場所
+
+```
+C:\Users\ユーザー名\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+`AppData`が表示されない場合：エクスプローラーで「表示」→「隠しファイル」を有効にしてください。
+
+---
+
+## 完全な設定例
+
+```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",
+        "FFMPEG_PATH": "ffmpeg"
+      }
+    }
+  }
+}
+```
+
+`FFMPEG_PATH`のデフォルトは`ffmpeg`（PATHにあることを前提）です。FFmpegが標準以外の場所にインストールされている場合のみ明示的に設定してください。

package/dist/index.js

@@ -60,30 +60,39 @@ const JOBS_DIR = join(tmpdir(), "whisper-mcp-jobs");
 function ensureJobsDir() {
     mkdirSync(JOBS_DIR, { recursive: true });
 }
-async function spawnDetached(filePath, model, language, threads) {
+async function spawnDetached(filePath, model, language, threads, outputFormat = "text") {
     ensureJobsDir();
     const jobId = `job_${Date.now()}`;
     const logPath = join(JOBS_DIR, `${jobId}.log`);
     const jobPath = join(JOBS_DIR, `${jobId}.json`);
-    // Convert to WAV first if needed (fast, blocking — keeps things simple)
+    // Convert to WAV first if needed (fast, blocking)
     let transcribeFrom = filePath;
     let isTmp = false;
     if (needsConversion(filePath)) {
         transcribeFrom = await convertToWav(filePath);
         isTmp = true;
     }
-    // Build args — use -otxt so whisper writes outputfile.txt itself
-    const outputBase = filePath.replace(/\.[^.]+$/, "");
-    const outputPath = outputBase + ".txt";
+    // Use a clean ASCII job-ID-based output path to avoid Unicode filename issues.
+    // After completion, readJobProgress will move the file to the correct destination.
+    const tmpOutputBase = join(JOBS_DIR, jobId);
+    // Determine final destination path
+    const sourceBase = filePath.replace(/\.[^.]+$/, "");
+    const ext = outputFormat === "srt" ? ".srt" : ".txt";
+    // For SRT with language code (non-English), append language code
+    const outputPath = outputFormat === "srt" && language !== "en" && language !== "auto"
+        ? `${sourceBase}.${language}.srt`
+        : `${sourceBase}${ext}`;
+    // Build args
+    const lang = language === "auto" ? "auto" : language;
     const args = [
         "-m", model,
         "-f", transcribeFrom,
-        "-l", language,
+        "-l", lang,
         "-t", String(threads),
-        "-otxt",
-        "-of", outputBase,
+        outputFormat === "srt" ? "-osrt" : "-otxt",
+        "-of", tmpOutputBase,
     ];
-    // Spawn detached, redirect both stdout+stderr to log file
+    // Spawn detached, redirect stdout+stderr to log file
     const logFd = openSync(logPath, "w");
     const child = spawn(WHISPER_CLI_PATH, args, {
         detached: true,
@@ -100,6 +109,8 @@ async function spawnDetached(filePath, model, language, threads) {
         transcribeFrom,
         isTmp,
         outputPath,
+        tmpOutputBase,
+        outputFormat,
         logPath,
         jobPath,
         startTime: new Date().toISOString(),
@@ -146,9 +157,21 @@ async function readJobProgress(jobId) {
     }
     const lastSec = parseLastTimestamp(logContent);
     const isRunning = await isPidRunning(job.pid);
-    const outputExists = existsSync(job.outputPath);
+    const ext = job.outputFormat === "srt" ? ".srt" : ".txt";
+    const tmpOutput = `${job.tmpOutputBase}${ext}`;
+    const outputExists = existsSync(job.outputPath) || existsSync(tmpOutput);
     // Completed
     if (!isRunning && outputExists) {
+        // Move temp output file to correct destination if needed
+        const ext = job.outputFormat === "srt" ? ".srt" : ".txt";
+        const tmpOutput = `${job.tmpOutputBase}${ext}`;
+        if (existsSync(tmpOutput) && tmpOutput !== job.outputPath) {
+            try {
+                writeFileSync(job.outputPath, readFileSync(tmpOutput, "utf8"), "utf8");
+                unlinkSync(tmpOutput);
+            }
+            catch { }
+        }
         job.status = "complete";
         writeFileSync(job.jobPath, JSON.stringify(job, null, 2), "utf8");
         // Clean up tmp wav if present
@@ -158,11 +181,14 @@ async function readJobProgress(jobId) {
             }
             catch { }
         }
-        const transcript = readFileSync(job.outputPath, "utf8").trim();
+        const outputContent = readFileSync(job.outputPath, "utf8").trim();
+        const preview = job.outputFormat === "srt"
+            ? outputContent.split("\n").slice(0, 20).join("\n")
+            : outputContent.slice(0, 600);
         return (`✅ Complete!\n\n` +
             `Source: ${basename(job.sourceFile)}\n` +
             `Output: ${job.outputPath}\n\n` +
-            `Preview:\n${transcript.slice(0, 600)}${transcript.length > 600 ? "..." : ""}`);
+            `Preview:\n${preview}${outputContent.length > 600 && job.outputFormat !== "srt" ? "..." : ""}`);
     }
     // Failed
     if (!isRunning && !outputExists) {
@@ -536,7 +562,7 @@ function getFiles(dir, recursive) {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "whisper-windows-mcp", version: "1.9.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "whisper-windows-mcp", version: "2.0.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
@@ -622,7 +648,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     },
                     translate_to_english: {
                         type: "boolean",
-                        description: "Also generate an English translation .srt alongside the native language .srt. Only applies when language is not 'en'.",
+                        description: "Also generate an English translation .srt alongside the native language .srt. Only applies when language is not 'en'. Not available in background mode.",
+                        default: false,
+                    },
+                    background: {
+                        type: "boolean",
+                        description: "Run as a detached background job — recommended for files over 10 minutes. Returns a job ID to use with check_progress. translate_to_english is not available in background mode.",
                         default: false,
                     },
                     threads: { type: "number", description: `CPU threads. Defaults to ${WHISPER_THREADS} of ${SYSTEM_THREADS}.` },
@@ -880,7 +911,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             try {
-                const { jobId, pid } = await spawnDetached(filePath, model, language, threads);
+                const { jobId, pid } = await spawnDetached(filePath, model, language, threads, outputFormat === "srt" ? "srt" : "text");
                 return {
                     content: [{
                             type: "text",
@@ -1015,6 +1046,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const filePath = args?.file_path;
         const language = args?.language || "en";
         const translateToEnglish = args?.translate_to_english || false;
+        const background = args?.background || 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 };
@@ -1026,6 +1058,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (await isWhisperRunning()) {
             return { content: [{ type: "text", text: "Transcription already in progress. Wait for it to finish first." }], isError: true };
         }
+        // Background mode — detached SRT job
+        if (background) {
+            try {
+                const { jobId, pid } = await spawnDetached(filePath, WHISPER_MODEL, language, threads, "srt");
+                return {
+                    content: [{
+                            type: "text",
+                            text: `⏳ Background subtitle generation started.\n\n` +
+                                `Source: ${basename(filePath)}\n` +
+                                `Job ID: ${jobId}\n` +
+                                `PID: ${pid}\n` +
+                                `Language: ${language}\n\n` +
+                                `Call check_progress with job_id="${jobId}" to monitor.\n` +
+                                `Note: translate_to_english is not available in background mode. ` +
+                                `Run generate_subtitles again after completion to create the English translation.`,
+                        }],
+                };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `Failed to start background subtitle job:\n\n${err?.message || String(err)}` }], isError: true };
+            }
+        }
         try {
             // Convert to WAV if needed
             let transcribeFrom = filePath;
@@ -1165,7 +1219,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`whisper-windows-mcp v1.9.0 running | threads: ${WHISPER_THREADS}/${SYSTEM_THREADS}`);
+    console.error(`whisper-windows-mcp v2.0.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.9.0",
+  "version": "2.0.0",
   "description": "Windows-native MCP server for local audio transcription using whisper.cpp with Vulkan GPU acceleration",
   "main": "dist/index.js",
   "bin": {