Spotify-Integration

Mit verbundenem Spotify hast du zwei Funktionsebenen:

• Read-only-Anzeigebefehle — !song, !playlist, !nexttracks.
• Song Requests aus dem Chat — !sr, dazu Mod-Befehle für die Wiedergabesteuerung (!skip, !playsong, !stopsong) und eine kanalweise Blacklist, die unerwünschte Künstler oder Keywords gar nicht erst auf die Playlist lässt.

Verbinden

1. Öffne /settings/spotify.
2. Klicke Spotify verbinden.
3. Du wirst zur Spotify-Autorisierungsseite geleitet — dort den Zugriff bestätigen.
4. Du wirst zurückgeleitet. Die Seite zeigt nun Verbunden und den Spotify-Accountnamen.

AveloBot fordert folgende OAuth-Scopes an: user-read-currently-playing, user-read-playback-state, user-modify-playback-state, playlist-read-private, playlist-read-collaborative, playlist-modify-public, playlist-modify-private. Fehlt deiner gespeicherten Verbindung einer davon (z.B. weil der Bot nach deinem letzten Verbinden ein Update bekommen hat), zeigt die Settings-Seite eine Warnung samt Reconnect-Button. Spotifys Refresh-Flow vergibt nachträglich keine neuen Scopes — ein manueller Reconnect ist der einzige Weg.

Playlists-Seite

Auf /playlists legst du fest, in welche Playlist Song Requests landen.

• Gespeicherte Playlists (obere Tabelle) — Playlists, die du aus deiner Spotify-Bibliothek importiert hast. Genau eine kann aktiv sein. Im Playlist-Modus landen Song Requests in der aktiven.
• Deine Spotify-Playlists (untere Tabelle) — frisch aus deiner Bibliothek. Klick Refresh, um sie zu laden.

Jede Playlist-Zeile zeigt einen Besitz-Chip:

• 🟢 Yours — die Playlist gehört deinem Spotify-Account. !sr darf hineinschreiben.
• 🟡 Following / Not yours — du folgst der Playlist nur (z.B. eine von Spotify kuratierte oder Community-Playlist). Spotify lehnt Schreibzugriffe auf nicht-eigene Playlists ab — !sr würde mit 403 fehlschlagen, wenn so eine Playlist aktiv ist. Wähl eine mit Yours-Chip oder leg dir in Spotify eine eigene an und importier sie.

Weitere Aktionen: Tracks ansehen, Aktivieren / Deaktivieren, Löschen (entfernt aus AveloBot, nicht aus Spotify).

Song Request-Einstellungen

Auf /settings/spotify gibt es eine Karte Song Requests mit allen Optionen pro Kanal. Jedes Feld speichert sofort beim Ändern — kein Speichern-Button nötig. Pro Änderung erscheint eine Bestätigungs-Snackbar.

Einstellung	Standard	Was sie macht
Enable song requests	an	Master-Schalter. Bei Aus antwortet !sr mit "Song requests are currently disabled."
Mode	Active playlist	Wohin Requests gehen — siehe unten.
Max. track length	7 Min	Tracks länger als angegebene Sekunden werden abgelehnt. Leer = unbegrenzt. Bereich 30 s – 30 Min.
Block explicit tracks	aus	Lehnt jeden mit explicit markierten Spotify-Track ab.
Duplicate check	an	Lehnt einen Track ab, der schon in der aktiven Playlist steckt (nur Playlist-Modus).
Max. requests per user per stream	unbegrenzt	Jeder Chatter darf pro Stream-Session maximal so viele Tracks erfolgreich requesten. Fehlversuche (nicht gefunden, blockiert, …) zählen nicht mit. Der Zähler wird zurückgesetzt, wenn der Kanal online geht (Twitch stream.online-Event). Leer = unbegrenzt. Bereich 1 – 100.

Modi

• Active playlist — !sr hängt den Track an die als Aktiv markierte Playlist an. Setzt voraus, dass diese Playlist deinem Spotify-Account gehört.
• Spotify queue — !sr reiht den Track in die Spotify-Player-Queue ein (die gleiche Queue, die du in der Spotify-App unter „Queue" siehst). Tracks sind flüchtig: wenn sie gespielt wurden, sind sie weg. Setzt voraus, dass Spotify gerade auf einem Gerät spielt — ohne aktives Device gibt der Queue-Endpoint 404 und der Chatter sieht "Could not queue track — Spotify is not playing on any device."

Blacklist

Auf /settings/spotify/blacklist blockst du Künstler oder Keywords.

• Artist-Blacklist — tipp den Künstlernamen ins Dialog-Feld; AveloBot löst ihn per Spotify-Search auf eine eindeutige Artist-ID auf. Damit ist der ganze Künstler (inklusive Features und Collaborations) gesperrt. Du kannst alternativ eine Spotify-URL (open.spotify.com/artist/…), URI (spotify:artist:…) oder die nackte ID einfügen — der Dialog erkennt alle drei Formen.
• Keyword-Blacklist — Substring-Match (case-insensitive) gegen Track-Namen und alle Künstlernamen. Gut für pauschale Sperren wie "baby shark" oder "christmas".

Wenn !sr einen Track ablehnt, sieht der Chatter "that track is blocked" (in Klammern dein optionaler Reason, falls gesetzt). Beide Blacklist-Typen sind tenant-gescoped — deine Einträge gehen nicht zu anderen Kanälen.

Chat-Befehle

Befehl	Berechtigung	Verhalten
!song (Alias !s)	Everyone	Postet den aktuell laufenden Track.
!playlist (Alias !pl)	Everyone	Zeigt die aktuell aktive gespeicherte Playlist mit Spotify-Link.
!sr <Eingabe> (Alias !songrequest)	Everyone	Requestet einen Song. Eingabe kann eine Spotify-Track-URL, URI oder Artist - Titel sein. Bei Freitext sucht der Bot via Spotify; ohne Treffer fällt er auf eine generische Suche zurück.
!nexttracks (Alias !queue)	Everyone	Zeigt die nächsten 3 Tracks. Im Playlist-Modus die nächsten 3 aus der aktiven Playlist (überspringt den aktuellen Track, falls er dort steht). Im Queue-Modus die live Spotify-Player-Queue.
!skip (Alias !next)	Moderator	Springt zum nächsten Track.
!playsong (Alias !play)	Moderator	Setzt die Spotify-Wiedergabe fort.
!stopsong (Aliase !stop, !pause)	Moderator	Pausiert die Spotify-Wiedergabe.

Alle Standardwerte (Trigger, Aliase, Berechtigung, Cooldowns) sind pro Kanal auf der Commands-Seite überschreibbar.

Trennen

Klicke auf der Spotify-Settings-Seite Disconnect. AveloBot löscht seine Tokens. Um den Zugriff vollständig zu widerrufen, entferne AveloBot zusätzlich unter spotify.com/account/apps.

Fehlerbehebung

• !sr sagt "the active playlist isn't owned by the streamer's Spotify account" — Wähle auf der Playlists-Seite eine Playlist mit grünem Yours-Chip aus oder schalte den Modus auf Spotify queue um.
• !sr sagt "Spotify is not playing on any device" (Queue-Modus) — Öffne Spotify und starte die Wiedergabe auf einem beliebigen Gerät.
• Settings-Seite zeigt "Your Spotify connection is missing the scopes …" — Klick Reconnect, um die fehlenden Scopes zu vergeben. Nach jedem Bot-Upgrade nötig, das neue Spotify-Capabilities hinzufügt.
• !sr sagt "Spotify connection needs re-authorization" — Der gespeicherte Token kann nicht erneuert werden; klick Reconnect.