whisper-windows-mcp 2.2.0 → 2.2.2

package/README.uk.md

@@ -0,0 +1,393 @@
+# whisper-windows-mcp
+
+Нативний MCP-сервер (Model Context Protocol) для Windows. Використовує [whisper.cpp](https://github.com/ggml-org/whisper.cpp) для транскрибування аудіо та відеофайлів локально в Claude Desktop — з апаратним прискоренням GPU, підтримкою багатьох мов і пакетним опрацюванням. Уся транскрипція виконується локально — жодні аудіо-, відеофайли чи шляхи до файлів не передаються назовні.
+
+> **Чому існує цей пакет?**
+> Популярний пакет `whisper-mcp` створено для macOS і розрахований на Unix-середовище. На Windows він не працює. Цей пакет написано спеціально для користувачів Windows, які хочуть локальне AI-транскрибування, інтегроване з Claude Desktop.
+
+---
+
+## Що ви можете робити
+
+Після встановлення можна говорити прямо в Claude Desktop:
+
+- *"Транскрибуй C:\Users\Me\Downloads\meeting.mp3"*
+- *"Транскрибуй всі записи в цій теці й збережи кожен як текстовий файл"*
+- *"Створи українські та англійські субтитри для цього відео"*
+- *"Почни пакетне транскрибування всіх файлів у цій теці"*
+- *"Скільки часу займе транскрибування цих файлів?"*
+- *"Перевір, чи працює прискорення GPU"*
+
+---
+
+## Вимоги
+
+1. **Node.js 18 або новіше** — [nodejs.org](https://nodejs.org)
+2. **Бінарники whisper.cpp з підтримкою Vulkan GPU** — дивіться Крок 1
+3. **Файл моделі Whisper** — дивіться Крок 2
+4. **FFmpeg** — необхідний для відеофайлів і аудіоформатів, що не є WAV/MP3
+
+---
+
+## Крок 1 — Встановлення бінарників whisper.cpp
+
+### Варіант А — Готовий Vulkan-реліз (рекомендовано)
+
+Завантажте `whisper-vulkan-win-x64.zip` зі [сторінки релізів](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0).
+
+Це спеціальна збірка з увімкненим **Vulkan GPU-прискоренням**. Працює з GPU від AMD, NVIDIA та Intel — без потреби в окремих 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 вмикається автоматично — жодних додаткових налаштувань не потрібно.
+
+### Варіант Б — Збірка з вихідного коду
+
+Потрібно: Git, CMake, Visual Studio Build Tools 2022+ з компонентом "Desktop development with C++", Vulkan SDK з [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
+```
+
+Скопіюйте бінарники з `build\bin\Release\` до `C:\whisper\Release\`.
+
+> **Примітка:** Офіційні Windows-релізи whisper.cpp на GitHub не містять Vulkan-збірки. Використовуйте готовий реліз вище або компілюйте з вихідного коду з прапором `-DGGML_VULKAN=ON`.
+
+---
+
+## Крок 2 — Завантаження моделі Whisper
+
+| Модель | Розмір | Швидкість | Точність | Найкраще для |
+|---|---|---|---|---|
+| `ggml-tiny.en.bin` | 75 МБ | Дуже швидко | Базова | Швидкі тести |
+| `ggml-base.en.bin` | 142 МБ | Швидко | Добра | Щоденна англійська |
+| `ggml-small.en.bin` | 466 МБ | Помірно | Краща | Важливі записи |
+| `ggml-medium.en.bin` | 1.5 ГБ | Швидко на GPU | Дуже добра | Найвища якість англійської |
+| `ggml-large-v3-turbo.bin` | 1.6 ГБ | Швидко на GPU | Відмінна | **Рекомендовано для пакетної обробки на GPU — ~у 6 разів швидше за large-v3 з мінімальною втратою точності** |
+| `ggml-large-v3.bin` | 2.9 ГБ | Швидко на GPU | Відмінна | Багатомовний, максимальна точність |
+| `ggml-medium.en-q5_0.bin` | 514 МБ | Швидко | Дуже добра | **Найкращий вибір для CPU-only англійської — висока точність при малому обсязі пам'яті** |
+| `ggml-large-v3-turbo-q5_0.bin` | 547 МБ | Швидко | Відмінна | **Найкращий вибір для CPU-only багатомовного** |
+| `ggml-large-v3-q5_0.bin` | 1.1 ГБ | Помірно на CPU | Відмінна | Багатомовний, сприятливий для CPU |
+
+Використовуйте `download_model` у Claude Desktop для встановлення безпосередньо. Для **лише англійської**: `large-v3-turbo` (GPU) або `medium.en-q5_0` (CPU) — найкращий вибір. Для **багатомовного**: `large-v3-turbo` або `large-v3-turbo-q5_0` (CPU). Моделі лише для англійської (`*.en.bin`) виводять `[FOREIGN]` для не-англійського аудіо і не можуть використовуватися для інших мов.
+
+---
+
+## Крок 3 — Встановлення FFmpeg
+
+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`
+
+> Використовуйте **подвійний зворотній слеш** у всіх шляхах.
+
+Збережіть і **повністю перезапустіть** Claude Desktop. Ви маєте побачити **whisper** у списку зі зеленим значком "запущено" в Налаштуваннях → Розробник.
+
+---
+
+## Крок 6 — Перевірка налаштування
+
+У Claude Desktop запитайте:
+
+> *"Перевір конфігурацію whisper"*
+
+Потім:
+
+> *"Перевір апаратне забезпечення системи"*
+
+Це підтвердить, що ваш GPU визначено і прискорення Vulkan активне.
+
+---
+
+## Доступні інструменти
+
+### `transcribe_audio`
+Транскрибує один файл. Підтримує блокувальний (типово) або фоновий режим для довгих файлів.
+
+| Параметр | Опис |
+|---|---|
+| `file_path` | Абсолютний шлях до файлу (обов'язково) |
+| `language` | Код мови (`uk`, `en`, `ja` тощо) або `auto` для автовизначення. Типово: `en` |
+| `output_format` | `text` (типово), `timestamps`, `json` або `srt` |
+| `save_to_file` | Зберегти транскрипцію як .txt поруч із вихідним файлом |
+| `background` | Запустити як окреме завдання — одразу повертає ID завдання. Використовуйте `check_progress` для стеження. Рекомендовано для файлів понад 10 хвилин. |
+| `threads` | Перевизначити кількість потоків CPU |
+| `temperature` | Температура вибірки 0.0–1.0. Типово 0.0 (детерміновано). Вищі значення зменшують галюцинації на шумному аудіо. |
+| `prompt` | Рядок попереднього контексту — підвищує точність для галузевої лексики або імен доповідачів. Приклад: `"Імена: Keemstar, DramaAlert."` |
+| `condition_on_prev_text` | Повторно увімкнути контекстне обумовлення між сегментами. Типово false. |
+| `beam_size` | Ширина пошуку за промінем. Вище = точніше, повільніше. Типово 5. |
+| `best_of` | Кількість оцінюваних послідовностей-кандидатів. Типово 5. |
+| `gpu_device` | Індекс пристрою GPU для багатогеркових систем. Типово 0. |
+| `processors` | Кількість паралельних процесорів. Типово 1. |
+| `word_timestamps` | Один рядок на слово з мітками часу. Корисно для вирівнювання кліпів. |
+| `max_segment_length` | Максимальна довжина сегмента в символах. |
+| `diarize` | Стерео-розрізнення доповідачів — потребує стерео аудіо з доповідачами на окремих каналах. |
+| `vad_model` | Шлях до .bin-файлу моделі Silero VAD. Видаляє тишу перед транскрипцією — зменшує галюцинації у шумних файлах. |
+| `offset_t` | Зміщення початку в мілісекундах. |
+| `duration` | Тривалість опрацювання в мілісекундах від зміщення. |
+
+---
+
+### `check_progress`
+Стежить за фоновим завданням транскрипції, запущеним через `transcribe_audio` (background=true).
+
+Повертає минулий час, останню опрацьовану мітку часу, відсоток і повну транскрипцію після завершення.
+
+| Параметр | Опис |
+|---|---|
+| `job_id` | ID завдання, повернений `transcribe_audio` |
+
+---
+
+### `start_batch`
+Автоматично і послідовно транскрибує всі ще не транскрибовані файли в теці. Сортує за тривалістю (від найкоротших), опрацьовує по одному як фонові завдання, перевіряє кожен результат.
+
+| Параметр | Опис |
+|---|---|
+| `folder_path` | Шлях до теки (обов'язково) |
+| `language` | Код мови. Типово: `en` |
+| `threads` | Перевизначити кількість потоків CPU |
+
+---
+
+### `check_batch_progress`
+Стежить за запущеним пакетом. Автоматично переходить до наступного файлу після завершення поточного. Повертає загальний прогрес, поточний файл з міткою часу, очікуваний час завершення і файли з помилками.
+
+| Параметр | Опис |
+|---|---|
+| `batch_id` | ID пакету, повернений `start_batch` |
+
+---
+
+### `transcribe_batch` (інтерактивний)
+Опрацьовує файли по одному з попереднім переглядом і підтвердженням перед кожним. Корисно, коли хочеться переглядати результати в процесі.
+
+| Параметр | Опис |
+|---|---|
+| `folder_path` | Шлях до теки (обов'язково) |
+| `file_index` | Який файл опрацювати (нумерація з 1). Пропустіть, щоб спочатку показати список файлів. |
+| `language` | Код мови. Типово: `en` |
+| `recursive` | Включити підтеки |
+
+---
+
+### `generate_subtitles`
+Створює файли субтитрів SRT. Підтримує автовизначення мови та вивід перекладу англійською.
+
+| Параметр | Опис |
+|---|---|
+| `file_path` | Шлях до файлу (обов'язково) |
+| `language` | Код мови або `auto` для автовизначення. Типово: `en` |
+| `translate_to_english` | Також створити `.en.srt` з перекладом англійською. Застосовується лише якщо джерело — не англійська. |
+| `threads` | Перевизначити кількість потоків CPU |
+
+Коли запитуються обидва варіанти, поруч із джерелом зберігаються два файли:
+- `назвафайлу.uk.srt` — рідна мова
+- `назвафайлу.en.srt` — переклад англійською
+
+> Вбудований переклад Whisper перекладає **лише на англійську**. Для інших цільових мов перекладайте вміст .srt-файлу окремо.
+
+---
+
+### `analyze_media`
+Аналізує файл перед транскрипцією. Повертає тривалість, розмір, кодек і орієнтовний час транскрипції на CPU та GPU. Для теки показує всі файли у таблиці з можливістю сортування й статусом транскрипції.
+
+| Параметр | Опис |
+|---|---|
+| `path` | Шлях до окремого файлу або теки (обов'язково) |
+| `sort_by` | Для теки: `duration` (типово), `name` або `size` |
+
+---
+
+### `check_config`
+Перевіряє, чи доступні whisper-cli.exe, файл моделі та FFmpeg. Запускайте це першим, якщо щось не працює.
+
+---
+
+### `list_models`
+Перелічує всі встановлені файли моделей Whisper у вашій теці моделей. Показує ім'я файлу, розмір, чи активна модель, статус квантизації та рекомендовані випадки використання. Без мережевих запитів — лише читання локальної файлової системи.
+
+---
+
+### `download_model`
+Завантажує модель Whisper безпосередньо з Hugging Face до вашої теки моделей. Приймає назву моделі (наприклад `large-v3-turbo`, `medium.en-q5_0`) і автоматично виконує завантаження. Завантажує лише з довірених просторів імен Hugging Face. Після завантаження активуйте через `switch_model`.
+
+| Параметр | Опис |
+|---|---|
+| `model_name` | Назва моделі для завантаження, наприклад `large-v3-turbo`, `large-v3-turbo-q5_0`, `medium.en-q5_0` |
+
+---
+
+### `switch_model`
+Перемикає активну модель Whisper для поточного сеансу без перезапуску Claude Desktop. Зміна діє лише в межах сеансу — після перезапуску не зберігається. Щоб зробити постійним, оновіть `WHISPER_MODEL` у конфігурації.
+
+| Параметр | Опис |
+|---|---|
+| `model_name` | Ім'я файлу моделі (наприклад `ggml-large-v3-turbo.bin`) або повний шлях. Має бути `.bin`-файлом у налаштованій теці моделей. |
+
+---
+
+### `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-го покоління). Будь-який GPU з підтримкою Vulkan 1.0+ має працювати, включно з NVIDIA та Intel Arc.
+
+**Порівняння продуктивності (модель medium.en, аудіофайл ~5 хвилин):**
+
+| Обладнання | Час |
+|---|---|
+| Лише CPU (Ryzen 7 2700x, 8 потоків) | 8–12 хвилин |
+| GPU (Vega 56 через Vulkan) | 20–40 секунд |
+
+Навантаження GPU під час транскрипції зазвичай становить 15–20% і повертається до простою між файлами. CPU зберігається близько 15%.
+
+---
+
+## Багатомовна підтримка
+
+Whisper може автоматично визначати мову мовлення і транскрибувати нею. Вбудована модель перекладу перекладає **лише на англійську**.
+
+Для найкращої точності у багатомовному режимі використовуйте модель `large-v3`. Моделі лише для англійської (`*.en.bin`) не можуть визначати або транскрибувати інші мови.
+
+**Приклад — іноземне відео із субтитрами:**
+1. Попросіть Claude створити субтитри з `language=auto` і `translate_to_english=true`
+2. Whisper визначає мову і створює SRT рідною мовою
+3. Другий прохід створює SRT з перекладом англійською
+4. Завантажте будь-який файл у VLC через Субтитри → Додати файл субтитрів
+
+---
+
+## Розроблено для користувачів безкоштовного плану
+
+Цей інструмент створено, щоб мінімізувати взаємодію з Claude API. Увесь робочий процес транскрипції — сканування, аналіз, черга, виконання, перевірка — розроблено так, щоб вимагати якомога менше взаємодій з Claude. Важка робота виконується локально на вашому комп'ютері.
+
+---
+
+## Додаткові змінні середовища
+
+| Змінна | Опис |
+|---|---|
+| `WHISPER_CLI_PATH` | Шлях до whisper-cli.exe (обов'язково) |
+| `WHISPER_MODEL` | Шлях до файлу моделі .bin (обов'язково) |
+| `WHISPER_THREADS` | Перевизначити кількість потоків CPU |
+| `FFMPEG_PATH` | Шлях до ffmpeg, якщо його немає в системному PATH |
+| `WHISPER_PRIVACY_MODE` | **Планується.** При значенні `true` відповіді інструментів повертають лише метадані — жодний текст транскрипції не передається Claude. Для регульованого або конфіденційного контенту. Дивіться [PRIVACY.md](PRIVACY.md). |
+
+---
+
+## Усунення несправностей
+
+Детальні рішення — у [TROUBLESHOOTING.md](TROUBLESHOOTING.md). Якщо ви працюєте з регульованим контентом, дивіться також [PRIVACY.md](PRIVACY.md).
+
+Швидкий контрольний список:
+- Шляхи в конфігурації використовують **подвійний зворотній слеш** (`C:\\whisper\\...`)
+- `whisper-cli.exe` існує за налаштованим шляхом
+- Файл моделі `.bin` існує за налаштованим шляхом
+- FFmpeg встановлено і доступно в PATH (`ffmpeg -version` працює)
+- Claude Desktop **повністю перезапущено** після редагування конфігурації
+- Whisper відображається як **запущено** (зелений значок) у Налаштуваннях → Розробник
+
+---
+
+## Безпека та конфіденційність
+
+whisper-windows-mcp розроблено з безпекою як основним принципом.
+
+**Аудіо ніколи не покидає ваш комп'ютер.** Жодні аудіо- чи відеофайли, шляхи до файлів або телеметрія не передаються на жодний сервер. Для основних функцій хмарні API не потрібні.
+
+**Текст транскрипції та межа API.** Коли відповідь інструменту містить текст транскрипції, цей текст опрацьовується API Claude — він покидає ваш локальний комп'ютер. Для більшості користувачів (публічний контент, подкасти, записи стрімів) це очікувана поведінка. Якщо ви працюєте з медичними, юридичними, фінансовими чи іншими регульованими записами, дивіться [PRIVACY.md](PRIVACY.md) для отримання рекомендацій щодо відповідності та параметрів налаштування.
+
+Планується змінна середовища `WHISPER_PRIVACY_MODE`, яка обмежить усі відповіді інструментів лише метаданими (ім'я файлу, тривалість, кількість слів) — жодний текст транскрипції не повертатиметься Claude. Це правильне налаштування для регульованого або конфіденційного контенту.
+
+**Перевірка вхідних даних.** Усі шляхи до файлів перевіряються перед використанням — UNC-шляхи (`\\server\share`) та послідовності обходу теки (`..`) відхиляються. Файли понад 10 ГБ відхиляються для запобігання вичерпанню ресурсів.
+
+**Усвідомлення ін'єкції транскрипції.** Аудіофайли можуть містити вимовлений контент, який після транскрипції нагадує інструкції. Вбудований захист Claude впорається з цим, але варто знати, що сам MCP-сервер обробляє вміст транскрипції як дані — ніколи як інструкції.
+
+**Завантаження моделей обмежено.** Інструмент `download_model` завантажує лише з двох довірених просторів імен Hugging Face (`ggerganov/whisper.cpp` і `ggml-org`). Довільні URL-адреси відхиляються. Переспрямування перевіряються за списком дозволених перед виконанням.
+
+**Перемикання моделей у пісочниці.** `switch_model` приймає лише `.bin`-файли з налаштованої теки моделей. Шляхи за межами цієї теки відхиляються.
+
+**Жодних нових мережевих залежностей.** Завантаження моделей використовує вбудований `https` Node.js — жодні зовнішні HTTP-бібліотеки не додаються до пакету.
+
+---
+
+## Ліцензія
+
+**Некомерційне використання:** MIT — безкоштовно для особистого, освітнього та некомерційного використання. Дивіться [LICENSE](LICENSE).
+
+**Комерційне використання:** Для будь-якого бізнес-, професійного або комерційного використання необхідна окрема комерційна ліцензійна угода. Умови та контактна інформація — у [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md).
+
+## Внески
+
+Pull requests вітаються. Дивіться [ROADMAP.md](ROADMAP.md) для запланованих функцій.
+
+Якщо ви тестували прискорення GPU на обладнанні, не вказаному вище, будь ласка, відкрийте issue з результатами — модель GPU, обсяг VRAM, розмір моделі та спостережувана пропускна здатність.