🎮 Electrum Overlay - Système d'overlay Twitch avec EventSub

Un système complet d'overlay pour Twitch avec intégration EventSub, animations en temps réel et statistiques de stream.

This readme is also available in English.

📋 Table des matières

🚀 Fonctionnalités
📦 Installation
⚙️ Configuration
🔧 Configuration Twitch
🌐 Tunnel Webhook (ngrok)
🚛 Intégration TruckyApp
🏃‍♂️ Lancement
📹 Overlays OBS
🧪 Tests
📷 Preview/Gallerie
🎨 Personnalisation
🛠️ Développement
❗ Dépannage

🚀 Fonctionnalités

✨ Alertes en temps réel

Nouveaux followers avec animations
Nouveaux abonnés et renouvellements
Cadeaux d'abonnements (sub gifts)
Raids entrants avec effet spéciaux
Donations de bits avec confettis
Queue d'alertes pour éviter les chevauchements

🎭 Overlays animés

Page de démarrage : Compte à rebours avant stream
Page principale : Statistiques en temps réel + alertes
Page de fin : Écran de fin de stream
Animations CSS avancées avec particules
Responsive design pour tous les écrans

📊 Statistiques en temps réel

Nombre de followers
Nombre d'abonnés
Spectateurs actuels
Mise à jour automatique via WebSocket

📦 Installation

Prérequis

Node.js 18+ (Télécharger)
npm (inclus avec Node.js)
Compte Twitch
ngrok (intégré) ou installation manuelle optionnelle (Télécharger)

Information : Prendre la version gratuite : https://ngrok.com/pricing
"Run your pre-release versions or internal apps on ngrok. Free forever."

1. Cloner le projet

git clone https://github.com/yazouv/ElectrumOverlay.git
cd electrum-overlay

2. Installer les dépendances

npm install

3. Préparer la configuration

cp src/config/config.example.js src/config/config.js

4. Structure du projet

electrum-overlay/
├── 📁 src/
│   ├── 📁 config/
│   │   └── config.js          # Configuration backend (sensible)
│   ├── 📁 routes/
│   │   └── api.js             # API routes principales
│   └── 📁 services/
│       ├── EventSubManager.js # Gestion EventSub
│       ├── TwitchAuth.js      # Authentification Twitch
│       ├── WebhookHandler.js  # Traitement webhooks
│       └── StreamStatsManager.js # Statistiques stream
├── 📁 public/
│   ├── index.html             # Overlay principal
│   ├── starting.html          # Page de démarrage
│   ├── ending.html            # Page de fin
│   ├── 📁 js/
│   │   ├── config.js          # Configuration frontend (public)
│   │   ├── overlay-common.js  # Fonctions communes
│   │   ├── index.js           # Logique page principale
│   │   ├── starting.js        # Logique démarrage
│   │   └── ending.js          # Logique fin
│   └── 📁 css/
│       ├── overlay-common.css # Styles communs
│       ├── index.css          # Styles page principale
│       ├── starting.css       # Styles démarrage
│       └── ending.css         # Styles fin
├── package.json
├── server.js                  # Serveur principal
├── ConfigOBS.json             # Configuration OBS

⚙️ Configuration

Le système utilise deux fichiers de configuration séparés :

📋 1. Configuration Backend (`src/config/config.js`)

⚠️ SENSIBLE - Ne pas partager publiquement

🔐 Génération du WEBHOOK_SECRET

Le WEBHOOK_SECRET est un secret cryptographique utilisé pour sécuriser les webhooks Twitch EventSub. Vous devez le générer vous-même :

// Dans Node.js (console ou script)
const crypto = require('crypto');
const webhookSecret = crypto.randomBytes(32).toString('hex');
console.log('WEBHOOK_SECRET:', webhookSecret);

Caractéristiques importantes :

32 caractères minimum (64 caractères en hexadécimal recommandés)
Aléatoire et unique pour votre application
Ne jamais partager ou committer dans Git
Utilisé pour vérifier que les webhooks proviennent bien de Twitch

