Network Architecture

Service Map

┌──────────────────────────────────────────────────────┐
│  hobo.tools (port 3100) — Central Hub                │
│  ├─ /api/auth      — SSO (RS256 JWT)                 │
│  ├─ /api/notifications — Notification CRUD           │
│  ├─ /api/push      — Web Push (VAPID)                │
│  ├─ /api/admin     — Unified admin panel             │
│  ├─ /api/admin/discord — Discord bot config          │
│  ├─ /internal      — Server-to-server API            │
│  └─ Discord bot    — Live alerts, system alerts      │
├──────────────────────────────────────────────────────┤
│  HoboStreamer.com (port 3000) — Streaming Platform   │
│  ├─ /api/streams   — Stream CRUD + go-live           │
│  ├─ /api/chat      — Chat REST API                   │
│  ├─ /api/tts       — TTS voice config                │
│  ├─ /api/controls  — Interactive control profiles    │
│  ├─ /ws/chat       — Real-time chat                  │
│  ├─ /ws/broadcast  — WebRTC signaling                │
│  ├─ /ws/control    — Hardware command relay           │
│  ├─ /whip/:id      — WHIP WebRTC ingestion           │
│  └─ RTMP server    — rtmp://host/live                │
└──────────────────────────────────────────────────────┘

Event Flow: Stream Goes Live

1. Streamer calls POST /api/streams (HoboStreamer)
2. HoboStreamer creates stream record, starts media endpoint
3. HoboStreamer calls POST /internal/events/stream-live (hobo.tools)
4. hobo.tools Discord bot sends embed to #alerts channel (with dedupe)
5. hobo.tools creates STREAM_LIVE notifications for:
   - All followers of the streamer
   - Users opted into "all live" alerts
6. Push notifications fire via Web Push (VAPID)
7. Fallback: HoboStreamer sends direct webhook if hobo.tools unreachable

WebSocket Services

Admin Proxy Architecture

hobo.tools admin panel proxies requests to HoboStreamer:

