ChatTwitchTTS

Бот для озвучивания сообщений из чата Twitch за баллы канала с использованием OmniVoice

Проект позволяет зрителям обменивать баллы канала на озвучивание своих сообщений. Бот подписывается на событие через EventSub, отслеживает активацию определённой награды канала и синтезирует речь в реальном времени с помощью нейросетевой модели OmniVoice

Основные возможности

• Интеграция с Twitch EventSub через награды канала (Channel Points)
• Синтез речи на основе OmniVoice
• Поддержка русского языка
• Использование собственных голосовых датасетов
• Возможность обработки на GPU
• Автоматическое переподключение при обрыве связи

Требования

• Python 3.12 (проект разработан и протестирован на этой версии)
• NVIDIA GPU с CUDA (опционально, для ускорения генерации)

Установка

1. Клонирование репозитория

git clone https://github.com/kiraping1337/ChatTwitchTTS.git
cd ChatTwitchTTS

2. Создание виртуального окружения

Важно: всегда работайте внутри виртуального окружения проекта.

python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # Linux/macOS

3. Установка зависимостей

Важно: PyTorch с CUDA нужно ставить до установки проекта, иначе pip подтянет CPU-only версию.

3.1. PyTorch

Для GPU (NVIDIA):

1. Проверьте версию CUDA:

nvidia-smi

Посмотрите на строку "CUDA Version" в правом верхнем углу вывода.

2. Установите PyTorch с поддержкой CUDA (пример для CUDA 12.8):

pip install torch==2.8.0+cu128 torchaudio==2.8.0+cu128 --extra-index-url https://download.pytorch.org/whl/cu128

Для CPU (без GPU) можно установить обычную версию, но генерация будет очень медленной.

3.2. Проект и зависимости

Установка проекта подтянет OmniVoice и остальные зависимости автоматически:

pip install -e .

Проверка окружения:

twitch-tts doctor

Должно показать CUDA: да и путь к Python внутри .venv. Если CUDA: НЕТ – команда twitch-tts запущена не из того окружения.

Настройка

1. Автоматическая настройка (рекомендуется)

При первом запуске бота (twitch-tts run) будет предложено выполнить автоматическую настройку:

twitch-tts setup

Команда автоматически:

• Запросит у вас OAuth токен
• Проверит валидность токена
• Получит client_id и broadcaster_id через Twitch API
• Покажет список наград канала и предложит выбрать нужную
• Сохранит конфигурацию в файл twitch_config.env

1.1. Ручная настройка через переменные окружения

Если вы хотите настроить вручную, создайте файл twitch_config.env в корне проекта со следующим содержимым:

TWITCH_TOKEN=ваш_oauth_token
TWITCH_CLIENT_ID=ваш_client_id
TWITCH_BROADCASTER_ID=id_пользователя
TWITCH_REWARD_ID=id_награды_канала

Как получить OAuth токен:

• Для production (рекомендуется):

  • Создайте приложение на https://dev.twitch.tv/console/apps
  • Получите токен через API Twitch с scope channel:read:redemptions
  • Важно: токен указывается БЕЗ префиксов oauth: или Bearer

• Для разработки/тестирования:

  • Можно использовать https://twitchtokengenerator.com/ (быстрый способ для прототипирования)
  • Внимание: этот способ не рекомендуется для production использования

Остальные параметры:

