transcription/README.md

# WhisperX Meeting Transcription

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

## Стек

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

## Установка

### 1. Python зависимости

```bash
pip install -r requirements.txt
```

### 2. ffmpeg (обязателен для видео)

Программа нуждается в ffmpeg для извлечения аудио из видео файлов.

**macOS:**
```bash
brew install ffmpeg
```

**Ubuntu/Debian:**
```bash
sudo apt-get update && sudo apt-get install ffmpeg
```

**Windows:**
Скачайте с [ffmpeg.org/download.html](https://ffmpeg.org/download.html) и добавьте в PATH.

### 3. HuggingFace токен

Нужен для диаризации (см. раздел ниже).

## 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')))"
```

## Первый запуск

**Важно:** при первом запуске программа скачает модели искусственного интеллекта. Это **нормально** и происходит только один time.

### Что скачивается

| Компонент | Размер | Назначение |
|-----------|--------|------------|
| Whisper `large-v3` | ~3.0 GB | Распознавание речи |
| Pyannote диаризация | ~0.4 GB | Разделение спикеров |
| Wav2Vec2 (русский) | ~1.0 GB | Точные таймкоды слов |
| **Итого** | **~4–5 GB** | **Скачиваются один раз** |

Время скачивания зависит от скорости интернета (обычно 10–30 минут).  
Все последующие запуски используют локальные файлы и работают **без интернета**.

### Где хранятся модели

Модели сохраняются в системный кэш:
- **Linux/Mac:** `~/.cache/`
- **Windows:** `%USERPROFILE%\.cache\`

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

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

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

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

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

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

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

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

```bash
python run.py -i meeting.wav -o meeting.docx
```

### Аргументы

| Аргумент | Описание |
|----------|----------|
| `-i, --input` | Путь к аудиофайлу (обязательный) |
| `-o, --output` | Путь к выходному файлу (если один формат) |
| `-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
# Базовый запуск (по умолчанию: docx + md)
python run.py -i meeting.wav

# Быстрый тест на маленькой модели
python run.py -i meeting.wav -m base

# Только один формат
python run.py -i meeting.wav -f docx

# Markdown выход
python run.py -i meeting.wav -f md -o meeting.md
```

**Видео файлы (автоматически извлекается аудио):**
```bash
# Из видео совещания
python run.py -i recording.mp4

# Из Zoom записи
python run.py -i zoom_meeting.mp4 -o protocol.docx

# Из Teams записи (MKV формат)
python run.py -i teams_recording.mkv
```

**Вывод в несколько форматов одновременно:**
```bash
# docx + md (по умолчанию из конфига)
python run.py -i meeting.wav

# docx + md + txt — все сразу
python run.py -i meeting.wav -f docx,md,txt

# Только docx и md
python run.py -i meeting.wav -f docx,md

# Явно указать выход только для одного формата, остальные рядом
python run.py -i meeting.wav -f docx,md -o output/meeting.docx
# Создаст: output/meeting.docx и output/meeting.md
```

**Продвинутые опции:**
```bash
# Сменить профиль
python run.py -i meeting.wav -p gpu_8gb

# Только CPU
python run.py -i meeting.wav -d cpu -m small

# Отключить диаризацию (быстрее, но без разделения спикеров)
# (нужно изменить diarize: false в config.yaml)
```

## Профили оборудования

Профили настроены в `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:
  formats: [docx, md]     # Можно указать один или несколько
  include_timestamps: true
  paragraph_pause_sec: 2.0
```

## 🌐 Веб-интерфейс

Проект включает веб-сервис с минималистичным фронтендом для удобной работы через браузер.

### Функции веб-интерфейса

- 📤 **Drag & Drop загрузка** — перетащите файлы или выберите через диалог
- 📦 **Пакетная загрузка** — загружайте несколько файлов одновременно
- 📊 **Прогресс в реальном времени** — WebSocket показывает статус обработки каждого файла
- 🌳 **Файловый менеджер** — дерево обработанных совещаний с датами
- 📝 **Просмотр Markdown** — встроенный рендерер с подсветкой синтаксиса
- ⬇️ **Скачивание** — docx и md файлы доступны для скачивания

### Запуск веб-сервера

```bash
# Установите HF_TOKEN
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxx

# Запустите сервер
python start_server.py
```

Сервер поднимается на `http://localhost:8000`

Откройте браузер и перетащите файлы в зону загрузки. Обработка происходит в фоне, прогресс отображается в реальном времени.

### API Endpoints

| Endpoint | Метод | Описание |
|----------|-------|----------|
| `/` | GET | Фронтенд |
| `/upload` | POST | Загрузка одного файла |
| `/upload-batch` | POST | Пакетная загрузка |
| `/ws` | WebSocket | Прогресс обработки |
| `/api/tasks` | GET | Список задач |
| `/api/files` | GET | Дерево обработанных файлов |
| `/api/files/content?path=...` | GET | Содержимое файла |
| `/api/files/download?path=...` | GET | Скачивание файла |

## Ограничения

- Перекрывающаяся речь (overlap) распознаётся плохо
- Качество зависит от записи: тихий/шумный звук требует более мощных моделей
- На CPU `large-v3` работает медленно (1 час записи ≈ 30-60 мин обработки)