ddadminandClaude Opus 4.6
e28232ef50
- Зачем: - обработка нескольких файлов за один вызов с загрузкой модели один раз. - хранение дефолтов (модель, язык, устройство) в .transcriber.toml. - Что: - добавлен config.py: поиск .transcriber.toml (CWD → ~/.config), парсинг, валидация, приоритет CLI > конфиг > хардкод. - рефакторинг transcriber.py: выделены load_model() и _transcribe_file() с TranscribeFileResult для переиспользования модели в батче. - добавлены expand_globs() с дедупликацией и has_existing_transcript() в utils.py. - CLI: files: list[Path], --force/-f, prescan-first батч с итоговой статистикой и временем, Status-спиннер для прогресса. - README: секции батч-режим, конфигурационный файл, --force в таблице опций. - ADR-002: зафиксированы архитектурные решения (prescan-first, TranscribeFileResult, конфиг без мержа). - Проверка: - uv run pytest -q — 94 passed, 1 skipped. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
204 lines
8.4 KiB
Markdown
204 lines
8.4 KiB
Markdown
# local-transcriber
|
||
|
||
Локальный CLI для транскрипции аудио и видео через [faster-whisper](https://github.com/SYSTRAN/faster-whisper).
|
||
Принимает файл, распознаёт речь на машине (без внешних API) и создаёт markdown с таймкодами.
|
||
Результат удобен для последующей обработки ИИ — суммаризация, action items и т.д.
|
||
Работает с GPU (NVIDIA CUDA, быстро) и CPU (медленнее).
|
||
|
||
```bash
|
||
transcribe meeting.mp4
|
||
# → meeting-transcript.md
|
||
```
|
||
|
||
## Требования
|
||
|
||
- Python ≥ 3.10
|
||
- [uv](https://docs.astral.sh/uv/) — менеджер пакетов
|
||
- ffmpeg в PATH
|
||
- (Опционально) NVIDIA GPU + установленный драйвер (проверка: `nvidia-smi`)
|
||
|
||
## Установка
|
||
|
||
```bash
|
||
git clone <repo>
|
||
cd local-transcriber
|
||
uv tool install .
|
||
```
|
||
|
||
После этого команда `transcribe` доступна глобально в PATH.
|
||
|
||
Обновление после `git pull`:
|
||
|
||
```bash
|
||
uv tool install --force .
|
||
```
|
||
|
||
Модели скачиваются автоматически при первом запуске (~3 GB для large-v3),
|
||
нужен доступ в интернет (Hugging Face Hub).
|
||
|
||
> **Если `transcribe: command not found`** — убедитесь, что директория
|
||
> инструментов uv добавлена в PATH. Выполните `uv tool dir --bin`
|
||
> чтобы узнать путь, и добавьте его в PATH вашего shell.
|
||
|
||
## Использование
|
||
|
||
```bash
|
||
# Простой запуск (large-v3, автодетект языка и устройства)
|
||
transcribe meeting.mp4
|
||
|
||
# Указать язык
|
||
transcribe lecture.mp3 --language ru
|
||
|
||
# Быстрая модель на CPU
|
||
transcribe podcast.wav --model small --device cpu
|
||
|
||
# Сохранить в конкретный файл
|
||
transcribe interview.m4a --output result.md
|
||
```
|
||
|
||
### Батч-режим
|
||
|
||
Обработка нескольких файлов за один вызов — модель загружается один раз:
|
||
|
||
```bash
|
||
# Все mp4 в директории
|
||
transcribe ./recordings/*.mp4
|
||
|
||
# Несколько файлов
|
||
transcribe meeting1.mp3 meeting2.mp3
|
||
|
||
# Перезаписать существующие транскрипты
|
||
transcribe *.mp4 --force
|
||
```
|
||
|
||
- Файлы с существующим транскриптом (`*-transcript.md`) автоматически пропускаются
|
||
- `--force` / `-f` — перезаписать существующие транскрипты
|
||
- В конце выводится итоговая статистика: обработано, пропущено, ошибок
|
||
- При ошибке в одном файле остальные продолжают обрабатываться
|
||
- `--output` несовместим с несколькими файлами
|
||
|
||
### Конфигурационный файл
|
||
|
||
Дефолтные параметры можно задать в `.transcriber.toml`:
|
||
|
||
```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 мин |
|
||
|
||
## Формат выходного файла
|
||
|
||
```markdown
|
||
# Транскрипт: 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.
|