whisper-windows-mcp 2.2.2 → 2.3.0

package/TROUBLESHOOTING.uk.md

@@ -1,323 +1,369 @@
-# 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 встановлено в нестандартному місці.
+# Усунення несправностей — 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 Desktop → Налаштування → Розробник → Редагувати конфігурацію
+2. Переконайтеся, що JSON є дійсним — вставте його на [jsonlint.com](https://jsonlint.com) у разі сумніву
+3. Переконайтеся, що `WHISPER_CLI_PATH` і `WHISPER_MODEL` вказують на файли, що фактично існують
+4. Завершіть Claude Desktop з системного трея (клацніть правою кнопкою миші на значку → Вийти)
+5. Перезапустіть Claude Desktop і перевірте знову
+
+Якщо whisper з'являється, але показує значок помилки замість зеленого:
+- Запитайте Claude: *"Перевір конфігурацію whisper"* — інструмент `check_config` повертає конкретне повідомлення про помилку
+- Перевірте Claude Desktop → Налаштування → Розробник → клацніть на назві сервера для журналу помилок
+
+### Помилка "whisper-cli.exe не знайдено"
+
+Шлях у `WHISPER_CLI_PATH` не збігається з місцем розташування бінарника.
+
+Очікуваний шлях за замовчуванням: `C:\whisper\Release\whisper-cli.exe`
+
+Перевірте наявність файлу:
+```powershell
+Test-Path "C:\whisper\Release\whisper-cli.exe"
+```
+
+Має повернути `True`. Якщо повертає `False`, або розпакуйте реліз у `C:\whisper\Release\`, або оновіть `WHISPER_CLI_PATH` у конфігурації відповідно до фактичного розташування.
+
+### Помилка "Модель не знайдена"
+
+Шлях у `WHISPER_MODEL` не збігається з фактичним розташуванням або назвою файлу моделі.
+
+Перевірте теку моделей:
+```powershell
+Get-ChildItem "C:\whisper\models\"
+```
+
+Назва файлу має включати повну назву разом із суфіксом квантизації, наприклад `ggml-large-v3-turbo-q5_0.bin`, а не `ggml-large-v3-turbo.bin`. Якщо моделі не встановлено, використовуйте `download_model` у Claude Desktop.
+
+---
+
+## Прискорення GPU
+
+### Транскрипція повільна — лише CPU, без GPU
+
+Запитайте Claude: *"Перевір апаратне забезпечення системи"*
+
+Інструмент `check_system` підтверджує наявність `ggml-vulkan.dll` у теці бінарника whisper. Якщо DLL відсутній, ви працюєте лише на CPU незалежно від вашого GPU.
+
+**Виправлення:** Завантажте `whisper-vulkan-win-x64.zip` зі [сторінки релізів](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0) і розпакуйте в `C:\whisper\Release\`. Zip містить DLL — вона має знаходитися в тій самій теці, що і `whisper-cli.exe`.
+
+### GPU визначено, але навантаження 0% під час транскрипції
+
+Бінарник запущено, але не відправляє задачі на GPU. Зазвичай це означає:
+- Vulkan SDK не встановлено або драйвер GPU не надає інтерфейс Vulkan
+- GPU є старішим за Vulkan 1.0 (рідко — більшість GPU після 2016 року підтримують його)
+
+Перевірте підтримку Vulkan:
+```powershell
+vulkaninfo
+```
+
+Будь-який вивід підтверджує доступність Vulkan. Якщо `vulkaninfo` не працює, встановіть останній драйвер GPU з сайту виробника.
+
+### VRAM відображається як половина фактичного розміру (AMD)
+
+Це відомий нюанс відображення Windows для GPU AMD з об'єднаною/спільною пам'яттю. Фактичний доступний VRAM для опрацювання зазвичай вдвічі більший за те, що повідомляє `wmic`. Рекомендація моделі може бути надмірно консервативною — ви можете спробувати більшу модель, ніж рекомендовано.
+
+---
+
+## Якість транскрипції
+
+### Вивід містить галюцинований текст або повторювані фрази
+
+Whisper іноді галюцинує на тихих або низькоякісних аудіосегментах. Інструмент за замовчуванням застосовує `--max-context 0` і `--no-speech-thold 0.6` для мінімізації цього.
+
+Додаткові підходи:
+- Використовуйте `temperature=0.2` — невелика випадковість допомагає розірвати цикли галюцинацій на шумному аудіо
+- Використовуйте модель VAD: завантажте файл `.bin` моделі Silero VAD і передайте його шлях як `vad_model`. Це видаляє тишу перед транскрипцією — найефективніше виправлення для галюцинацій на записах з паузами.
+- Використовуйте більшу модель (`large-v3` або `large-v3-turbo`) — менші моделі галюцинують більше на складному аудіо
+- Використовуйте `prompt` для встановлення контексту: *"Це інтерв'ю подкасту про розробку програмного забезпечення."*
+
+### Вивід транскрипції порожній або дуже короткий
+
+Запитайте Claude: *"Проаналізуй цей файл"* (`analyze_media`), щоб підтвердити наявність аудіовмісту і розпізнаний формат.
+
+Якщо FFprobe повідомляє про аудіо, але транскрипція нічого не виробляє:
+- Файл може бути мовою, що не збігається з налаштованим параметром `language`
+- Спробуйте `language=auto`, щоб Whisper визначив мову
+- Аудіо може бути надто тихим або сильно обробленим — для транскрипції потрібна розбірлива мова
+
+---
+
+## Режим конфіденційності і ворота згоди
+
+### Я не бачу запиту на згоду перед транскрипцією
+
+Ворота згоди спрацьовують **один раз за сеанс** у стандартному режимі. Якщо ви вже підтвердили транскрипцію в цьому сеансі (після останнього перезапуску Claude Desktop), вони не спрацюють знову.
+
+Інші причини, чому ворота можуть не з'явитися:
+- `WHISPER_CONSENT_ACKNOWLEDGED=true` встановлено у вашій конфігурації — це повністю пригнічує ворота
+- `WHISPER_PRIVACY_MODE=true` встановлено — режим конфіденційності використовує власні окремі ворота для кожної операції
+- Ви перевіряєте прогрес блокувальної транскрипції, яка вже завершилась — ворота були використані на початку завдання
+
+**Щоб скинути і знову побачити ворота:** повністю перезапустіть Claude Desktop (завершіть з системного трея, перезапустіть).
+
+### Claude опрацьовує мій файл без запиту
+
+Якщо `WHISPER_CONSENT_ACKNOWLEDGED=true` є у вашій конфігурації, ворота пригнічені навмисно. Це передбачена поведінка для користувачів, які ознайомилися з наслідками для конфіденційності.
+
+Якщо це не встановлено і Claude продовжив без запиту, ворота сеансу вже були використані попередньою транскрипцією в цьому сеансі. Ворота спрацьовують один раз за сеанс.
+
+Для підтвердження перед кожною транскрипцією незалежно від стану сеансу увімкніть режим конфіденційності: передайте `privacy_mode=true` або встановіть `WHISPER_PRIVACY_MODE=true` у конфігурації.
+
+### Режим конфіденційності активний, але я хочу прочитати одну транскрипцію
+
+Передайте `privacy_mode=false` безпосередньо інструменту транскрипції для цього конкретного виклику. Це перевизначає глобальне налаштування `WHISPER_PRIVACY_MODE=true` лише для одного виклику:
+
+- *"Транскрибуй цей файл, privacy_mode=false"*
+
+Перезапуск не потрібен. Перевизначення застосовується лише до цього одного виклику інструменту.
+
+### Режим конфіденційності запитує підтвердження перед кожним файлом
+
+Це правильна і навмисна поведінка. Режим конфіденційності вимагає згоди перед кожною операцією — ворота спрацьовують перед кожною транскрипцією і не можуть бути обійдені, поки режим конфіденційності активний.
+
+Якщо вам потрібно транскрибувати багато файлів без підтвердження для кожного і контент не є чутливим, вимкніть режим конфіденційності:
+- Видаліть `WHISPER_PRIVACY_MODE=true` з конфігурації і перезапустіть Claude Desktop
+- Або передайте `privacy_mode=false` для конкретних нечутливих файлів
+
+### Фонові завдання і ворота згоди
+
+Для фонової транскрипції (`background=true`) у стандартному режимі ворота згоди спрацьовують при `check_progress`, коли повертається транскрипція — **не** при `transcribe_audio`, коли завдання запускається. На момент запуску завдання текст транскрипції ще не існує. Ворота спрацьовують у момент, коли текст транскрипції вперше повертається до API.
+
+Для фонових завдань у режимі конфіденційності ворота спрацьовують **перед запуском** — до початку будь-якого аудіоопрацювання.
+
+### Як назавжди пропустити ворота згоди?
+
+Встановіть `WHISPER_CONSENT_ACKNOWLEDGED=true` у розділі env файлу `claude_desktop_config.json`. Це пригнічує одноразове розкриття сеансу у стандартному режимі.
+
+Примітка: не має ефекту, коли режим конфіденційності активний.
+
+---
+
+## Фонова транскрипція і пакет
+
+### Фонове завдання ніколи не показується як завершене
+
+Стан завдання відстежується за виходом процесу whisper-cli.exe. Перевірте:
+
+1. Запитайте Claude: *"Перевір прогрес job_id"* — якщо процес ще виконується, інструмент повертає "В процесі" з минулим часом і останньою міткою часу сегмента
+2. Якщо файл дуже довгий (2+ години), дайте більше часу — транскрипція GPU 2-годинного файлу займає приблизно 15–20 хвилин на середньому GPU
+3. Якщо минулий час здається неправильним, відкрийте Диспетчер завдань → Деталі і перевірте наявність `whisper-cli.exe` у списку
+
+### Фонове завдання завершено, але вихідний файл відсутній або знаходиться не там
+
+Фонові завдання записують вивід до тимчасового шляху в `%TEMP%\whisper-mcp-jobs\` під час опрацювання, а потім переміщують файл до вихідної теки після завершення. Якщо переміщення не вдається (диск повний, проблема з правами доступу або довжиною шляху), `check_progress` повертає конкретну помилку.
+
+Перевірте:
+- Вихідна тека існує і доступна для запису
+- Достатньо місця на диску
+- Цільовий шлях не надто довгий (Windows за замовчуванням має обмеження шляху в 260 символів)
+
+Необроблений вивід може залишатися в `%TEMP%\whisper-mcp-jobs\` з іменем файлу на основі ID завдання.
+
+### Пакет застряг або не переходить до наступного файлу
+
+`start_batch` використовує зворотній виклик виходу для самостійного просування без опитування. Якщо пакет здається застряглим:
+
+1. Викличте `check_batch_progress` — це примусово перевіряє прогрес і повторно оцінює поточний стан
+2. Якщо поточний файл ще виконується, зачекайте його завершення — перевірте Диспетчер завдань на наявність `whisper-cli.exe`
+3. Якщо `check_batch_progress` показує поточний файл як невдалий, він спробує перейти до наступного
+
+### Пакет повідомляє файл як "невдалий", хоча він виглядає завершеним
+
+Валідатор перевіряє, що вихідний файл не порожній і має принаймні один рядок на кожні 30 секунд аудіо. Короткі файли або записи з довгими тихими секціями можуть виробляти вивід, який валідатор вважає підозріло коротким.
+
+Якщо транскрипція виглядає правильно при відкритті:
+- Валідація є надмірно консервативною для цього файлу
+- Повторно запустіть через `transcribe_audio` окремо і перевірте результат вручну
+
+---
+
+## Генерація субтитрів
+
+### SRT-файл збережено, але з неправильною назвою або не там
+
+SRT і VTT файли зберігаються поруч із вихідним файлом з доданим кодом мови, якщо мова джерела не англійська:
+- Англійське джерело: `назвафайлу.srt`
+- Українське джерело: `назвафайлу.uk.srt`
+- З перекладом англійською: `назвафайлу.uk.srt` + `назвафайлу.en.srt`
+
+### VTT-вивід для веб — як завантажити у десктопний плеєр?
+
+VLC підтримує VTT через Субтитри → Додати файл субтитрів → вибрати `.vtt` файл. Більшість інших десктопних плеєрів краще підтримують SRT, ніж VTT. Використовуйте `output_format=srt` для максимальної сумісності з десктопними плеєрами.
+
+VTT найкраще підходить для елементів HTML5 `<video>` і веб-відеоплеєрів.
+
+### LRC-файли не відображаються у медіаплеєрі
+
+LRC (`.lrc`) файли призначені для плеєрів з функціями відображення текстів/караоке: foobar2000, Winamp, AIMP та різні мобільні плеєри. Стандартні відеоплеєри не відображають LRC. Якщо вам потрібні синхронізовані субтитри для відео, використовуйте `srt` або `vtt`.
+
+### CSV-вивід — який формат?
+
+CSV-вивід включає час початку сегмента, час закінчення і текст у кожному рядку. Призначений для імпорту в табличні інструменти або скрипти аналізу нижнього рівня. Використовуйте `srt` або `vtt` для фактичного відображення субтитрів.
+
+### Генерація субтитрів завершується тайм-аутом з помилкою 4 хвилини
+
+`generate_subtitles` за замовчуванням виконується синхронно і може досягти 4-хвилинного тайм-ауту MCP Claude Desktop на довгих файлах. Використовуйте `background=true` для файлів понад 10 хвилин:
+
+- *"Створи субтитри для цього файлу, background=true"*
+
+Потім перевіряйте прогрес через `check_progress`. Примітка: `translate_to_english=true` недоступно у фоновому режимі. Виконайте другий прохід після завершення фонового завдання для генерації перекладу.
+
+---
+
+## Управління моделями
+
+### `download_model` завершується мережевою помилкою
+
+Інструмент завантажує з Hugging Face. Переконайтеся, що ваш комп'ютер має доступ до інтернету і `huggingface.co` не заблоковано брандмауером або проксі.
+
+Якщо завантаження починається, але переривається, файл `.part` видаляється автоматично. Повторно запустіть `download_model` для повторної спроби.
+
+### `switch_model` повідомляє, що модель не знаходиться в теці моделей
+
+Інструмент `switch_model` приймає лише файли в теці, налаштованій у `WHISPER_MODEL` (зокрема, тека, що містить цей файл).
+
+Якщо ваша модель знаходиться в іншому місці, або перемістіть її до теки моделей, або оновіть `WHISPER_MODEL` у конфігурації, щоб вказати на файл у тій самій теці, що і ваші моделі.
+
+### Активна модель повертається до моделі з конфігурації після перезапуску Claude Desktop
+
+`switch_model` є сеансовим за дизайном. Щоб зробити перемикання моделі постійним, оновіть `WHISPER_MODEL` у `claude_desktop_config.json` і перезапустіть Claude Desktop.
+
+---
+
+## Шляхи до файлів і формати
+
+### Імена файлів Unicode спричиняють тихе невдале виконання транскрипції
+
+Фонова транскрипція спрямовує весь вивід через санований ASCII-шлях на основі ID завдання, що правильно обробляє імена файлів Unicode. Якщо ви бачите збій з іменем файлу Unicode у блокувальному режимі, перевірте доступність файлу:
+
+```powershell
+Test-Path "C:\Users\ВашеІм'я\Documents\запис_наради.mp4"
+```
+
+Має повернути `True`. Якщо шлях недоступний для PowerShell, він також буде недоступний для MCP-сервера.
+
+### Відеофайл не виробляє вивід або негайна помилка
+
+FFmpeg потрібен для всіх відеоформатів. Переконайтеся, що FFmpeg встановлено:
+```
+ffmpeg -version
+```
+
+Якщо FFmpeg не в PATH, встановіть `FFMPEG_PATH` у конфігурації на повний шлях до `ffmpeg.exe`.
+
+Якщо FFmpeg встановлено, але конкретне відео не вдається, це може бути пошкоджений файл або незвичайний варіант кодека. Спробуйте конвертувати вручну:
+```
+ffmpeg -i input.mp4 -ar 16000 -ac 1 output.wav
+```
+Потім транскрибуйте WAV-файл безпосередньо.
+
+### Помилка "Файл надто великий"
+
+Інструмент відхиляє файли понад 10 ГБ. Це обмеження безпеки для запобігання надмірному використанню пам'яті. Файли, що наближаються до цього розміру, слід розділити перед транскрипцією.
+
+### Відхилення UNC-шляху
+
+Шляхи, що починаються з `\\server\share` (UNC-шляхи до мережевих ресурсів), відхиляються валідатором вхідних даних. Підключіть мережевий ресурс як літеру диска (наприклад `Z:\`) і використовуйте цей шлях.
+
+---
+
+## Очищення тимчасових файлів
+
+Файли стану завдань (`.json` і `.log`) у `%TEMP%\whisper-mcp-jobs\` автоматично очищуються при запуску для файлів старших 7 днів. При необхідності можна виконати ручне очищення:
+
+```powershell
+Remove-Item "$env:TEMP\whisper-mcp-jobs\*" -Force
+```
+
+Тимчасові WAV-файли конвертування (`whisper_tmp_*.wav` у `%TEMP%`) видаляються одразу після завершення кожної транскрипції. Якщо транскрипція аварійно завершилась, вони можуть залишитися. Видаліть їх вручну:
+
+```powershell
+Remove-Item "$env:TEMP\whisper_tmp_*.wav" -Force
+```
+
+---
+
+## Великий автономний пакет з командного рядка
+
+Для дуже великих пакетів без Claude використовуйте PowerShell безпосередньо.
+
+**Важливо:** whisper-cli.exe не може безпосередньо читати MP4, MKV або більшість відеоформатів. FFmpeg має попередньо конвертувати кожен файл у WAV. Whisper записує транскрипцію у stdout, а діагностику у stderr — використовуйте `Start-Process -RedirectStandardOutput` для правильного захоплення.
+
+```powershell
+$whisper = "C:\whisper\Release\whisper-cli.exe"
+$model   = "C:\whisper\models\ggml-medium.en.bin"
+$dir     = "C:\шлях\до\вашої\теки"
+$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 "ПРОПУСК (існує): $($_.Name)"
+        return
+    }
+    Write-Host "Конвертування:    $($_.Name)"
+    & $ffmpeg -y -i $_.FullName -ar 16000 -ac 1 -c:a pcm_s16le $tmp 2>$null
+    Write-Host "Транскрипція:  $($_.Name)"
+    $wArgs = "-m `"$model`" -f `"$tmp`" --threads 8 --max-context 0 --no-speech-thold 0.6"
+    Start-Process -FilePath $whisper -ArgumentList $wArgs -RedirectStandardOutput $out -Wait -NoNewWindow
+    Write-Host "Готово:          $($_.BaseName).txt"
+}
+
+Remove-Item $tmp -ErrorAction SilentlyContinue
+Write-Host "Все готово."
+```
+
+Замініть `*.mp4` на `*.mkv`, `*.m4a` тощо відповідно до типів ваших файлів. Перевірка пропуску `Test-Path` означає, що повторний запуск скрипту після переривання не переопрацьовуватиме вже завершені файли.
+
+---
+
+## Розташування файлу конфігурації
+
+```
+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 встановлено в нестандартному місці.