hobo.tools /api/admin/streamer/*  →  HoboStreamer /api/admin/*
hobo.tools /api/admin/streamer-tts/*  →  HoboStreamer /api/tts/*
hobo.tools /api/admin/streamer-mod/*  →  HoboStreamer /api/mod/*

Protected by X-Internal-Key header for server-to-server calls.

1. AUTHENTICATION

REST Endpoints

API Tokens (hbt_ prefix)

For bots and integrations that need long-lived auth without JWTs:

Use in headers: Authorization: Bearer hbt_xxxxxxxxxxxx

Example: Login and get token

const res = await fetch('https://hobostreamer.com/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'yourname', password: 'yourpass' })
});
const { token, user } = await res.json();
// Use token in all subsequent requests

2. STREAMS & CHANNELS

Stream REST API

Supported Ingestion Protocols

• webrtc — Mediasoup SFU. Lowest latency (~200ms). Use browser or WHIP encoder (OBS 30+).
• rtmp — Traditional RTMP ingest (OBS/ffmpeg). Plays back as HTTP-FLV.
• jsmpeg — MPEG1 over WebSocket. Runs on Raspberry Pi and low-power hardware.

Example: Create a stream and get the WHIP URL

const stream = await fetch('https://hobostreamer.com/api/streams', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Robot cam', protocol: 'webrtc', category: 'Technology' })
}).then(r => r.json());

const endpoint = await fetch(`https://hobostreamer.com/api/streams/${stream.id}/endpoint`, {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

console.log(endpoint.whip_url);  // POST SDP offer here
// Remember to call /heartbeat every 30s to keep stream alive

3. WEBRTC BROADCAST PROTOCOL

WHIP Ingestion (OBS / ffmpeg / custom encoder)

RFC 9725 compliant. POST a raw SDP offer, receive SDP answer.

Broadcast WebSocket — /ws/broadcast

Connect: wss://hobostreamer.com/ws/broadcast?streamId=ID&role=broadcaster|viewer&token=JWT

All messages are JSON. Send: ws.send(JSON.stringify({ type: 'watch' }))

RTMP Ingest (OBS)

Server: rtmp://hobostreamer.com/live
Key:    YOUR_STREAM_KEY   (get from Dashboard → Stream Key)

# Playback proxy for browser
GET /api/streams/rtmp-proxy/:streamId.flv

4. CHAT SYSTEM — CHATBOT GUIDE

Connect to the chat WebSocket to read and send messages. Perfect for building chat bots, overlays, alert systems, and integrations.

Chat WebSocket — /ws/chat

Connect: wss://hobostreamer.com/ws/chat?stream=STREAM_ID&token=JWT

Both params are optional: omit stream for global chat; omit token to connect anonymously (assigned anonXXXXX identity).

Client → Server Messages

Server → Client Messages

Chat Bot — Complete Example (Node.js)

const WebSocket = require('ws');

const WS_URL = 'wss://hobostreamer.com/ws/chat?stream=123&token=YOUR_JWT';
const ws = new WebSocket(WS_URL);

ws.on('open', () => console.log('Bot connected'));

ws.on('message', (raw) => {
  const msg = JSON.parse(raw);

  if (msg.type === 'auth') {
    console.log('Logged in as:', msg.username);
  }

  if (msg.type === 'chat') {
    console.log(`[${msg.username}] ${msg.message}`);

    // Respond to commands
    if (msg.message.startsWith('!hello')) {
      ws.send(JSON.stringify({
        type: 'chat',
        message: `Hey @${msg.username}! 👋`
      }));
    }

    if (msg.message.startsWith('!time')) {
      ws.send(JSON.stringify({
        type: 'chat',
        message: `The time is ${new Date().toLocaleTimeString()}`
      }));
    }
  }
});

ws.on('close', () => setTimeout(() => reconnect(), 5000));

Chat Bot — Complete Example (Python)

import json, websocket, time

TOKEN = 'YOUR_JWT_TOKEN'
STREAM_ID = '123'
WS_URL = f'wss://hobostreamer.com/ws/chat?stream={STREAM_ID}&token={TOKEN}'

def send(ws, message):
    ws.send(json.dumps({ 'type': 'chat', 'message': message }))

def on_message(ws, raw):
    msg = json.loads(raw)
    if msg.get('type') == 'auth':
        print(f"Connected as {msg.get('username')}")
    if msg.get('type') == 'chat':
        user = msg.get('username', '?')
        text = msg.get('message', '')
        print(f'[{user}] {text}')
        if text.startswith('!hello'):
            send(ws, f'Hey @{user}!')
        if text.startswith('!uptime'):
            send(ws, f'Bot uptime: {int(time.time() - start_time)}s')

def on_open(ws): print('Connected')
def on_close(ws, *a): print('Disconnected — reconnecting...')
def on_error(ws, e): print(f'Error: {e}')

start_time = time.time()
while True:
    ws = websocket.WebSocketApp(WS_URL, on_message=on_message,
        on_open=on_open, on_close=on_close, on_error=on_error)
    ws.run_forever()
    time.sleep(5)

Chat Commands (built-in)

User Roles

Chat REST API

5. INTERACTIVE CONTROL SYSTEM — ROBOT/HARDWARE GUIDE

The control system lets streamers expose interactive buttons that viewers press to control physical hardware (robots, cameras, servo rigs, etc.). Three interaction types: single-press buttons, keyboard hold (continuous drive), and video-click (x/y coordinates on the live video feed).

Control Config Profiles

Streamers create reusable control configs. Each config holds buttons. When going live, a config is applied to the stream — its buttons get copied to that stream session.

Button Schema

{
  "label":        "Forward",     // Display name shown to viewers (max 50)
  "command":      "forward",     // String sent to your hardware bridge (max 100)
  "icon":         "fa-arrow-up", // FontAwesome icon class (without fa-solid prefix)
  "control_type": "keyboard",    // "button" | "keyboard" | "toggle" | "dpad"
  "key_binding":  "w",           // Optional keyboard shortcut for viewers (max 20)
  "cooldown_ms":  100,           // Per-press cooldown in ms (0-30000)
  "sort_order":   0,             // Display order (ascending)
  "btn_color":    "#ffffff",     // Button text color (CSS color — safe values only)
  "btn_bg":       "#1a1a2e",     // Button background color
  "btn_border_color": "#6366f1", // Button border color
  "is_enabled":   1              // 1=shown, 0=hidden
}

Control Type Behaviour

Channel Control Settings

{
  "control_mode":          "open",   // "open" | "whitelist" | "disabled"
  "anon_controls_enabled": true,     // Allow anonymous viewers to use controls
  "control_rate_limit_ms": 100,      // Global rate limit per user (100-30000)
  "video_click_enabled":   true,     // Enable video click input
  "video_click_rate_limit_ms": 0      // Per-user minimum time between video clicks; 0 = use global rate limit
}

Per-Stream Controls (Legacy / Direct)

6. CONTROL WEBSOCKET — HARDWARE BRIDGE

This is how your code receives viewer commands. Connect as mode=hardware and listen for messages. Your bridge translates them into robot/hardware actions.

Connection URLs

# Hardware bridge (your robot/device — receives commands)
wss://hobostreamer.com/ws/control?mode=hardware&stream_key=YOUR_STREAM_KEY

# Viewer (browser/bot — sends commands)
wss://hobostreamer.com/ws/control?mode=viewer&token=JWT&stream=STREAM_ID

Hardware Receives These Messages

Hardware Can Send

Viewer Sends These Messages

Viewer Receives These Messages

Permission Model

Hardware Bridge — Python (Full Example)

#!/usr/bin/env python3
"""
HoboStreamer Hardware Bridge — generic template.
pip install websocket-client
"""
import json, time, threading, websocket

STREAM_KEY = 'YOUR_STREAM_KEY'
WS_URL = f'wss://hobostreamer.com/ws/control?mode=hardware&stream_key={STREAM_KEY}'

held_keys = set()  # Track currently held keyboard commands

def do_command(cmd):
    """Map command strings to your hardware."""
    print(f'Command: {cmd}')
    # Example: call GPIO, serial, HTTP, etc.
    # if cmd == 'forward': robot.drive(speed=100)

def do_start_hold(cmd):
    """Called when a keyboard-type button starts being held."""
    held_keys.add(cmd)
    print(f'Hold start: {cmd}')

def do_stop_hold(cmd):
    """Called when a keyboard-type button is released."""
    held_keys.discard(cmd)
    print(f'Hold stop: {cmd}')
    if not held_keys:
        print('All keys released — stop movement')
        # robot.stop()

def do_video_click(x, y):
    """Called when a viewer clicks the video feed. x,y are 0-1 normalized."""
    print(f'Video click at ({x:.2f}, {y:.2f})')
    # Navigate toward click: x < 0.4 = turn left, x > 0.6 = turn right
    # y close to 0 = far away (drive more), y close to 1 = near (drive less)

def on_message(ws, raw):
    try:
        msg = json.loads(raw)
        t = msg.get('type')
        if t == 'connected':
            print('Hardware bridge authenticated!')
        elif t == 'command':
            do_command(msg['command'])
        elif t == 'key_down':
            do_start_hold(msg['command'])
        elif t == 'key_up':
            do_stop_hold(msg['command'])
        elif t == 'video_click':
            do_video_click(msg['x'], msg['y'])
    except Exception as e:
        print(f'Error: {e}')

def on_open(ws): print('Connected')
def on_close(ws, *a): print('Disconnected')
def on_error(ws, e): print(f'WS error: {e}')

while True:
    ws = websocket.WebSocketApp(WS_URL, on_message=on_message,
        on_open=on_open, on_close=on_close, on_error=on_error)
    ws.run_forever(ping_interval=30)
    print('Reconnecting in 5s...')
    time.sleep(5)

Hardware Bridge — Node.js (Full Example)

const WebSocket = require('ws');

const STREAM_KEY = 'YOUR_STREAM_KEY';
const WS_URL = `wss://hobostreamer.com/ws/control?mode=hardware&stream_key=${STREAM_KEY}`;
const heldKeys = new Set();

function connect() {
  const ws = new WebSocket(WS_URL);

  ws.on('message', (raw) => {
    const msg = JSON.parse(raw);
    switch (msg.type) {
      case 'connected':
        console.log('Hardware bridge authenticated!');
        break;
      case 'command':
        console.log(`Button: ${msg.command} by ${msg.from_user}`);
        doCommand(msg.command);
        break;
      case 'key_down':
        heldKeys.add(msg.command);
        console.log(`Hold start: ${msg.command}`);
        startContinuous(msg.command);
        break;
      case 'key_up':
        heldKeys.delete(msg.command);
        console.log(`Hold stop: ${msg.command}`);
        if (heldKeys.size === 0) stopAll();
        break;
      case 'video_click':
        console.log(`Click at (${msg.x.toFixed(2)}, ${msg.y.toFixed(2)}) by ${msg.from_user}`);
        navigateToClick(msg.x, msg.y);
        break;
    }
  });

  ws.on('close', () => setTimeout(connect, 5000));
  ws.on('error', (e) => console.error(e));
}

function doCommand(cmd) { /* implement hardware control */ }
function startContinuous(cmd) { /* start motors etc. */ }
function stopAll() { /* stop all motors */ }
function navigateToClick(x, y) { /* steer toward x,y */ }

