VLX ChatBridge

VLX ChatBridge is a unified, self-hosted backend server designed for Linux environments that seamlessly integrates streaming platform events (Twitch, YouTube) with a bi-directional Discord audio gateway and overlay management system.

This project is a merge of VLX_ChatFlow (OBS Alert Overlay System) and VLX_AudioBridge (Discord-to-SRT Audio Gateway).

NOTE: The idea, logic, architecture, reviews, and validation were created by VirusLox, with code generation assisted by AI.

Unified Architecture

ChatBridge operates as a single binary with six primary, independently configurable, hot-swappable modules sharing a unified core:

1. ChatFlow Module (Event Management & Overlays):
   • Ingests events via Twitch EventSub Webhooks and YouTube API Polling.
   • Manages visual alerts, media commands via chat, and emote wall physics.
   • Depends on Twitch, YouTube, and Overlay configurations.
2. AudioBridge Module (Audio Routing & Discord):
   • Connects to Discord voice channels.
   • Captures incoming Discord audio, mixes it with internal ChatFlow audio, and pipes the resulting PCM stream.
3. Server Module (HTTP/WebSocket Webserver):
   • Serves low-latency WebSocket connections to OBS Browser Sources.
   • Hosts the frontend HTML/JS overlays.
4. Streaming Module (SRT Egress):
   • Manages the egress of mixed audio to an SRT destination via FFmpeg.
5. AudioSource Module (Audio Feed Ingest):
   • Ingests external audio feeds via FFmpeg and pipes them directly into the internal audio mixer.
6. Connector Module (IPC Output):
   • High-performance local Inter-Process Communication (IPC) via Unix Domain Sockets for streaming raw PCM audio and JSON control events to VLX_VisionBridge.

Hot-Swappable Modules

All six modules can be enabled or disabled on-the-fly via configuration (modules block), allowing the server to act solely as an alert system, an audio bridge, an SRT streamer, an IPC connector, or a combination of them simultaneously.

---

Features

ChatFlow Features

• Twitch Integration: EventSub Webhooks (Follows, Subs, Raids) and IRC Bot with Role-Based Access Control (!commands).
• YouTube Integration: Live polling for Super Chats, Stickers, and Memberships.
• Overlays: Alerts overlay, Chat Media overlay, Emote Wall, and Scenes overlay.
• Smart Rate Limiting & Persistence: Token buckets for API quotas and SQLite for state/token management.
• Dynamic Command Generation: File-based chat commands generation by dropping files in corresponding permission folders (everyone, subscribers, vips). Use the owner_ prefix to enforce strict broadcaster-only access control.
• Dynamic File-Based Routing (ZMQ & Webhooks): As part of "The Holy Trinity" architecture, ChatBridge acts as the central nervous system. It receives chat commands and routes them instantly via IPC/ZMQ to VLX_VisionBridge (for zero-latency video mixing) and via HTTP Webhooks to VLX_FrameFlow (for IRL backpack control).

Real-Time Telemetry (GPS)

ChatBridge natively receives GPS and Speed data directly from the FrameFlow backpack. It acts as a real-time telemetry receiver, ingesting JSON payload data and immediately broadcasting it to the frontend.

• Zero Latency: The overlay runs at 60fps via WebSockets with zero latency, entirely eliminating disk I/O, database token checks, and HTTP polling.
• Setup Instructions: To set this up in VisionBridge, add a Chromium web layer pointing directly to http://127.0.0.1:<PORT>/gps_overlay.html.

AudioBridge Features

• Discord Ingress/Egress: Joins voice channels, captures Opus packets (libdave/godave support), and injects internal audio.
• Soft-Clipping Mixer: Real-time PCM mixing with volume normalization and clipping protection.
• SRT Streaming: High-quality, low-latency audio transmission via FFmpeg.
• Direct Audio Injection: Seamlessly routes .mp3/.wav media played via chat commands directly to Discord and the SRT stream.

---

Project Structure

VLX_ChatBridge/
├── cmd/
│   └── chatbridge/
│       └── main.go              # Entry point. Initializes core and starts modules.
├── config.yml                   # Unified configuration file
├── internal/
│   ├── core/                    # Shared components (config, logger, db, audio, module manager)
│   └── modules/
│       ├── chatflow/            # Logic for Twitch, YouTube, WebSockets, Overlays
│       ├── audiobridge/         # Logic for Discord bot
│       ├── server/              # Logic for HTTP webserver and reverse proxy mapping
│       ├── streaming/           # Logic for SRT output mixing via FFmpeg
│       ├── audiosource/         # Logic for external audio ingest
│       └── connector/           # Logic for local IPC with VisionBridge
├── static/                      # Frontend folder (HTML/JS/CSS/Assets for OBS)
│   └── chat/                    # Audio/Video assets storage for commands
└── scripts/                     # Systemd service files

