local-transcriber/README.md

local-transcriber

Локальный CLI для транскрипции аудио и видео через faster-whisper. Принимает файл, распознаёт речь на машине (без внешних API) и создаёт markdown с таймкодами. Результат удобен для последующей обработки ИИ — суммаризация, action items и т.д. Работает с GPU (NVIDIA CUDA, быстро) и CPU (медленнее).

transcribe meeting.mp4
# → meeting-transcript.md

Требования

• Python ≥ 3.10
• uv — менеджер пакетов
• ffmpeg в PATH
• (Опционально) NVIDIA GPU + установленный драйвер (проверка: nvidia-smi)

Установка

git clone <repo>
cd local-transcriber
uv tool install .

После этого команда transcribe доступна глобально в PATH.

Обновление после git pull:

uv tool install --force .

Модели скачиваются автоматически при первом запуске (~3 GB для large-v3), нужен доступ в интернет (Hugging Face Hub).

Если transcribe: command not found — убедитесь, что директория инструментов uv добавлена в PATH. Выполните uv tool dir --bin чтобы узнать путь, и добавьте его в PATH вашего shell.

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

# Простой запуск (large-v3, автодетект языка и устройства)
transcribe meeting.mp4

# Указать язык
transcribe lecture.mp3 --language ru

# Быстрая модель на CPU
transcribe podcast.wav --model small --device cpu

# Сохранить в конкретный файл
transcribe interview.m4a --output result.md

Батч-режим

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

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

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

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

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

Конфигурационный файл

Дефолтные параметры можно задать в .transcriber.toml:

model = "small"
language = "ru"
device = "cpu"
compute_type = "int8"

Порядок поиска:

1. .transcriber.toml в текущей директории (проектный конфиг)
2. ~/.config/transcriber/config.toml (глобальный конфиг пользователя)

Приоритет: CLI-аргумент > конфиг > встроенный дефолт.

Опции CLI

Опция	Сокращение	По умолчанию	Описание
--model	-m	large-v3	Модель Whisper
--language	-l	auto	Язык (ru, en, auto)
--output	-o	<файл>-transcript.md	Путь к выходному файлу
--device	-d	auto	Устройство (auto, cpu, cuda)
--compute-type	—	int8	Тип вычислений
--force	-f	—	Перезаписать существующие транскрипты
--verbose	-v	—	Подробный вывод

Модели

Модель	Размер на диске	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	★	★★★★★

Типы квантизации (--compute-type)

Тип	VRAM	Скорость	Качество	Когда использовать
int8	Низкое	Быстро	Почти без потерь	По умолчанию, GPU от 4 GB и CPU
int8_float16	Низкое	Быстро	Почти без потерь	GPU, чуть точнее int8
float16	Среднее	Быстро	Без потерь	GPU от 6 GB
float32	Высокое	Медленно	Эталон	CPU (если int8 недоступен)

По умолчанию int8 — универсален для GPU от 4 GB и CPU.

Установка ffmpeg

• Linux / WSL2: sudo apt install ffmpeg
• macOS: brew install ffmpeg
• Windows: winget install ffmpeg

GPU и CUDA

Для работы с GPU необходим установленный NVIDIA драйвер (проверка: nvidia-smi в терминале). Драйвер предоставляет libcuda.so.1, без которого CUDA не работает — его нельзя поставить через pip.

По платформам

• Linux / WSL2 (x86_64): библиотека cuBLAS ставится автоматически (зависимость nvidia-cublas-cu12 подтягивается при установке). Дополнительных шагов не требуется. На ARM (aarch64) cuBLAS через pip недоступен — нужен системный CUDA toolkit.
• Windows: нужен системный CUDA toolkit (choco install cuda или winget install -e --id Nvidia.CUDA)

Режимы --device

• auto (по умолчанию) — выберет GPU если nvidia-smi доступен, иначе CPU
• cuda — строго GPU, ошибка если недоступен (без silent fallback)
• cpu — строго CPU

Совместимость GPU

GPU	VRAM	large-v3 int8	Рекомендация
RTX 3060	6 GB	✅	int8
RTX 4050	6 GB	✅	int8
Quadro M3000M	4 GB	✅	int8 обязательно

Ожидаемая скорость

Конфигурация	1 час аудио ≈
RTX 3060 + large-v3	4–6 мин
CPU + large-v3	60–120 мин
CPU + small	12–20 мин

Формат выходного файла

# Транскрипт: meeting.mp4

- **Дата транскрипции**: 2026-03-17 14:30:05
- **Модель**: large-v3
- **Язык**: ru (detected)
- **Длительность**: 01:23:45
- **Устройство**: CUDA (NVIDIA GeForce RTX 3060)

---

[00:00:00.00 - 00:00:15.40] Добрый день, коллеги. Сегодня мы обсудим результаты
квартала. Первый вопрос — по метрикам продукта. Как вы видите на слайде, MAU вырос
на двадцать три процента по сравнению с предыдущим кварталом.

[00:00:18.10 - 00:00:25.73] Теперь перейдём к финансовым показателям.

...

Близкие по времени сегменты автоматически объединяются в абзацы (пауза > 2 сек или длительность > 60 сек разделяет абзацы). Таймкоды: MM:SS.ss, для записей длиннее 1 часа — HH:MM:SS.ss.

Поддерживаемые форматы

• Аудио: mp3, wav, flac, ogg, m4a, wma, aac
• Видео: mp4, mkv, avi, mov, webm, ts

Формат определяется по расширению, декодирование выполняет ffmpeg.