connect();

API Keys (for hardware bridges without JWT)

Per-Profile Bridge Script Generator

Download Python bridge scripts that come pre-configured with your control profile's buttons and your stream key. Available from the Dashboard (Hardware Bridge Scripts section) or the Broadcast page (Script button next to profile selector).

# Download via API:
GET /api/controls/configs/42/bridge-script?type=generic
GET /api/controls/configs/42/bridge-script?type=cozmo

# Both return a .py file download with:
# - Your stream key (auto-connects as hardware bridge)
# - All enabled buttons from the profile listed as BUTTONS
# - Skeleton handler functions ready to fill in

Hardware Status Indicator

When a hardware bridge connects, viewers see a live connection indicator:

Hardware bridges send { type: "status", connected: true } on connect. The server broadcasts this to all viewers as a hardware_status message. Send a status with connected: true to turn the indicator green.

ONVIF Camera Control

Control PTZ cameras via ONVIF. Cameras appear as controls in the stream control panel.

ONVIF movements (send via control WS with isOnvif: true, cameraId: X, movement: Y):

pan_left, pan_right, tilt_up, tilt_down, zoom_in, zoom_out

TTS & AUDIO SYSTEM

Text-to-Speech

TTS reads chat messages, donation alerts, and custom text aloud on stream. Viewers hear it in the broadcast audio mix. Streamers configure which voice, volume, rate, and message types trigger TTS.

