# local-transcriber Локальная транскрипция аудио и видео в markdown — без облака, без API-ключей. ```bash transcribe meeting.mp4 # → meeting-transcript.md ``` - **Полностью локально** — данные не покидают машину - **Авто-ускорение** — NVIDIA CUDA при наличии GPU, иначе ONNX на CPU - **Батч-режим** — обработка нескольких файлов за один вызов - **Из проводника Windows** — пункт Transcribe в меню «Отправить» ([установка](#контекстное-меню-проводника-windows)) - **Markdown с таймкодами** — удобен для суммаризации ИИ - **Аудио и видео** — mp3, wav, mp4, mkv и [другие форматы](#поддерживаемые-форматы) ## Установка **1. Установить [uv](https://docs.astral.sh/uv/getting-started/installation/)** (если ещё нет): ```bash curl -LsSf https://astral.sh/uv/install.sh | sh # Linux / macOS ``` ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows ``` **2. Установить transcriber:** ```bash uv tool install git+https://git.dementev.space/ddmitry/local-transcriber.git ``` **3. Ускорение (ставится автоматически):** - **NVIDIA CUDA** (GPU): если есть GPU — транскрипция в 5-10× быстрее - **Windows**: `winget install -e --id Nvidia.CUDA --version 12.9` (от администратора), перезапустить терминал - **Linux / WSL2**: работает из коробки (нужен только драйвер: `nvidia-smi`) - **Без NVIDIA GPU**: автоматически используется ONNX с GigaAM RNN-T на CPU. Эта модель понимает только русскую речь - **Другие языки без NVIDIA**: выбирайте Whisper явно — `--device openvino-cpu --model medium` на x86 или `--device cpu --model medium` на любой платформе - **OpenVINO** для Intel GPU или x86 CPU остаётся доступен через явный `--device openvino`, `--device openvino-gpu` или `--device openvino-cpu` **4. Готово:** ```bash transcribe meeting.mp4 ``` Модели скачиваются автоматически при первом запуске; размер зависит от выбранного профиля, нужен доступ в интернет.
transcribe: command not found Выполните `uv tool update-shell` — это добавит нужный путь в PATH автоматически.
**Обновление:** ```bash uv tool install --force git+https://git.dementev.space/ddmitry/local-transcriber.git ``` **Удаление:** ```bash uv tool uninstall local-transcriber ``` **Очистка моделей:** Модели кешируются в `~/.cache/huggingface/hub/` и могут занимать несколько гигабайт. На Windows без Developer Mode файлы копируются без симлинков — место удваивается. ```bash # Linux / macOS — посмотреть размер кеша du -sh ~/.cache/huggingface/hub/models--* # Удалить все скачанные модели rm -rf ~/.cache/huggingface/hub/models--Systran--faster-whisper-* rm -rf ~/.cache/huggingface/hub/models--OpenVINO--whisper-* ``` ```powershell # Windows dir "$env:USERPROFILE\.cache\huggingface\hub\models--*" # Удалить все скачанные модели Remove-Item -Recurse "$env:USERPROFILE\.cache\huggingface\hub\models--Systran--faster-whisper-*" Remove-Item -Recurse "$env:USERPROFILE\.cache\huggingface\hub\models--OpenVINO--whisper-*" ``` При следующем запуске нужная модель скачается заново.
Windows: ошибка WinError 1314 при первом запуске HuggingFace Hub использует симлинки для экономии места. На Windows без Developer Mode первая загрузка модели может упасть с ошибкой `WinError 1314`. Повторный запуск команды обычно помогает — HF Hub переключается на копирование файлов. Чтобы избежать проблемы и сэкономить место, включите Developer Mode: [Инструкция Microsoft](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development)
## Использование ```bash # Простой запуск (CUDA medium или ONNX GigaAM RNN-T, язык ru) transcribe meeting.mp4 # Указать язык transcribe lecture.mp3 --language en # Максимальное качество на NVIDIA GPU transcribe podcast.wav --model large-v3 --compute-type float16 # Максимальное качество на Intel GPU transcribe podcast.wav --model large-v3 --device openvino-gpu # Максимальная скорость на CPU (русский) transcribe meeting.mp4 --device onnx --model gigaam-v3 # CPU с пунктуацией и нормализацией русского текста transcribe podcast.wav --device onnx --model gigaam-v3-e2e-ctc # Смешанная русско-английская речь transcribe meeting.wav --device onnx --model gigaam-multilingual-ctc # Повышенная точность смешанной речи (медленнее, ~590 MB) transcribe meeting.wav --device onnx --model gigaam-multilingual-large-ctc # Сохранить в конкретный файл transcribe interview.m4a --output result.md ``` ### Батч-режим Обработка нескольких файлов за один вызов — модель загружается один раз: ```bash # Все mp4 в директории transcribe ./recordings/*.mp4 # Несколько файлов transcribe meeting1.mp3 meeting2.mp3 # Перезаписать существующие транскрипты transcribe *.mp4 --force ``` - Файлы с существующим транскриптом (`*-transcript.md`) автоматически пропускаются - `--force` / `-f` — перезаписать существующие транскрипты - При ошибке в одном файле остальные продолжают обрабатываться - `--output` несовместим с несколькими файлами ### Контекстное меню проводника (Windows) Установить пункт `Transcribe` в меню «Отправить»: ```bash transcribe --install-menu ``` (при запуске из клона репозитория — `uv run transcribe --install-menu`) Использование: выделите один или несколько аудио/видеофайлов в проводнике, откройте контекстное меню правой кнопкой. В Windows 11 выберите «Показать дополнительные параметры» или нажмите Shift+F10, затем «Отправить» → «Transcribe». Несколько выделенных файлов передаются в один процесс и обрабатываются одним батчем. Удалить пункт меню: ```bash transcribe --uninstall-menu ``` Если что-то пошло не так, пункт можно удалить вручную: Win+R → `shell:sendto` → удалить `Transcribe.cmd`. Известные ограничения: - После переноса или пересоздания проекта/venv выполните `--install-menu` заново: внутри `Transcribe.cmd` хранится абсолютный путь к `transcribe.exe`. - Очень большой мультивыбор с суммарной длиной путей ≳8000 символов упирается в лимит командной строки cmd.exe. Обрабатывайте такие файлы частями. ### Опции CLI | Опция | Сокращение | По умолчанию | Описание | |-------|-----------|-------------|----------| | `--model` | `-m` | medium (CUDA) / gigaam-v3-e2e-rnnt (ONNX) | Модель распознавания | | `--language` | `-l` | `ru` | Язык (ru, en, auto и др.); автоматический профиль без NVIDIA понимает только русский | | `--output` | `-o` | `<файл>-transcript.md` | Путь к выходному файлу | | `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda, openvino, openvino-gpu, openvino-cpu, onnx) | | `--compute-type` | — | float16 (CUDA) / int8 (ONNX/OpenVINO) / float32 (CPU) | Тип вычислений | | `--threads` | `-t` | 0 (авто) | Потоки CPU (рекомендуется = число физ. ядер) | | `--force` | `-f` | — | Перезаписать существующие транскрипты | | `--verbose` | `-v` | — | Подробный вывод | ## Платформы | | Linux / WSL2 | macOS | Windows | |---|---|---|---| | CPU через ONNX | ✅ авто | ✅ авто | ✅ авто | | OpenVINO (x86 CPU) | ✅ явно | — | ✅ явно | | OpenVINO (Intel GPU) | ✅ явно | — | ✅ явно | | GPU (NVIDIA) | ✅ авто | — | ✅ (нужен CUDA 12) | Данные по macOS основаны на доступности пакетов onnxruntime: прогонов на этой платформе не было.
Linux / WSL2 - **Intel GPU** (Arc, встроенная графика) работает из коробки через OpenVINO - **NVIDIA GPU** работает из коробки — cuBLAS ставится автоматически как зависимость - Нужен только драйвер NVIDIA (проверка: `nvidia-smi`) - На ARM (aarch64) cuBLAS через pip недоступен — нужен системный CUDA toolkit
macOS - Работает на CPU (Intel и Apple Silicon) - GPU (CUDA) недоступен — NVIDIA не поддерживает macOS
Windows - CPU работает из коробки - **Intel GPU** (Arc, встроенная графика) работает из коробки через OpenVINO - Для **NVIDIA GPU** нужен **CUDA 12** (ctranslate2 4.7 не совместим с CUDA 11 и 13): ``` winget install -e --id Nvidia.CUDA --version 12.9 ``` > `winget install` требует запуска от имени администратора (elevated terminal). > `uv tool install` работает без админа (ставит в пользовательскую директорию). - После установки CUDA перезапустите терминал
## Конфигурация Дефолтные параметры можно задать в `.transcriber.toml`: ```toml device = "openvino-cpu" model = "large-v3-turbo" compute_type = "int8" language = "ru" ``` Порядок поиска: 1. `.transcriber.toml` в текущей директории 2. `~/.config/transcriber/config.toml` Приоритет: **CLI-аргумент > конфиг > device-aware дефолт > встроенный дефолт**. При `device = "auto"` выбирается CUDA, если доступен `nvidia-smi`, иначе ONNX. Явный `device` из CLI или конфига отключает этот автоматический выбор. Каталоги моделей различаются между бэкендами, поэтому при закреплении `model` в конфиге рекомендуется явно закрепить и совместимый `device`. То же с языком: автоматический ONNX-профиль рассчитан на русскую речь, а для остальных языков нужен Whisper — например, `device = "openvino-cpu"` и `model = "medium"`. Дефолты зависят от устройства: | Параметр | CUDA | OpenVINO (GPU) | OpenVINO (CPU) | ONNX | CPU | |----------|------|----------------|----------------|------|-----| | model | medium | medium | medium | gigaam-v3-e2e-rnnt | medium | | compute_type | float16 | int8 | int8 | int8 | float32 | | language | ru | ru | ru | ru | ru | ## Модели и GPU Рекомендации: - **По умолчанию без CUDA:** ONNX `gigaam-v3-e2e-rnnt` — читаемый русский текст с пунктуацией почти без потери скорости относительно сырого `gigaam-v3` - **Макс. качество (NVIDIA):** `large-v3` + `--compute-type float16` - **Макс. качество (Intel GPU):** `large-v3` + `--device openvino-gpu` - **Макс. скорость CPU (русский):** `--device onnx --model gigaam-v3` (17-29× RTF, без пунктуации; рекомендуется LLM-нормализация терминов после) - **Быстрый OpenVINO с низким WER:** `--device openvino-cpu --model large-v3-turbo --compute-type int8` (7,2× RTFx на контрольном Intel CPU; пунктуация может быть слабой) - **OpenVINO для чтения и конспекта:** `--device openvino-cpu --model medium` (около 6× RTFx; независимая оценка показала лучшую сохранность содержания, чем turbo) - **Быстрый тест:** `tiny` — для проверки пайплайна
Таблица моделей #### Whisper через faster-whisper (`--device cuda`, `--device cpu`) | Модель | Размер на диске | VRAM (int8) | Скорость (GPU) | Качество | |--------|----------------|-------------|----------------|----------| | `tiny` | ~75 MB | ~1 GB | ★★★★★ | ★ | | `base` | ~140 MB | ~1 GB | ★★★★ | ★★ | | `small` | ~460 MB | ~1.5 GB | ★★★ | ★★★ | | `medium` | ~1.5 GB | ~2.5 GB | ★★ | ★★★★ | | `large-v3` | ~3 GB | ~2.5 GB | ★ | ★★★★★ | #### Whisper через OpenVINO (`--device openvino-cpu`, `--device openvino-gpu`) Здесь те же модели Whisper, но предквантизированные, поэтому на диске они занимают меньше места: `medium` int8 — 748 MB, `large-v3-turbo` int8 — 790 MB, `large-v3-turbo` fp16 — 1552 MB. Модель `large-v3-turbo` доступна только здесь: faster-whisper её не поддерживает, и запуск с `--device cuda` завершится ошибкой. Полный список репозиториев — [docs/gpu.md](docs/gpu.md#доступные-openvino-модели). #### ONNX-модели (`--device onnx`) Другие архитектуры, не Whisper. Работают через onnxruntime на CPU: | Модель | Размер (int8) | RTFx CPU | Языки | Пунктуация | |--------|--------------|----------|-------|-----------| | `gigaam-v3` | ~300 MB | 17-29× | ru | ❌ | | `gigaam-multilingual-ctc` | ~300 MB | 10,0×* | ru, en, kk, ky, uz | ❌ | | `gigaam-multilingual-large-ctc` | ~590 MB | 4,8×* | ru, en, kk, ky, uz | ❌ | | `gigaam-v3-e2e-ctc` | ~300 MB | 11,9×* | ru | ✅ | | `gigaam-v3-e2e-rnnt` | ~300 MB | 11,5×* | ru | ✅ | | `parakeet-v3` | ~600 MB | 7,6×* | 25 языков | ✅ | \* Наблюдение на AMD Ryzen 7 8845H, Windows, `int8`, три записи общей длительностью 43:37. Это не приёмочный замер для целевого Intel Core i5. Методика и качественное сравнение: [benchmark GigaAM и Whisper](docs/benchmarks/2026-08-11-gigaam-model-comparison.md). > **Рекомендация**: ONNX по умолчанию использует `gigaam-v3-e2e-rnnt` для > готового читаемого русского текста. Для последующей машинной обработки можно > явно выбрать более точный по словам `gigaam-v3` без пунктуации. Для смешанной > речи с приоритетом качества используйте `gigaam-multilingual-large-ctc`: она примерно вдвое > медленнее small-варианта, но приблизилась к monolingual GigaAM по WER. > `parakeet-v3` в 1,58 раза быстрее Large и ставит пунктуацию, но на тех же > трёх записях хуже по WER и вставляет ложные английские фразы в русскую речь; > это подтверждает проблемы из [ADR-005](docs/adr/005-parakeet-evaluation.md). Обе GigaAM Multilingual сами распознают русский, английский, казахский, кыргызский и узбекский внутри одной записи. `onnx-asr` не передаёт этим моделям подсказку языка, поэтому `--language` не управляет выбором языка. Если модель не понимает запрошенный язык, CLI предупреждает об этом до начала распознавания и подсказывает совместимый профиль, но работу не прерывает. Для моделей из таблицы опубликованы `int8` и `float32`. Если неявный device-aware дефолт недоступен для выбранной модели, CLI сообщит о подстановке доступного варианта. Явное значение из `--compute-type` или `.transcriber.toml` вместо подстановки завершится ошибкой.
Типы квантизации (--compute-type) | Тип | Бэкенд | VRAM/RAM | Качество | Когда использовать | |-----|--------|----------|----------|--------------------| | `float16` | CUDA | ~4.5-5 GB | Отлично | **По умолчанию для CUDA** | | `int8_float16` | CUDA | ~4.7 GB | Отлично | GPU от 6 GB, альтернатива float16 | | `int8_float32` | CPU | Среднее | Отлично | **Рекомендуется для CPU** — 1.5x быстрее float32 при том же качестве | | `int8` | CUDA / OpenVINO / ONNX | Низкое | Хорошо, но бывают галлюцинации | **По умолчанию для OpenVINO и ONNX** | | `fp16` | OpenVINO | Низкое | Отлично | OpenVINO large-v3 (выбирается автоматически) | | `float32` | CPU / ONNX | Среднее | Отлично | **По умолчанию для CPU** | **Важно:** `int8` на длинных записях может давать галлюцинации (повтор фраз, потеря контента). `float16`/`fp16` и `float32` значительно стабильнее на записях >20 минут. > Для OpenVINO `--compute-type` выбирает предквантизированную модель (int8 или fp16), > а не параметр времени выполнения. Для `large-v3` по умолчанию выбирается > `fp16`; для `large-v3-turbo` доступны явные варианты `int8` и `fp16`, а > неявный профиль OpenVINO использует `int8`.
Подробнее: бенчмарки, OpenVINO, совместимость GPU, результаты тестирования — [docs/gpu.md](docs/gpu.md). Сравнение `large-v3-turbo` с CPU-профилями: [OpenVINO 2026.3 и large-v3-turbo](docs/benchmarks/2026-08-12-openvino-large-v3-turbo-comparison.md).
Формат вывода ```markdown # Транскрипт: meeting.mp4 - **Дата транскрипции**: 2026-03-17 14:30:05 - **Модель**: large-v3 - **Язык**: ru (задан явно) - **Длительность**: 01:23:45 - **Устройство**: CUDA (NVIDIA GeForce RTX 3060) --- [00:00:00.00 - 00:00:15.40] Добрый день, коллеги. Сегодня мы обсудим результаты квартала. Первый вопрос — по метрикам продукта. [00:00:18.10 - 00:00:25.73] Теперь перейдём к финансовым показателям. ``` Близкие по времени сегменты автоматически объединяются в абзацы (пауза > 2 сек или длительность > 60 сек разделяет абзацы). Таймкоды: `MM:SS.ss`, для записей длиннее 1 часа — `HH:MM:SS.ss`. В скобках после языка указан его источник: - `задан явно` — язык взят из `--language` или конфига; - `определён автоматически` — распознан моделью при `--language auto`; - `из профиля модели` — у модели всего один язык, как у GigaAM. Если язык определить не удалось, строка выглядит так: `- **Язык**: не определён`.
## Поддерживаемые форматы - **Аудио**: mp3, wav, flac, ogg, m4a, wma, aac - **Видео**: mp4, mkv, avi, mov, webm, ts ## Для разработчиков ```bash git clone https://github.com/dementev-dev/local-transcriber cd local-transcriber uv sync uv run transcribe meeting.mp4 # запуск CLI uv run pytest # тесты ``` Подробнее — [CONTRIBUTING.md](CONTRIBUTING.md).