whisper-windows-mcp 2.2.0 → 2.2.2

package/TROUBLESHOOTING.uk.md

@@ -0,0 +1,323 @@
+# whisper-windows-mcp — Усунення несправностей
+
+---
+
+## Швидкий контрольний список
+
+Перед детальнішим розслідуванням перевірте все нижченаведене:
+
+- Шляхи в `claude_desktop_config.json` використовують **подвійний зворотній слеш** (`C:\\whisper\\...`)
+- `whisper-cli.exe` існує за шляхом, вказаним у `WHISPER_CLI_PATH`
+- Файл моделі `.bin` існує за шляхом, вказаним у `WHISPER_MODEL`
+- FFmpeg встановлено і доступно (`ffmpeg -version` працює в командному рядку)
+- Claude Desktop **повністю перезапущено** після редагування конфігурації (завершено з системного трея, а не просто закрито вікно)
+- Сервер whisper відображається як **запущено** (зелений значок) у Налаштуваннях → Розробник
+
+---
+
+## "whisper не підключено" або інструменти недоступні
+
+**Найпоширеніша причина:** Claude Desktop не було повністю перезапущено після редагування конфігурації.
+
+1. Клацніть правою кнопкою миші на значку Claude в системному треї → Вийти
+2. Повторно відкрийте Claude Desktop
+3. Перейдіть до Налаштувань → Розробник і перевірте наявність зеленого значка **запущено** поруч з whisper
+
+Якщо все одно не відображається:
+
+1. Відкрийте `claude_desktop_config.json` і перевірте синтаксичні помилки JSON (відсутні коми, незбалансовані дужки)
+2. Переконайтеся, що всі шляхи використовують подвійний зворотній слеш
+3. Виконайте `check_config` у Claude Desktop, щоб отримати діагностичну інформацію
+
+---
+
+## download_model завершується тайм-аутом для великих моделей
+
+Claude Desktop має 4-хвилинний тайм-аут для викликів інструментів MCP. Завантаження великих моделей на повільному з'єднанні може перевищити цей ліміт.
+
+**Розміри файлів:**
+- `large-v3` — 2.9 ГБ
+- `large-v3-turbo` — 1.6 ГБ
+- `large-v3-q5_0` — 1.1 ГБ
+- `large-v3-turbo-q5_0` — 547 МБ
+- `medium.en` — 1.5 ГБ
+- `medium.en-q5_0` — 514 МБ
+
+На швидкому з'єднанні (100 Мбіт/с і вище) навіть large-v3 завантажується менш ніж за 4 хвилини. На повільніших з'єднаннях використовуйте браузер або PowerShell для прямого завантаження і помістіть файл у теку моделей вручну:
+
+```powershell
+# Приклад — пряме завантаження large-v3-turbo
+Invoke-WebRequest -Uri "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin" `
+  -OutFile "C:\whisper\models\ggml-large-v3-turbo.bin"
+```
+
+Потім активуйте через `switch_model ggml-large-v3-turbo.bin`.
+
+---
+
+## `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 встановлено в нестандартному місці, задайте змінну середовища `FFMPEG_PATH` у конфігурації Claude Desktop:
+```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"
+```
+
+Або перевизначте для кожної транскрипції окремо за допомогою параметра `model` у `transcribe_audio` або `generate_subtitles`.
+
+> **Примітка:** Моделі лише для англійської (`*.en.bin`) швидші і точніші для англійського контенту, але абсолютно не можуть опрацьовувати інші мови. Якщо ви працюєте з багатомовним контентом, `large-v3` — правильна модель незалежно від апаратного забезпечення.
+
+---
+
+## Транскрипція не дає результату або порожній файл
+
+**Можливі причини:**
+
+1. **Неправильна модель для мови** — Моделі лише для англійської (`*.en.bin`) не можуть транскрибувати інші мови. Використовуйте `ggml-large-v3.bin` для багатомовного контенту.
+
+2. **Надто низька якість аудіо** — Файли з дуже низьким бітрейтом (наприклад, старі `.3gp` записи телефону з кодеком AMR-NB ~12 Кбіт/с) можуть бути на межі можливостей whisper. Шумні середовища (фоновий шум, луна, далекі доповідачі) також є проблематичними. Спробуйте `large-v3`, який краще справляється з деградованим аудіо.
+
+3. **Файл тихий або пошкоджений** — Запустіть `analyze_media` для файлу, щоб перевірити, чи FFprobe виявляє дійсний аудіопотік.
+
+4. **Помилка конвертування** — Файл може не конвертуватися у WAV правильно. Спробуйте конвертувати вручну:
+```
+ffmpeg -i yourfile.3gp -ar 16000 -ac 1 output.wav
+```
+Потім транскрибуйте WAV напряму.
+
+---
+
+## Фонове завдання не виконується для файлів з Unicode або спеціальними символами в назві
+
+**Причина:** whisper-cli.exe не може записати вихідний файл, коли шлях містить символи Unicode (українські, японські, китайські, емодзі, дужки тощо) або певні спеціальні символи.
+
+**Поточне обхідне рішення:** Перейменуйте файл, щоб використовувати лише ASCII-символи перед транскрипцією, а потім, якщо потрібно, перейменуйте назад.
+
+```
+ren "назва_файлу.mp4" "temp_transcribe.mp4"
+```
+
+**Статус:** Це відомий баг. Планується виправлення, яке буде спрямовувати вивід через санованный тимчасовий шлях і переміщати результат до правильного призначення після завершення.
+
+---
+
+## Фонове завдання показує "помилку" без результату
+
+**Можливі причини:**
+
+1. **Ім'я файлу з Unicode** — Дивіться вище.
+
+2. **Неправильний шлях до моделі** — Відокремлений процес не успадковує виправлені шляхи. Виконайте `check_config` для перевірки шляхів.
+
+3. **Процес було примусово завершено** — Якщо whisper-cli.exe було вручну зупинено під час завдання, вихідного файлу не буде. Повторіть спробу.
+
+4. **Недостатньо VRAM** — Великі моделі на GPU з малим VRAM можуть тихо зазнавати збоїв. Спробуйте меншу модель.
+
+5. **Помилка конвертування файлу** — Спробуйте транскрибувати WAV-файл напряму, щоб з'ясувати, чи проблема у конвертуванні чи у транскрипції.
+
+---
+
+## Фонова транскрипція не створює вихідний SRT
+
+**Причина:** Фоновий режим (`background=true` у `transcribe_audio`) наразі виробляє лише `.txt`-вивід. Формат SRT у фоновому режимі ще не реалізовано.
+
+**Обхідне рішення:** Для файлів менше ~4 хвилин використовуйте `generate_subtitles` у блокувальному режимі. Для довших файлів спочатку транскрибуйте у фоновому режимі, щоб отримати `.txt`, а потім, якщо потрібен SRT, виконайте `generate_subtitles` для того самого файлу (буде транскрибовано знову).
+
+**Статус:** Підтримку SRT у фоновому режимі заплановано у майбутньому релізі.
+
+---
+
+## GPU не використовується (CPU постійно понад 50%)
+
+**Причина:** Ви запускаєте бінарник лише для CPU, що постачається зі стандартним релізом whisper.cpp.
+
+**Виправлення:** Завантажте збірку з підтримкою Vulkan зі [сторінки релізів](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0) і розпакуйте в `C:\whisper\Release\`.
+
+Перевірте, чи активне прискорення GPU:
+- Попросіть Claude виконати `check_system`
+- Знайдіть `✅ Vulkan binary: ggml-vulkan.dll found` у виведенні
+- Спостерігайте за Диспетчером завдань → Продуктивність → GPU під час транскрипції — навантаження GPU має зрости до 15–30%
+
+---
+
+## `check_system` показує неправильний обсяг VRAM
+
+Це відоме обмеження Windows. Команда `wmic` зчитує VRAM з реєстру, і на багатьох картах AMD відображає половину фізичного VRAM. Vega 56 з 8 ГБ HBM2 зазвичай показуватиме 4 ГБ. Це лише проблема відображення — whisper використовує весь фізичний VRAM під час виводу.
+
+---
+
+## Помилка "Транскрипція вже виконується"
+
+Запущений процес `whisper-cli.exe` від попереднього завдання. Зачекайте його завершення або:
+
+1. Відкрийте Диспетчер завдань → вкладка Відомості
+2. Знайдіть `whisper-cli.exe`
+3. Клацніть правою кнопкою миші → Завершити завдання
+
+Потім повторіть спробу.
+
+---
+
+## Автовизначення мови дає неправильний результат
+
+Автовизначення Whisper виконується за першими 30 секундами аудіо. Якщо файл починається іншою мовою, ніж більшість його вмісту, визначення може бути неправильним.
+
+**Виправлення:** Вкажіть мову явно (наприклад `language=uk`), а не покладайтеся на автовизначення.
+
+---
+
+## Створення субтитрів дає "(говорить іноземною мовою)" по всьому відео
+
+Whisper виявив мовлення, але не може транскрибувати. Найпоширеніші причини:
+
+1. **Неправильна модель** — Використання моделі лише для англійської для не-англійського аудіо. Використовуйте `large-v3`.
+
+2. **Якість аудіо** — Шумні середовища (кухні, натовп, луна) можуть бути складними для моделі medium. Спробуйте `large-v3`.
+
+3. **Змішані мови** — Файли з двома мовами, що чергуються, матимуть меншоживану мову замінену заповнювачем при налаштуванні однієї мови.
+
+---
+
+## Переклад субтитрів дає лише англійський вивід
+
+Це навмисна поведінка. Вбудований прапорець `--translate` Whisper перекладає **лише на англійську**. Для перекладу на інші цільові мови опрацьовуйте вміст `.srt`-файлу окремо.
+
+---
+
+## Пакетна транскрипція зупинила просування
+
+Знову викличте `check_batch_progress`. Якщо все ще зависло:
+
+1. Перевірте Диспетчер завдань на наявність запущеного процесу `whisper-cli.exe`
+2. Перевірте журнали завдань у `%TEMP%\whisper-mcp-jobs\`
+3. Файли зі збоями позначені у звіті пакету — запустіть їх окремо через `transcribe_audio`
+
+---
+
+## Очищення тимчасової теки завдань
+
+whisper-windows-mcp записує файли стану завдань і журнали до `%TEMP%\whisper-mcp-jobs\` під час транскрипції. Вони накопичуються з часом і можуть займати місце на диску, особливо файли `.log` від тривалих завдань транскрипції.
+
+Після завершення пакету або завдання і підтвердження вихідних транскрипцій ви можете безпечно видалити все в цій теці:
+
+```powershell
+Remove-Item "$env:TEMP\whisper-mcp-jobs\*" -Recurse -Force
+```
+
+Теку буде автоматично відтворено під час наступної транскрипції. Жодні вихідні файли транскрипцій не зберігаються тут постійно — вони переміщуються до вихідної теки після завершення. Залишаються лише метадані завдань і журнали.
+
+**Примітка:** Не видаляйте цю теку під час виконання транскрипції — файли стану пакету необхідні для роботи `check_batch_progress`.
+
+---
+
+## Великий автономний пакет з командного рядка
+
+Для дуже великих пакетів, де ви хочете запустити нічну роботу без Claude, використовуйте PowerShell.
+
+**Важливо:** whisper-cli.exe не може безпосередньо читати MP4, MKV або більшість відеоформатів. FFmpeg повинен заздалегідь конвертувати кожен файл у WAV. whisper також записує транскрипцію у stdout, а діагностичний вивід — у stderr — використовуйте `Start-Process -RedirectStandardOutput` для правильного захоплення транскрипції. Використання pipe `|` або перенаправлення stderr через `2>$null` не захоплює нічого.
+
+```powershell
+$whisper = "C:\whisper\Release\whisper-cli.exe"
+$model   = "C:\whisper\models\ggml-medium.en.bin"
+$dir     = "C:\path\to\your\folder"
+$ffmpeg  = "ffmpeg"
+$tmp     = "$env:TEMP\whisper_convert.wav"
+
+Get-ChildItem "$dir\*.mp4" | ForEach-Object {
+    $out = ($_.FullName -replace '\.mp4$', '') + ".txt"
+    if (Test-Path $out) {
+        Write-Host "SKIP (exists): $($_.Name)"
+        return
+    }
+    Write-Host "Converting:    $($_.Name)"
+    & $ffmpeg -y -i $_.FullName -ar 16000 -ac 1 -c:a pcm_s16le $tmp 2>$null
+    Write-Host "Transcribing:  $($_.Name)"
+    $wArgs = "-m `"$model`" -f `"$tmp`" --threads 8 --condition-on-previous-text 0 --no-speech-thold 0.6"
+    Start-Process -FilePath $whisper -ArgumentList $wArgs -RedirectStandardOutput $out -Wait -NoNewWindow
+    Write-Host "Done:          $($_.BaseName).txt"
+}
+
+Remove-Item $tmp -ErrorAction SilentlyContinue
+Write-Host "All done."
+```
+
+Замініть `*.mp4` на `*.mkv`, `*.m4a` тощо відповідно до типів ваших файлів. Перевірка пропуску `Test-Path` означає, що повторний запуск скрипту після переривання не переопрацьовуватиме вже завершені файли.
+
+Це записує `.txt`-файли поруч з кожним джерелом. Інструменти MCP розпізнають їх як вже транскрибовані, коли ви потім виконаєте `analyze_media` або `start_batch`.
+
+---
+
+## Розташування файлу конфігурації
+
+```
+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/TROUBLESHOOTING.vi.md

