whisper-windows-mcp 2.2.1 → 2.2.2

package/ROADMAP.uk.md

@@ -1,291 +1,290 @@
-# whisper-windows-mcp — Дорожня карта
-
-Поточна версія: **v2.2.0**
-
----
-
-## Принципи проєктування
-
-Ці принципи визначають кожне рішення в цьому проєкті і мають пріоритет над швидкістю додавання функцій.
-
-**Мінімізація використання Claude API.** Весь робочий процес транскрипції — сканування, аналіз, черга, виконання, перевірка, перемикання моделей — має виконуватися з мінімальною кількістю взаємодій з Claude. Цей інструмент має повноцінно працювати для користувачів безкоштовного плану Claude, які не платять за підписки Pro або Max. Кожен виклик інструменту витрачає ліміт використання. Проєктуйте відповідно.
-
-**Завжди лише один екземпляр whisper.** Ніколи не запускайте другий процес whisper-cli.exe, поки один вже виконується. Блокування процесу є обов'язковим і не підлягає переговорам.
-
-**Локальний пріоритет, приватно за замовчуванням.** Аудіо ніколи не покидає комп'ютер. Для основних функцій хмарні API не потрібні. Необов'язкові інтеграції (наприклад, завантаження моделей з Hugging Face) мають бути чітко задокументовані як необов'язкові.
-
-**Явний контроль користувача.** Жодних тихих масових операцій. Руйнівні або незворотні дії потребують підтвердження. Користувач завжди має знати, що відбуватиметься, до того, як це станеться.
-
-**Unicode-безпечні шляхи.** Весь файловий введення-виведення має правильно обробляти не-ASCII імена файлів, включно з українськими, японськими, китайськими, емодзі, дужками та іншими спеціальними символами.
-
-**Модульність і компонованість.** Інструменти незалежні. Користувачі використовують те, що їм потрібно. Жодна функція не повинна вимагати іншої, якщо цього неможливо уникнути.
-
-**Оптимізація перед функціями.** Якщо сумніваєтеся між додаванням функції та зменшенням навантаження на систему або кількості викликів API — зменшуйте навантаження. Великі оптимізаційні роботи дорого коштують. Спроєктуйте архітектуру правильно з першого разу.
-
----
-
-## Завершено
-
-### ✅ v1.3.1 — Блокування процесу
-Додано перевірку `isWhisperRunning()` з використанням `tasklist /FI` перед запуском будь-якої транскрипції. Повертає чітку помилку з інструкціями Диспетчера завдань замість запуску конкурентного процесу.
-
-### ✅ v1.4.0 — Vulkan GPU-прискорення
-Скомпільовано whisper.cpp з вихідного коду з `-DGGML_VULKAN=ON` за допомогою VS Build Tools 2022 і Vulkan SDK. Готові Vulkan-бінарники розповсюджуються як `whisper-vulkan-win-x64.zip`.
-
-**Результати на AMD Radeon RX Vega 56:** Середнє навантаження GPU ~16%. 58-хвилинний файл завершується за ~4.5 хвилини на GPU проти ~88 хвилин лише на CPU.
-
-### ✅ v1.5.0 — Системна діагностика
-Інструмент `check_system`: виявлення GPU через `wmic`, перевірка Vulkan DLL, звіт про VRAM, рекомендація розміру моделі.
-
-### ✅ v1.6.0 — Попередній аналіз файлу
-Інструмент `analyze_media` через FFprobe: тривалість, розмір, кодек, статус транскрипції, оцінки часу CPU і GPU. Сканування одного файлу або теки з параметрами сортування.
-
-### ✅ v1.7.0 — Фонова транскрипція + Відображення прогресу
-Архітектура відокремленого процесу: `transcribe_audio` з `background=true` запускає whisper як відокремлений процес і одразу повертає ID завдання. `check_progress` аналізує мітки часу сегментів stderr whisper для відсотку і ETA в реальному часі.
-
-### ✅ v1.8.0 — Послідовний пакет з перевіркою
-`start_batch` і `check_batch_progress`: автоматична послідовна обробка, перевірка транскрипції (виявлення порожнього/короткого виводу), автоматичне просування черги, мітки часу прогресу для кожного файлу.
-
-### ✅ v1.9.0 — Багатомовна підтримка і переклад
-`generate_subtitles` з виявленням `language=auto` і подвійним SRT-виводом `translate_to_english=true`. Додано підтримку форматів `.3gp` і `.ts`. `language=auto` також доступний у `transcribe_audio`.
-
-**Відоме обмеження:** Вбудований переклад Whisper орієнтований лише на англійську. Для не-англійських мов потрібна модель `large-v3` — моделі лише для англійської (`*.en.bin`) виводять `[FOREIGN]` для не-англійського аудіо.
-
-### ✅ v2.0.0 — Unicode-безпечні шляхи + Фоновий SRT
-**Імена файлів Unicode:** Файли з не-ASCII символами в іменах спричиняли тихе невдале виконання фонової транскрипції. Виправлено шляхом спрямування всього виводу через санований тимчасовий шлях на основі ID завдання, а потім переміщення результату до правильного призначення після завершення.
-
-**SRT у фоновому режимі:** `spawnDetached` раніше жорстко кодував `-otxt` незалежно від запитаного формату, а `generate_subtitles` синхронно блокував і досягав 4-хвилинного тайм-ауту MCP на довших файлах. Виправлено додаванням параметра `outputFormat` до `spawnDetached`, що підтримує вивід `text` і `srt` у фоновому режимі.
-
-### ✅ v2.0.1 — Виправлення помилок (включено у v2.2.0)
-- `--max-context 0` жорстко закодовано в `buildArgs` і `spawnDetached` — запобігає циклам галюцинацій на довгих аудіозаписах. `--condition-on-previous-text` і `--no-context` — недійсні прапорці в поточному бінарнику (покоління v1.8.3) — `--max-context N` є правильним прапорцем.
-- `--no-speech-thold 0.6` жорстко закодовано в обох функціях — сегменти нижче порогу впевненості обробляються як тиша, а не як галюцинований вміст.
-- Перевірка шляху (`validateInputPath`) — відхиляє UNC-шляхи і обходи `..`.
-- Захист розміру файлу `MAX_FILE_SIZE_MB = 10240`.
-- Коментар безпеки ін'єкції транскрипції у `transcribeSingle`.
-- Виправлено зламану команду CLI-пакету у TROUBLESHOOTING.md — задокументовано правильний підхід до попереднього конвертування FFmpeg і метод `Start-Process -RedirectStandardOutput`.
-
-### ✅ v2.1.0 — Набір інструментів управління моделями (включено у v2.2.0)
-- `WHISPER_MODEL` змінено з `const` на `let` (змінюється в межах сеансу).
-- `MODEL_REGISTRY` — 16 моделей, варіанти повної точності та квантизовані, URL завантаження Hugging Face.
-- `ALLOWED_HF_PREFIXES` — список дозволених URL, що обмежує завантаження просторами імен `ggerganov/whisper.cpp` і `ggml-org`.
-- Інструмент `list_models` — сканує теку моделей, показує активну модель, розміри, випадки використання, доступні завантаження.
-- Інструмент `download_model` — завантажує з Hugging Face через вбудований `https` Node.js, атомарне перейменування (виправлення стану гонки звільнення файлового дескриптора Windows).
-- Інструмент `switch_model` — перевіряє розширення `.bin`, обмеження теки, перевірку блокування процесу.
-- `recommendedModel()` оновлено для рекомендації `large-v3-turbo` при VRAM 6 ГБ+.
-
-### ✅ v2.2.0 — Розширення якості, параметрів і апаратного забезпечення (поточна)
-- Інтерфейс `WhisperOptions` замінює позиційні аргументи в `buildArgs`.
-- Нові параметри у `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`.
-- Нові параметри у `generate_subtitles`: `temperature`, `prompt`, `beam_size`, `best_of`, `diarize`, `vad_model`.
-- Рефакторинг `spawnDetached` — усі прапорці якості тепер застосовуються у фоновому/пакетному режимі.
-- `runSrtPass` оновлено для прийняття `extraOpts`.
-- Виправлення виводу пакету — `readBatchProgress` тепер переміщає тимчасовий вивід до кінцевого призначення перед перевіркою (це була корінна причина всіх результатів "помилка" у пакеті).
-
-**Примітка щодо сумісності прапорців:** `gpu_device` / `-g` додано у whisper.cpp v1.8.4. Готовий Vulkan-бінарник у релізах є покоління v1.8.3 — цей параметр приймається інструментом, але не матиме ефекту, доки користувачі не оновляться до бінарника v1.8.4+.
-
-**Підтверджені дійсні прапорці у поточному бінарнику (покоління v1.8.3):**
-`--max-context`, `--no-speech-thold`, `--processors`, `--offset-t`, `--duration`, `--best-of`, `--beam-size`, `--diarize`, `--tinydiarize`, `--temperature`, `--prompt`, VAD-прапорці.
-
-**Відсутні у поточному бінарнику:** `--no-context` (використовуйте `--max-context 0`), `--condition-on-previous-text` (лише назва Python API), `--gpu-device` / `-g` (v1.8.4+).
-
----
-
-## Критична помилка — Автоматичне просування пакету (підтверджено, очікує виправлення)
-
-### Пакет не просувається без активного опитування
-
-`start_batch` не просуває чергу автономно між файлами. Пакет просувається лише при виклику `check_batch_progress`. Без опитування пакет зависає на невизначений час після кожного файлу — whisper-cli.exe завершується, новий процес не запускається, черга не просувається.
-
-Це підриває мету дизайну автономної нічної пакетної обробки і безпосередньо порушує принцип мінімізації викликів Claude API. Пакет з 95 коротких кліпів вимагав близько 200 викликів опитування протягом 100 хвилин для завершення.
-
-**Корінна причина:** `readBatchProgress` містить всю логіку просування черги. Він виконується лише при явному виклику `check_batch_progress`. Немає фонового таймера, спостерігача файлів або автономного циклу.
-
-**Заплановане виправлення — Варіант Б (зворотній виклик виходу, наполегливо рекомендовано):** Прикріпити обробник `on('exit')` до породженого дочірнього процесу whisper-cli. Коли процес завершується, негайно викликати логіку просування для перевірки виводу і запуску наступного завдання. Подієво-орієнтований, спрацьовує рівно один раз при завершенні кожного файлу, нульові витрати на опитування, нуль спожитих викликів API.
-
-**Варіант А (лише резервний):** Фоновий `setInterval` з інтервалом опитування на основі тривалості, виведеним з даних тривалості FFprobe, вже наявних у JSON стану пакету. Розмір файлу не є надійним замінником тривалості.
-
-**Додаткове обмеження:** Виправлення не повинно породжувати другий whisper-cli.exe, поки один вже виконується — блокування процесу має дотримуватися в шляху автопросування.
-
-**Обхідне рішення (поточне):** Повторно викликайте `check_batch_progress` до завершення пакету. Приблизно один виклик опитування на файл.
-
----
-
-## Заплановано — Архітектура конфіденційності (до міграції на Bun)
-
-Ці зміни мають бути випущені до міграції на Bun і до будь-яких змін ліцензії, що сприяють комерційному або корпоративному прийняттю. Випуск інструментів корпоративного рівня без вирішених засобів захисту відповідності створює відповідальність для користувачів у регульованих галузях.
-
-### Змінна середовища `WHISPER_PRIVACY_MODE`
-Інструмент наразі гарантує, що жодне **аудіо** не покидає комп'ютер. Ця гарантія не поширюється на **текст транскрипції** — коли вміст транскрипції повертається в рядку у відповіді інструменту, цей текст опрацьовується API Claude і покидає локальне середовище.
-
-Цей розрив невидимий для користувачів, які розумно тлумачать "дані не покидають ваш комп'ютер" як таке, що охоплює весь контент, отриманий з їхнього аудіо.
-
-Додати `WHISPER_PRIVACY_MODE` як змінну середовища у `claude_desktop_config.json`. При увімкненні:
-- Усі відповіді інструментів повертають лише метадані: ім'я файлу, тривалість, кількість слів, статус завершення
-- Жоден текст транскрипції не включається до жодної відповіді інструменту
-- Claude не може читати, аналізувати або передавати вміст транскрипції в жодній формі
-- Транскрипція існує лише як локальний `.txt`-файл
-
-Це правильне рішення для медичних, юридичних, фінансових і корпоративних розгортань. Нуль викликів API, нуль передачі даних, нуль ризику відповідності.
-
-### Ворота згоди для вмісту транскрипції
-Коли `WHISPER_PRIVACY_MODE` не увімкнено (типово), будь-яка відповідь інструменту, що містить текст транскрипції, має передуватися повідомленням про розкриття інформації при першому використанні за сеанс. Це повідомлення має чітко передати, що текст транскрипції передається до API Anthropic, що це виходить за межі гарантії "дані не покидають ваш комп'ютер", і що користувачі, які працюють з регульованим контентом, мають перевірити зобов'язання відповідності перед продовженням.
-
-Реалізація: змінна середовища `WHISPER_CONSENT_ACKNOWLEDGED` за замовчуванням `false`. При першому поверненні транскрипції за сеанс, якщо не підтверджено, Claude представляє повідомлення про розкриття і просить явного підтвердження. Після підтвердження для сеансу наступні транскрипції повертаються без повторного запиту.
-
-### Документація `PRIVACY.md`
-Створити `PRIVACY.md` у кореневій теці репозиторію:
-- Які дані завжди залишаються локально: аудіо, відео, файли моделей
-- Які дані можуть покидати локальне середовище (за замовчуванням): текст транскрипції у відповідях інструментів
-- Які дані ніколи не покидають локальне середовище (з режимом конфіденційності): все
-- Настанови щодо відповідності за галуззю (HIPAA, GDPR, адвокатська таємниця, FERPA, SOX, PCI-DSS, NDA/комерційна таємниця)
-- Як налаштувати режим конфіденційності
-- Відмова від відповідальності: автори інструменту не є юридичними радниками
-
-### Попередження конфіденційності у схемі інструментів
-Оновити описи інструментів `ListToolsRequestSchema`, включивши примітку про конфіденційність для будь-якого інструменту, що повертає текст транскрипції. Це відображається в описах інструментів Claude Desktop і підвищує обізнаність у точці використання.
-
-### Автоматичне очищення тимчасової теки
-`%TEMP%\whisper-mcp-jobs\` накопичує файли стану завдань і журнали з часом. Додати автоматичне очищення завершених файлів завдань після налаштованого вікна збереження (типово: 7 днів). Наразі вимагає ручного `Remove-Item` від користувача.
-
----
-
-## Заплановано — Міграція на Bun
-
-Перенести середовище виконання з Node.js на [Bun](https://bun.sh) після завершення архітектури конфіденційності і до додавання функцій v2.3.0.
-
-Оскільки Claude Desktop запускає MCP-сервер заново при кожному запуску сеансу, час запуску знаходиться на критичному шляху. Bun виконує TypeScript нативно без кроку компіляції, запускається значно швидше за Node і має швидший введення-виведення.
-
-**Що змінюється:**
-- Усунення кроку збірки `tsc` і теки `dist/`
-- Користувачі запускають вихідний код TypeScript безпосередньо
-- `tsconfig.json` стає необов'язковим
-- Оновлення скриптів `package.json`
-- Оновлення робочого процесу публікації npm
-
-**Що не змінюється:**
-- Вихідний код `src/index.ts` — Bun сумісний з існуючим TypeScript і вбудованими API Node.js
-- Уся поведінка інструментів і формати виводу
-- Конфігурація Claude Desktop для кінцевих користувачів
-
-**Чому після конфіденційності, до v2.3.0:** Кодова база найлегше піддається міграції зараз. Міграція після додавання більшої кількості інструментів лише збільшує поверхню без вигоди. Архітектура конфіденційності має бути реалізована першою, як зазначено вище.
-
----
-
-## Заплановано — Перегляд ліцензії (після міграції на Bun)
-
-Поточна ліцензія MIT дозволяє необмежене комерційне використання. До того, як інструмент досягне профільних і корпоративних ринків у масштабі, ситуацію з ліцензією необхідно оцінити.
-
-**Запланований підхід — Подвійна ліцензія:**
-- MIT для особистого та некомерційного використання (без змін для існуючих користувачів)
-- Окрема комерційна ліцензія для бізнес- і корпоративного використання
-- Точка переходу: наступний мажорний реліз після міграції на Bun
-
-**Чому не зараз:** Зміна ліцензії до завершення архітектури конфіденційності означала б продаж комерційних ліцензій для інструменту з невирішеними прогалинами відповідності HIPAA/GDPR. Спочатку конфіденційність, потім перегляд ліцензії.
-
-Комерційна ліцензія, попередження конфіденційності у схемі інструментів і `PRIVACY.md` разом формують мінімально достатню розповідь про відповідність для корпоративних покупців.
-
----
-
-## Заплановано — v2.3.0: Розширення форматів виводу
-
-### Формат субтитрів VTT
-Вивід WebVTT (`.vtt`) разом з SRT. VTT — веб-стандарт, що використовується YouTube, HTML5 `<video>` і більшістю сучасних програвачів. whisper-cli підтримує його нативно. Додати `vtt` як дійсний формат виводу у `transcribe_audio`, `generate_subtitles` і `spawnDetached`. Оновити `buildArgs` і всі відповідні схеми інструментів, README і багатомовну документацію.
-
-### Формат LRC
-Вивід у форматі LRC (`.lrc`) текстів пісень/караоке через `-olrc`. Використовується медіапрогравачами для синхронізованого відображення текстів. Нульові витрати на реалізацію — рідний прапорець CLI.
-
-### Формат CSV
-Вивід CSV (`.csv`) через `-ocsv`. Структуровані табличні дані з часовою розміткою сегментів — корисні для аналізу нижнього рівня, робочих процесів вирівнювання кліпів та імпорту в табличні інструменти. Нульові витрати на реалізацію — рідний прапорець CLI.
-
----
-
-## Заплановано — Майбутні релізи
-
-### TinyDiarize
-Підтримка прапорця `--tinydiarize` з варіантами моделей, що підтримують `tdrz` (наприклад `large-v2-tdrz`). На відміну від стерео-прапорця `--diarize`, TinyDiarize працює з моно записами. Потребує завантаження спеціального варіанту моделі. Нижча точність, ніж дiaризація на основі pyannote, але нульові додаткові залежності за межами файлу моделі.
-
-**Статус:** Заплановано. Залежить від підтримки варіантів моделей tdrz у `download_model`.
-
-### Транскрипція URL YouTube
-Пряма транскрипція з URL YouTube через yt-dlp. Завантаження аудіо і транскрипція в один крок. Потребує встановленого yt-dlp і наявності в PATH.
-
-**Обмеження проєктування:** yt-dlp є необов'язковим. Інструмент має коректно деградувати з чіткими інструкціями щодо встановлення, якщо його не знайдено. Жодних змін в основній функціональності для користувачів, яким це не потрібно.
-
-### Інструменти робочого процесу відеопроєкту
-Для користувачів, що керують великими проєктами відеомонтажу з теками вихідних і відредагованих кліпів:
-
-1. Сканування вихідної теки і підтеки кліпів
-2. Нечітке зіставлення транскрипцій відредагованих кліпів з вихідними транскрипціями для визначення точок походження
-3. Відображення описових імен файлів, запропонованих Claude на основі вмісту транскрипцій, з вимогою явного підтвердження від користувача перед виконанням будь-якого перейменування
-4. Пошук транскрипцій у теці проєкту з результатами за часовим кодом
-
-**Обмеження проєктування:**
-- Вихідні файли **ніколи не перейменовуються і не змінюються**
-- Усі перейменування вимагають **явного підтвердження користувача**
-- Пошук — це окремий інструмент, що може використовуватися незалежно
-- Аналіз і зіставлення відбуваються локально — Claude викликається лише коли користувач переглядає результати, мінімізуючи виклики API
-
-**Статус:** Фаза проєктування.
-
-### Розрізнення доповідачів (pyannote-audio)
-Повне розрізнення доповідачів у моно з мітками ID доповідача — позначає переходи між доповідачами по всьому запису незалежно від конфігурації каналів. Відрізняється від вбудованого стерео-прапорця `--diarize` (v2.2.0) і TinyDiarize.
-
-**Реалізація:** Потребує [pyannote-audio](https://github.com/pyannote/pyannote-audio) — бібліотеки на основі Python з вимогою токена доступу до моделей Hugging Face. Повністю окремий стек залежностей від конвеєра whisper.cpp.
-
-**Статус:** Необов'язкова розширена функція з власною документацією з налаштування. Не входить до основного пакету.
-
-### Переклад на не-англійські мови
-Прапорець `--translate` Whisper орієнтований лише на англійську. Підтримка довільних цільових мов потребує зовнішнього API перекладу або локальної моделі перекладу.
-
-**Варіанти, що розглядаються:** LibreTranslate (можна розгорнути самостійно, локальний пріоритет), локальний LLM-переклад або явна документація поза межами охоплення.
-
-**Статус:** Відкладено, очікує дизайнерського рішення щодо локального пріоритету проти залежності від API.
-
-### Очищення і форматування транскрипції
-Конвеєр постобробки:
-- Видалення слів-заповнювачів і невдалих початків (необов'язково, під контролем користувача)
-- Розриви абзаців на природних межах тем
-- Форматування з урахуванням доповідачів у поєднанні з виводом розрізнення
-- Експорт у PDF або DOCX
-
-**Статус:** Заплановано. Варіант з урахуванням доповідачів залежить від розрізнення.
-
----
-
-## Поширення
-
-Доступно на [npm](https://www.npmjs.com/package/whisper-windows-mcp), [mcpservers.org](https://mcpservers.org) і [Glama](https://glama.ai).
-
----
-
-## Багатомовна документація
-
-Документація японською, корейською, в'єтнамською, індонезійською та українською мовами підтримується паралельно з англійською. Після кожного релізу необхідно оновлювати такі файли відповідно до англійської документації:
-
-**Японська (`*.ja.md`)**
-- `README.ja.md` / `TROUBLESHOOTING.ja.md` / `ROADMAP.ja.md` / `PRIVACY.ja.md` / `SECURITY.ja.md`
-
-**Корейська (`*.ko.md`)**
-- `README.ko.md` / `TROUBLESHOOTING.ko.md` / `ROADMAP.ko.md` / `PRIVACY.ko.md` / `SECURITY.ko.md`
-
-**В'єтнамська (`*.vi.md`)**
-- `README.vi.md` / `TROUBLESHOOTING.vi.md` / `ROADMAP.vi.md` / `PRIVACY.vi.md` / `SECURITY.vi.md`
-
-**Індонезійська (`*.id.md`)**
-- `README.id.md` / `TROUBLESHOOTING.id.md` / `ROADMAP.id.md` / `PRIVACY.id.md` / `SECURITY.id.md`
-
-**Українська (`*.uk.md`)** — `README.uk.md` / `TROUBLESHOOTING.uk.md` / `ROADMAP.uk.md` / `PRIVACY.uk.md` / `SECURITY.uk.md`
-
-**Бразильська португальська (`*.pt-BR.md`)** — `README.pt-BR.md` / `TROUBLESHOOTING.pt-BR.md` / `ROADMAP.pt-BR.md` / `PRIVACY.pt-BR.md` / `SECURITY.pt-BR.md`
-
-**Іспанська (`*.es.md`)** — `README.es.md` / `TROUBLESHOOTING.es.md` / `ROADMAP.es.md` / `PRIVACY.es.md` / `SECURITY.es.md`
-
-Внески спільноти для інших мов вітаються.
-
----
-
-## Внески
-
-Pull requests вітаються. Перевірте наявні issues перед початком роботи.
-
-Якщо ви тестували прискорення GPU на обладнанні, не вказаному вище, будь ласка, відкрийте issue з результатами — модель GPU, обсяг VRAM, розмір моделі та спостережувана пропускна здатність. Це допомагає створити точний орієнтир продуктивності для інших користувачів.
+# whisper-windows-mcp — Дорожня карта
+
+Поточна версія: **v2.2.0**
+
+---
+
+## Принципи проєктування
+
+Ці принципи визначають кожне рішення в цьому проєкті і мають пріоритет над швидкістю додавання функцій.
+
+**Мінімізація використання Claude API.** Весь робочий процес транскрипції — сканування, аналіз, черга, виконання, перевірка, перемикання моделей — має виконуватися з мінімальною кількістю взаємодій з Claude. Цей інструмент має повноцінно працювати для користувачів безкоштовного плану Claude, які не платять за підписки Pro або Max. Кожен виклик інструменту витрачає ліміт використання. Проєктуйте відповідно.
+
+**Завжди лише один екземпляр whisper.** Ніколи не запускайте другий процес whisper-cli.exe, поки один вже виконується. Блокування процесу є обов'язковим і не підлягає переговорам.
+
+**Локальний пріоритет, приватно за замовчуванням.** Аудіо ніколи не покидає комп'ютер. Для основних функцій хмарні API не потрібні. Необов'язкові інтеграції (наприклад, завантаження моделей з Hugging Face) мають бути чітко задокументовані як необов'язкові.
+
+**Явний контроль користувача.** Жодних тихих масових операцій. Руйнівні або незворотні дії потребують підтвердження. Користувач завжди має знати, що відбуватиметься, до того, як це станеться.
+
+**Unicode-безпечні шляхи.** Весь файловий введення-виведення має правильно обробляти не-ASCII імена файлів, включно з українськими, японськими, китайськими, емодзі, дужками та іншими спеціальними символами.
+
+**Модульність і компонованість.** Інструменти незалежні. Користувачі використовують те, що їм потрібно. Жодна функція не повинна вимагати іншої, якщо цього неможливо уникнути.
+
+**Оптимізація перед функціями.** Якщо сумніваєтеся між додаванням функції та зменшенням навантаження на систему або кількості викликів API — зменшуйте навантаження. Великі оптимізаційні роботи дорого коштують. Спроєктуйте архітектуру правильно з першого разу.
+
+---
+
+## Завершено
+
+### ✅ v1.3.1 — Блокування процесу
+Додано перевірку `isWhisperRunning()` з використанням `tasklist /FI` перед запуском будь-якої транскрипції. Повертає чітку помилку з інструкціями Диспетчера завдань замість запуску конкурентного процесу.
+
+### ✅ v1.4.0 — Vulkan GPU-прискорення
+Скомпільовано whisper.cpp з вихідного коду з `-DGGML_VULKAN=ON` за допомогою VS Build Tools 2022 і Vulkan SDK. Готові Vulkan-бінарники розповсюджуються як `whisper-vulkan-win-x64.zip`.
+
+**Результати на AMD Radeon RX Vega 56:** Середнє навантаження GPU ~16%. 58-хвилинний файл завершується за ~4.5 хвилини на GPU проти ~88 хвилин лише на CPU.
+
+### ✅ v1.5.0 — Системна діагностика
+Інструмент `check_system`: виявлення GPU через `wmic`, перевірка Vulkan DLL, звіт про VRAM, рекомендація розміру моделі.
+
+### ✅ v1.6.0 — Попередній аналіз файлу
+Інструмент `analyze_media` через FFprobe: тривалість, розмір, кодек, статус транскрипції, оцінки часу CPU і GPU. Сканування одного файлу або теки з параметрами сортування.
+
+### ✅ v1.7.0 — Фонова транскрипція + Відображення прогресу
+Архітектура відокремленого процесу: `transcribe_audio` з `background=true` запускає whisper як відокремлений процес і одразу повертає ID завдання. `check_progress` аналізує мітки часу сегментів stderr whisper для відсотку і ETA в реальному часі.
+
+### ✅ v1.8.0 — Послідовний пакет з перевіркою
+`start_batch` і `check_batch_progress`: автоматична послідовна обробка, перевірка транскрипції (виявлення порожнього/короткого виводу), автоматичне просування черги, мітки часу прогресу для кожного файлу.
+
+### ✅ v1.9.0 — Багатомовна підтримка і переклад
+`generate_subtitles` з виявленням `language=auto` і подвійним SRT-виводом `translate_to_english=true`. Додано підтримку форматів `.3gp` і `.ts`. `language=auto` також доступний у `transcribe_audio`.
+
+**Відоме обмеження:** Вбудований переклад Whisper орієнтований лише на англійську. Для не-англійських мов потрібна модель `large-v3` — моделі лише для англійської (`*.en.bin`) виводять `[FOREIGN]` для не-англійського аудіо.
+
+### ✅ v2.0.0 — Unicode-безпечні шляхи + Фоновий SRT
+**Імена файлів Unicode:** Файли з не-ASCII символами в іменах спричиняли тихе невдале виконання фонової транскрипції. Виправлено шляхом спрямування всього виводу через санований тимчасовий шлях на основі ID завдання, а потім переміщення результату до правильного призначення після завершення.
+
+**SRT у фоновому режимі:** `spawnDetached` раніше жорстко кодував `-otxt` незалежно від запитаного формату, а `generate_subtitles` синхронно блокував і досягав 4-хвилинного тайм-ауту MCP на довших файлах. Виправлено додаванням параметра `outputFormat` до `spawnDetached`, що підтримує вивід `text` і `srt` у фоновому режимі.
+
+### ✅ v2.0.1 — Виправлення помилок (включено у v2.2.0)
+- `--max-context 0` жорстко закодовано в `buildArgs` і `spawnDetached` — запобігає циклам галюцинацій на довгих аудіозаписах. `--condition-on-previous-text` і `--no-context` — недійсні прапорці в поточному бінарнику (покоління v1.8.3) — `--max-context N` є правильним прапорцем.
+- `--no-speech-thold 0.6` жорстко закодовано в обох функціях — сегменти нижче порогу впевненості обробляються як тиша, а не як галюцинований вміст.
+- Перевірка шляху (`validateInputPath`) — відхиляє UNC-шляхи і обходи `..`.
+- Захист розміру файлу `MAX_FILE_SIZE_MB = 10240`.
+- Коментар безпеки ін'єкції транскрипції у `transcribeSingle`.
+- Виправлено зламану команду CLI-пакету у TROUBLESHOOTING.md — задокументовано правильний підхід до попереднього конвертування FFmpeg і метод `Start-Process -RedirectStandardOutput`.
+
+### ✅ v2.1.0 — Набір інструментів управління моделями (включено у v2.2.0)
+- `WHISPER_MODEL` змінено з `const` на `let` (змінюється в межах сеансу).
+- `MODEL_REGISTRY` — 16 моделей, варіанти повної точності та квантизовані, URL завантаження Hugging Face.
+- `ALLOWED_HF_PREFIXES` — список дозволених URL, що обмежує завантаження просторами імен `ggerganov/whisper.cpp` і `ggml-org`.
+- Інструмент `list_models` — сканує теку моделей, показує активну модель, розміри, випадки використання, доступні завантаження.
+- Інструмент `download_model` — завантажує з Hugging Face через вбудований `https` Node.js, атомарне перейменування (виправлення стану гонки звільнення файлового дескриптора Windows).
+- Інструмент `switch_model` — перевіряє розширення `.bin`, обмеження теки, перевірку блокування процесу.
+- `recommendedModel()` оновлено для рекомендації `large-v3-turbo` при VRAM 6 ГБ+.
+
+### ✅ v2.2.0 — Розширення якості, параметрів і апаратного забезпечення (поточна)
+- Інтерфейс `WhisperOptions` замінює позиційні аргументи в `buildArgs`.
+- Нові параметри у `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`.
+- Нові параметри у `generate_subtitles`: `temperature`, `prompt`, `beam_size`, `best_of`, `diarize`, `vad_model`.
+- Рефакторинг `spawnDetached` — усі прапорці якості тепер застосовуються у фоновому/пакетному режимі.
+- `runSrtPass` оновлено для прийняття `extraOpts`.
+- Виправлення виводу пакету — `readBatchProgress` тепер переміщає тимчасовий вивід до кінцевого призначення перед перевіркою (це була корінна причина всіх результатів "помилка" у пакеті).
+
+**Примітка щодо сумісності прапорців:** `gpu_device` / `-g` додано у whisper.cpp v1.8.4. Готовий Vulkan-бінарник у релізах є покоління v1.8.3 — цей параметр приймається інструментом, але не матиме ефекту, доки користувачі не оновляться до бінарника v1.8.4+.
+
+**Підтверджені дійсні прапорці у поточному бінарнику (покоління v1.8.3):**
+`--max-context`, `--no-speech-thold`, `--processors`, `--offset-t`, `--duration`, `--best-of`, `--beam-size`, `--diarize`, `--tinydiarize`, `--temperature`, `--prompt`, VAD-прапорці.
+
+**Відсутні у поточному бінарнику:** `--no-context` (використовуйте `--max-context 0`), `--condition-on-previous-text` (лише назва Python API), `--gpu-device` / `-g` (v1.8.4+).
+
+---
+
+## Критична помилка — Автоматичне просування пакету (підтверджено, очікує виправлення)
+
+### Пакет не просувається без активного опитування
+
+`start_batch` не просуває чергу автономно між файлами. Пакет просувається лише при виклику `check_batch_progress`. Без опитування пакет зависає на невизначений час після кожного файлу — whisper-cli.exe завершується, новий процес не запускається, черга не просувається.
+
+Це підриває мету дизайну автономної нічної пакетної обробки і безпосередньо порушує принцип мінімізації викликів Claude API. Пакет з 95 коротких кліпів вимагав близько 200 викликів опитування протягом 100 хвилин для завершення.
+
+**Корінна причина:** `readBatchProgress` містить всю логіку просування черги. Він виконується лише при явному виклику `check_batch_progress`. Немає фонового таймера, спостерігача файлів або автономного циклу.
+
+**Заплановане виправлення — Варіант Б (зворотній виклик виходу, наполегливо рекомендовано):** Прикріпити обробник `on('exit')` до породженого дочірнього процесу whisper-cli. Коли процес завершується, негайно викликати логіку просування для перевірки виводу і запуску наступного завдання. Подієво-орієнтований, спрацьовує рівно один раз при завершенні кожного файлу, нульові витрати на опитування, нуль спожитих викликів API.
+
+**Варіант А (лише резервний):** Фоновий `setInterval` з інтервалом опитування на основі тривалості, виведеним з даних тривалості FFprobe, вже наявних у JSON стану пакету. Розмір файлу не є надійним замінником тривалості.
+
+**Додаткове обмеження:** Виправлення не повинно породжувати другий whisper-cli.exe, поки один вже виконується — блокування процесу має дотримуватися в шляху автопросування.
+
+**Обхідне рішення (поточне):** Повторно викликайте `check_batch_progress` до завершення пакету. Приблизно один виклик опитування на файл.
+
+---
+
+## Заплановано — Архітектура конфіденційності (до міграції на Bun)
+
+Ці зміни мають бути випущені до міграції на Bun і до будь-яких змін ліцензії, що сприяють комерційному або корпоративному прийняттю. Випуск інструментів корпоративного рівня без вирішених засобів захисту відповідності створює відповідальність для користувачів у регульованих галузях.
+
+### Змінна середовища `WHISPER_PRIVACY_MODE`
+Інструмент наразі гарантує, що жодне **аудіо** не покидає комп'ютер. Ця гарантія не поширюється на **текст транскрипції** — коли вміст транскрипції повертається в рядку у відповіді інструменту, цей текст опрацьовується API Claude і покидає локальне середовище.
+
+Цей розрив невидимий для користувачів, які розумно тлумачать "дані не покидають ваш комп'ютер" як таке, що охоплює весь контент, отриманий з їхнього аудіо.
+
+Додати `WHISPER_PRIVACY_MODE` як змінну середовища у `claude_desktop_config.json`. При увімкненні:
+- Усі відповіді інструментів повертають лише метадані: ім'я файлу, тривалість, кількість слів, статус завершення
+- Жоден текст транскрипції не включається до жодної відповіді інструменту
+- Claude не може читати, аналізувати або передавати вміст транскрипції в жодній формі
+- Транскрипція існує лише як локальний `.txt`-файл
+
+Це правильне рішення для медичних, юридичних, фінансових і корпоративних розгортань. Нуль викликів API, нуль передачі даних, нуль ризику відповідності.
+
+### Ворота згоди для вмісту транскрипції
+Коли `WHISPER_PRIVACY_MODE` не увімкнено (типово), будь-яка відповідь інструменту, що містить текст транскрипції, має передуватися повідомленням про розкриття інформації при першому використанні за сеанс. Це повідомлення має чітко передати, що текст транскрипції передається до API Anthropic, що це виходить за межі гарантії "дані не покидають ваш комп'ютер", і що користувачі, які працюють з регульованим контентом, мають перевірити зобов'язання відповідності перед продовженням.
+
+Реалізація: змінна середовища `WHISPER_CONSENT_ACKNOWLEDGED` за замовчуванням `false`. При першому поверненні транскрипції за сеанс, якщо не підтверджено, Claude представляє повідомлення про розкриття і просить явного підтвердження. Після підтвердження для сеансу наступні транскрипції повертаються без повторного запиту.
+
+### Документація `PRIVACY.md`
+Створити `PRIVACY.md` у кореневій теці репозиторію:
+- Які дані завжди залишаються локально: аудіо, відео, файли моделей
+- Які дані можуть покидати локальне середовище (за замовчуванням): текст транскрипції у відповідях інструментів
+- Які дані ніколи не покидають локальне середовище (з режимом конфіденційності): все
+- Настанови щодо відповідності за галуззю (HIPAA, GDPR, адвокатська таємниця, FERPA, SOX, PCI-DSS, NDA/комерційна таємниця)
+- Як налаштувати режим конфіденційності
+- Відмова від відповідальності: автори інструменту не є юридичними радниками
+
+### Попередження конфіденційності у схемі інструментів
+Оновити описи інструментів `ListToolsRequestSchema`, включивши примітку про конфіденційність для будь-якого інструменту, що повертає текст транскрипції. Це відображається в описах інструментів Claude Desktop і підвищує обізнаність у точці використання.
+
+### Автоматичне очищення тимчасової теки
+`%TEMP%\whisper-mcp-jobs\` накопичує файли стану завдань і журнали з часом. Додати автоматичне очищення завершених файлів завдань після налаштованого вікна збереження (типово: 7 днів). Наразі вимагає ручного `Remove-Item` від користувача.
+
+---
+
+## Заплановано — Міграція на Bun
+
+Перенести середовище виконання з Node.js на [Bun](https://bun.sh) після завершення архітектури конфіденційності і до додавання функцій v2.3.0.
+
+Оскільки Claude Desktop запускає MCP-сервер заново при кожному запуску сеансу, час запуску знаходиться на критичному шляху. Bun виконує TypeScript нативно без кроку компіляції, запускається значно швидше за Node і має швидший введення-виведення.
+
+**Що змінюється:**
+- Усунення кроку збірки `tsc` і теки `dist/`
+- Користувачі запускають вихідний код TypeScript безпосередньо
+- `tsconfig.json` стає необов'язковим
+- Оновлення скриптів `package.json`
+- Оновлення робочого процесу публікації npm
+
+**Що не змінюється:**
+- Вихідний код `src/index.ts` — Bun сумісний з існуючим TypeScript і вбудованими API Node.js
+- Уся поведінка інструментів і формати виводу
+- Конфігурація Claude Desktop для кінцевих користувачів
+
+**Чому після конфіденційності, до v2.3.0:** Кодова база найлегше піддається міграції зараз. Міграція після додавання більшої кількості інструментів лише збільшує поверхню без вигоди. Архітектура конфіденційності має бути реалізована першою, як зазначено вище.
+
+---
+
+## Ліцензування
+
+whisper-windows-mcp використовує подвійну ліцензію.
+
+**Некомерційне використання:** MIT — безкоштовно для особистого, освітнього та некомерційного використання. Дивіться [LICENSE](LICENSE).
+
+**Комерційне використання:** Необхідна окрема комерційна ліцензійна угода. Дивіться [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md).
+
+`WHISPER_PRIVACY_MODE` для регульованих галузей розробляється і планується у майбутньому релізі. Дивіться [PRIVACY.md](PRIVACY.md) для поточних рекомендацій.
+
+## Заплановано — v2.3.0: Розширення форматів виводу
+
+### Формат субтитрів VTT
+Вивід WebVTT (`.vtt`) разом з SRT. VTT — веб-стандарт, що використовується YouTube, HTML5 `<video>` і більшістю сучасних програвачів. whisper-cli підтримує його нативно. Додати `vtt` як дійсний формат виводу у `transcribe_audio`, `generate_subtitles` і `spawnDetached`. Оновити `buildArgs` і всі відповідні схеми інструментів, README і багатомовну документацію.
+
+### Формат LRC
+Вивід у форматі LRC (`.lrc`) текстів пісень/караоке через `-olrc`. Використовується медіапрогравачами для синхронізованого відображення текстів. Нульові витрати на реалізацію — рідний прапорець CLI.
+
+### Формат CSV
+Вивід CSV (`.csv`) через `-ocsv`. Структуровані табличні дані з часовою розміткою сегментів — корисні для аналізу нижнього рівня, робочих процесів вирівнювання кліпів та імпорту в табличні інструменти. Нульові витрати на реалізацію — рідний прапорець CLI.
+
+---
+
+## Заплановано — Майбутні релізи
+
+### TinyDiarize
+Підтримка прапорця `--tinydiarize` з варіантами моделей, що підтримують `tdrz` (наприклад `large-v2-tdrz`). На відміну від стерео-прапорця `--diarize`, TinyDiarize працює з моно записами. Потребує завантаження спеціального варіанту моделі. Нижча точність, ніж дiaризація на основі pyannote, але нульові додаткові залежності за межами файлу моделі.
+
+**Статус:** Заплановано. Залежить від підтримки варіантів моделей tdrz у `download_model`.
+
+### Транскрипція URL YouTube
+Пряма транскрипція з URL YouTube через yt-dlp. Завантаження аудіо і транскрипція в один крок. Потребує встановленого yt-dlp і наявності в PATH.
+
+**Обмеження проєктування:** yt-dlp є необов'язковим. Інструмент має коректно деградувати з чіткими інструкціями щодо встановлення, якщо його не знайдено. Жодних змін в основній функціональності для користувачів, яким це не потрібно.
+
+### Інструменти робочого процесу відеопроєкту
+Для користувачів, що керують великими проєктами відеомонтажу з теками вихідних і відредагованих кліпів:
+
+1. Сканування вихідної теки і підтеки кліпів
+2. Нечітке зіставлення транскрипцій відредагованих кліпів з вихідними транскрипціями для визначення точок походження
+3. Відображення описових імен файлів, запропонованих Claude на основі вмісту транскрипцій, з вимогою явного підтвердження від користувача перед виконанням будь-якого перейменування
+4. Пошук транскрипцій у теці проєкту з результатами за часовим кодом
+
+**Обмеження проєктування:**
+- Вихідні файли **ніколи не перейменовуються і не змінюються**
+- Усі перейменування вимагають **явного підтвердження користувача**
+- Пошук — це окремий інструмент, що може використовуватися незалежно
+- Аналіз і зіставлення відбуваються локально — Claude викликається лише коли користувач переглядає результати, мінімізуючи виклики API
+
+**Статус:** Фаза проєктування.
+
+### Розрізнення доповідачів (pyannote-audio)
+Повне розрізнення доповідачів у моно з мітками ID доповідача — позначає переходи між доповідачами по всьому запису незалежно від конфігурації каналів. Відрізняється від вбудованого стерео-прапорця `--diarize` (v2.2.0) і TinyDiarize.
+
+**Реалізація:** Потребує [pyannote-audio](https://github.com/pyannote/pyannote-audio) — бібліотеки на основі Python з вимогою токена доступу до моделей Hugging Face. Повністю окремий стек залежностей від конвеєра whisper.cpp.
+
+**Статус:** Необов'язкова розширена функція з власною документацією з налаштування. Не входить до основного пакету.
+
+### Переклад на не-англійські мови
+Прапорець `--translate` Whisper орієнтований лише на англійську. Підтримка довільних цільових мов потребує зовнішнього API перекладу або локальної моделі перекладу.
+
+**Варіанти, що розглядаються:** LibreTranslate (можна розгорнути самостійно, локальний пріоритет), локальний LLM-переклад або явна документація поза межами охоплення.
+
+**Статус:** Відкладено, очікує дизайнерського рішення щодо локального пріоритету проти залежності від API.
+
+### Очищення і форматування транскрипції
+Конвеєр постобробки:
+- Видалення слів-заповнювачів і невдалих початків (необов'язково, під контролем користувача)
+- Розриви абзаців на природних межах тем
+- Форматування з урахуванням доповідачів у поєднанні з виводом розрізнення
+- Експорт у PDF або DOCX
+
+**Статус:** Заплановано. Варіант з урахуванням доповідачів залежить від розрізнення.
+
+---
+
+## Поширення
+
+Доступно на [npm](https://www.npmjs.com/package/whisper-windows-mcp), [mcpservers.org](https://mcpservers.org) і [Glama](https://glama.ai).
+
+---
+
+## Багатомовна документація
+
+Документація японською, корейською, в'єтнамською, індонезійською та українською мовами підтримується паралельно з англійською. Після кожного релізу необхідно оновлювати такі файли відповідно до англійської документації:
+
+**Японська (`*.ja.md`)**
+- `README.ja.md` / `TROUBLESHOOTING.ja.md` / `ROADMAP.ja.md` / `PRIVACY.ja.md` / `SECURITY.ja.md`
+
+**Корейська (`*.ko.md`)**
+- `README.ko.md` / `TROUBLESHOOTING.ko.md` / `ROADMAP.ko.md` / `PRIVACY.ko.md` / `SECURITY.ko.md`
+
+**В'єтнамська (`*.vi.md`)**
+- `README.vi.md` / `TROUBLESHOOTING.vi.md` / `ROADMAP.vi.md` / `PRIVACY.vi.md` / `SECURITY.vi.md`
+
+**Індонезійська (`*.id.md`)**
+- `README.id.md` / `TROUBLESHOOTING.id.md` / `ROADMAP.id.md` / `PRIVACY.id.md` / `SECURITY.id.md`
+
+**Українська (`*.uk.md`)** — `README.uk.md` / `TROUBLESHOOTING.uk.md` / `ROADMAP.uk.md` / `PRIVACY.uk.md` / `SECURITY.uk.md`
+
+**Бразильська португальська (`*.pt-BR.md`)** — `README.pt-BR.md` / `TROUBLESHOOTING.pt-BR.md` / `ROADMAP.pt-BR.md` / `PRIVACY.pt-BR.md` / `SECURITY.pt-BR.md`
+
+**Іспанська (`*.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`
+
+Внески спільноти для інших мов вітаються.
+
+---
+
+## Внески
+
+Pull requests вітаються. Перевірте наявні issues перед початком роботи.
+
+Якщо ви тестували прискорення GPU на обладнанні, не вказаному вище, будь ласка, відкрийте issue з результатами — модель GPU, обсяг VRAM, розмір моделі та спостережувана пропускна здатність. Це допомагає створити точний орієнтир продуктивності для інших користувачів.