docs: добавлен README с инструкцией по установке и использованию

- Зачем: - чтобы коллега мог установить и запустить проект на Windows/WSL2/Linux без вопросов (шаг 7 plan.md). - Что: - создан README.md: требования, установка через uv tool, примеры CLI, таблицы моделей и квантизаций. - описаны настройка GPU/CUDA по платформам, совместимость GPU, ожидаемая скорость. - добавлен пример выходного файла, соответствующий реальному формату formatter (HH:MM:SS.ss, группировка абзацев). - отмечен шаг 7 как выполненный в plan.md. - Проверка: - uv tool install . && transcribe --help — CLI доступен глобально. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-18 20:16:33 +03:00
parent a72ac1187c
commit b46827a283
2 changed files with 173 additions and 13 deletions
@@ -0,0 +1,164 @@
+# 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
+```
+
+### Опции 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` | Тип вычислений |
+| `--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.
@@ -275,19 +275,15 @@

 > PRD-ссылки: 4.2 (требования), 4.1.1 (GPU таблица), 4.3 (кроссплатформенность)

- [ ] Описание: что делает, зачем
- [ ] Требования: Python ≥ 3.10, ffmpeg, (опционально) NVIDIA GPU + CUDA
- [ ] Установка:
-  ```bash
-  git clone <repo>
-  cd local-transcriber
-  uv sync
-  ```
- [ ] Использование: 3-4 примера команд (простой, с языком, с моделью, CPU)
- [ ] Установка ffmpeg: Linux (`apt`), Windows (`winget`/`scoop`), WSL2, macOS (`brew`)
- [ ] GPU и CUDA: краткое пояснение, ссылка на NVIDIA docs, что CTranslate2 ставит нужное
- [ ] Таблица моделей: имя, размер на диске, VRAM (int8), относительная скорость, качество
- [ ] Пример выходного файла (сокращённый)
+- [x] Описание: что делает, зачем
+- [x] Требования: Python ≥ 3.10, uv, ffmpeg, (опционально) NVIDIA GPU + драйвер
+- [x] Установка: `uv tool install .` (CLI глобально в PATH), troubleshooting
+- [x] Использование: 4 примера команд, таблица опций CLI
+- [x] Таблица моделей + таблица типов квантизации (`--compute-type`)
+- [x] Установка ffmpeg: Linux/WSL2 (`apt`), Windows (`winget`), macOS (`brew`)
+- [x] GPU и CUDA: платформы, режимы `--device`, совместимость GPU, ожидаемая скорость
+- [x] Пример выходного файла (с корректными HH:MM:SS.ss и группировкой абзацев)
+- [x] Поддерживаемые форматы аудио/видео

 **Критерий готовности**: коллега может по README установить и запустить на Windows/WSL2 без вопросов.