⚙️ Configuration des événements EventSub

N'oubliez pas de configurer les conditions pour certains événements dans src/config/config.js (ligne 50-51) :

"condition": {
    "broadcaster_user_id": "197983290",     // Votre User ID
    "moderator_user_id": "197983290"        // Même User ID pour être modérateur
}

Important : Remplacez "197983290" par votre propre User ID Twitch obtenu à l'étape suivante.

🌐 2. Configuration Frontend (`public/js/config.js`)

✅ PUBLIC - Peut être partagé

🔧 Configuration Twitch

1. 🏗️ Créer une application Twitch

Allez sur Twitch Developers Console
Cliquez sur "Enregistrer votre application"
Remplissez les informations :
- Nom : Mon Overlay Twitch
- URL de redirection OAuth : http://localhost:8080/auth-callback
- Catégorie : Application Integration
- Type de client : Confidentiel
Cliquez sur "Créer"
Notez votre Client ID et Client Secret et mettez le dans le src/config/config.js

2. 🆔 Obtenir votre User ID

Récuperez votre User ID sur : StreamWeasels
Mettez le dans le public/js/config.js > OVERLAY_CONFIG.twitch.broadcasterId
Mettez le aussi dans src/config/config.js > twitch.BROADCASTER_ID

3. 🔑 Obtenir un Access Token

Méthode 1 : Flow OAuth (Recommandé)

Démarrez le serveur : npm start
Allez sur http://localhost:8080/auth-url
Autorisez l'application
Le token sera affiché dans la console
Mettez le dans src/config/config.js > twitch.USER_ACCESS_TOKEN

Méthode 2 : Token Generator

Allez sur Twitch Token Generator
Sélectionnez les scopes nécessaires
Générez le token
Mettez le dans src/config/config.js > twitch.USER_ACCESS_TOKEN

🌐 Tunnel Webhook (ngrok)

Les webhooks EventSub nécessitent une URL HTTPS publique. ngrok est intégré et activé par défaut dans ElectrumOverlay :

🔄 Mode automatique (par défaut)

Le système démarre automatiquement ngrok et configure l'URL webhook. Dans src/config/config.js :

"ngrok": {
    "ENABLED": true,  // ngrok activé par défaut
},

Avantages :

✅ Configuration automatique
✅ Pas besoin de gérer manuellement ngrok
✅ URL webhook mise à jour automatiquement

⚙️ Mode manuel (optionnel)

Si vous préférez gérer ngrok manuellement, désactivez le mode automatique :

1. 🔧 Désactiver ngrok automatique

Dans src/config/config.js :

"ngrok": {
    "ENABLED": false,  // Désactiver ngrok automatique
},

2. 📥 Installer ngrok

Téléchargez depuis ngrok.com
Ou via npm : npm install -g ngrok

3. 🚀 Démarrer le tunnel

# Dans un terminal séparé
ngrok http 8080

4. 📋 Copier l'URL

Ngrok va afficher quelque chose comme :

Forwarding  https://abcdefgijkl.ngrok-free.app -> http://localhost:8080

5. ⚙️ Configurer l'URL webhook

Dans src/config/config.js :

WEBHOOK_URL: "https://abcdefgijkl.ngrok-free.app/eventsub"

6. ⚠️ Note importante

L'URL ngrok change à chaque redémarrage (version gratuite)
Pensez à mettre à jour la configuration après chaque redémarrage

🚛 Intégration TruckyApp

ElectrumOverlay inclut une intégration TruckyApp activée par défaut pour les streameurs de simulation de camion :

🔄 Mode activé (par défaut)

L'intégration TruckyApp récupère automatiquement vos statistiques de jeu. Dans src/config/config.js :

"trucky": {
    "enable": true,                    // TruckyApp activé par défaut
    "USER_ID": "90694",               // Remplacez par votre ID utilisateur Trucky
},

Fonctionnalités :