• client_id — ID клиента (получается автоматически из токена или при создании приложения на https://dev.twitch.tv/console/apps)
• broadcaster_id — ID пользователя (можно узнать через команду twitch-tts check-token или Twitch API)
• reward_id — ID награды канала (список можно получить через twitch-tts check-token или Twitch API)

2. Создайте config.yaml (опционально)

copy config.example.yaml config.yaml   # Windows
cp config.example.yaml config.yaml     # Linux/macOS

Здесь настраиваются параметры TTS, размер очереди, уровень логов и пути к голосам.

3. Добавление своих голосов

Перейдите в папку refs_wavs(если ее нет, то создайте) и поместите туда:

• Отдельные .wav файлы с образцами голоса

Перейдите в папку refs_texts (если ее нет, то создайте) и поместите туда:

• Отдельные .txt файлы с расшифровкой образца голоса

Голоса подхватываются автоматически по имени файла:

• arthas_dataset.wav → arthas_text.txt
• vasap_maboi_dataset_1.wav → vasap_maboi_text_1.txt

Проверить список: twitch-tts list-voices Требования к аудио:

• Формат: WAV (обязательно)
• Частота дискретизации: любая (автоматически ресэмплируется)
• Каналы: mono или stereo (stereo автоматически конвертируется в mono)
• Качество: чистая речь без фонового шума, эха и посторонних звуков
• Длительность: минимум 6 секунд, рекомендуется 20 секунд для качественного клонирования голоса
• Содержание: эмоционально нейтральная речь даёт лучшие результаты

4. Клонирование голосов (промпты)

Чтобы не клонировать голос из .wav/.txt при каждом запуске, бот один раз создаёт для каждого голоса промпт-файл (.pt) и далее переиспользует его.

Как это работает:

• При запуске (twitch-tts run, test и т.д.) для каждого голоса проверяется наличие промпта в refs_prompts/.
• Если промпта нет — он клонируется из .wav + .txt и сохраняется как refs_prompts/<имя_голоса>.pt.
• Если промпт уже есть — он просто загружается, повторное клонирование не выполняется.
• При синтезе используется готовый промпт, а не исходные .wav/.txt.

Из этого следуют удобные сценарии:

• Раздача без исходников. После первого запуска можно оставить только папку refs_prompts/ (с .pt) и удалить refs_wavs/ и refs_texts/ — бот продолжит работать на промптах.
• Обновление голоса. Если вы изменили .wav/.txt для голоса, удалите соответствующий .pt из refs_prompts/ — при следующем запуске промпт пересоздастся.
• Добавление голоса. Новый голос (.wav + .txt) при следующем запуске автоматически получит свой .pt, остальные промпты не затрагиваются.

Путь к папке промптов задаётся в config.yaml (paths.refs_prompts_dir, по умолчанию refs_prompts).

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

CLI-команды

twitch-tts run              # запустить бота
twitch-tts setup            # выполнить автоматическую настройку
twitch-tts doctor           # проверить Python, CUDA, голоса
twitch-tts check-token      # проверить токен и показать награды
twitch-tts list-voices      # список доступных голосов
twitch-tts test "Привет"    # тест синтеза без Twitch
twitch-tts test "Привет" --voice arthas   # тест с конкретным голосом

Альтернативные способы запуска:

python -m twitch_chat_tts run
python main.py              # обратная совместимость

Работа с Twitch

1. Бот подписывается на событие через EventSub, отслеживает активацию определённой награды канала
2. Зрители активируют награду канала (указанную в reward_id), вводят текст. Если зритель хочет озвучку конкретным голосом, ему необходимо в начале или в конце сообщения написать --voice:имя, где вместо имя нужно вписать название файла промпта без .pt, например --voice:arthas Ваше сообщение или Ваше сообщение --voice:valakas
3. Сообщение автоматически попадает в очередь и озвучивается
4. В случае если пользователь не указал --voice, то случайным образом выбирается один голос из доступных
5. Озвучка воспроизводится через системный аудиовыход

Логи

В консоли вы увидите структурированные логи:

12:00:00 [INFO] twitch_chat_tts.tts.engine: Устройство: cuda
12:00:05 [INFO] twitch_chat_tts.tts.engine: Модель загружена
12:00:06 [INFO] twitch_chat_tts.twitch.eventsub: Подключено к Twitch EventSub
12:00:07 [INFO] twitch_chat_tts.twitch.eventsub: Session ID: abc123
12:00:08 [INFO] twitch_chat_tts.twitch.eventsub: Подписка EventSub создана
12:01:00 [INFO] twitch_chat_tts.twitch.eventsub: Событие: награда='Озвучить' user=viewer текст='привет' match=True

Уровень логов и запись в файл настраиваются в config.yaml.

Решение проблем

Бот не подключается к Twitch

• Убедитесь, что файл twitch_config.env создан и содержит корректные данные
• Проверьте, что токен действителен
• Убедитесь, что в token НЕ указан префикс oauth: или Bearer
• Попробуйте сгенерировать новый токен

Сообщения не озвучиваются

• Проверьте, что reward_id соответствует созданной награде канала
• Убедитесь, что награда активна в настройках канала
• Попробуйте активировать награду сами для теста

Ошибки при загрузке модели

• Убедитесь, что установлен PyTorch правильной версии
• Проверьте наличие интернета при первом запуске (модель скачивается ~3GB)
• Проверьте свободное место на диске

Плохое качество голоса

• Используйте более качественные датасеты (чистая запись, хороший микрофон)
• Увеличьте длительность референсных аудио
• Проверьте правильность текстовой расшифровки
• После изменения датасета удалите старый промпт .pt из refs_prompts/, чтобы он пересоздался
• Экспериментируйте с параметрами position_temperature и num_step

Медленная генерация на CPU

• Запустите twitch-tts doctor – если CUDA: НЕТ, проблема в окружении, а не в коде
• Убедитесь, что активирован .venv до запуска команды
• twitch-tts из cmd без активации venv может использовать глобальный Python с CPU-only PyTorch
• Переустановите CUDA PyTorch внутри venv (см. раздел «Установка проекта»)

Медленная генерация (общее)

• Это нормально для CPU, рассмотрите использование GPU
• Уменьшите длину сообщений (установите лимит символов в награде)
• Закройте другие программы для освобождения ресурсов

Настройка и кастомизация

Изменение параметров синтеза речи

В config.yaml секция tts:

• position_temperature: стабильность vs. естественность (по умолчанию 4.0)
• num_step: качество vs. скорость (по умолчанию 64)

Изменение размера очереди

В config.yaml: queue_maxsize: 10 (0 = без ограничения)

Структура проекта

twitch_chat_tts/
├── refs_prompts/       # Папка с готовыми голосами
├── refs_texts/         # Папка с расшифровками новых голосов
├── refs_wavs/          # Папка с образцами голоса новых голосов
├── cli.py              # CLI-команды
├── config.py           # загрузка twitch_config.env и config.yaml
├── queue_worker.py     # очередь озвучки
├── tts/
│   ├── engine.py       # OmniVoice
│   └── voices.py       # автоподхват голосов и промптов
├── twitch/
│   ├── api.py          # Helix API
│   ├── eventsub.py     # EventSub WebSocket
│   └── moderation.py   # бан, AutoMod
└── audio/
    └── player.py       # воспроизведение