remote-streamerbot-chat

A lightweight live chat overlay that connects to a remote Streamer.bot instance over WebSocket and displays Twitch/YouTube chat messages in a clean dark-themed browser window.

---

How It Works

Streamer.bot (Windows PC at 10.0.0.195)
        │
        │  WebSocket  ws://10.0.0.195:8080
        │
Linux machine
  └── ./chat  (bash script)
        └── helium-browser  (Chromium-based)
              └── chat.html  (UI + streamerbot-client.js)

1. The chat script launches an isolated Helium browser window pointed at chat.html via a file:// URL.
2. chat.html loads the bundled streamerbot-client.js library and opens a WebSocket connection to Streamer.bot.
3. Incoming Twitch.ChatMessage and YouTube.ChatMessage events are parsed and rendered in real time.

No HTTP server is involved — the page loads directly from disk.

---

Requirements

Dependency	Purpose
helium-browser	Chromium-based browser used to display the overlay
bash	Runs the launcher script

Python, curl, and a web server are not required.

---

File Structure

remote-streamerbot-chat/
├── chat                   # Bash launcher script
├── chat.html              # Chat overlay UI
├── streamerbot-client.js  # Bundled @streamerbot/client library (local copy)
├── install.sh             # Installs the desktop entry for your app launcher
└── README.md              # This file

---

Setup

1. Streamer.bot (Windows machine)

1. Open Streamer.bot.
2. Go to Servers/Clients → WebSocket Server.
3. Enable the WebSocket server.
4. Set the bind address to your LAN IP (e.g. 10.0.0.195) — not 127.0.0.1, otherwise remote connections will be refused.
5. Set the port to 8080 (or update chat.html to match your chosen port).
6. Make sure your Windows firewall allows inbound connections on that port.

2. Linux machine

Clone the repo:

git clone https://github.com/YOUR_USERNAME/remote-streamerbot-chat.git
cd remote-streamerbot-chat

Make the script executable:

chmod +x chat

Edit chat.html and update the host/port to match your Streamer.bot machine:

const client = new StreamerbotClient({
    host: "10.0.0.195",  // ← your Streamer.bot machine's LAN IP
    port: 8080,
    password: "",         // ← fill in if you set a password in Streamer.bot
    autoReconnect: true,
    ...
});

---

Usage

./chat

Or from anywhere:

~/github/remote-streamerbot-chat/chat

The overlay opens as a standalone app window (no browser chrome/address bar) with:

• A dark header showing "Live Chat" and a connection status badge
  • 🟠 Orange = Connecting…
  • 🟢 Green = Connected
  • 🔴 Red = Disconnected
• Each chat message shows:
  • 🟣 Twitch or 🔴 YouTube platform icon
  • User badges (broadcaster, subscriber, etc.)
  • Username in the user's chat colour
  • Message text
  • Timestamp

The window blocks the terminal until it is closed, then exits cleanly.

---

How the Script Works

#!/usr/bin/env bash

CHAT_FILE="$HOME/github/remote-streamerbot-chat/chat.html"
PROFILE_DIR="$HOME/.config/streamerbot-chat-profile"

• CHAT_FILE — absolute path to the HTML file, hardcoded to $HOME.
• PROFILE_DIR — a persistent isolated Chromium profile stored in ~/.config. Keeping it persistent avoids a slow first-run initialisation on every launch.

rm -f "$PROFILE_DIR/SingletonLock" "$PROFILE_DIR/SingletonCookie" "$PROFILE_DIR/SingletonSocket"

Chromium writes a SingletonLock file to prevent two instances sharing a profile. If the browser crashes or is killed, the lock is never cleaned up, causing subsequent launches to hand the URL off to a non-existent process (resulting in a grey window). Only the lock files are removed — the rest of the profile is preserved.

helium-browser \
  --user-data-dir="$PROFILE_DIR" \
  --disable-gpu \
  --ozone-platform=x11 \
  --no-first-run \
  --no-default-browser-check \
  --disable-extensions \
  --allow-file-access-from-files \
  --disable-web-security \
  --class="StreamerBotChat" \
  "file://${CHAT_FILE}"

Flag	Reason
--user-data-dir	Forces a new isolated browser process; prevents URL handoff to an existing Helium session
--disable-gpu	Works around a vaInitialize failed GPU error that causes grey windows on some systems
--ozone-platform=x11	Explicitly selects X11 rendering on X11 sessions
--no-first-run	Skips the new-profile welcome screen
--no-default-browser-check	Suppresses the "make Helium your default browser" prompt
--disable-extensions	Prevents extensions (e.g. uBlock) from initialising, speeding up startup
--allow-file-access-from-files	Allows file:// pages to load local scripts (e.g. streamerbot-client.js)
--disable-web-security	Allows file:// pages to open WebSocket connections to remote hosts
--class=StreamerBotChat	Sets the X11 window class, useful for window manager rules

The script runs Helium in the foreground (no &), so it naturally blocks until the window is closed — no need to track PIDs.

---

Updating the Streamer.bot Client Library

streamerbot-client.js is a local copy of the @streamerbot/client npm package. It is bundled locally so the overlay works without internet access.

To update it to the latest version:

curl -sL "https://cdn.jsdelivr.net/npm/@streamerbot/client/dist/streamerbot-client.js" \
  -o ~/github/remote-streamerbot-chat/streamerbot-client.js

---

Changing the Streamer.bot Host or Port

Edit chat.html and update the StreamerbotClient constructor:

const client = new StreamerbotClient({
    host: "10.0.0.195",  // LAN IP of the machine running Streamer.bot
    port: 8080,          // WebSocket server port set in Streamer.bot
    password: "",        // Leave empty if no password is set
    autoReconnect: true,
    ...
});

---

Installing as a Desktop Application

Run the included install script to register the overlay as an application in your launcher (rofi, dmenu, GNOME, KDE, etc.):

./install.sh

This will:

• Make the chat script executable
• Write a .desktop entry to ~/.local/share/applications/streamerbot-chat.desktop using the correct absolute path automatically
• Refresh the desktop database so the entry appears in your launcher immediately

You can then launch StreamerBot Chat from your application launcher like any other app, no terminal needed.

---

Troubleshooting

Grey/blank window on launch The SingletonLock cleanup in the script handles this automatically. If it still happens, delete the entire profile and let it rebuild:

rm -rf ~/.config/streamerbot-chat-profile

Status stays "Connecting…" forever

• Confirm Streamer.bot is running on the Windows machine.
• Confirm the WebSocket server in Streamer.bot is enabled and bound to the LAN IP (not 127.0.0.1).
• Test connectivity from the Linux machine:

  nc -zv 10.0.0.195 8080

• Check that the Windows firewall allows inbound TCP on port 8080.

Messages appear but are blank The payload structure from Streamer.bot changed. Open chat.html, add onData: (raw) => console.log(raw) to the StreamerbotClient constructor, relaunch, and inspect the browser console (right-click → Inspect) to see the raw payload shape. Then update handleChatMessage accordingly.

"Opening in existing browser session" and nothing loads An existing Helium window is running without --user-data-dir. The SingletonLock cleanup and --user-data-dir flag together prevent this. If it recurs, kill all Helium processes:

pkill helium

Then relaunch with ./chat.