twitchBot-intelligent/README.md

twitchBot-intelligent

Bot Twitch qui enregistre l’audio d’un stream, le transcrit en texte, analyse le contenu avec une couche de type « chat IA » (ex. tgpt), et peut répondre dans le chat. Le dépôt inclut une interface web pour piloter les flux et les composants (enregistrement, sous-titres, génération, envoi de messages).

Fonctionnalités principales

• Enregistrement audio du stream (via intégration avec twitch-recordAudio).
• Transcription / alignement temporel (workflow prévu avec WhisperX).
• Génération de réponses et stockage des générations (fichiers JSON sous storage/).
• Lecture et envoi sur le chat Twitch (OAuth, utilisateurs dans config/user.json).
• Interaction chat (mentions) : si un viewer mentionne un des comptes enregistrés (ex: @exoticnaturees), le bot peut répondre automatiquement via réponses, TGPT, ou création de clip (via règles).
• Clips : création manuelle de clips via l’API Helix (page “Clips”) + actions “Créer un clip” dans les règles (Interaction chat / Sous-titres).
• Sous-titres multi-flux : stockage séparé par flux + sélection du flux dans l’onglet “Sous-titres”.
• Règles sur sous-titres : déclencher des actions (clip / message) quand un sous-titre contient un mot/texte.
• Interface web (Flask + Socket.IO) : gestion des flux, sous-titres, règles, prompts IA, etc.

L’architecture détaillée des routes et composants est décrite dans README_ARCHITECTURE.md. L’interface utilisateur côté navigateur est décrite dans README_WEB_INTERFACE.md.

Structure du dépôt

Élément	Rôle
start_web_interface.py	Point d’entrée recommandé : vérifie dépendances, config, lance le serveur.
web_interface.py	Application Flask : routes HTTP, Socket.IO, boucles auto (sous-titres / messages).
twitch_bot/	Logique métier isolée : controller.py (orchestration des flux et bots), chat_state.py (drapeau d’envoi des messages).
fonction/	Classes principales du bot (first_class.py, second_fonction.py).
config/	config.json (paramètres généraux), user.json (comptes / tokens Twitch).
storage/	Données JSON (sous-titres, générations IA, etc.).
static/, templates/	Frontend de l’interface web.
main_auto_loop.py	Mode terminal : boucle clavier pour enregistrement / IA sans passer par le web.
debug/	Scripts et essais de debug (hors chemin nominal).

Prérequis

• Python 3.10+ (le projet a été utilisé avec 3.10 ; adaptez le venv si vous changez de version).
• Comptes / tokens Twitch configurés pour le chat et l’API selon votre usage.
• Pour la transcription GPU : CUDA / cuDNN si vous utilisez Whisper côté machine (ex. Arch : sudo pacman -S cuda cudnn — ajustez selon votre distribution).

Installation

git clone https://github.com/Foufure13/twitchBot-intelligent.git
cd twitchBot-intelligent

python3 -m venv env
source env/bin/activate   # Windows: env\Scripts\activate

pip install -r requirements.txt

Dépôts externes (selon votre pipeline)

• Audio : twitch-recordAudio — enregistrement du flux.
• Transcription : WhisperX — installation suivant la doc du projet (python setup.py install ou équivalent).
• « Chat » texte en CLI : tgpt — binaire ou méthode d’appel attendue par votre configuration.

Fichiers de configuration

Avant de lancer l’interface, créez ou complétez au minimum :

• config/config.json — paramètres du bot (prompts, limites, twitch_client_id pour Helix clips).
• config/user.json — utilisateurs Twitch (OAuth) pour envoyer des messages et appeler Helix (clips).

Twitch Client-ID (Helix)

Pour créer des clips (page “Clips” + règles “Créer un clip”), ajoutez :

• twitch_client_id dans config/config.json

Scopes OAuth requis

• Envoyer des messages chat : chat:edit (souvent + chat:read)
• Créer des clips : clips:edit

Astuce : vous pouvez générer un seul token avec les scopes clips:edit chat:edit chat:read et le mettre dans config/user.json.

Le script start_web_interface.py vérifie la présence de ces fichiers et crée les dossiers storage/, record/, in_record/ si besoin.

Lancement

source env/bin/activate
python start_web_interface.py

L’interface écoute par défaut sur http://0.0.0.0:5000 (voir start_web_interface.py).

Interaction chat (mentions @)

Principe

• Si un message de chat contient une mention d’un compte enregistré (défini dans config/user.json), par exemple @exoticnaturees, alors le module “Interaction chat” peut répondre automatiquement en notifiant l’auteur:
  • par défaut: @<auteur> salut
  • ou via une règle conditionnelle (ex: si cammenbert dit “etoile etoile”, répondre @cammenbert filante)

Configuration

• La configuration se fait dans l’interface web, onglet Interaction chat.
• Les données sont stockées sous storage/ :
  • storage/interaction_chat_config.json
  • storage/interaction_chat_log.json

Mode TGPT + Actions de règles

• Le mode TGPT est disponible : il envoie le message du viewer à tgpt avec un préprompt (global ou par règle), puis renvoie la réponse.
• Les règles peuvent aussi déclencher l’action Créer un clip.

Sous-titres (multi-flux) + règles

• Chaque flux écrit ses sous-titres dans un fichier séparé : storage/subtitle_data__<channel>.json.
• L’onglet Sous-titres permet de choisir le flux à afficher.
• Les règles “Sous-titres → actions” sont stockées sous :
  • storage/subtitle_rules_config.json
  • storage/subtitle_rules_log.json (créé après la 1ère exécution)

Flux : options par flux

Lors de l’ajout d’un flux dans l’interface web, vous pouvez configurer :

• Enregistrer l’audio du stream
• Autoriser l’envoi de messages sur ce stream (bloque l’envoi auto et les actions “message” de ce flux)
• Activer génération TGPT (IA) à partir des sous-titres (si OFF : pas d’IA_generator et pas d’envoi auto basé sur TGPT)

Mode terminal sans interface web :

python main_auto_loop.py -twitchname NOM_DU_CANAL

(Consulter les options -threads, -recordtime dans le script.)

Dépannage

Réparer un environnement pip cassé

deactivate
rm -rf env
python3 -m venv env
source env/bin/activate
pip install -r requirements.txt

Whisper / erreurs fréquentes

• Discussion utile : openai/whisper#1027.
• Sur Arch, si besoin : sudo pacman -S python-openai-whisper.

Références communautaires (bots / chat Twitch)

• Kichi779/Twitch-Chat-Bot
• mark-rez/Twitch-Chat-Reader
• twitchat.fr

---

Pour le comportement des toggles chat / sous-titres et correctifs récents, voir aussi les fichiers notes du dépôt (CHAT_TOGGLE_README.md, TOGGLE_IMPROVEMENTS.md, etc.) si présents.