Rumble Spotify Jukebox

A comprehensive, interactive music controller for Rumble streamers. This application connects your Rumble chat to your Spotify playback, allowing viewers to request songs, view the queue, and interact with the stream. It features a robust GUI for the streamer, dynamic browser overlays for OBS, and a credit-based economy system.

Features

🎵 Core Functionality

• Chat Integration: Listens to Rumble chat in real-time for commands.
• Spotify Automation: Automatically searches, queues, and plays tracks on your active Spotify device.
• Queue System: A persistent, file-based queue that syncs between the bot, the GUI, and the overlays.
• Smart Playback: Uses a "Peek-then-Pop" logic to ensure tracks are only removed from the queue after they successfully start playing.

💻 Streamer GUI (main.py)

• Dashboard: Manage Rumble connection, Spotify credentials, and application settings.
• Queue Manager Tab: View the current queue, remove specific tracks, or clear the entire list directly from the app.
• Port Management: Automatically finds an available port (default 5000) and updates your Spotify Redirect URI configuration.
• Browser Fixes: Includes specific handling for Brave and Chrome browsers to prevent automation crashes.

🎨 Overlays (OBS/Streamlabs)

• Now Playing: A customizable card showing track artwork, title, artist, requester, and a progress bar.
• Queue List: Displays upcoming tracks in a list or scrolling ticker format.
• Dynamic Customization: Change colors, sizes, fonts, and orientations (Portrait/Landscape) via the GUI.

💰 Economy & Moderation

• Credit System: Configurable "credits" per user. Users spend credits to request songs.
• Blacklist: Ban specific words or Spotify track URIs.
• Permissions: Restrict commands to Everyone, Supporters, or Moderators.

Installation

Prerequisites

1. Python 3.10+ (on required if running from source).
2. Spotify Premium account (required for API playback control).
3. Google Chrome or Brave Browser installed.
4. Rumble account.

Setup Steps

1. Spotify Dashboard:

   • Go to the Spotify Developer Dashboard.
   • Create an app.
   • Set the Redirect URI to http://127.0.0.1:5000/callback (or the port shown in the app logs, e.g., 5000-20000).
   • Copy the Client ID and Client Secret.

2. Application Config:

   • Launch the application (main.py or .exe).
   • Spotify Tab: Enter your Client ID and Secret. Click Detect Devices (ensure Spotify is running).
   • Rumble Tab: Enter your Stream URL and Chat ID.
   • Login: Click 1. Login & Capture to authenticate with Rumble via the browser.

3. OBS Setup:

   • Go to the Overlays Tab in the app.
   • Copy the Now Playing URL (e.g., http://127.0.0.1:5000/overlay/nowplaying).
   • In OBS, create a Browser Source, paste the URL, and set dimensions (e.g., 500x150).
   • Repeat for the Queue overlay.

Chat Commands

| Command | Usage | Description | Permission | | :--- | :--- | :--- | :--- | | !play | !play <song> | Search and queue a song by name or Spotify URL. | Configurable | | !skip | !skip | Skips the currently playing track. | Mods/Admin | | !queue | !queue | Shows the next 3 songs in the chat. | Everyone | | !tunes | !tunes | Shows help/available playlists. | Everyone | | !listplaylists | !listplaylists | Lists configured playlists for fallback. | Everyone |

Architecture & Operation

The application uses a multi-threaded architecture to handle the GUI, Web Server, and Chat Listener simultaneously.

Sequence Diagram

```mermaid sequenceDiagram participant User as Rumble Chat User participant Bot as Bot Engine (Thread) participant Server as Flask Server (Jukebox) participant DB as JSON Files (Queue/Config) participant Spotify as Spotify API participant Overlay as OBS Browser Source

Note over Server, Spotify: 1. Playback Monitor Loop (Every 5s)
loop Playback Monitor
    Server->>DB: Read queue.json
    alt Queue has Item & Spotify Idle
        Server->>Spotify: Start Playback (Track URI)
        Spotify-->>Server: Success (204)
        Server->>DB: Remove Item & Save queue.json
    end
end

Note over User, Bot: 2. Request Flow
User->>Bot: "!play Despacito"
Bot->>DB: Check Credits & Blacklist
alt Allowed
    Bot->>Spotify: Search "Despacito"
    Spotify-->>Bot: Return Track Details
    Bot->>Server: POST /queue (Add Track)
    Server->>DB: Update queue.json
    Bot->>User: "Queued: Despacito"
else Denied
    Bot->>User: "No Credits / Blacklisted"
end

Note over Overlay, Server: 3. Overlay Update Loop (Every 1s)
loop Overlay Polling
    Overlay->>Server: GET /status.json
    Server->>Spotify: Get Current Playback Status
    Spotify-->>Server: Track, Artist, Progress, Artwork
    Server-->>Overlay: JSON Data
    Overlay->>Overlay: Update HTML/CSS (Show Thumbnail/Timer)
end