✅ Récupération automatique des données utilisateur
✅ Affichage du dernier job effectué
✅ Statistiques de compagnie (si applicable)
✅ Intégration seamless avec les overlays

⚙️ Configuration TruckyApp

1. 🆔 Obtenir votre User ID TruckyApp

Allez sur TruckyApp
Connectez-vous à votre compte
Allez dans votre profil
L'ID utilisateur se trouve dans l'URL : https://truckyapp.com/user/[VOTRE_ID]

2. 🔧 Configurer l'ID

Dans src/config/config.js, remplacez "90694" par votre ID :

"trucky": {
    "enable": true,
    "USER_ID": "VOTRE_ID_TRUCKY",
},

🚫 Désactiver TruckyApp (optionnel)

Si vous ne jouez pas aux jeux de simulation de camion, vous pouvez désactiver cette fonctionnalité :

Dans src/config/config.js :

"trucky": {
    "enable": false,              // Désactiver TruckyApp
    "USER_ID": "90694",
},

Note : Même désactivée, cette configuration n'affecte pas les autres fonctionnalités du système.

🏃‍♂️ Lancement

🚀 Démarrage complet

Le système démarre automatiquement ngrok par défaut. Si ngrok est activé :

Démarrer le serveur :

npm start

Accéder aux overlays :
- Principal : http://localhost:8080
- Démarrage : http://localhost:8080/starting.html
- Fin : http://localhost:8080/ending.html
- Pause : http://localhost:8080/pause.html

Si vous avez désactivé ngrok (mode manuel) :

Démarrer ngrok (terminal 1) :

ngrok http 8080

Mettre à jour l'URL webhook dans src/config/config.js
Démarrer le serveur (terminal 2) :

npm start

Accéder aux overlays :
- Principal : http://localhost:8080
- Démarrage : http://localhost:8080/starting.html
- Fin : http://localhost:8080/ending.html
- Pause : http://localhost:8080/pause.html

📊 Commandes disponibles

npm start          # Démarrer le serveur
npm run dev        # Mode développement (nodemon)
npm run clean      # Nettoyer les abonnements EventSub
npm run setup      # Assistant de configuration
npm run config     # Mettre à jour la configuration

📹 Overlays OBS

Utilisez le fichier ConfigOBS.json pour configurer les overlays dans OBS :

Celui-ci contient les scènes préconfigurées pour les overlays, avec les sources nécessaires.

🧪 Tests

🔧 Avec Twitch CLI

Installer Twitch CLI :
- Guide d'installation
Configurer :

twitch configure

Tester les événements :

# Test follow
twitch event trigger channel.follow --to-user-id=197983290 --from-user-id=123456

# Test subscription
twitch event trigger channel.subscribe --to-user-id=197983290 --user-id=123456

# Test raid
twitch event trigger channel.raid --to-user-id=197983290 --from-user-id=123456

# Test bits
twitch event trigger channel.cheer --to-user-id=197983290 --user-id=123456

🌐 Test via API

# Test webhook directement
curl -X POST http://localhost:8080/eventsub \
  -H "Content-Type: application/json" \
  -d '{
    "subscription": {
      "type": "channel.follow",
      "version": "1"
    },
    "event": {
      "user_name": "TestUser",
      "user_display_name": "TestUser"
    }
  }'

📷 Preview/Gallerie

Ecran de démarrage

Ecran de pause

Ecran de fin

Note : Les overlays sont conçus pour être utilisés avec OBS ou tout autre logiciel de streaming compatible.

🎨 Personnalisation

🎨 Modifier les couleurs

Dans public/js/config.js :

theme: {
    primary: '#3b82f6',      // Couleur principale
    secondary: '#10b981',    // Couleur secondaire
    accent: '#f59e0b',       // Couleur d'accent
    background: '#1f2937',   // Fond
    text: '#f9fafb'         // Texte
}

✨ Personnaliser les alertes

