VLX_Robot - OBS Alert Overlay System

VLX_Robot is a self-hosted Go backend server for managing OBS alerts and overlays, featuring real-time integration for Twitch (EventSub) and YouTube (Polling). It is built with production-grade stability features including structured logging, rate limiting, and automated testing. NOTE: The idea, the logics, the architecture, reviews, validation are made in VirusLox, but the code is 95% generated by Gemini 2.5

Project Structure

VLX_Robot/
├── go.mod                # Go module definition file
├── go.sum                # Dependency checksums
├── main.go               # Application entry point. Starts the server.
├── config.yml            # Configuration (DB string, Twitch/YT API keys)
|
├── internal/             # Private Go project code
│   ├── config/           # Logic for loading config.yml
│   │   └── config.go
│   ├── database/         # Logic for PostgreSQL connection
│   │   └── postgres.go   # (Saves state and tokens)
│   ├── server/           # HTTP server logic
│   │   ├── server.go     # (Sets up public routes: /ws, /static/*, /webhooks)
│   │   └── test_server.go# (Private local server for manual alert testing)
│   ├── websocket/        # WebSocket Hub logic
│   │   ├── hub.go        # (Manages connections/broadcasts to overlays)
│   │   └── client.go
│   ├── twitch/           # Logic for Twitch Integration
│   │   ├── eventsub.go   # (Handles Webhooks: Follows, Subs, Raids)
│   │   └── chat.go       # (Handles IRC: Chat commands !cmd, Cooldowns, Permissions)
│   └── youtube/          # Logic for YouTube Integration
│       └── youtube.go    # (Handles Polling: SuperChats, Sticker, Commands)
│
└── static/               # <-- THIS IS YOUR FRONTEND FOLDER
    ├── overlay.css       # Shared styles for all overlays
    ├── alerts_overlay.html # Visual overlay for Alerts (Follows, Subs, SuperChats)
    ├── alerts_overlay.js   # Logic for visual alerts
    ├── chat_overlay.html   # Hidden overlay for playing Audio/Video commands
    ├── chat_overlay.js     # Logic for media playback
    ├── emotes_overlay.html # Overlay for the floating "Emote Wall"
    ├── emotes_overlay.js   # Logic for emote physics/animation
    └── chat/             # Audio/Video assets storage
        ├── everyone/     # Commands available to everyone
        ├── subscribers/  # Commands for Subs only
        └── vips/         # Commands for VIPs/Mods

Features

The application operates as a standalone HTTP and WebSocket server. It ingests events from streaming platforms—via EventSub Webhooks for Twitch and API Polling for YouTube—and broadcasts normalized payloads to connected frontend clients (OBS Browser Sources). State persistence and token lifecycle management are handled via PostgreSQL.

Core Reliability

• Structured Logging: Uses Zap to output high-performance JSON logs, making debugging and monitoring easy in production environments.
• Smart Rate Limiting: Implements Token Bucket algorithms to strictly adhere to Twitch and YouTube API quotas, preventing bans from spam or polling loops.
• Volume Normalization: Centralized volume control for all overlays via configuration.
• Automated Testing: Comprehensive unit tests for critical logic (Chat parsing, YouTube polling, WebSocket broadcasting).

Integrations

• Twitch: EventSub Webhooks (Follows, Subs, Raids, Cheers) and an IRC Chat Bot with RBAC (Role-Based Access Control) commands.
• YouTube Live: Monitors Super Chats, Super Stickers, and Member milestones via optimized polling.
• Overlay System: Low-latency WebSocket connection rendering alerts, playing media, and animating an emote wall.

Overlay System

The frontend utilizes a low-latency WebSocket connection to render assets dynamically:

• Alerts Overlay: Displays visual notifications for monetization and engagement events.
• Chat Media Overlay: dedicated layer for playing audio/video assets triggered by chat commands.
• Emote Wall Overlay: Renders physics-based floating emotes based on real-time chat activity.

---

Installation & Deployment

0. Prerequisites:

   • Go 1.21+
   • PostgreSQL running (configure in config.yml)

1. Clone the Repository:

   mkdir -p ~/go/src/ && cd ~/go/src/
   git clone https://github.com/viruslox/VLX_Robot
   cd VLX_Robot

2. Install Dependencies:

   go mod init
   go mod tidy

3. Optional - Run Tests: Run the test suite with verbose output to verify system stability and internal logic.

   go test -v ./...

   Verifies logic in Twitch Chat, YouTube Polling, and WebSockets.

4. Build:

   go build

5. ** Deploy to /opt ** I hate "sudo", but let's make it easy:

sudo mkdir -p /opt/VLX_Robot

# Ensure your user owns the directory
sudo chown -R $USER:$USER /opt/VLX_Robot
cp ~/go/src/VLX_Robot/VLX_Robot /opt/VLX_Robot

# Copy config the example, but remember to edit it
cp ~/go/src/VLX_Robot/config.yml /opt/VLX_Robot/

Configuration

Edit config.yml to set up your environment.

Server settings (Overlay)

server:
  base_url: "[https://your-domain.com](https://your-domain.com)" # Public HTTPS URL (Required for Webhooks)
  port: "8000"       # Public traffic port
  test_port: "8001"  # Private testing port
  overlay_volume: 50 # Master volume for audio/video alerts (0-100%)

Twitch

Ensure you have generated your User Access Tokens and API Keys. Requires a User Access Token with specific scopes (channel:read:subscriptions, bits:read, etc.) for full functionality. It's ecommended to use 2 different accounts, or at least 2 different tokens Easier way to get tokens is use twitch for developers in combination with https://twitchtokengenerator.com/

twitch:
  client_id: "..."
  client_secret: "..."
  webhook_secret: "..."
  chat:
    bot_username: "BotName"
    bot_token: "oauth:..."
    command_cooldown: 15 # Global command cooldown in seconds

YouTube

youtube:
  api_key: "..."
  channel_id: "UC..."
  polling_interval: 5 # Seconds (Min: 5)

---

OBS Studio Integration

Add Browser Sources to your OBS scenes (1920x1080):

1. Alerts: http://localhost:8000/static/alerts_overlay.html
2. Media Commands: http://localhost:8000/static/chat_overlay.html (Enable "Control audio via OBS" if needed)
3. Emote Wall: http://localhost:8000/static/emotes_overlay.html

Adding Custom Commands

Place .mp3, .wav, .mp4, or .webm files in static/chat/<permission_level>/. The filename becomes the command (e.g., hello.mp3 -> !hello). The system automatically scans these folders on startup.

• everyone/: All users.
• subscribers/: Subs and Founders.
• vips/: VIPs and Moderators.

Local Testing

You can trigger manual alerts without waiting for real events using the private test port (default 8001):

# Test Twitch Follow
curl -X POST -d '{"type":"twitch_follow", "user_name":"TestUser"}' http://localhost:8001/test/alert

# Test YouTube Super Chat
curl -X POST -d '{"type":"youtube_super_chat", "user_name":"Donor", "amount_string":"$10.00"}' http://localhost:8001/test/alert