whisper-windows-mcp 2.2.0 → 2.2.2

package/README.vi.md

@@ -0,0 +1,393 @@
+# whisper-windows-mcp
+
+Máy chủ MCP (Model Context Protocol) dành riêng cho Windows. Sử dụng [whisper.cpp](https://github.com/ggml-org/whisper.cpp) để phiên âm tệp âm thanh và video cục bộ trong Claude Desktop — hỗ trợ tăng tốc GPU, đa ngôn ngữ và xử lý hàng loạt. Toàn bộ quá trình phiên âm chạy cục bộ — không có tệp âm thanh, video hay đường dẫn tệp nào được gửi ra ngoài.
+
+> **Tại sao có gói này?**
+> Gói `whisper-mcp` phổ biến được xây dựng cho macOS và yêu cầu môi trường Unix. Gói đó không hoạt động trên Windows. Gói này được viết dành riêng cho người dùng Windows muốn phiên âm AI cục bộ tích hợp với Claude Desktop.
+
+---
+
+## Bạn có thể làm gì
+
+Sau khi cài đặt, bạn có thể nói trực tiếp trong Claude Desktop:
+
+- *"Phiên âm C:\Users\Me\Downloads\meeting.mp3"*
+- *"Phiên âm tất cả bản ghi trong thư mục này và lưu mỗi file thành văn bản"*
+- *"Tạo phụ đề tiếng Việt và tiếng Anh cho video này"*
+- *"Bắt đầu phiên âm hàng loạt tất cả file trong thư mục này"*
+- *"Phiên âm những file này sẽ mất bao lâu?"*
+- *"Kiểm tra xem tăng tốc GPU có đang hoạt động không"*
+
+---
+
+## Yêu cầu
+
+1. **Node.js 18 trở lên** — [nodejs.org](https://nodejs.org)
+2. **Tệp nhị phân whisper.cpp hỗ trợ Vulkan GPU** — xem Bước 1
+3. **Tệp mô hình Whisper** — xem Bước 2
+4. **FFmpeg** — cần thiết cho tệp video và định dạng âm thanh không phải WAV/MP3
+
+---
+
+## Bước 1 — Cài đặt tệp nhị phân whisper.cpp
+
+### Tùy chọn A — Bản phát hành Vulkan đã được biên dịch sẵn (khuyến nghị)
+
+Tải xuống `whisper-vulkan-win-x64.zip` từ [trang phát hành](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0).
+
+Đây là bản build tùy chỉnh với **tăng tốc Vulkan GPU** được bật. Hoạt động với GPU AMD, NVIDIA và Intel — không cần SDK riêng của từng nhà sản xuất.
+
+Giải nén vào `C:\whisper\Release\`. Bạn sẽ có các tệp sau:
+
+```
+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
+```
+
+Tăng tốc GPU được kích hoạt tự động — không cần cấu hình thêm.
+
+### Tùy chọn B — Biên dịch từ mã nguồn
+
+Yêu cầu: Git, CMake, Visual Studio Build Tools 2022+ với "Desktop development with C++", Vulkan SDK từ [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
+```
+
+Sao chép các tệp nhị phân từ `build\bin\Release\` vào `C:\whisper\Release\`.
+
+> **Lưu ý:** Bản phát hành Windows chính thức của whisper.cpp trên GitHub không bao gồm bản Vulkan. Bạn phải sử dụng bản phát hành đã biên dịch sẵn ở trên hoặc tự biên dịch từ mã nguồn với `-DGGML_VULKAN=ON`.
+
+---
+
+## Bước 2 — Tải xuống mô hình Whisper
+
+| Mô hình | Kích thước | Tốc độ | Độ chính xác | Phù hợp nhất |
+|---|---|---|---|---|
+| `ggml-tiny.en.bin` | 75 MB | Rất nhanh | Cơ bản | Kiểm tra nhanh |
+| `ggml-base.en.bin` | 142 MB | Nhanh | Tốt | Tiếng Anh hàng ngày |
+| `ggml-small.en.bin` | 466 MB | Vừa | Tốt hơn | Bản ghi quan trọng |
+| `ggml-medium.en.bin` | 1.5 GB | Nhanh trên GPU | Rất tốt | Tiếng Anh chất lượng cao nhất |
+| `ggml-large-v3-turbo.bin` | 1.6 GB | Nhanh trên GPU | Xuất sắc | **Khuyến nghị cho xử lý hàng loạt GPU tiếng Anh — nhanh hơn large-v3 khoảng 6 lần với độ giảm chính xác tối thiểu** |
+| `ggml-large-v3.bin` | 2.9 GB | Nhanh trên GPU | Xuất sắc | Đa ngôn ngữ, độ chính xác tối đa |
+| `ggml-medium.en-q5_0.bin` | 514 MB | Nhanh | Rất tốt | **Lựa chọn tốt nhất chỉ dùng CPU tiếng Anh — độ chính xác cao với bộ nhớ thấp** |
+| `ggml-large-v3-turbo-q5_0.bin` | 547 MB | Nhanh | Xuất sắc | **Lựa chọn tốt nhất chỉ dùng CPU đa ngôn ngữ** |
+| `ggml-large-v3-q5_0.bin` | 1.1 GB | Vừa trên CPU | Xuất sắc | Đa ngôn ngữ, thân thiện với CPU |
+
+Sử dụng `download_model` trong Claude Desktop để cài đặt trực tiếp. Cho **tiếng Anh**: `large-v3-turbo` (GPU) hoặc `medium.en-q5_0` (CPU) là lựa chọn tốt nhất. Cho **đa ngôn ngữ**: `large-v3-turbo` hoặc `large-v3-turbo-q5_0` (CPU). Mô hình chỉ tiếng Anh (`*.en.bin`) xuất ra `[FOREIGN]` với âm thanh không phải tiếng Anh và không thể dùng cho ngôn ngữ khác.
+
+---
+
+## Bước 3 — Cài đặt FFmpeg
+
+FFmpeg cần thiết cho tệp video và định dạng âm thanh không phải gốc.
+
+Cài đặt qua winget:
+```
+winget install ffmpeg
+```
+
+Hoặc tải xuống từ [ffmpeg.org](https://ffmpeg.org/download.html) và thêm vào PATH.
+
+Xác nhận:
+```
+ffmpeg -version
+```
+
+---
+
+## Bước 4 — Cài đặt máy chủ MCP
+
+```
+npm install -g whisper-windows-mcp
+```
+
+---
+
+## Bước 5 — Cấu hình Claude Desktop
+
+Mở Claude Desktop → Cài đặt → Nhà phát triển → Chỉnh sửa cấu hình.
+
+Thêm mục `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"
+      }
+    }
+  }
+}
+```
+
+Vị trí tệp cấu hình: `C:\Users\TênNgườiDùng\AppData\Roaming\Claude\claude_desktop_config.json`
+
+> Sử dụng **dấu gạch chéo ngược kép** trong tất cả đường dẫn.
+
+Lưu và **khởi động lại hoàn toàn** Claude Desktop. Bạn sẽ thấy **whisper** được liệt kê với huy hiệu đang chạy màu xanh trong Cài đặt → Nhà phát triển.
+
+---
+
+## Bước 6 — Xác nhận cài đặt
+
+Trong Claude Desktop, hỏi:
+
+> *"Kiểm tra cấu hình whisper"*
+
+Sau đó:
+
+> *"Kiểm tra phần cứng hệ thống"*
+
+Điều này xác nhận GPU của bạn được phát hiện và tăng tốc Vulkan đang hoạt động.
+
+---
+
+## Công cụ có sẵn
+
+### `transcribe_audio`
+Phiên âm một tệp. Hỗ trợ chế độ chặn (mặc định) hoặc nền cho tệp dài.
+
+| Tham số | Mô tả |
+|---|---|
+| `file_path` | Đường dẫn tuyệt đối đến tệp (bắt buộc) |
+| `language` | Mã ngôn ngữ (`vi`, `en`, `ja`, v.v.) hoặc `auto` để tự phát hiện. Mặc định: `en` |
+| `output_format` | `text` (mặc định), `timestamps`, `json`, hoặc `srt` |
+| `save_to_file` | Lưu bản phiên âm dưới dạng .txt bên cạnh tệp nguồn |
+| `background` | Chạy như tác vụ nền — trả về ID tác vụ ngay lập tức. Dùng `check_progress` để theo dõi. Khuyến nghị cho tệp trên 10 phút. |
+| `threads` | Ghi đè số luồng CPU |
+| `temperature` | Nhiệt độ lấy mẫu 0.0–1.0. Mặc định 0.0 (xác định). Giá trị cao hơn giảm ảo giác trên âm thanh nhiều tạp âm. |
+| `prompt` | Chuỗi ngữ cảnh trước — cải thiện độ chính xác cho từ vựng chuyên ngành hoặc tên người nói. Ví dụ: `"Tên: Keemstar, DramaAlert."` |
+| `condition_on_prev_text` | Bật lại điều kiện hóa ngữ cảnh giữa các đoạn. Mặc định false. |
+| `beam_size` | Độ rộng tìm kiếm chùm. Cao hơn = chính xác hơn, chậm hơn. Mặc định 5. |
+| `best_of` | Số chuỗi ứng viên được đánh giá. Mặc định 5. |
+| `gpu_device` | Chỉ số thiết bị GPU cho hệ thống đa GPU. Mặc định 0. |
+| `processors` | Số bộ xử lý song song. Mặc định 1. |
+| `word_timestamps` | Một từ mỗi đoạn có dấu thời gian. Hữu ích cho căn chỉnh clip. |
+| `max_segment_length` | Độ dài đoạn tối đa tính bằng ký tự. |
+| `diarize` | Phân tách người nói stereo — yêu cầu âm thanh stereo với người nói trên các kênh riêng biệt. |
+| `vad_model` | Đường dẫn đến tệp .bin mô hình Silero VAD. Loại bỏ im lặng trước khi phiên âm — giảm ảo giác trên tệp nhiều tạp âm. |
+| `offset_t` | Độ lệch bắt đầu tính bằng mili giây. |
+| `duration` | Thời lượng xử lý tính bằng mili giây từ độ lệch. |
+
+---
+
+### `check_progress`
+Theo dõi tác vụ phiên âm nền được bắt đầu bằng `transcribe_audio` (background=true).
+
+Trả về thời gian đã trôi qua, dấu thời gian xử lý cuối cùng, phần trăm và bản phiên âm đầy đủ khi hoàn thành.
+
+| Tham số | Mô tả |
+|---|---|
+| `job_id` | ID tác vụ được trả về bởi `transcribe_audio` |
+
+---
+
+### `start_batch`
+Tự động phiên âm tuần tự tất cả tệp chưa phiên âm trong thư mục. Sắp xếp theo thời lượng (ngắn trước), xử lý từng tệp như tác vụ nền và xác nhận mỗi đầu ra.
+
+| Tham số | Mô tả |
+|---|---|
+| `folder_path` | Đường dẫn đến thư mục (bắt buộc) |
+| `language` | Mã ngôn ngữ. Mặc định: `en` |
+| `threads` | Ghi đè số luồng CPU |
+
+---
+
+### `check_batch_progress`
+Theo dõi một đợt đang chạy. Tự động chuyển sang tệp tiếp theo khi tệp hiện tại hoàn thành. Trả về tiến trình tổng thể, tệp hiện tại với dấu thời gian, ETA và các tệp thất bại.
+
+| Tham số | Mô tả |
+|---|---|
+| `batch_id` | ID đợt được trả về bởi `start_batch` |
+
+---
+
+### `transcribe_batch` (tương tác)
+Xử lý từng tệp một với xem trước và xác nhận trước mỗi tệp. Hữu ích khi bạn muốn xem xét trong quá trình thực hiện.
+
+| Tham số | Mô tả |
+|---|---|
+| `folder_path` | Đường dẫn đến thư mục (bắt buộc) |
+| `file_index` | Tệp cần xử lý (bắt đầu từ 1). Bỏ qua để liệt kê tệp trước. |
+| `language` | Mã ngôn ngữ. Mặc định: `en` |
+| `recursive` | Bao gồm các thư mục con |
+
+---
+
+### `generate_subtitles`
+Tạo tệp phụ đề SRT. Hỗ trợ tự động phát hiện ngôn ngữ và đầu ra dịch sang tiếng Anh.
+
+| Tham số | Mô tả |
+|---|---|
+| `file_path` | Đường dẫn đến tệp (bắt buộc) |
+| `language` | Mã ngôn ngữ hoặc `auto` để tự phát hiện. Mặc định: `en` |
+| `translate_to_english` | Cũng tạo `.en.srt` dịch sang tiếng Anh. Chỉ áp dụng khi nguồn không phải tiếng Anh. |
+| `threads` | Ghi đè số luồng CPU |
+
+Khi cả hai được yêu cầu, hai tệp được lưu bên cạnh nguồn:
+- `tenfile.vi.srt` — ngôn ngữ gốc
+- `tenfile.en.srt` — bản dịch tiếng Anh
+
+> Bản dịch tích hợp của Whisper chỉ dịch **sang tiếng Anh**. Để dịch sang ngôn ngữ khác, hãy xử lý nội dung tệp .srt riêng biệt.
+
+---
+
+### `analyze_media`
+Phân tích tệp trước khi phiên âm. Trả về thời lượng, kích thước, codec và thời gian phiên âm ước tính trên CPU và GPU. Với thư mục, hiển thị tất cả tệp trong bảng có thể sắp xếp kèm trạng thái phiên âm.
+
+| Tham số | Mô tả |
+|---|---|
+| `path` | Đường dẫn đến tệp đơn hoặc thư mục (bắt buộc) |
+| `sort_by` | Với thư mục: `duration` (mặc định), `name`, hoặc `size` |
+
+---
+
+### `check_config`
+Xác nhận whisper-cli.exe, tệp mô hình và FFmpeg đều có thể truy cập. Chạy lệnh này trước nếu có bất kỳ sự cố nào.
+
+---
+
+### `list_models`
+Liệt kê tất cả tệp mô hình Whisper đã cài đặt trong thư mục mô hình của bạn. Hiển thị tên tệp, kích thước, có đang hoạt động không, trạng thái lượng tử hóa và trường hợp sử dụng được khuyến nghị. Không gọi mạng — chỉ đọc hệ thống tệp cục bộ.
+
+---
+
+### `download_model`
+Tải xuống mô hình Whisper trực tiếp từ Hugging Face vào thư mục mô hình của bạn. Nhận tên mô hình (ví dụ: `large-v3-turbo`, `medium.en-q5_0`) và tự động xử lý việc tải xuống. Chỉ tải xuống từ các namespace Hugging Face đáng tin cậy. Sau khi tải xuống, sử dụng `switch_model` để kích hoạt.
+
+| Tham số | Mô tả |
+|---|---|
+| `model_name` | Tên mô hình cần tải xuống, ví dụ: `large-v3-turbo`, `large-v3-turbo-q5_0`, `medium.en-q5_0` |
+
+---
+
+### `switch_model`
+Chuyển mô hình Whisper đang hoạt động cho phiên hiện tại mà không cần khởi động lại Claude Desktop. Thay đổi chỉ có hiệu lực trong phiên — không lưu sau khi khởi động lại. Để thay đổi vĩnh viễn, cập nhật `WHISPER_MODEL` trong cấu hình của bạn.
+
+| Tham số | Mô tả |
+|---|---|
+| `model_name` | Tên tệp mô hình (ví dụ: `ggml-large-v3-turbo.bin`) hoặc đường dẫn đầy đủ. Phải là tệp `.bin` trong thư mục mô hình đã cấu hình. |
+
+---
+
+### `check_system`
+Phát hiện phần cứng GPU và xác nhận tăng tốc Vulkan có sẵn. Báo cáo tên GPU, VRAM, có `ggml-vulkan.dll` không và đề xuất kích thước mô hình tốt nhất cho phần cứng của bạn.
+
+---
+
+## Định dạng được hỗ trợ
+
+| Loại | Định dạng |
+|---|---|
+| Gốc (không cần chuyển đổi) | `mp3`, `wav` |
+| Video (tự động chuyển đổi qua FFmpeg) | `mp4`, `mkv`, `avi`, `mov`, `webm`, `flv`, `wmv`, `m4v`, `ts`, `3gp` |
+| Âm thanh (tự động chuyển đổi qua FFmpeg) | `m4a`, `ogg`, `flac` |
+
+---
+
+## Tăng tốc GPU
+
+Bản phát hành Vulkan đã biên dịch sẵn bật tăng tốc GPU tự động. Đã thử nghiệm trên AMD Radeon RX Vega 56 (GCN thế hệ 5). Bất kỳ GPU nào hỗ trợ Vulkan 1.0+ đều sẽ hoạt động, bao gồm NVIDIA và Intel Arc.
+
+**So sánh hiệu suất (mô hình medium.en, tệp âm thanh ~5 phút):**
+
+| Phần cứng | Thời gian |
+|---|---|
+| Chỉ CPU (Ryzen 7 2700x, 8 luồng) | 8–12 phút |
+| GPU (Vega 56 qua Vulkan) | 20–40 giây |
+
+Mức sử dụng GPU trong quá trình phiên âm thường là 15–20%, giảm về trạng thái nhàn rỗi giữa các tệp. CPU duy trì khoảng 15%.
+
+---
+
+## Hỗ trợ đa ngôn ngữ
+
+Whisper có thể tự động phát hiện ngôn ngữ được nói và phiên âm bằng ngôn ngữ đó. Mô hình dịch tích hợp chỉ dịch **sang tiếng Anh**.
+
+Để có độ chính xác đa ngôn ngữ tốt nhất, hãy sử dụng mô hình `large-v3`. Mô hình chỉ tiếng Anh (`*.en.bin`) không thể phát hiện hoặc phiên âm các ngôn ngữ khác.
+
+**Ví dụ — video nước ngoài có phụ đề:**
+1. Yêu cầu Claude tạo phụ đề với `language=auto` và `translate_to_english=true`
+2. Whisper phát hiện ngôn ngữ và tạo SRT ngôn ngữ gốc
+3. Lần xử lý thứ hai tạo SRT dịch sang tiếng Anh
+4. Tải tệp trong VLC qua Phụ đề → Thêm tệp phụ đề
+
+---
+
+## Thiết kế cho người dùng gói miễn phí
+
+Công cụ này được xây dựng để giảm thiểu các tương tác với Claude API. Toàn bộ quy trình phiên âm — quét, phân tích, xếp hàng, chạy, xác nhận — được thiết kế để yêu cầu ít tương tác Claude nhất có thể. Công việc nặng được thực hiện cục bộ trên máy của bạn.
+
+---
+
+## Biến môi trường tùy chọn
+
+| Biến | Mô tả |
+|---|---|
+| `WHISPER_CLI_PATH` | Đường dẫn đến whisper-cli.exe (bắt buộc) |
+| `WHISPER_MODEL` | Đường dẫn đến tệp mô hình .bin (bắt buộc) |
+| `WHISPER_THREADS` | Ghi đè số luồng CPU |
+| `FFMPEG_PATH` | Đường dẫn đến ffmpeg nếu không có trong PATH hệ thống |
+| `WHISPER_PRIVACY_MODE` | **Đang lên kế hoạch.** Khi đặt thành `true`, phản hồi công cụ chỉ trả về siêu dữ liệu — không có văn bản phiên âm nào được trả về cho Claude. Dành cho nội dung được quản lý hoặc bí mật. Xem [PRIVACY.md](PRIVACY.md). |
+
+---
+
+## Khắc phục sự cố
+
+Xem [TROUBLESHOOTING.md](TROUBLESHOOTING.md) để biết giải pháp chi tiết. Xem [PRIVACY.md](PRIVACY.md) nếu bạn xử lý nội dung được quản lý.
+
+Danh sách kiểm tra nhanh:
+- Đường dẫn trong cấu hình dùng **dấu gạch chéo ngược kép** (`C:\\whisper\\...`)
+- `whisper-cli.exe` tồn tại tại đường dẫn đã cấu hình
+- Tệp mô hình `.bin` tồn tại tại đường dẫn đã cấu hình
+- FFmpeg đã cài đặt và có trong PATH (`ffmpeg -version` hoạt động)
+- Claude Desktop đã được **khởi động lại hoàn toàn** sau khi chỉnh sửa cấu hình
+- Whisper hiển thị **đang chạy** (huy hiệu màu xanh) trong Cài đặt → Nhà phát triển
+
+---
+
+## Bảo mật và quyền riêng tư
+
+whisper-windows-mcp được thiết kế với bảo mật là nguyên tắc cốt lõi.
+
+**Âm thanh không bao giờ rời khỏi máy của bạn.** Không có tệp âm thanh hoặc video, đường dẫn tệp, hay dữ liệu đo lường nào được truyền đến bất kỳ máy chủ nào. Không cần API đám mây cho chức năng cốt lõi.
+
+**Văn bản phiên âm và ranh giới API.** Khi phản hồi công cụ bao gồm văn bản phiên âm, văn bản đó được xử lý bởi API của Claude — nó rời khỏi máy cục bộ của bạn. Đối với hầu hết người dùng (nội dung công khai, podcast, bản ghi phát trực tuyến) đây là hành vi bình thường. Nếu bạn xử lý bản ghi y tế, pháp lý, tài chính hoặc được quản lý khác, hãy xem [PRIVACY.md](PRIVACY.md) để biết hướng dẫn tuân thủ và các tùy chọn cấu hình.
+
+Biến môi trường `WHISPER_PRIVACY_MODE` đang được lên kế hoạch, sẽ giới hạn tất cả phản hồi công cụ chỉ có siêu dữ liệu (tên tệp, thời lượng, số từ) — không có văn bản phiên âm nào được trả về cho Claude. Đây là cấu hình chính xác cho nội dung được quản lý hoặc bí mật.
+
+**Xác thực đầu vào.** Tất cả đường dẫn tệp được xác thực trước khi sử dụng — đường dẫn UNC (`\\server\share`) và chuỗi duyệt thư mục (`..`) bị từ chối. Tệp trên 10 GB bị từ chối để ngăn cạn kiệt tài nguyên.
+
+**Nhận thức về tiêm nhiễm phiên âm.** Tệp âm thanh có thể chứa nội dung khi phiên âm trông giống như hướng dẫn. Các biện pháp phòng thủ tích hợp của Claude xử lý điều này, nhưng biết rằng nội dung phiên âm được coi là dữ liệu — không bao giờ là hướng dẫn — bởi chính máy chủ MCP cũng rất hữu ích.
+
+**Tải xuống mô hình bị hạn chế.** Công cụ `download_model` chỉ tải xuống từ hai namespace Hugging Face đáng tin cậy (`ggerganov/whisper.cpp` và `ggml-org`). URL tùy ý bị từ chối. Chuyển hướng được xác thực dựa trên danh sách cho phép trước khi tuân theo.
+
+**Chuyển đổi mô hình được sandbox hóa.** `switch_model` chỉ chấp nhận tệp `.bin` trong thư mục mô hình đã cấu hình. Đường dẫn ngoài thư mục đó bị từ chối.
+
+**Không có phụ thuộc mạng mới.** Tải xuống mô hình sử dụng `https` tích hợp sẵn của Node.js — không có thư viện HTTP bên ngoài nào được thêm vào gói.
+
+---
+
+## Giấy phép
+
+**Sử dụng phi thương mại:** MIT — miễn phí cho mục đích cá nhân, giáo dục và phi thương mại. Xem [LICENSE](LICENSE).
+
+**Sử dụng thương mại:** Cần có thỏa thuận giấy phép thương mại riêng cho bất kỳ mục đích kinh doanh, chuyên nghiệp hoặc tạo doanh thu nào. Xem [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md) để biết điều khoản và thông tin liên hệ.
+
+## Đóng góp
+
+Chào mừng pull request. Xem [ROADMAP.md](ROADMAP.md) để biết các tính năng đã lên kế hoạch.
+
+Nếu bạn đã thử nghiệm tăng tốc GPU trên phần cứng không được liệt kê ở trên, vui lòng mở issue với kết quả của bạn — mô hình GPU, VRAM, kích thước mô hình và thông lượng quan sát được.

package/ROADMAP.es.md

@@ -0,0 +1,200 @@
+# whisper-windows-mcp — Hoja de Ruta
+
+Versión actual: **v2.2.0**
+
+---
+
+## Principios de diseño
+
+Estos principios rigen cada decisión en este proyecto y tienen prioridad sobre la velocidad de adición de funcionalidades.
+
+**Minimizar el uso de la API de Claude.** Todo el flujo de trabajo de transcripción — escaneo, análisis, cola, ejecución, validación, cambio de modelos — debe ser ejecutable con el menor número posible de interacciones con Claude. Esta herramienta debe funcionar completamente para usuarios de Claude en el plan gratuito que no pagan por suscripciones Pro o Max. Cada llamada a herramienta consume presupuesto de uso. Diseña en consecuencia.
+
+**Siempre una única instancia de whisper.** Nunca crees un segundo proceso whisper-cli.exe mientras uno esté en ejecución. El bloqueo de proceso es obligatorio e innegociable.
+
+**Local primero, privado por defecto.** El audio nunca sale de la máquina. No se necesita ninguna API de nube para la funcionalidad principal. Las integraciones opcionales (ej.: descargas de modelos de Hugging Face) deben estar claramente documentadas como opcionales.
+
+**Control explícito del usuario.** Sin operaciones masivas silenciosas. Las acciones destructivas o irreversibles requieren confirmación. El usuario debe saber siempre qué va a ocurrir antes de que ocurra.
+
+**Rutas seguras para Unicode.** Toda E/S de archivo debe manejar correctamente nombres de archivo no-ASCII, incluyendo español, japonés, chino, emoji, corchetes y otros caracteres especiales.
+
+**Modular y combinable.** Las herramientas son independientes. Los usuarios usan lo que necesitan. Ninguna funcionalidad debe requerir otra, a menos que sea inevitable.
+
+**Optimización antes que funcionalidades.** Cuando haya dudas entre agregar una funcionalidad y reducir la carga del sistema o el número de llamadas a la API, reduce la carga. Las sesiones de optimización grandes son costosas. Diseña la arquitectura correctamente desde el principio.
+
+---
+
+## Completado
+
+### ✅ v1.3.1 — Bloqueo de proceso
+Añadida verificación `isWhisperRunning()` usando `tasklist /FI` antes de crear cualquier proceso de transcripción. Devuelve un error claro con instrucciones del Administrador de Tareas en lugar de crear un proceso concurrente.
+
+### ✅ v1.4.0 — Aceleración GPU Vulkan
+Compilado whisper.cpp desde el código fuente con `-DGGML_VULKAN=ON` usando VS Build Tools 2022 y Vulkan SDK. Binarios Vulkan precompilados distribuidos como `whisper-vulkan-win-x64.zip`.
+
+**Resultados en AMD Radeon RX Vega 56:** Utilización media de GPU ~16%. Archivo de 58 minutos completado en ~4,5 minutos en GPU vs. ~88 minutos solo en CPU.
+
+### ✅ v1.5.0 — Diagnóstico del sistema
+Herramienta `check_system`: detección de GPU via `wmic`, verificación de DLL Vulkan, reporte de VRAM, recomendación de tamaño de modelo.
+
+### ✅ v1.6.0 — Pre-análisis de archivo
+Herramienta `analyze_media` via FFprobe: duración, tamaño, códec, estado de transcripción, estimaciones de tiempo de CPU y GPU. Escaneo de archivo único o carpeta con opciones de ordenación.
+
+### ✅ v1.7.0 — Transcripción en segundo plano + Visibilidad del progreso
+Arquitectura de proceso desconectado: `transcribe_audio` con `background=true` crea whisper como proceso desconectado y devuelve inmediatamente un ID de tarea. `check_progress` analiza las marcas de tiempo de segmento del stderr de whisper para porcentaje y ETA en tiempo real.
+
+### ✅ v1.8.0 — Lote secuencial con validación
+`start_batch` y `check_batch_progress`: procesamiento secuencial automático, validación de transcripción (detección de salida vacía/corta), avance automático de cola, marcas de tiempo de progreso por archivo.
+
+### ✅ v1.9.0 — Soporte multilingüe y traducción
+`generate_subtitles` con detección `language=auto` y salida SRT doble `translate_to_english=true`. Añadido soporte para formatos `.3gp` y `.ts`. `language=auto` también disponible en `transcribe_audio`.
+
+**Limitación conocida:** La traducción integrada de Whisper solo apunta al inglés. Requiere modelo `large-v3` para idiomas que no sean inglés — los modelos solo inglés (`*.en.bin`) generan `[FOREIGN]` en audio que no sea inglés.
+
+### ✅ v2.0.0 — Rutas seguras para Unicode + SRT en segundo plano
+**Nombres de archivo Unicode:** Los archivos con caracteres no-ASCII en los nombres causaban fallos silenciosos en la transcripción en segundo plano. Corregido enrutando toda la salida a través de una ruta temporal saneada basada en ID de tarea, luego moviendo el resultado al destino correcto tras completarse.
+
+**SRT en modo en segundo plano:** `spawnDetached` anteriormente codificaba de forma rígida `-otxt` independientemente del formato solicitado, y `generate_subtitles` bloqueaba de forma síncrona y alcanzaba el timeout de MCP de 4 minutos en archivos más largos. Corregido añadiendo parámetro `outputFormat` a `spawnDetached`, soportando salida `text` y `srt` en modo en segundo plano.
+
+### ✅ v2.0.1 — Correcciones de bugs (incluido en v2.2.0)
+- `--max-context 0` fijo en `buildArgs` y `spawnDetached` — previene bucles de alucinación en audio largo.
+- `--no-speech-thold 0.6` fijo en ambas funciones — segmentos por debajo del umbral de confianza son tratados como silencio.
+- Validación de ruta (`validateInputPath`) — rechaza rutas UNC y traversales `..`.
+- Guarda de tamaño de archivo `MAX_FILE_SIZE_MB = 10240`.
+- Comentario de seguridad de inyección de transcripción en `transcribeSingle`.
+- Comando CLI de lote corregido en TROUBLESHOOTING.md.
+
+### ✅ v2.1.0 — Suite de gestión de modelos (incluido en v2.2.0)
+- `WHISPER_MODEL` cambiado de `const` a `let` (mutable dentro de la sesión).
+- `MODEL_REGISTRY` — 16 modelos, variantes de precisión total y cuantizadas, URLs de descarga de Hugging Face.
+- `ALLOWED_HF_PREFIXES` — lista de permitidos de URL que limita las descargas a los espacios de nombres `ggerganov/whisper.cpp` y `ggml-org`.
+- Herramienta `list_models` — escanea el directorio de modelos, muestra el modelo activo, tamaños, casos de uso, descargas disponibles.
+- Herramienta `download_model` — descarga de Hugging Face via `https` integrado de Node.js, renombrado atómico.
+- Herramienta `switch_model` — valida extensión `.bin`, restricción de directorio, verificación de bloqueo de proceso.
+- `recommendedModel()` actualizado para recomendar `large-v3-turbo` para VRAM de 6GB+.
+
+### ✅ v2.2.0 — Expansión de calidad, parámetros y hardware (actual)
+- Interfaz `WhisperOptions` reemplazando argumentos posicionales en `buildArgs`.
+- Nuevos parámetros en `transcribe_audio`: `temperature`, `prompt`, `condition_on_prev_text`, `no_speech_thold`, `beam_size`, `best_of`, `gpu_device`, `processors`, `word_timestamps`, `max_segment_length`, `split_on_word`, `diarize`, `vad_model`, `offset_t`, `duration`.
+- Nuevos parámetros en `generate_subtitles`: `temperature`, `prompt`, `beam_size`, `best_of`, `diarize`, `vad_model`.
+- `spawnDetached` refactorizado — todos los flags de calidad ahora se aplican en modo en segundo plano/lote.
+- Salida de lote corregida — `readBatchProgress` ahora mueve la salida temporal al destino final antes de validar.
+
+---
+
+## Bug crítico — Avance automático del lote (confirmado, pendiente de corrección)
+
+### El lote no avanza sin polling activo
+
+`start_batch` no avanza la cola de forma autónoma entre archivos. El lote solo avanza cuando se llama a `check_batch_progress`. Sin polling, el lote se detiene indefinidamente tras cada archivo.
+
+**Corrección planificada — Opción B (callback de salida):** Adjuntar un handler `on('exit')` al proceso hijo whisper-cli creado. Cuando el proceso salga, llamar inmediatamente a la lógica de avance para validar la salida y crear la siguiente tarea.
+
+**Solución alternativa (actual):** Llama a `check_batch_progress` repetidamente hasta que el lote se complete.
+
+---
+
+## Planificado — Arquitectura de Privacidad (antes de la migración a Bun)
+
+### Variable de entorno `WHISPER_PRIVACY_MODE`
+Añadir `WHISPER_PRIVACY_MODE` como variable de entorno en `claude_desktop_config.json`. Cuando esté activado, todas las respuestas de herramientas solo devuelven metadatos — ningún texto de transcripción incluido en ninguna respuesta.
+
+### Gateway de consentimiento para contenido de transcripción
+Cuando `WHISPER_PRIVACY_MODE` no está activado (predeterminado), cualquier respuesta de herramienta que incluya texto de transcripción debe estar precedida de una divulgación en el primer uso por sesión.
+
+### Documentación `PRIVACY.md`
+Crear `PRIVACY.md` en la raíz del repositorio con orientación completa de privacidad y marcos de cumplimiento.
+
+### Limpieza automática del directorio temporal
+Añadir limpieza automática de archivos de tareas completadas tras un período de retención configurable (predeterminado: 7 días).
+
+---
+
+## Planificado — Migración a Bun
+
+Migrar el runtime de Node.js a [Bun](https://bun.sh) tras la conclusión de la arquitectura de privacidad y antes de las adiciones de funcionalidades del v2.3.0. El Bun ejecuta TypeScript nativamente sin paso de compilación, inicia significativamente más rápido que Node y tiene E/S más rápida.
+
+---
+
+## Licenciamiento
+
+whisper-windows-mcp usa licencia dual.
+
+**Uso no comercial:** MIT — gratuito para uso personal, educativo y no comercial. Ver [LICENSE](LICENSE).
+
+**Uso comercial:** Se requiere un acuerdo de licencia comercial separado. Ver [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md).
+
+`WHISPER_PRIVACY_MODE` para implementaciones en sectores regulados está en desarrollo y planificado para una versión futura. Ver [PRIVACY.md](PRIVACY.md) para orientación actual.
+
+## Planificado — v2.3.0: Expansión de formatos de salida
+
+### Formato de subtítulos VTT
+Salida WebVTT (`.vtt`) junto con SRT. Estándar web usado por YouTube, HTML5 `<video>` y la mayoría de los reproductores modernos.
+
+### Formato LRC
+Salida en formato LRC (`.lrc`) de letras/karaoke via `-olrc`.
+
+### Formato CSV
+Salida CSV (`.csv`) via `-ocsv`. Datos tabulares estructurados con timing de segmentos.
+
+---
+
+## Planificado — Releases futuros
+
+### TinyDiarize
+Soporte al flag `--tinydiarize` con variantes de modelo que soportan `tdrz`. Funciona en grabaciones mono a diferencia del flag `--diarize` estéreo.
+
+### Transcripción de URL de YouTube
+Transcripción directa desde URLs de YouTube via yt-dlp. Requiere yt-dlp instalado y en el PATH.
+
+### Herramientas de flujo de trabajo de proyecto de video
+Para usuarios que gestionan proyectos grandes de edición de video con directorios de clips fuente y editados. Los archivos fuente nunca son renombrados ni modificados sin confirmación explícita del usuario.
+
+### Diarización de hablantes (pyannote-audio)
+Diarización de hablantes mono completa con etiquetas de ID de hablante. Requiere pyannote-audio — biblioteca basada en Python con requisito de token de acceso a modelos de Hugging Face.
+
+### Traducción a idiomas que no sean inglés
+El flag `--translate` de Whisper solo apunta al inglés. Soportar idiomas de destino arbitrarios requiere una API de traducción externa o modelo de traducción local.
+
+### Limpieza y formateo de transcripciones
+Pipeline de post-procesamiento: eliminación de muletillas, saltos de párrafo en límites de temas naturales, formateo con conciencia de hablante, exportación a PDF o DOCX.
+
+---
+
+## Distribución
+
+Disponible en [npm](https://www.npmjs.com/package/whisper-windows-mcp), [mcpservers.org](https://mcpservers.org) y [Glama](https://glama.ai).
+
+---
+
+## Documentación multilingüe
+
+La documentación en japonés, coreano, vietnamita, indonesio, ucraniano, portugués brasileño y español se mantiene en paralelo con el inglés. Los siguientes archivos deben ser actualizados para coincidir con los documentos en inglés tras cada release:
+
+**Japonés (`*.ja.md`)** — `README.ja.md` / `TROUBLESHOOTING.ja.md` / `ROADMAP.ja.md` / `PRIVACY.ja.md` / `SECURITY.ja.md`
+
+**Coreano (`*.ko.md`)** — `README.ko.md` / `TROUBLESHOOTING.ko.md` / `ROADMAP.ko.md` / `PRIVACY.ko.md` / `SECURITY.ko.md`
+
+**Vietnamita (`*.vi.md`)** — `README.vi.md` / `TROUBLESHOOTING.vi.md` / `ROADMAP.vi.md` / `PRIVACY.vi.md` / `SECURITY.vi.md`
+
+**Indonesio (`*.id.md`)** — `README.id.md` / `TROUBLESHOOTING.id.md` / `ROADMAP.id.md` / `PRIVACY.id.md` / `SECURITY.id.md`
+
+**Ucraniano (`*.uk.md`)** — `README.uk.md` / `TROUBLESHOOTING.uk.md` / `ROADMAP.uk.md` / `PRIVACY.uk.md` / `SECURITY.uk.md`
+
+**Portugués Brasileño (`*.pt-BR.md`)** — `README.pt-BR.md` / `TROUBLESHOOTING.pt-BR.md` / `ROADMAP.pt-BR.md` / `PRIVACY.pt-BR.md` / `SECURITY.pt-BR.md`
+
+**Español (`*.es.md`)** — `README.es.md` / `TROUBLESHOOTING.es.md` / `ROADMAP.es.md` / `PRIVACY.es.md` / `SECURITY.es.md`
+
+**Polish (`*.pl.md`)** — `README.pl.md` / `TROUBLESHOOTING.pl.md` / `ROADMAP.pl.md` / `PRIVACY.pl.md` / `SECURITY.pl.md`
+
+**Romanian (`*.ro.md`)** — `README.ro.md` / `TROUBLESHOOTING.ro.md` / `ROADMAP.ro.md` / `PRIVACY.ro.md` / `SECURITY.ro.md`
+
+Las contribuciones de la comunidad para otros idiomas son bienvenidas.
+
+---
+
+## Contribuciones
+
+Los pull requests son bienvenidos. Revisa las issues existentes antes de comenzar a trabajar.
+
+Si has probado la aceleración por GPU en hardware no listado arriba, abre una issue con el modelo de GPU, VRAM, tamaño de modelo y throughput observado.