# Локальная система распознавания и диаризации речи (Whisper & WhisperX)

Этот репозиторий содержит набор скриптов для создания полностью автономной системы расшифровки аудиозаписей на вашем компьютере. Решение позволяет не только превращать речь в текст, но и автоматически разделять его по говорящим (диаризация), что идеально подходит для анализа лекций, интервью и совещаний.

В основе лежат мощные open-source модели **OpenAI Whisper** и **WhisperX**, что гарантирует высокую точность и полную приватность ваших данных.

<img width="2604" height="2166" alt="Снимок экрана от 2026-04-15 12-41-38" src="https://github.com/user-attachments/assets/7eb6d815-d27c-4536-8b4e-07569e0a788b" />

## ✨ Ключевые возможности

*   **Два режима работы:**
    1.  **Простая транскрибация (Whisper):** быстрое получение сплошного текста из аудио. Идеально для монологов, лекций.
    2.  **Транскрибация с диаризацией (WhisperX):** получение структурированного диалога с разметкой по спикерам (`SPEAKER_01`, `SPEAKER_02`). Отлично подходит для совещаний, интервью.
*   **Приватность:** все ваши аудиозаписи и текстовые расшифровки остаются на вашем компьютере. Никакие данные не передаются третьим лицам.
*   **Бесплатно и Open Source:** проект построен на бесплатных инструментах. Вы не платите за подписку или поминутное распознавание.
*   **Высокая точность:** используется модель `large-v3` от OpenAI, которая является одной из самых точных для распознавания речи, включая русский язык.
*   **Ускорение на GPU:** решение оптимизировано для работы с видеокартами NVIDIA, что многократно ускоряет обработку.
*   **Простая установка:** для каждого режима предусмотрены bash-скрипты, которые автоматизируют настройку окружения.

## 🤔 Какой метод выбрать?

| Критерий | Метод 1: Простая транскрибация (Whisper) | Метод 2: Диа-ри-за-ци-я (WhisperX + Docker) |
| :--- | :--- | :--- |
| **Задача** | Получить сплошной текст из аудио (лекция, доклад) | Разделить речь на реплики разных спикеров (совещание) |
| **Результат** | `...текст одного спикера текст другого...` | `[время] SPEAKER_01: текст...`<br>`[время] SPEAKER_02: текст...` |
| **Технологии** | Python, PyTorch, Whisper | Docker, NVIDIA Container Toolkit, WhisperX |
| **Сложность** | Простая настройка в виртуальном окружении Python | Требует Docker и токен Hugging Face. Установка автоматизирована. |
| **Когда использовать** | Для быстрой расшифровки монологов, лекций, личных заметок. | Для анализа диалогов, интервью, совещаний, создания протоколов. |

---

## 🚀 Метод 1: простая транскрибация (Whisper)

Этот метод идеально подходит для быстрой расшифровки аудиозаписей без необходимости разделять речь по спикерам.

### Шаг 1: Подготовка окружения

Для автоматической установки всех необходимых компонентов (Python, FFmpeg, NVIDIA Drivers, CUDA, PyTorch) используется специальный bash-скрипт.

1.  **Клонируйте репозиторий:**
    ```bash
    git clone https://github.com/empenoso/offline-audio-transcriber
    cd offline-audio-transcriber
    ```

2.  **Сделайте скрипт установки исполняемым:**
    ```bash
    chmod +x whisper_transcribe_setup.sh
    ```

3.  **Запустите скрипт:**
    ```bash
    ./whisper_transcribe_setup.sh
    ```
    Скрипт обновит систему, установит драйверы NVIDIA (если необходимо), CUDA, создаст виртуальное окружение `.venv` и установит все Python-библиотеки.

    > **Примечание:** Если скрипт установит драйверы NVIDIA, может потребоваться перезагрузка компьютера.

### Шаг 2: Запуск распознавания

1.  **Поместите ваши аудиофайлы** (поддерживаются `.mp3`, `.wav`, `.m4a`) в любую папку, например, `audio/`.

