From bdd94b860f3d636a735ce234482fdd2ed55bfd1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9A=D0=B8=D1=80=D0=B8=D0=BB=D0=BB=20=D0=91=D0=BB=D0=B8?= =?UTF-8?q?=D0=BD=D0=BE=D0=B2?= Date: Fri, 29 May 2026 10:28:16 +0300 Subject: [PATCH] Add README and fix .gitignore for markdown files --- .gitignore | 2 + README.md | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 168 insertions(+) create mode 100644 README.md diff --git a/.gitignore b/.gitignore index f4974dc..28fb84c 100644 --- a/.gitignore +++ b/.gitignore @@ -41,6 +41,8 @@ output/ *.flac *.docx *.md +!README.md +!AGENTS.md *.txt !.gitkeep diff --git a/README.md b/README.md new file mode 100644 index 0000000..de1bbe3 --- /dev/null +++ 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 мин обработки)