local-transcriber

Локальная транскрипция аудио и видео в markdown — без облака, без API-ключей.

transcribe meeting.mp4
# → meeting-transcript.md

• Полностью локально — данные не покидают машину
• Авто-ускорение — NVIDIA CUDA при наличии GPU, иначе ONNX на CPU
• Батч-режим — обработка нескольких файлов за один вызов
• Из проводника Windows — пункт Transcribe в меню «Отправить» (установка)
• Markdown с таймкодами — удобен для суммаризации ИИ
• Аудио и видео — mp3, wav, mp4, mkv и другие форматы

Установка

1. Установить uv (если ещё нет):

curl -LsSf https://astral.sh/uv/install.sh | sh          # Linux / macOS

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

2. Установить transcriber:

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. Готово:

transcribe meeting.mp4

Модели скачиваются автоматически при первом запуске; размер зависит от выбранного профиля, нужен доступ в интернет.

transcribe: command not found

Выполните uv tool update-shell — это добавит нужный путь в PATH автоматически.

Обновление:

uv tool install --force git+https://git.dementev.space/ddmitry/local-transcriber.git

Удаление:

uv tool uninstall local-transcriber

Очистка моделей:

Модели кешируются в ~/.cache/huggingface/hub/ и могут занимать несколько гигабайт. На Windows без Developer Mode файлы копируются без симлинков — место удваивается.

# 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-*

# 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

Использование

# Простой запуск (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

Батч-режим

Обработка нескольких файлов за один вызов — модель загружается один раз:

# Все mp4 в директории
transcribe ./recordings/*.mp4

# Несколько файлов
transcribe meeting1.mp3 meeting2.mp3

# Перезаписать существующие транскрипты
transcribe *.mp4 --force

• Файлы с существующим транскриптом (*-transcript.md) автоматически пропускаются
• --force / -f — перезаписать существующие транскрипты
• При ошибке в одном файле остальные продолжают обрабатываться
• --output несовместим с несколькими файлами

Контекстное меню проводника (Windows)

Установить пункт Transcribe в меню «Отправить»:

transcribe --install-menu

(при запуске из клона репозитория — uv run transcribe --install-menu)

Использование: выделите один или несколько аудио/видеофайлов в проводнике, откройте контекстное меню правой кнопкой. В Windows 11 выберите «Показать дополнительные параметры» или нажмите Shift+F10, затем «Отправить» → «Transcribe». Несколько выделенных файлов передаются в один процесс и обрабатываются одним батчем.

Удалить пункт меню:

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:

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.

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.

Рекомендация: ONNX по умолчанию использует gigaam-v3-e2e-rnnt для готового читаемого русского текста. Для последующей машинной обработки можно явно выбрать более точный по словам gigaam-v3 без пунктуации. Для смешанной речи с приоритетом качества используйте gigaam-multilingual-large-ctc: она примерно вдвое медленнее small-варианта, но приблизилась к monolingual GigaAM по WER. parakeet-v3 в 1,58 раза быстрее Large и ставит пунктуацию, но на тех же трёх записях хуже по WER и вставляет ложные английские фразы в русскую речь; это подтверждает проблемы из ADR-005.

Обе 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. Сравнение large-v3-turbo с CPU-профилями: OpenVINO 2026.3 и large-v3-turbo.

Формат вывода

# Транскрипт: 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

Для разработчиков

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.