@@ -0,0 +1,323 @@
+# whisper-windows-mcp — Khắc phục sự cố
+
+---
+
+## Danh sách kiểm tra nhanh
+
+Trước khi tìm hiểu sâu hơn, hãy xác nhận tất cả những điều sau:
+
+- Đường dẫn trong `claude_desktop_config.json` 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 chỉ định trong `WHISPER_CLI_PATH`
+- Tệp mô hình `.bin` tồn tại tại đường dẫn được chỉ định trong `WHISPER_MODEL`
+- FFmpeg đã cài đặt và có thể truy cập (`ffmpeg -version` hoạt động trong command prompt)
+- Claude Desktop đã được **khởi động lại hoàn toàn** sau khi chỉnh sửa cấu hình (thoát từ system tray, không chỉ đóng cửa sổ)
+- Máy chủ whisper hiển thị **đang chạy** (huy hiệu màu xanh) trong Cài đặt → Nhà phát triển
+
+---
+
+## "whisper không được kết nối" hoặc không có công cụ nào
+
+**Nguyên nhân phổ biến nhất:** Claude Desktop không được khởi động lại hoàn toàn sau khi chỉnh sửa cấu hình.
+
+1. Nhấp chuột phải vào biểu tượng Claude trong system tray → Thoát
+2. Mở lại Claude Desktop
+3. Đi đến Cài đặt → Nhà phát triển và kiểm tra huy hiệu **đang chạy** màu xanh bên cạnh whisper
+
+Nếu vẫn không hiển thị:
+
+1. Mở `claude_desktop_config.json` và kiểm tra lỗi cú pháp JSON (thiếu dấu phẩy, dấu ngoặc không khớp)
+2. Đảm bảo tất cả đường dẫn dùng dấu gạch chéo ngược kép
+3. Chạy `check_config` trong Claude Desktop để nhận thông tin chẩn đoán
+
+---
+
+## download_model bị timeout với mô hình lớn
+
+Claude Desktop có thời gian timeout 4 phút cho các lệnh gọi công cụ MCP. Tải xuống mô hình lớn trên kết nối chậm có thể vượt quá giới hạn này.
+
+**Kích thước tệp:**
+- `large-v3` — 2.9 GB
+- `large-v3-turbo` — 1.6 GB
+- `large-v3-q5_0` — 1.1 GB
+- `large-v3-turbo-q5_0` — 547 MB
+- `medium.en` — 1.5 GB
+- `medium.en-q5_0` — 514 MB
+
+Trên kết nối nhanh (100 Mbps+), ngay cả large-v3 cũng tải trong vòng 4 phút. Trên kết nối chậm hơn, hãy dùng trình duyệt hoặc PowerShell để tải trực tiếp và đặt tệp vào thư mục mô hình thủ công:
+
+```powershell
+# Ví dụ — tải trực tiếp large-v3-turbo
+Invoke-WebRequest -Uri "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin" `
+  -OutFile "C:\whisper\models\ggml-large-v3-turbo.bin"
+```
+
+Sau đó dùng `switch_model ggml-large-v3-turbo.bin` để kích hoạt.
+
+---
+
+## `check_config` báo không tìm thấy whisper-cli.exe
+
+Đường dẫn trong cấu hình không khớp với vị trí thực tế của tệp.
+
+Xác nhận tệp tồn tại:
+```
+dir C:\whisper\Release\whisper-cli.exe
+```
+
+Nếu ở vị trí khác, hãy cập nhật `WHISPER_CLI_PATH` trong cấu hình để khớp với đường dẫn thực tế.
+
+---
+
+## `check_config` báo không tìm thấy FFmpeg
+
+FFmpeg chưa được cài đặt hoặc không có trong PATH hệ thống.
+
+Cài đặt qua winget:
+```
+winget install ffmpeg
+```
+
+Hoặc tải xuống từ [ffmpeg.org](https://ffmpeg.org/download.html), giải nén và thêm thư mục `bin` vào PATH hệ thống.
+
+Sau khi cài đặt, mở command prompt mới và xác nhận:
+```
+ffmpeg -version
+```
+
+Nếu bạn cài FFmpeg ở vị trí không chuẩn, hãy đặt biến môi trường `FFMPEG_PATH` trong cấu hình Claude Desktop:
+```json
+"env": {
+  "FFMPEG_PATH": "C:\\ffmpeg\\bin\\ffmpeg.exe"
+}
+```
+
+---
+
+## Kết quả phiên âm đầy thẻ `[FOREIGN]`
+
+**Nguyên nhân:** Bạn đang dùng mô hình chỉ tiếng Anh (ví dụ: `ggml-medium.en.bin`) với âm thanh không phải tiếng Anh. Mô hình chỉ tiếng Anh không thể xử lý các ngôn ngữ khác và xuất ra `[FOREIGN]` cho mọi đoạn không thể xử lý.
+
+**Cách sửa:** Tải xuống và sử dụng `ggml-large-v3.bin` — mô hình đa ngôn ngữ. Đây là yêu cầu bắt buộc cho bất kỳ phiên âm không phải tiếng Anh, tự động phát hiện ngôn ngữ hoặc dịch nào.
+
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin
+```
+
+Lưu vào `C:\whisper\models\` và cập nhật cấu hình:
+```json
+"WHISPER_MODEL": "C:\\whisper\\models\\ggml-large-v3.bin"
+```
+
+Hoặc ghi đè từng lần phiên âm bằng tham số `model` trong `transcribe_audio` hoặc `generate_subtitles`.
+
+> **Lưu ý:** Mô hình chỉ tiếng Anh (`*.en.bin`) nhanh hơn và chính xác hơn cho nội dung tiếng Anh nhưng hoàn toàn không thể xử lý các ngôn ngữ khác. Nếu bạn làm việc với nội dung đa ngôn ngữ, `large-v3` là mô hình đúng bất kể phần cứng.
+
+---
+
+## Phiên âm không tạo ra đầu ra hoặc tệp trống
+
+**Nguyên nhân có thể:**
+
+1. **Mô hình sai cho ngôn ngữ** — Mô hình chỉ tiếng Anh (`*.en.bin`) không thể phiên âm các ngôn ngữ khác. Sử dụng `ggml-large-v3.bin` cho nội dung đa ngôn ngữ.
+
+2. **Chất lượng âm thanh quá thấp** — Tệp có bitrate rất thấp (ví dụ: bản ghi điện thoại `.3gp` cũ dùng codec AMR-NB ~12kbps) có thể ở ranh giới whisper có thể xử lý. Môi trường nhiều tạp âm (tiếng ồn nền, vang, người nói xa) cũng gặp khó khăn. Hãy thử `large-v3` vì nó xử lý âm thanh kém chất lượng tốt hơn các mô hình nhỏ.
+
+3. **Tệp im lặng hoặc bị hỏng** — Chạy `analyze_media` trên tệp để kiểm tra xem FFprobe có phát hiện luồng âm thanh hợp lệ không.
+
+4. **Lỗi chuyển đổi** — Tệp có thể không chuyển đổi sang WAV đúng cách. Thử chuyển đổi thủ công trước:
+```
+ffmpeg -i yourfile.3gp -ar 16000 -ac 1 output.wav
+```
+Sau đó phiên âm tệp WAV trực tiếp.
+
+---
+
+## Tác vụ nền thất bại với tên tệp chứa ký tự đặc biệt hoặc Unicode
+
+**Nguyên nhân:** whisper-cli.exe không thể ghi tệp đầu ra khi đường dẫn chứa ký tự Unicode (tiếng Việt, tiếng Nhật, tiếng Hàn, emoji, dấu ngoặc, v.v.) hoặc một số ký tự đặc biệt nhất định.
+
+**Giải pháp tạm thời hiện tại:** Đổi tên tệp để chỉ dùng ký tự ASCII trước khi phiên âm, sau đó đổi lại nếu cần.
+
+```
+ren "ten_file_tieng_viet.mp4" "temp_transcribe.mp4"
+```
+
+**Trạng thái:** Đây là lỗi đã biết. Đang lên kế hoạch sửa bằng cách định tuyến đầu ra qua đường dẫn tạm thời đã làm sạch và di chuyển kết quả đến đích chính xác sau khi hoàn thành.
+
+---
+
+## Tác vụ nền hiển thị "thất bại" không có đầu ra
+
+**Nguyên nhân có thể:**
+
+1. **Tên tệp Unicode** — Xem ở trên.
+
+2. **Đường dẫn mô hình sai** — Tiến trình tách rời không kế thừa đường dẫn đã sửa. Chạy `check_config` để xác nhận đường dẫn.
+
+3. **Tiến trình bị tắt** — Nếu whisper-cli.exe bị tắt thủ công giữa chừng, sẽ không có tệp đầu ra. Thử lại.
+
+4. **VRAM không đủ** — Mô hình lớn trên GPU ít VRAM có thể thất bại lặng lẽ. Thử mô hình nhỏ hơn.
+
+5. **Lỗi chuyển đổi tệp** — Thử phiên âm tệp WAV trực tiếp để xác định vấn đề là ở chuyển đổi hay phiên âm.
+
+---
+
+## Phiên âm nền không tạo ra đầu ra SRT
+
+**Nguyên nhân:** Chế độ nền (`background=true` trong `transcribe_audio`) hiện chỉ tạo ra đầu ra `.txt`. Định dạng SRT trong chế độ nền chưa được triển khai.
+
+**Giải pháp tạm thời:** Với tệp dưới ~4 phút, sử dụng `generate_subtitles` ở chế độ chặn. Với tệp dài hơn, trước tiên phiên âm ở chế độ nền để lấy `.txt`, sau đó nếu cần SRT, hãy dùng `generate_subtitles` trên cùng tệp đó (sẽ phiên âm lại).
+
+**Trạng thái:** Hỗ trợ SRT trong chế độ nền được lên kế hoạch cho bản phát hành tương lai.
+
+---
+
+## GPU không được sử dụng (CPU cao trên 50%)
+
+**Nguyên nhân:** Bạn đang chạy tệp nhị phân chỉ dùng CPU đi kèm với bản phát hành whisper.cpp tiêu chuẩn.
+
+**Cách sửa:** Tải xuống bản build có Vulkan từ [trang phát hành](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0) và giải nén vào `C:\whisper\Release\`.
+
+Xác nhận tăng tốc GPU đang hoạt động:
+- Yêu cầu Claude `check_system`
+- Tìm `✅ Vulkan binary: ggml-vulkan.dll found` trong đầu ra
+- Theo dõi Task Manager → Hiệu suất → GPU trong quá trình phiên âm — mức sử dụng GPU sẽ tăng lên 15–30%
+
+---
+
+## `check_system` báo dung lượng VRAM sai
+
+Đây là giới hạn đã biết của Windows. Lệnh `wmic` đọc VRAM từ registry, trên nhiều card AMD báo một nửa VRAM vật lý. Card Vega 56 có 8GB HBM2 thường hiển thị 4GB. Đây chỉ là vấn đề hiển thị — whisper sử dụng đầy đủ VRAM vật lý trong quá trình suy luận.
+
+---
+
+## Lỗi "Đang phiên âm"
+
+Có một tiến trình `whisper-cli.exe` đang chạy từ tác vụ trước. Chờ nó hoàn thành, hoặc:
+
+1. Mở Task Manager → tab Chi tiết
+2. Tìm `whisper-cli.exe`
+3. Nhấp chuột phải → Kết thúc tác vụ
+
+Sau đó thử lại.
+
+---
+
+## Tự động phát hiện ngôn ngữ sai
+
+Tự động phát hiện của Whisper chạy trên 30 giây đầu tiên của âm thanh. Nếu tệp bắt đầu bằng ngôn ngữ khác với phần lớn nội dung, việc phát hiện có thể sai.
+
+**Cách sửa:** Chỉ định ngôn ngữ rõ ràng (ví dụ: `language=vi`) thay vì dựa vào tự động phát hiện.
+
+---
+
+## Tạo phụ đề tạo ra "(đang nói bằng tiếng nước ngoài)" trong suốt
+
+Whisper phát hiện giọng nói nhưng không thể phiên âm. Nguyên nhân phổ biến nhất:
+
+1. **Mô hình sai** — Đang dùng mô hình chỉ tiếng Anh với âm thanh không phải tiếng Anh. Dùng `large-v3`.
+
+2. **Chất lượng âm thanh** — Môi trường nhiều tạp âm (nhà bếp, đám đông, tiếng vang) có thể vượt quá khả năng của mô hình medium. Thử `large-v3`.
+
+3. **Ngôn ngữ hỗn hợp** — Tệp có hai ngôn ngữ xen kẽ sẽ có ngôn ngữ thiểu số được thay thế bằng ký hiệu chỗ giữ khi dùng cài đặt một ngôn ngữ.
+
+---
+
+## Dịch phụ đề chỉ ra tiếng Anh
+
+Đây là hành vi có chủ ý. Flag `--translate` tích hợp của Whisper chỉ dịch **sang tiếng Anh**. Để dịch sang các ngôn ngữ đích khác, hãy xử lý nội dung tệp `.srt` riêng biệt.
+
+---
+
+## Phiên âm hàng loạt ngừng tiến triển
+
+Gọi `check_batch_progress` lại. Nếu vẫn bị kẹt:
+
+1. Kiểm tra Task Manager xem có tiến trình `whisper-cli.exe` đang chạy không
+2. Kiểm tra nhật ký tác vụ trong `%TEMP%\whisper-mcp-jobs\`
+3. Các tệp thất bại được đánh dấu trong báo cáo đợt — hãy chạy lại từng tệp riêng lẻ bằng `transcribe_audio`
+
+---
+
+## Dọn dẹp thư mục tệp tạm thời
+
+whisper-windows-mcp ghi tệp trạng thái tác vụ và nhật ký vào `%TEMP%\whisper-mcp-jobs\` trong quá trình phiên âm. Chúng tích lũy theo thời gian và có thể chiếm dung lượng đĩa, đặc biệt là các tệp `.log` từ các tác vụ phiên âm dài.
+
+Sau khi đợt hoặc tác vụ hoàn thành và bạn đã xác nhận các bản phiên âm đầu ra, bạn có thể xóa an toàn mọi thứ trong thư mục này:
+
+```powershell
+Remove-Item "$env:TEMP\whisper-mcp-jobs\*" -Recurse -Force
+```
+
+Thư mục sẽ được tạo lại tự động vào lần phiên âm tiếp theo. Không có tệp đầu ra phiên âm nào được lưu vĩnh viễn ở đây — chúng được di chuyển đến thư mục nguồn khi hoàn thành. Chỉ có siêu dữ liệu tác vụ và nhật ký còn lại.
+
+**Lưu ý:** Không xóa thư mục này trong khi đang phiên âm — các tệp trạng thái đợt cần thiết để `check_batch_progress` hoạt động.
+
+---
+
+## Xử lý hàng loạt lớn không giám sát từ dòng lệnh
+
+Với các đợt rất lớn mà bạn muốn chạy qua đêm không cần Claude, hãy sử dụng PowerShell.
+
+**Quan trọng:** whisper-cli.exe không thể đọc trực tiếp MP4, MKV hoặc hầu hết các định dạng video. FFmpeg phải chuyển đổi từng tệp sang WAV trước. whisper cũng ghi bản phiên âm vào stdout và đầu ra chẩn đoán vào stderr — sử dụng `Start-Process -RedirectStandardOutput` để bắt bản phiên âm đúng cách. Dùng pipe `|` hoặc chuyển hướng stderr với `2>$null` sẽ không bắt được gì.
+
+```powershell
+$whisper = "C:\whisper\Release\whisper-cli.exe"
+$model   = "C:\whisper\models\ggml-medium.en.bin"
+$dir     = "C:\path\to\your\folder"
+$ffmpeg  = "ffmpeg"
+$tmp     = "$env:TEMP\whisper_convert.wav"
+
+Get-ChildItem "$dir\*.mp4" | ForEach-Object {
+    $out = ($_.FullName -replace '\.mp4$', '') + ".txt"
+    if (Test-Path $out) {
+        Write-Host "SKIP (exists): $($_.Name)"
+        return
+    }
+    Write-Host "Converting:    $($_.Name)"
+    & $ffmpeg -y -i $_.FullName -ar 16000 -ac 1 -c:a pcm_s16le $tmp 2>$null
+    Write-Host "Transcribing:  $($_.Name)"
+    $wArgs = "-m `"$model`" -f `"$tmp`" --threads 8 --condition-on-previous-text 0 --no-speech-thold 0.6"
+    Start-Process -FilePath $whisper -ArgumentList $wArgs -RedirectStandardOutput $out -Wait -NoNewWindow
+    Write-Host "Done:          $($_.BaseName).txt"
+}
+
+Remove-Item $tmp -ErrorAction SilentlyContinue
+Write-Host "All done."
+```
+
+Thay `*.mp4` bằng `*.mkv`, `*.m4a` v.v. để khớp với loại tệp của bạn. Kiểm tra bỏ qua `Test-Path` có nghĩa là chạy lại script sau khi bị gián đoạn sẽ không xử lý lại các tệp đã hoàn thành.
+
+Script này ghi tệp `.txt` bên cạnh mỗi tệp nguồn. Các công cụ MCP sẽ nhận ra chúng là đã được phiên âm khi bạn chạy `analyze_media` hoặc `start_batch` sau đó.
+
+---
+
+## Vị trí tệp cấu hình
+
+```
+C:\Users\TênNgườiDùng\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+Nếu `AppData` không hiển thị: Xem → Hiển thị → Mục ẩn trong File Explorer.
+
+---
+
+## Ví dụ cấu hình hoàn chỉnh hoạt động
+
+```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` mặc định là `ffmpeg` (giả sử có trong PATH). Chỉ đặt rõ ràng nếu FFmpeg được cài đặt ở vị trí không chuẩn.

package/glama.json

@@ -0,0 +1,6 @@
+{
+  "name": "whisper-windows-mcp",
+  "description": "Windows-native MCP server for local audio/video transcription using whisper.cpp with Vulkan GPU acceleration. Batch processing, model management, multilingual support. No cloud APIs, no Python required.",
+  "license": "MIT",
+  "homepage": "https://github.com/eviscerations/whisper-windows-mcp"
+}