🎵 Twitch SR Bot

Moderner EventSub-basierter Twitch Song Request Bot mit Spotify-Integration. Zuschauer können Songs per Chat-Command wünschen, die automatisch zur Warteschlange hinzugefügt und abgespielt werden.

⚠️ WICHTIG: Für die Steuerung der Spotify-Wiedergabe wird ein Spotify Premium Account benötigt!

✨ Features

• 👤 Song Requests: Chat-basierte Song-Wünsche (!sr)
• 💯 Smart Voting: Mehrfach gewünschte Songs steigen in der Queue auf
• 🔐 Berechtigungssystem:
  • Alle User
  • Nur Follower (mit Twitch API Verifikation)
  • Nur Subscriber
• ⏱️ Intelligente Limits:
  • Max. Queue-Größe
  • Songs pro User
  • Song-Länge
  • Cooldown-System
• 🎯 Queue Management: Live-Updates, Sortierung, Force Play
• 🤖 Autopilot: Fallback-Playlist wenn Queue leer
• 🌍 Multi-Language: Deutsch & Englisch
• 🎨 Moderne UI: CustomTkinter mit Dark Theme
• 📊 Live-Logs: Ein-/ausblendbare Debug-Informationen
• 🔄 EventSub WebSocket: Moderne Twitch API (kein IRC)
• 📈 Song Statistics: Detaillierte Tracking-Daten mit Top Songs/Requesters/Artists
• 🎥 OBS Overlay: Integriertes Browser-Source Overlay für Streams

🚀 Quick Start

Option 1: Standalone Executable (Empfohlen)

1. Download TwitchSRBot.exe aus den Releases
2. Starte die .exe - keine Installation nötig!
3. Folge der Installations-Anleitung

Option 2: Python

git clone https://github.com/Brunsben/TwitchSpotifySRBot.git
cd TwitchSpotifySRBot
pip install -r requirements.txt
python app.py

📋 Voraussetzungen

Für Twitch

• Twitch Developer App (dev.twitch.tv/console)
• OAuth Redirect URL: http://localhost:3000
• Scopes: user:read:chat, user:write:chat, user:bot

Für Spotify

• Spotify Premium Account (erforderlich für Playback-Steuerung!)
• Spotify Developer App (developer.spotify.com)
• Redirect URI: http://localhost:8888/callback

Detaillierte Anleitung: INSTALL.md

🎮 Verwendung

Chat Commands

👥 Für alle User (EVERYONE)

!sr <Songname>          - Sucht und fügt Song hinzu
!sr <Spotify-Link>      - Fügt Song direkt hinzu
!currentsong / !song    - Zeigt aktuellen Song
!songinfo               - Detaillierte Spotify-Metadaten (Album, Release, Dauer, Popularität)
!queue                  - Zeigt erste 5 Songs in der Queue
!blacklist              - Zeigt blockierte Songs/Artists
!wrongsong / !oops      - Entfernt eigenen letzten Request
!srhelp / !commands     - Zeigt alle verfügbaren Commands

🔨 Für Moderatoren (MODERATORS)

!skip                   - Überspringt aktuellen Song
!clearqueue             - Löscht komplette Queue
!pauserequests          - Pausiert Song Requests
!resumerequests         - Aktiviert Song Requests wieder
!pausesr                - Pausiert Spotify-Wiedergabe
!resumesr               - Setzt Spotify-Wiedergabe fort
!addblacklist <name>    - Fügt Song/Artist zur Blacklist hinzu
!removeblacklist <name> - Entfernt Song/Artist von Blacklist

Hinweis: Alle Permissions können individuell konfiguriert werden!

Beispiele:

!sr Never Gonna Give You Up
!sr https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT
!songinfo
!addblacklist Nickelback
!pauserequests

GUI Bedienung

• STARTEN/STOPPEN: Bot-Verbindung steuern
• Force Play: Ausgewählten Song sofort spielen
• Skip: Aktuellen Song überspringen
• Alle löschen: Queue komplett leeren
• 🔍 Debug Log: Technische Logs anzeigen/verbergen

🏗️ Architektur

TwitchSpotifySRBot/
├── app.py                    # Einstiegspunkt
├── requirements.txt          # Dependencies
├── src/
│   ├── constants.py         # Version & Metadaten
│   ├── models/              # Datenmodelle (Pydantic)
│   │   ├── config.py       # Konfiguration
│   │   └── song.py         # Song & Queue Items
│   ├── services/            # Business Logic
│   │   ├── twitch_service.py      # TwitchIO 3.x EventSub
│   │   ├── spotify_service.py     # Spotify Web API
│   │   ├── queue_manager.py       # Queue-Logik
│   │   └── bot_orchestrator.py    # Koordination
│   ├── ui/                  # GUI (CustomTkinter)
│   │   ├── main_window.py
│   │   ├── settings_window.py
│   │   └── help_window.py
│   └── utils/               # Hilfsfunktionen
│       ├── config_manager.py
│       ├── i18n.py
│       ├── logging_config.py
│       └── twitch_oauth.py
└── locales/                 # Übersetzungen (DE/EN)