---

System Requirements

• OS: Linux (Tested on Debian)
• Dependencies: Go 1.24+, SQLite, FFmpeg, libopus-dev, libopusfile-dev, pkg-config, cmake, clang, build-essential
• Note: PortAudio and Chromium dependencies previously required by AudioBridge have been removed in favor of direct internal audio decoding.

Installation & Build

1. Install libdave (Required for Discord Voice E2EE)

mkdir -p ~/Projects/ ; cd ~/Projects/
git clone https://github.com/disgoorg/godave.git
cd godave/scripts ; export CC=/usr/bin/clang CXX=/usr/bin/clang
export PKG_CONFIG_PATH="$HOME/.local/lib/pkgconfig:$PKG_CONFIG_PATH"
./libdave_install.sh v1.1.0

2. Clone and Build

git clone https://github.com/viruslox/VLX_ChatBridge
cd VLX_ChatBridge
go mod init
go mod tidy
./build.sh

3. Deploy

sudo ./VLX_ChatBridge install

---

Configuration

Edit /opt/VLX_ChatBridge/config.yml to configure the system. You can use environment variables (e.g., ${ENV_VAR}).

modules:
  chatflow_enabled: yes
  audiobridge_enabled: yes
  server_enabled: yes
  streaming_enabled: yes
  audio_source_enabled: no
  connector_enabled: no

server:
  base_url: "https://your.ngrok.io"
  path_prefix: "/asortofkey"
  websocket_path: "/websocket"
  port: "8000"
  test_port: "8001"
  overlay_volume: 70

database:
  path: "/opt/VLX_ChatBridge/var/chatbridge.db"

twitch:
  # ... Twitch App IDs, Secrets, Tokens ...

youtube:
  # ... YouTube API Key, Channel ID ...

overlay:
  enable: yes
  emotes:
    html: yes
  alerts:
    html: yes
    discord: yes
    streaming: no
    volume: 75
  chat:
    html: yes
    discord: yes
    streaming: yes
    volume: 75
  scenes:
    enable: yes
    html: yes
    discord: yes
    streaming: yes
    volume: 75

discord:
  token: "YOUR_DISCORD_BOT_TOKEN"
  prefix: "vlx."
  streaming: yes

streaming:
  enable: yes
  destination_url: "srt://127.0.0.1:8890?streamid=publish:vlx_audio&mode=caller&pkt_size=1316"
  bitrate: "128k"
  volume: 75

audio_source:
  enable: no
  discord: yes
  streaming: no
  volume: 80
  url: "srt://127.0.0.1:2020?..."

connector:
  ipc_control_out: yes
  control_socket: "/tmp/vlx_control.sock"

Reverse Proxy Configuration

The server supports a path_prefix configuration token that a reverse proxy can strip to enhance security. Below is an example of an Apache reverse proxy configuration that properly routes requests, including upgrading WebSocket connections.

RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule "^/<path_prefix>/websocket$" "ws://localhost:8000/websocket" [P,L]
ProxyPass /<path_prefix>/ http://localhost:8000/
ProxyPassReverse /<path_prefix>/ http://localhost:8000/

Security Considerations

The WebSocket upgrade path performs strict, exact matching against the configured websocket_path in chatbridge.settings.template to prevent unauthorized WebSocket connections and aligns with Go 1.24+ http.ServeMux standards.

---

Twitch Webhook Configuration