TTS Settings Schema

{
  "tts_enabled": true,
  "tts_voice": "en-US-Standard-D",
  "tts_volume": 0.8,
  "tts_rate": 1.0,
  "tts_read_chat": true,
  "tts_read_username": true,
  "tts_min_bits": 0,
  "tts_max_length": 200,
  "tts_filter_links": true,
  "tts_filter_emotes": false
}

101Soundboards Integration

Viewers paste 101soundboards.com URLs in chat to play sound effects. The server fetches, caches, and routes audio through the TTS queue with optional pitch/speed modifiers.

Chat Syntax

# Basic — just paste the URL
https://www.101soundboards.com/sounds/12345

# With pitch modifier (cents — 100 = one semitone up)
https://www.101soundboards.com/sounds/12345 100p

# Negative pitch (down)
https://www.101soundboards.com/sounds/12345 -200p

# With speed modifier (1.0 = normal, 0.5-3.0 range)
https://www.101soundboards.com/sounds/12345 2.5

# Both pitch and speed
https://www.101soundboards.com/sounds/12345 150p 2

Channel Soundboard Settings

Rate Limits

Audio Queue

TTS and soundboard audio share a single playback queue. Messages play in FIFO order. The audio element routes through a GainNode for volume control. Soundboard clips support playbackRate for pitch/speed modification.

INTEGRATIONS — DISCORD, PUSH, WEBHOOKS

Discord Bot (via hobo.tools)

The Discord bot runs on hobo.tools (not HoboStreamer). When a stream goes live, HoboStreamer fires an internal event, and the bot posts an embed in the configured alerts channel.

Discord Admin API (hobo.tools)

Discord Account Linking

Web Push Notifications

Push notifications use VAPID (Web Push API). Users subscribe via their browser, and receive alerts for stream go-live events.

Notification Preferences

Internal Events API (server-to-server)

HoboStreamer emits events to hobo.tools via internal API. Protected by X-Internal-Key header.

Fallback Webhook (HoboStreamer direct)

If hobo.tools is unreachable, HoboStreamer falls back to its built-in Discord webhook sender. Configure the webhook URL in HoboStreamer site settings (discord_webhook_url).

8. VODS, CLIPS & PASTES

9. MISC API

Rate Limits

HoboStreamer is open source. Contribute at github.com/HoboStreamer/HoboStreamer.com. Self-host it, fork it, vibe code on top of it.