alerts: {
    types: {
        follow: {
            icon: '<i class="fas fa-heart"></i>',          // Icône
            title: 'NOUVEAU FOLLOW',                        // Titre
            gradient: 'linear-gradient(...)',               // Dégradé
            border: '#3b82f6',                             // Couleur bordure
            defaultMessage: 'Merci pour le follow !'       // Message par défaut
        }
    }
}

🎭 Modifier les animations

Dans public/css/overlay-common.css :

/* Animation d'apparition des alertes */
.alert-container.show {
    animation: slideInFromTop 0.8s cubic-bezier(0.25, 0.46, 0.45, 0.94);
}

/* Animation de particules */
.particle {
    animation: particleFloat 3s infinite ease-in-out;
}

📊 Configurer les panneaux

Dans public/js/config.js :

panels: {
    followers: {
        enabled: true,           // Activer/désactiver
        position: 'top-left',    // Position
        updateInterval: 5000,    // Intervalle de mise à jour (ms)
        animationDuration: 300   // Durée animation (ms)
    }
}

🛠️ Développement

🔧 Mode développement

npm run dev

Le serveur redémarre automatiquement lors des modifications.

📁 Structure du code

Backend (`src/`)

services/ : Services métier
- EventSubManager.js : Gestion des abonnements EventSub
- TwitchAuth.js : Authentification Twitch
- WebhookHandler.js : Traitement des webhooks
- StreamStatsManager.js : Statistiques en temps réel
routes/ : Routes Express
- api.js : API principale
- api-fixed.js : API avec données fixes
config/ : Configuration
- config.js : Configuration sensible backend

Frontend (`public/`)

js/ : Scripts JavaScript
- config.js : Configuration publique
- overlay-common.js : Fonctions partagées
- index.js, starting.js, ending.js : Logique par page
css/ : Styles CSS
- overlay-common.css : Styles partagés
- Page-specific CSS files

🔌 API Endpoints

GET  /                          // Page principale
GET  /starting.html             // Page de démarrage
GET  /ending.html               // Page de fin
GET  /auth                      // Authentification Twitch
GET  /auth-callback             // Callback OAuth
POST /eventsub                  // Webhooks EventSub
GET  /api/stream-stats          // Statistiques de stream en json
GET  /api/stream-stats-html     // Statistiques de stream en html

🔄 WebSocket Events

// Côté client
socket.on('alert', (data) => {
    // Nouvelle alerte reçue
});

socket.on('stats-update', (data) => {
    // Mise à jour des statistiques
});

// Côté serveur
wss.broadcast('alert', alertData);
wss.broadcast('stats-update', statsData);

❗ Dépannage

🚫 Erreurs communes

1. "ECONNREFUSED" lors du démarrage

Cause : Port déjà utilisé
Solution : Changer le port dans config.js ou arrêter le processus

2. Webhooks non reçus

Cause : URL ngrok incorrecte ou expirée
Solution : 
1. Vérifier que ngrok fonctionne
2. Mettre à jour WEBHOOK_URL dans config.js
3. Redémarrer le serveur

3. Alertes non affichées

Cause : Configuration EventSub ou WebSocket
Solution :
1. Vérifier les logs serveur
2. Tester avec Twitch CLI
3. Vérifier les scopes du token

4. "Token expired" ou "401 Unauthorized"

Cause : Access token expiré
Solution : Générer un nouveau token d'accès

📋 Vérifications de santé

1. Vérifier la configuration

# Tester la configuration
npm run config

2. Vérifier les abonnements EventSub

# Lister les abonnements actifs
curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Client-Id: YOUR_CLIENT_ID'

3. Nettoyer les abonnements

# Supprimer tous les abonnements
npm run clean

4. Logs détaillés

Activer les logs dans public/js/config.js :

debug: {
    enabled: true,              // Activer les logs debug
    websocket: true,            // Logs WebSocket
    alerts: true,               // Logs alertes
    api: true                   // Logs API
}

🔧 Outils de débogage

1. Console navigateur

