transcription/README.md

WhisperX Meeting Transcription

Пайплайн для транскрибации аудиозаписей совещаний с диаризацией (кто говорил) и таймкодами.

Стек

• WhisperX — ASR + alignment + диаризация (всё-в-одном)
• python-docx — генерация .docx
• PyYAML — конфигурация

Установка

pip install -r requirements.txt

Дополнительно потребуется:

• ffmpeg (для обработки аудио)
• HuggingFace токен для pyannote (см. ниже)

HuggingFace Token (обязателен для диаризации)

Зачем нужен токен?

WhisperX для определения спикеров (диаризация) использует модели pyannote.audio, которые хранятся на платформе HuggingFace. Эти модели:

• НЕ являются публично доступными без регистрации
• Требуют принятия пользовательского соглашения (license)
• Требуют аутентификации через токен при скачивании

Без токена диаризация не будет работать — вы получите ошибку авторизации.

Как получить токен (пошагово)

Шаг 1: Регистрация

1. Перейдите на huggingface.co
2. Нажмите "Sign Up" (регистрация через email или GitHub/Google)
3. Подтвердите email

Шаг 2: Создание токена

1. Войдите в аккаунт
2. Перейдите в Settings → Access Tokens
3. Нажмите "New token"
4. Введите название (например, transcription)
5. Выберите тип: Read (только чтение — достаточно)
6. Нажмите "Generate token"
7. Скопируйте токен сразу — он показывается только один раз!

Шаг 3: Принятие соглашений

Нужно принять соглашение для каждой из этих моделей (зайдите по ссылкам и нажмите "Access repository", затем согласитесь с условиями):

1. pyannote/speaker-diarization-3.1
2. pyannote/segmentation-3.0

Важно: Если не принять соглашения, даже с правильным токеном будет ошибка 403 (Forbidden)!

Шаг 4: Установка токена

Вариант A — через переменную окружения (рекомендуется):

export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxx

Вариант B — в config.yaml (менее безопасно, токен попадёт в git):

hf_token: "hf_xxxxxxxxxxxxxxxxxxxxxxxx"

Вариант C — в .env файл (если добавить .env в .gitignore):

# .env
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxx

Безопасность: Токен — это ваш пароль от HuggingFace. Никогда не коммитьте его в публичный репозиторий!

Проверка токена

После установки можно проверить:

python -c "import os; print('Token установлен:', bool(os.environ.get('HF_TOKEN')))"

Работа офлайн — всё локально!

Да, все модели работают полностью локально.

Токен HuggingFace нужен только один раз — чтобы скачать модели при первом запуске. После этого:

• ✅ Интернет не нужен — можно отключить Wi-Fi
• ✅ Аудио не уходит никуда — обработка только на вашем устройстве
• ✅ Текст не уходит в облако — результат только у вас
• ✅ Подходит для конфиденциальных совещаний

Что скачивается при первом запуске

Компонент	Размер	Зачем
Whisper large-v3	~3 GB	Распознавание речи
Pyannote диаризация	~400 MB	Разделение спикеров
Wav2Vec2 (русский)	~1 GB	Точные таймкоды слов
Итого	~4–5 GB	Скачиваются один раз

Модели сохраняются в системный кэш (~/.cache/ на Linux/Mac, %USERPROFILE%\.cache\ на Windows) и переиспользуются при каждом запуске.

Использование

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

Примеры

# Базовый запуск
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:

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 мин обработки)