2.  **Активируйте виртуальное окружение:**
    ```bash
    source .venv/bin/activate
    ```

3.  **Запустите скрипт `whisper_transcribe.py`:**

    *   **Простой запуск** (поиск аудио в текущей папке):
        ```bash
        python3 whisper_transcribe.py
        ```

    *   **Указание параметров вручную** (папка с аудио, модель, папка для результатов):
        ```bash
        python3 whisper_transcribe.py ./audio large ./results
        ```

### Шаг 3: Анализ результатов

После выполнения скрипта в выходной папке вы найдете:
*   **`.txt` файл** для каждой аудиозаписи с полным текстом.
*   **`.srt` файл** для каждой аудиозаписи с субтитрами и таймкодами.
*   **`all_transcripts.txt`** — один файл, содержащий все расшифровки подряд.

---

## 🚀 Метод 2: транскрибация с диаризацией (WhisperX + Docker)

Этот метод использует Docker для решения проблем с зависимостями и позволяет не только транскрибировать аудио, но и определять, кто из спикеров говорил.

### Подготовка

1.  **Docker и NVIDIA GPU:** для работы требуется установленный Docker и видеокарта NVIDIA с актуальными драйверами.
2.  **Токен Hugging Face:** для диаризации необходим токен доступа.
    *   Получите его в [настройках профиля Hugging Face](https://huggingface.co/settings/tokens).
    *   Примите условия использования моделей [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1) и [pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0).

### Шаг 1: Установка и настройка

Специальный скрипт автоматизирует установку Docker, NVIDIA Container Toolkit и настройку рабочего пространства.

1.  **Сделайте скрипт исполняемым:**
    ```bash
    chmod +x whisperx_diarization_setup.sh
    ```

2.  **Запустите установщик:**
    ```bash
    ./whisperx_diarization_setup.sh
    ```
    Скрипт установит и настроит Docker, скачает необходимый образ WhisperX и создаст структуру папок (`audio`, `results`) и файл конфигурации `config.env`.

3.  **Настройте `config.env`:**
    Откройте файл `config.env` и вставьте ваш токен Hugging Face:
    ```ini
    HF_TOKEN=your_token_here
    ```

4.  **Перезагрузка:** После установки может потребоваться перезагрузка, чтобы применились права для группы `docker`.
    ```bash
    sudo reboot
    ```

### Шаг 2: Запуск диаризации

1.  **Поместите аудиофайлы** в папку `audio/`.

2.  **Запустите скрипт-оркестратор:**
    *   Для проверки системы:
        ```bash
        python3 whisperx_diarization.py --check
        ```
    *   Для обработки всех файлов в папке `audio/`:
        ```bash
        python3 whisperx_diarization.py
        ```

### Шаг 3: Анализ результатов

Результаты для каждого аудиофайла будут сохранены в отдельной подпапке внутри `results/`. Вы получите структурированный протокол встречи.

**Было (обычный Whisper):**
> ...да, я согласен с этим подходом но нужно учесть риски которые мы не обсудили например финансовую сторону вопроса и как это повлияет на сроки я думаю нам стоит вернуться к этому на следующей неделе...

**Стало (WhisperX с диаризацией):**

> [00:01:15.520 --> 00:01:19.880] SPEAKER_01: Да, я согласен с этим подходом, но нужно учесть риски, которые мы не обсудили.

> [00:01:20.100 --> 00:01:22.740] SPEAKER_02: Например, финансовую сторону вопроса и как это повлияет на сроки?

> [00:01:23.020 --> 00:01:25.900] SPEAKER_01: Именно. Я думаю, нам стоит вернуться к этому на следующей неделе.

## ❓ Где получить помощь?

Если у вас возникли проблемы с установкой, запуском или есть предложения по улучшению, пожалуйста, создайте `Issue` в этом репозитории.

## 👤 Автор и поддержка

**Автор:** Михаил Шардин

**Онлайн-визитка:** [shardin.name](https://shardin.name/?utm_source=github)

**Telegram-канал:** ["Умный Дом Инвестора"](https://t.me/+asaEcPax8o41MjQy)