Multi-Platform Live Chat Overlay

A retro pixel art illustration of a glowing scroll with Twitch, YouTube, and TikTok logos in neon cyan, red, and purple glows.

Project Overview

In the modern streaming landscape, content creators frequently broadcast to multiple platforms simultaneously (e.g., Twitch, YouTube, and TikTok LIVE) to maximize reach. However, managing and displaying a unified chat feed is a persistent challenge. Standard chat widgets are often bloated, resource-heavy, and difficult to custom-style.

This project delivers a high-performance, lightweight, and visually striking solution: a retro pixel-art scroll chat client and OBS overlay. By combining native WebSockets with local API endpoints and a custom containerized relay server, it aggregates live chat events from Streamer.bot (handling Twitch and YouTube) and TikTok Live into a single, unified, hardware-accelerated interface.

With advanced responsive typography, direct OBS transparent-mode support, dynamic backend routing, and extensive seasonal Easter eggs, the client offers broadcasters a premium, low-overhead overlay that enriches viewer engagement.

Technical Pipeline & Architecture

The application is split into two primary components to minimize resource usage on the broadcaster’s streaming machine: a lightweight static frontend and a stateless, headless containerized relay server.

graph TD
    subgraph Broadcast Machine
        SB[Streamer.bot Local App]
        OBS[OBS Studio / Browser Client]
        FE[Static Frontend - Cloudflare Pages]
    end

    subgraph Cloud Infrastructure
        TR[TikTok Relay Server - Node.js Container]
        CF[Cloudflare Pages Functions /env]
    end

    subgraph Platform APIs
        TW[Twitch Chat Server]
        YT[YouTube Live Chat API]
        TT[TikTok LIVE Servers]
    end

    TW -->|WebSocket/IRC| SB
    YT -->|Polling/API| SB
    SB -->|Local WS ws://127.0.0.1:8080| FE
    
    TT -->|Webcast Protobuf| TR
    TR -->|Secure WS wss://| FE
    
    FE -->|Render Overlay| OBS
    CF -->|Route Environment| FE

1. Dual-WebSocket Client Orchestration

The frontend static client (script.js) establishes parallel WebSocket channels to pull messages instantly as they occur:

