Add README and fix .gitignore for markdown files

2026-05-29 10:28:16 +03:00 · 2026-05-29 10:28:16 +03:00 · bdd94b860f
commit bdd94b860f
parent 5a5d1fa960
2 changed files with 168 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -41,6 +41,8 @@ output/
 *.flac
 *.docx
 *.md
+!README.md
+!AGENTS.md
 *.txt
 !.gitkeep

--- a/README.md
+++ b/README.md
@ -0,0 +1,166 @@
+# WhisperX Meeting Transcription
+
+Пайплайн для транскрибации аудиозаписей совещаний с диаризацией (кто говорил) и таймкодами.
+
+## Стек
+
+- **WhisperX** — ASR + alignment + диаризация (всё-в-одном)
+- **python-docx** — генерация `.docx`
+- **PyYAML** — конфигурация
+
+## Установка
+
+```bash
+pip install -r requirements.txt
+```
+
+Дополнительно потребуется:
+- [ffmpeg](https://ffmpeg.org/download.html) (для обработки аудио)
+- HuggingFace токен для pyannote (см. ниже)
+
+## HuggingFace Token (обязателен для диаризации)
+
+### Зачем нужен токен?
+
+WhisperX для определения спикеров (диаризация) использует модели `pyannote.audio`, которые хранятся на платформе HuggingFace. Эти модели:
+- **НЕ являются публично доступными** без регистрации
+- Требуют принятия пользовательского соглашения (license)
+- Требуют аутентификации через токен при скачивании
+
+Без токена диаризация **не будет работать** — вы получите ошибку авторизации.
+
+### Как получить токен (пошагово)
+
+**Шаг 1: Регистрация**
+1. Перейдите на [huggingface.co](https://huggingface.co)
+2. Нажмите "Sign Up" (регистрация через email или GitHub/Google)
+3. Подтвердите email
+
+**Шаг 2: Создание токена**
+1. Войдите в аккаунт
+2. Перейдите в [Settings → Access Tokens](https://huggingface.co/settings/tokens)
+3. Нажмите "New token"
+4. Введите название (например, `transcription`)
+5. Выберите тип: **`Read`** (только чтение — достаточно)
+6. Нажмите "Generate token"
+7. **Скопируйте токен сразу** — он показывается только один раз!
+
+**Шаг 3: Принятие соглашений**
+
+Нужно принять соглашение для **каждой** из этих моделей (зайдите по ссылкам и нажмите "Access repository", затем согласитесь с условиями):
+
+1. [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1)
+2. [pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0)
+
+> **Важно:** Если не принять соглашения, даже с правильным токеном будет ошибка 403 (Forbidden)!
+
+**Шаг 4: Установка токена**
+
+Вариант A — через переменную окружения (рекомендуется):
+```bash
+export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Вариант B — в `config.yaml` (менее безопасно, токен попадёт в git):
+```yaml
+hf_token: "hf_xxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+Вариант C — в `.env` файл (если добавить `.env` в `.gitignore`):
+```bash
+# .env
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+> **Безопасность:** Токен — это ваш пароль от HuggingFace. Никогда не коммитьте его в публичный репозиторий!
+
+### Проверка токена
+
+После установки можно проверить:
+```bash
+python -c "import os; print('Token установлен:', bool(os.environ.get('HF_TOKEN')))"
+```
+
+## Использование
+
+```bash
+python run.py -i meeting.wav -o meeting.docx
+```
+
+### Аргументы
+
+| Аргумент | Описание |
+|----------|----------|
+| `-i, --input` | Путь к аудиофайлу (обязательный) |
+| `-o, --output` | Путь к выходному файлу (docx/md/txt) |
+| `-p, --profile` | Профиль: `mac_m4`, `gpu_8gb`, `cpu_best` |
+| `-c, --config` | Путь к `config.yaml` |
+| `-d, --device` | Принудительно: `cpu`, `cuda`, `mps` |
+| `-m, --model` | Модель: `tiny`, `base`, `small`, `medium`, `large-v3` |
+| `-l, --language` | Язык: `ru`, `en`, ... |
+| `-f, --format` | Формат: `docx`, `md`, `txt` |
+
+### Примеры
+
+```bash
+# Базовый запуск
+python run.py -i meeting.wav
+
+# Сменить профиль
+python run.py -i meeting.wav -p gpu_8gb
+
+# Быстрый тест на маленькой модели
+python run.py -i meeting.wav -m base
+
+# Только CPU
+python run.py -i meeting.wav -d cpu -m small
+
+# Markdown выход
+python run.py -i meeting.wav -f md -o meeting.md
+```
+
+## Профили оборудования
+
+Профили настроены в `config.yaml`:
+
+- **`mac_m4`** (по умолчанию): CPU + int8, `large-v3`. Оптимально для MacBook Air M4 16GB.
+- **`gpu_8gb`**: CUDA + float16/int8, `large-v3`, `batch_size=1`. Для видеокарты с 8GB VRAM.
+- **`cpu_best`**: CPU + int8, `large-v3`. Универсальный CPU.
+
+## Выходной формат
+
+### DOCX
+- Заголовок "Протокол совещания"
+- Каждый спикер — отдельный абзац
+- Таймкоды в формате `[HH:MM:SS.mmm]`
+- Новый абзац при смене спикера или паузе > 2 сек
+
+### Markdown / TXT
+- Аналогичная структура
+- Таймкоды опционально (включаются в `config.yaml`)
+
+## Настройка
+
+Измените `config.yaml`:
+
+```yaml
+active_profile: mac_m4  # или gpu_8gb
+
+profiles:
+  mac_m4:
+    device: cpu
+    compute_type: int8
+    model: large-v3
+    language: ru
+    
+output:
+  format: docx
+  include_timestamps: true
+  paragraph_pause_sec: 2.0
+```
+
+## Ограничения
+
+- Перекрывающаяся речь (overlap) распознаётся плохо
+- Качество зависит от записи: тихий/шумный звук требует более мощных моделей
+- На CPU `large-v3` работает медленно (1 час записи ≈ 30-60 мин обработки)