Modular HTML / CSS / JS / WebSocket Stream Overlay

A modular streaming overlay built with HTML, CSS, JavaScript, and WebSocket, designed to be controlled by Streamer.bot.
Each module can be used independently or combined to create a fully customized stream experience.

✨ Features

• ⚡ Real-time updates via WebSocket
• 🧩 Modular design — load only what you need
• 🎯 Perfect for OBS or any browser source
• 🔌 Seamless integration with Streamer.bot actions

📦 Included Modules

scrolling-banner

Displays a scrolling banner with custom alert text.

alert-video

Plays video alerts triggered by stream events such as subscriptions, follows, or raids.

chat

Displays the stream's live chat directly on screen.

popup

Shows popup messages on the stream for quick announcements or alerts.

big-emote

Displays a large emote that moves randomly across the screen.
Typically used with the "giant emote" power-up.

apple-music

Connects to the Cider app to display the currently playing track from Apple Music.

---

🛠 Setting Up Modules

The overlay.html file defines which modules are loaded in your overlay.
To add or remove modules, edit overlay.html and include/exclude <script> tags like this:

<!-- Required core script -->
<script type="text/javascript" src="modules/overlay-core/overlay-core.js"></script>

<!-- Example: enable popup module -->
<script type="text/javascript" src="modules/popup/popup.js"></script>

<!-- Example: enable scrolling banner -->
<script type="text/javascript" src="modules/scrolling-banner/scrolling-banner.js"></script>

Important:

• overlay-core.js is required for the overlay to function.
• Each module has its own CSS file located in its module folder (e.g., modules/popup/css/popup.css) that you can edit to customize the style.

---

🎥 Adding to OBS

1. In OBS, create a new Browser Source.
2. Point it to the overlay.html file (local path or hosted URL).
3. Set it to match your full stream resolution.
4. Optionally, you can pass connection parameters in the URL:

?address=127.0.0.1&port=8080&password=StreamerBotWSPassword

Parameters:

Parameter	Description
address	IP address of the machine running Streamer.bot (default: 127.0.0.1)
port	WebSocket port configured in Streamer.bot
password	WebSocket password set in Streamer.bot

Example full URL:

overlay.html?address=127.0.0.1&port=8080&password=MySecretPassword

---

🎮 Controlling Modules from Streamer.bot

1. In Streamer.bot, locate the included "WebSocket" action (provided in the repository or your import file).
2. Call this action from other actions or events with the following parameters:

Parameter	Description
wsAction	The module or action to trigger (e.g., scrolling-banner, popup, big-emote)
wsParam1	First parameter for the module (depends on module)
wsParam2	Second parameter (optional)
wsParam3	Third parameter (optional)
...	Additional parameters as needed by the module

---

📌 Example: Showing a Popup (modules/popup/popup.js module)

Action: wsAction = stream-popup
Parameters:

Parameter	Description
wsParam1	Popup title
wsParam2	Popup message
wsParam3	Display duration in seconds (-1 for unlimited)
wsParam4	X position (-1 for random, default)
wsParam5	Y position (-1 for random, default)
wsParam6	Reference (optional, useful for manual deletion)
wsParam7	Image URL (e.g., user profile picture)

Example usage:

wsAction = stream-popup
wsParam1 = New Subscriber!
wsParam2 = Thanks for subscribing, JohnDoe!
wsParam3 = 10
wsParam4 = -1
wsParam5 = -1
wsParam6 = subAlert123
wsParam7 = https://static-cdn.jtvnw.net/jtv_user_pictures/463d3058-d3aa-4abd-af1d-6a28fccc1dd7-profile_image-300x300.png

---

🗑 Example: Deleting a Popup (modules/popup/popup.js module)

Action: wsAction = stream-popup-delete
Parameters:

Parameter	Description
wsParam1	Reference of the popup to delete (optional, deletes all if not provided)

Example usage:

wsAction = stream-popup-delete
wsParam1 = subAlert123

---

🚀 Installation

1. Clone the repository:
2. Edit overlay.html to include the modules you want.
3. Add the overlay.html file to OBS as a Browser Source.
4. Configure your Streamer.bot WebSocket output to send events to the overlay.

---

🔌 Requirements

• Streamer.bot installed and configured
• WebSocket enabled in Streamer.bot
• OBS Studio (or compatible browser source streaming software)

---