Ouvrir F12 → Console
Vérifier les erreurs JavaScript
Voir les messages WebSocket

2. Logs serveur

Les logs s'affichent dans le terminal
Format : [TIMESTAMP] [LEVEL] Message

3. Test manual des endpoints

# Tester l'API stats
curl http://localhost:8080/api/stats

# Tester le webhook
curl -X POST http://localhost:8080/eventsub \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

📞 Support

Vérifier les logs pour identifier l'erreur
Consulter la documentation Twitch : EventSub Guide
Nettoyer et recommencer : npm run clean puis redémarrer

📄 Licence

MIT License - Voir le fichier LICENSE pour plus de détails.

🤝 Contribution

Les contributions sont les bienvenues ! Veuillez :

Fork le projet
Créer une branche pour votre fonctionnalité
Commiter vos changements
Pousser vers la branche
Ouvrir une Pull Request

🎮 Bon streaming ! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github		.github
public		public
readme		readme
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
ConfigOBS.json		ConfigOBS.json
LICENSE		LICENSE
README-EN.md		README-EN.md
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
server.js		server.js

Uh oh!

License

yazouv/ElectrumOverlay

Folders and files

Latest commit

History

Repository files navigation

🎮 Electrum Overlay - Système d'overlay Twitch avec EventSub

📋 Table des matières

🚀 Fonctionnalités

✨ Alertes en temps réel

🎭 Overlays animés

📊 Statistiques en temps réel

📦 Installation

Prérequis

1. Cloner le projet

2. Installer les dépendances

3. Préparer la configuration

4. Structure du projet

⚙️ Configuration

📋 1. Configuration Backend (src/config/config.js)

🔐 Génération du WEBHOOK_SECRET

⚙️ Configuration des événements EventSub

🌐 2. Configuration Frontend (public/js/config.js)

🔧 Configuration Twitch

1. 🏗️ Créer une application Twitch

2. 🆔 Obtenir votre User ID

3. 🔑 Obtenir un Access Token

Méthode 1 : Flow OAuth (Recommandé)

Méthode 2 : Token Generator

🌐 Tunnel Webhook (ngrok)

🔄 Mode automatique (par défaut)

⚙️ Mode manuel (optionnel)

1. 🔧 Désactiver ngrok automatique

2. 📥 Installer ngrok

3. 🚀 Démarrer le tunnel

4. 📋 Copier l'URL

5. ⚙️ Configurer l'URL webhook

6. ⚠️ Note importante

🚛 Intégration TruckyApp

🔄 Mode activé (par défaut)

⚙️ Configuration TruckyApp

1. 🆔 Obtenir votre User ID TruckyApp

2. 🔧 Configurer l'ID

🚫 Désactiver TruckyApp (optionnel)

🏃‍♂️ Lancement

🚀 Démarrage complet

📊 Commandes disponibles

📹 Overlays OBS

🧪 Tests

🔧 Avec Twitch CLI

🌐 Test via API

📷 Preview/Gallerie

🎨 Personnalisation

🎨 Modifier les couleurs

✨ Personnaliser les alertes

🎭 Modifier les animations

📊 Configurer les panneaux

🛠️ Développement

🔧 Mode développement

📁 Structure du code

Backend (src/)

Frontend (public/)

🔌 API Endpoints

🔄 WebSocket Events

❗ Dépannage

🚫 Erreurs communes

1. "ECONNREFUSED" lors du démarrage

2. Webhooks non reçus

3. Alertes non affichées

4. "Token expired" ou "401 Unauthorized"

📋 Vérifications de santé

1. Vérifier la configuration

2. Vérifier les abonnements EventSub

3. Nettoyer les abonnements

4. Logs détaillés

🔧 Outils de débogage

1. Console navigateur

2. Logs serveur

3. Test manual des endpoints

📋 1. Configuration Backend (`src/config/config.js`)

🌐 2. Configuration Frontend (`public/js/config.js`)

Backend (`src/`)

Frontend (`public/`)