🔧 Einstellungen

Command Permissions (NEU in v0.9.9)

• 5-Tier System: EVERYONE, FOLLOWERS, SUBSCRIBERS, MODERATORS, BROADCASTER
• 15 Commands: Jeder Command individuell konfigurierbar
• GUI-Verwaltung: Settings-Tab → "Commands" mit Dropdown-Menüs
• Flexible Kontrolle: Bestimme genau, wer welche Commands nutzen darf

Anti-Spam & Cooldowns (NEU in v0.9.9)

• User-Cooldown: Wartezeit zwischen Requests pro User (Standard: 3 Min., 0 = aus)
• Song-Cooldown: Wartezeit bis Song erneut gewünscht werden kann (Standard: 15 Min., 0 = aus)
• Bypass: Moderatoren und Broadcaster ignorieren Cooldowns

Blacklist (NEU in v0.9.9)

• Songs blockieren: Verhindere bestimmte Tracks
• Artists blockieren: Sperre komplette Künstler
• Partial Matching: Automatische Namens-Erkennung
• Live-Updates: Änderungen sofort aktiv
• Verwaltung: Via GUI oder Chat-Commands

Berechtigungen

• Alle: Jeder kann Songs wünschen
• Nur Follower: Twitch API prüft Follower-Status (5 Min. Cache)
• Nur Subscriber: Nur Subs dürfen Requests machen

Regeln & Limits

• Max. Queue: Warteschlangengröße (z.B. 10)
• Max. pro User: Songs gleichzeitig pro User (z.B. 2)
• Max. Länge: Song-Dauer in Minuten (z.B. 8)
• Duplicate Detection: Verhindert doppelte Songs (wenn Smart Voting aus)

Autopilot

• Zweck: Spielt Musik wenn Queue leer
• Setup: Link zu öffentlicher Spotify Playlist
• Wechselt automatisch zwischen Requests und Autopilot

🔬 Technologie

• Python 3.13: Moderne Features & Performance
• TwitchIO 3.1.0: EventSub WebSocket API (moderne Architektur)
• Spotipy 2.23.0: Spotify Web API
• CustomTkinter: Modernes GUI Framework
• Pydantic 2.0: Type-Safe Konfiguration
• PyInstaller: Standalone Executables

Was ist EventSub?

TwitchIO 3.x nutzt EventSub über WebSocket statt IRC:

• ✅ Offizielle Twitch API
• ✅ Moderne OAuth2-Authentifizierung
• ✅ Bessere Skalierbarkeit
• ✅ Echtzeit-Events
• ❌ Kein IRC mehr

🔨 Build von Source

# PyInstaller installieren
pip install pyinstaller

# Executable bauen
python build.py

# Output: dist/TwitchSRBot.exe

Details: BUILD.md

🐛 Troubleshooting

Bot empfängt keine Nachrichten

• ✅ Prüfe OAuth Scopes (user:read:chat, user:write:chat, user:bot)
• ✅ Erstelle neuen Token mit korrekten Scopes
• ✅ TwitchIO 3.x benötigt EventSub-Authentifizierung

Spotify nicht verbunden

• ✅ GUI Statusanzeige beachten: "⚠️ Spotify: Bitte starten!" bedeutet Spotify läuft nicht
• ✅ Spotify muss auf einem Gerät aktiv sein (PC, Handy, Browser)
• ✅ Premium Account erforderlich für Playback-Steuerung
• ✅ Prüfe Spotify API Credentials in Settings

Commands funktionieren nicht

• ✅ Permissions prüfen: Settings → Commands Tab
• ✅ Jeder Command hat eigene Permission-Level
• ✅ Standard: Moderator-Commands nur für Mods, User-Commands für alle

Follower-Check funktioniert nicht

• ✅ Twitch App benötigt zusätzliche Permissions
• ✅ Cache wird alle 5 Minuten aktualisiert
• ✅ Prüfe Logs für API-Fehler

Autopilot spielt nicht

• ✅ Playlist muss ÖFFENTLICH sein
• ✅ Spotify muss aktiv sein (auf irgendeinem Gerät)
• ✅ Premium Account erforderlich

Weitere Hilfe: TROUBLESHOOTING.md

📝 Changelog

v0.9.9 (2025-12-23)