Local Streamer.bot Connection: Uses the official @streamerbot/client module to hook directly into the local Streamer.bot instance via ws://127.0.0.1:8080. It listens for native Twitch.ChatMessage and YouTube.Message events.
Remote TikTok Relay Connection: Establishes a WebSocket connection to the custom TikTok relay server. For security and architectural flexibility, the frontend fetches its routing endpoint dynamically from a Cloudflare Pages Function (/env) on startup. This allows swapping local development relays (ws://127.0.0.1:8081) and production secure relays (wss://) without hardcoding URLs.

2. State-Aware TikTok Live Relay Backend (`server.js`)

TikTok does not provide a standard open chat API for real-time applications. To bridge this, a custom Node.js backend relay server connects to TikTok’s internal chat servers using tiktok-live-connector (an unofficial client leveraging TikTok’s Webcast protocol):

Pre-Flight Connection Handshake: The relay uses tiktokConnection.fetchIsLive() to verify if the stream is active before invoking a connect event. This prevents the library from hanging or throwing unhandled UserOfflineError exceptions due to TikTok’s unstable offline response flags.
Resource-Aware Connection Lifecycle: To prevent rate-limiting from TikTok’s aggressive bot-detection scripts, the relay tracks connected frontend clients. When the number of active clients drops to zero (e.g., the streamer closes OBS), a 30-second graceful teardown timer is scheduled. If no clients reconnect in that window, the relay automatically disconnects from TikTok’s servers, saving cloud compute and preserving the channel’s API reputation.
Auto-Reconnections: Implements a stateful 60-second retry loop to automatically restore the TikTok chat stream if physical internet connectivity fluctuates.

Retro CSS Styling & Dynamic SVG Overlay

To achieve an authentic 8-bit gaming aesthetic, the client avoids bulky image textures, relying entirely on clean vector geometry and mathematical CSS calculations:

1. Grid-Aligned Inline SVG Backdrop

The scroll background is an inline <svg> element configured with a native coordinate space of $600 \times 800$ (viewBox="0 0 600 800").

Blocky Pixel Aesthetics: All SVG elements (rect, polygon, line) are mapped strictly to coordinate multiples of 4. This blocky visual alignment perfectly emulates hand-drawn 2D game tiles.
Dynamic Styling Variables: Utilizes a highly flexible CSS variable palette (--scroll-paper-light, --scroll-paper-dark, --scroll-outline) embedded directly in the SVG vector elements, allowing instant global styling changes.

2. Absolute Text Area Masking & Scaling

To ensure the scrollable chat text is perfectly confined within the unfurled region of the parchment paper, the frontend calculates precise absolute positioning coordinates based on the SVG’s viewBox:

Parchment Boundaries: The chat text box (.chat-text-area) is mapped using relative percentages matching the parchment’s active area: $$\text{top}: \frac{44}{800} \approx 5.5% \quad \text{left}: \frac{100}{600} \approx 16.6% \quad \text{width}: \frac{400}{600} \approx 66.6% \quad \text{height}: \frac{712}{800} \approx 89%$$
Fluid Typography: Leverages modern CSS clamps to guarantee that text remains beautifully readable on massive monitors and small phone screens alike:
```
font-size: clamp(12px, max(1.8vw, 2vh), 24px);
```

3. High-Performance OBS Transparent Overlay Mode

When broadcasters load the widget in OBS Studio, they can append the ?transparent=true URL parameter. This triggers a structural UI mutation:

Visual Graphic Strip: The client injects a transparent-mode class onto the body, entirely hiding the SVG background and borders (display: none).
Container Realignment: Modifies the layout of the chat text area from standard relative scrolling to a bottom-anchored vertical flexbox (justify-content: flex-end), forcing new messages to pop up from the bottom of the screen.
Contrast Enhancing Shadows: To keep text legible against high-motion, bright gaming graphics behind the overlay, the client applies a robust, heavy four-directional text-outline shadow:
```
text-shadow: 2px 2px 0 #000, -2px -2px 0 #000, 2px -2px 0 #000, -2px 2px 0 #000;
```

Interactive Features & Easter Eggs Engine

A live stream thrives on micro-interactions. The chat client includes custom JavaScript features that feel incredibly responsive and dynamic:

1. Deterministic Username Color Hashing

To assign distinct, stable colors to chatters without loading a database, the frontend implements a custom deterministic string-hashing algorithm:

The Hashing Loop: Iterates over the characters in a username, shifting bits to generate a unique numeric hash code.
Visually Constrained HSL Mapping: Maps this hash to a Hue value ($0\text{—}359$) and extracts a lightness range mathematically restricted between $40%$ and $55%$:
```
const hue = hash % 360;
const lightness = 40 + (hash % 16);
const color = `hsl(${hue}, 80%, ${lightness}%)`;
```
This ensures that regardless of the username, the resulting color is vibrant, highly saturated, and passes strict accessibility contrast ratios against both light parchment paper and dark transparent screens.

2. Calendar-Driven Holiday Overlay System

A self-executing calendar framework evaluates the host machine’s system date at execution time and sets global holiday flags. If a match is found, all incoming chat messages are dynamically processed:

Special Holiday Decorators:
- Valentine’s Day: Wraps messages in glowing heart emojis: ❤️ [Message] ❤️.
- Halloween: Injects eerie pumpkin and ghost tags: 🎃 [Message] 👻.
- Christmas: Injects festive trees and gifts: 🎄 [Message] 🎁.
- St. Patrick’s Day: Surrounds comments with four-leaf clovers: 🍀 [Message] 🍀.

3. April Fools’ Rotational Transform

On April 1st, a custom text manipulator splits chat messages into discrete tokens by matching whitespace boundaries.

Wrap & Rotate: It reverses the word ordering, wrapping each individual word in an inline-block container with a $180^\circ$ rotational CSS transformation:
```
return `<span style="display:inline-block; transform:rotate(180deg);">${part}</span>`;
```
By rotating individual word segments rather than the entire message container, the system successfully flips the text upside down while allowing the browser’s native text-wrapping engines to flow lines normally.

4. Friday the 13th Spooky Ghost Engine

If the broadcaster streams on Friday the 13th, the client triggers a background ghost service.

Poltergeist Simulation: Automatically schedules random spooky accounts (e.g. 👁️ WatcherX, 🕸️ W3bsT3r) that write chilling, italicized messages directly to the chat log (e.g., “I’m in your walls.”, “The static is getting louder.”).
Deterministic Jitter: Utilizes a randomized interval scheduler (triggering every $45\text{—}150$ seconds) to emulate authentic viewer participation, confusing and entertaining the broadcaster.

Production Deployment & DevOps

To make the system highly reliable and easy to deploy, the architecture leverages modern DevOps containers and serverless platforms:

Cloudflare Pages Integration: The frontend is packaged as a serverless static asset bundle. Using wrangler, deployments are managed instantly through simple terminal hooks:
```
npm run pages:deploy
```
Multi-Arch Dockerization: The TikTok Live relay is fully containerized. A multi-stage Dockerfile handles building the native C++ libraries required by tiktok-live-connector on different CPU architectures.
GitHub Actions CI/CD Pipeline: The repository includes a GitHub workflow that runs container builds on a matrix configuration, automatically packaging and pushing both amd64 and arm64 container images to the GitHub Container Registry (ghcr.io) upon committing to the main branch.
Self-Healing Network Protocol: Both the Streamer.bot and TikTok WebSocket loops feature aggressive keepalive rules, sending keepalive ping frames every 30 seconds to prevent network proxies from dropping idle channels.

Key Project Accomplishments

Stream Aggregation: Developed a zero-latency real-time chat overlay uniting Twitch, YouTube, and TikTok chat streams into a single client.
Containerized Relay: Built a resilient, headless Node.js TikTok LIVE proxy with memory-safe teardowns and automatic client-based throttling.
Dynamic Environment Injection: Secured backend connection links using serverless Cloudflare Page Functions to serve environment configurations on request.
Aesthetic Engineering: Created a fully responsive, retro-themed vector interface using pure inline SVG and mathematical CSS viewport formulas.
Micro-Interaction Engine: Built an engaging client-side holiday parser and April Fools’ upside-down text wrap engine utilizing pure CSS transforms.