Twitch EventSub requires a publicly accessible HTTPS endpoint to deliver events. base_url: Must be your root public domain (e.g., https://yourdomain.com). Do not include any path prefixes or obfuscation tokens here, as Twitch will append /webhooks/twitch automatically. Ingestion: ChatBridge listens for notifications at the /webhooks/twitch path. Ensure your reverse proxy (e.g., Apache/Nginx) is configured to forward requests from https://yourdomain.com/webhooks/twitch to the internal port defined in server.port. Security: Ensure twitch.webhook_secret matches the secret provided in your Twitch Developer Console, as this is used to validate the HMAC signature of every incoming event.

Usage

Dynamic File-Based Routing

ChatBridge parses text files dropped into static/chat/ to generate commands on the fly. By adding special blocks to these files, you can trigger routing to VisionBridge or FrameFlow.

1. ZMQ Control Example (VisionBridge) Create a file at static/chat/owner_cam1.txt to trigger a scene change in VLX_VisionBridge via local IPC. The owner_ prefix ensures only the broadcaster can run !cam1.

[ZMQ_CONTROL]
Target=stream
Enabled=true

2. Webhook Control Example (FrameFlow) Create a file at static/chat/owner_bitrate.txt to send an HTTP POST request to VLX_FrameFlow running on the local backpack.

[WEBHOOK]
Method=POST
URL=http://127.0.0.1:8080/api/frameflow/bitrate
Body={"action": "increase"}

Stealth Mode (AutoDelete)

Both [ZMQ_CONTROL] and [WEBHOOK] files support an AutoDelete=true flag. This feature allows you to silently execute commands without cluttering the public chat. When enabled, it leverages dynamically refreshed DB tokens and the Twitch Helix API to instantly delete the invoking chat message.

Example with Stealth Mode:

[ZMQ_CONTROL]
Target=stream
Enabled=true
AutoDelete=true

Running Manually

/opt/VLX_ChatBridge/VLX_ChatBridge -config /opt/VLX_ChatBridge/config.yml

Running as a Service (Systemd)

mkdir -p ~/.config/systemd/user/
cp scripts/vlx_chatbridge.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable vlx_chatbridge.service
systemctl --user start vlx_chatbridge.service

OBS Integration

Add Browser Sources in OBS pointing to the local server (e.g., http://localhost:8000/static/alerts_overlay.html).

Discord Commands

• vlx.join : Bot joins your voice channel and starts the SRT stream.
• vlx.leave: Bot stops streaming and disconnects.

Twitch OAuth2 Credentials and Token Configuration

VLX_ChatBridge utilizes the modern Twitch API (Helix) and IRC interfaces. To ensure security and stability, the system uses an automatic token renewal mechanism backed by a local database. This means you will only need to generate your tokens manually once, and the system will keep them valid indefinitely.

You will need two sets of credentials: the Application credentials and the User Tokens (one for your main broadcaster channel and one for the Bot).

Step 1: Create the Twitch Application (Client ID & Secret)

These credentials identify your software on Twitch's servers.

1. Go to the Twitch Developer Console and log in.
2. Click on "Register Your Application".
3. Choose a name for your app (e.g., VLX_ChatBridge_App).
4. In OAuth Redirect URLs, enter: http://localhost
5. In Category, select Chat Bot.
6. Click "Create". Once created, click "Manage" to get your Client ID and generate a Client Secret.
7. Insert these two values into the vlx_chatbridge.conf file under the twitch section.

Step 2: Generate Tokens (Access & Refresh)

ChatBridge requires explicit authorization to act as both a Bot and the channel owner (e.g., to delete messages for the Auto-Delete feature).

The fastest way to generate the initial tokens is by using a secure site like Twitch Token Generator:

1. Go to the site and scroll down to the "Custom Scope Token" section.
2. You will need to generate TWO distinct tokens. Log in to Twitch first with your Bot account, and then repeat the process with your Broadcaster account (your main channel).

Required Permissions (Scopes)

Select the following boxes with extreme care. It is highly recommended to include all these scopes to ensure compatibility with moderation features and future expansions of the bridge:

For the BOT account (e.g., VirusRoboLox): Check these boxes, then click "Generate Token" while logged in with the bot profile:

• chat:read (Required to read commands)
• chat:edit (Required to reply in chat)
• channel:moderate (Required for basic moderation actions)
• whispers:read and whispers:edit (If the bot uses whispers)

For the BROADCASTER account (Your main channel): Return to the site, check these boxes, and log in with your main account:

• moderator:manage:chat_messages (REQUIRED for the Auto-Delete command feature to work)
• channel:read:redemptions (To intercept Channel Points)
• channel:manage:broadcast (To update stream info via commands)
• channel:read:subscriptions (To intercept subs via API)
• moderation:read (To read chat state)
• chat:read and chat:edit (For security fallback)

Note: Once generated, the site will provide two long strings for each account: an ACCESS TOKEN and a REFRESH TOKEN. Copy them and keep them safe.

Step 3: Database Insertion (Automatic Renewal)

To enable automatic renewal, you must insert these initial tokens into the ChatBridge SQLite database (chatbridge.db or your configured database). Open the database (via terminal with sqlite3 or using a GUI tool like DB Browser for SQLite) and execute this query using your data:

-- Insert Broadcaster (Owner) Token
INSERT OR REPLACE INTO twitch_credentials (user_id, access_token, refresh_token, expires_at) 
VALUES ('BROADCASTER_NUMERIC_ID', 'BROADCASTER_ACCESS_TOKEN', 'BROADCASTER_REFRESH_TOKEN', '2030-01-01 00:00:00');

-- Insert Bot Token
INSERT OR REPLACE INTO twitch_credentials (user_id, access_token, refresh_token, expires_at) 
VALUES ('BOT_NUMERIC_ID', 'BOT_ACCESS_TOKEN', 'BOT_REFRESH_TOKEN', '2030-01-01 00:00:00');

(Tip: You can find Twitch account numeric IDs using free sites like Twitch Insights or StreamWeasels).

Once inserted, make sure your vlx_chatbridge.conf file has the bot_id: "BOT_NUMERIC_ID" entry configured. From this moment on, ChatBridge will manage the tokens completely autonomously, silently renewing them before they expire. You will never have to repeat this procedure!

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.