From b46827a283b2e37ae79acff31594e8326eb72bfd Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Wed, 18 Mar 2026 20:16:33 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=20README=20=D1=81=20=D0=B8=D0=BD=D1=81=D1=82=D1=80?= =?UTF-8?q?=D1=83=D0=BA=D1=86=D0=B8=D0=B5=D0=B9=20=D0=BF=D0=BE=20=D1=83?= =?UTF-8?q?=D1=81=D1=82=D0=B0=D0=BD=D0=BE=D0=B2=D0=BA=D0=B5=20=D0=B8=20?= =?UTF-8?q?=D0=B8=D1=81=D0=BF=D0=BE=D0=BB=D1=8C=D0=B7=D0=BE=D0=B2=D0=B0?= =?UTF-8?q?=D0=BD=D0=B8=D1=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - чтобы коллега мог установить и запустить проект на 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 --- README.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/plan.md | 22 +++---- 2 files changed, 173 insertions(+), 13 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..71db140 --- /dev/null +++ b/README.md @@ -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 +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. diff --git a/docs/plan.md b/docs/plan.md index d72de60..ca4cb48 100644 --- a/docs/plan.md +++ b/docs/plan.md @@ -275,19 +275,15 @@ > PRD-ссылки: 4.2 (требования), 4.1.1 (GPU таблица), 4.3 (кроссплатформенность) -- [ ] Описание: что делает, зачем -- [ ] Требования: Python ≥ 3.10, ffmpeg, (опционально) NVIDIA GPU + CUDA -- [ ] Установка: - ```bash - git clone - 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 без вопросов.