• 🎉 MAJOR: Flexible Command Permission System
  • 5-Tier Levels: EVERYONE → FOLLOWERS → SUBSCRIBERS → MODERATORS → BROADCASTER
  • Per-Command Configuration: 15 commands individually configurable
  • Full GUI Integration: New "Commands" tab in settings
• 🎮 12 NEW COMMANDS (3 → 15 total):
  • Queue Control: !queue, !clearqueue, !pauserequests, !resumerequests
  • Blacklist: !blacklist, !addblacklist, !removeblacklist
  • Playback: !pausesr, !resumesr
  • Info: !songinfo, !srhelp/!commands
  • User: !wrongsong/!oops
• 🚫 Blacklist System: Block songs or entire artists with live updates
• ⏱️ Anti-Spam System: User-Cooldown (3 min) + Song-Cooldown (15 min)
• 🔍 Duplicate Detection: Prevents duplicate songs in queue (Smart Voting dependent)
• 📊 Spotify Status Display: Real-time connection monitoring in GUI
  • ✅ Connected (green) / ⚠️ Please start Spotify (orange) / ❌ Not connected (red)
• 📚 OBS Setup Documentation: 340 lines comprehensive API guide (OBS_SETUP.md)
• 🐛 5 Critical Bug Fixes: Twitch connection, config structure, Spotify client, playback resume, error handling
• 🌍 i18n Complete: Full German/English translations for all features

v0.9.8 (2025-12-15)

• 📊 NEW: Song History & Statistics tracking system
  • Track all played songs with timestamps and requesters
  • Top Songs, Top Requesters, Top Artists tabs
  • Time filtering (All Time, Last 7 Days, Last 30 Days)
  • CSV/JSON export functionality
  • Statistics overview with skip rate and autopilot percentage
• 🎥 NEW: OBS Overlay for streaming
  • Real-time WebSocket-based overlay at http://localhost:8080
  • Shows current song with cover art, artist, and requester
  • Beautiful gradient design (Twitch purple to Spotify green)
  • Smooth animations for song changes
  • Easy OBS Browser Source setup
• 🖼️ Cover art now displayed in overlay
• 🔧 Internal: Song model extended with cover_url field

v0.9.7 (2025-12-14)

• ✨ New custom icon with Twitch + Spotify branding (purple & green)
• 🐛 Fixed autopilot/fallback playlist not starting in .exe builds
• ⚡ Improved window closing - instant response with background cleanup
• 🎨 Icon now visible in taskbar and on .exe file

v0.9.6 (2025-12-14)

• 🐛 Fixed 'lost sys.stdin' error in PyInstaller builds
• ✅ Improved graceful shutdown when closing app while bot is running
• 🔧 Better async cleanup and error handling on exit

v0.9.5 (2025-12-14)

• 🐛 Fixed browser window stealing focus on bot startup
• 🔧 Added global webbrowser patch to prevent focus theft
• 🔗 Fixed Help window links to use autoraise=False

v0.9.4 (2025-12-13)

• 📖 Comprehensive Smart Voting documentation
• 📚 Added detailed help section explaining voting system
• 🎯 Updated README with Smart Voting feature

v0.9.3 (2025-12-13)

• ✨ Added !skip command (Broadcaster/Moderator only)
• ✨ Added !currentsong / !song command (all users)
• 🔒 Browser no longer steals focus during OAuth (prevents token leaks)
• 🔗 Developer portal buttons in settings (Twitch & Spotify)
• 🎯 Username mentions in command responses

v0.9.2 (2025-12-13)

• 🎮 Initial implementation of new chat commands
• 🐛 Bug fixes and improvements

v0.9.1 (2025-12-13)

• 🐛 Fixed PyInstaller resource paths
• 📖 Comprehensive help documentation
• ✅ All locales load correctly in .exe

v0.9.0 (2025-12-13)

• ✨ Complete refactor from monolithic to modular architecture
• 🔄 Migration to TwitchIO 3.x EventSub
• 🔐 Permission system (all/followers/subscribers)
• 🌐 Follower API integration with caching
• 🎨 Tab-based settings UI
• 📊 Toggle-able debug logs
• 🌍 Multi-language support
• 🏗️ Modern async architecture
• 📦 PyInstaller build system

Legacy (Pre-v0.9.0)

• Original monolithic implementation
• TwitchIO 2.x IRC-based

📄 Lizenz

MIT License - siehe LICENSE

👤 Autor

uprisin6 GitHub: @Brunsben

🙏 Credits

• TwitchIO - EventSub WebSocket Integration
• Spotipy - Spotify Web API
• CustomTkinter - Modern GUI
• Pydantic - Data Validation

🔗 Links

• 📦 Releases
• 📖 Installation Guide
• 🔨 Build Instructions
• 🐛 Troubleshooting
• 🔄 Migration from Legacy

---

Viel Spaß beim Streamen! 🎵