HOBOSTREAMER PLATFORM — COMPLETE DEVELOPER REFERENCE

HoboStreamer is a self-hosted, open-source live streaming platform. Stack: Node.js + Express + SQLite (better-sqlite3) + Mediasoup WebRTC SFU. Frontend: vanilla JS SPA. All API endpoints return JSON. WebSocket endpoints on same host/port.

Base URL: https://hobostreamer.com (replace with your instance). All authenticated endpoints require: Authorization: Bearer <JWT> header, or ?token=JWT query param on WebSocket URLs.

1. AUTHENTICATION

REST Endpoints

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": 500,      // Global rate limit per user (100-30000)
  "video_click_enabled":   true      // Enable video click input
}

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.

7. 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

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.