Network Architecture

Service Map

┌──────────────────────────────────────────────────────┐
│  openvibe.network (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      │
├──────────────────────────────────────────────────────┤
│  OpenVibe.Live (port 3000) — Streaming Platform   │
│  ├─ /api/streams   — Stream CRUD + go-live           │
│  ├─ /api/chat      — Chat REST API                   │
│  ├─ /api/tts       — TTS voice config                │
│  ├─ /ws/chat       — Real-time chat                  │
│  ├─ /ws/broadcast  — WebRTC signaling                │
│  ├─ /whip/:id      — WHIP WebRTC ingestion           │
│  └─ RTMP server    — rtmp://host/live                │
└──────────────────────────────────────────────────────┘

Event Flow: Stream Goes Live

1. Streamer goes live (Go-Live API, RTMP, WHIP or the OpenRestream mirror)
2. OpenVibe.Live creates the stream record and publishes live.stream.started to OpenVibe.Events
3. openvibe.network's Events consumer tells the streamer's followers (its own follows):
   inbox notification, Web Push (VAPID), email and Discord, at most once per streamer per window
4. A go-live while openvibe.network is down waits in OpenVibe.Events and is delivered on retry

WebSocket Services

Admin Proxy Architecture

openvibe.network admin panel proxies requests to OpenVibe.Live:

openvibe.network /api/admin/streamer/*  →  OpenVibe.Live /api/admin/*
openvibe.network /api/admin/streamer-tts/*  →  OpenVibe.Live /api/tts/*
openvibe.network /api/admin/streamer-mod/*  →  OpenVibe.Live /api/mod/*

Server-to-server calls carry a short-lived service token from openvibe.network, scoped to the one capability each route performs.

1. AUTHENTICATION

All identity is OpenVibe SSO. There is no local password login on OpenVibe.Live — POST /api/auth/register and POST /api/auth/login are permanently disabled (return 410). Humans sign in through openvibe.network OAuth2; OpenVibe.Live receives an RS256 JWT signed by openvibe.network and verifies it locally. For bots and scripts, use a long-lived hbt_ API token (below) — no browser login needed.

How auth is sent

Every authenticated request carries a token as Authorization: Bearer <token> (REST also reads the ov_token cookie; a WebSocket takes only the header or the token in its first join message). requireAuth accepts either:

• API token — a string starting with hbt_. Best for bots/integrations. Cannot itself create/list/revoke tokens.
• openvibe.network JWT (RS256) — from the SSO login flow; auto-links/creates a local account. Roles come from the token.

Roles: admin > global_mod > streamer > user (+ anonymous). Banned accounts get 403.

REST Endpoints

API Tokens (hbt_ prefix)

Long-lived, scoped tokens for bots/integrations. Create them from Dashboard → API Tokens (max 10 active). The token string is shown once. Use as Authorization: Bearer hbt_xxxxxxxxxxxx.

Scopes: chat, read, stream, control, vibe_coding_publish. Presets: chat-bot (chat,read), stream-controller (read,stream,control), vibe-coding-publisher (read,vibe_coding_publish).

Example: use an API token

// Create the token once from Dashboard → API Tokens (scopes: chat, read),
// then use it directly — no login flow needed.
const TOKEN = 'hbt_xxxxxxxxxxxxxxxx';

const me = await fetch('https://openvibe.live/api/auth/me', {
  headers: { 'Authorization': `Bearer ${TOKEN}` }
}).then(r => r.json());
console.log('Acting as:', me.user.username);

2. STREAMS & CHANNELS

Model: a managed stream is a persistent slot (a saved config: title, category, protocol, its own stream_key, plus recording/clip/privacy settings). A stream is one live session started from a slot. You do NOT create streams directly — you create a slot, then go live from it.

Managed streams (slots)

Per-slot settings (PUT /managed/:id): streaming_method (browser|whip|cli|rtmp — auto-derives protocol), browser_mode (camera|mic_only|screen), default_vod_visibility / default_clip_visibility (public|unlisted|private), slot_vod_recording_enabled, slot_clip_recording_enabled, slot_clip_notify_enabled (0/1), weather fields, control_config_id.

Go live / sessions

Discovery & channels

Supported ingest protocols

• webrtc (streaming_method browser or whip) — Mediasoup SFU, lowest latency. Browser capture or a WHIP encoder (OBS 30+).
• rtmp — classic RTMP ingest (OBS/ffmpeg). Recorded losslessly to .mp4; plays back via HTTP-FLV.
• jsmpeg (streaming_method cli) — MPEG-TS over WebSocket for Raspberry Pi / low-power devices.

The ingest URL comes from GET /api/streams/:id/endpoint — webrtc returns { roomId, signalingUrl, whipUrlBase }, rtmp returns { rtmpUrl, streamKey, flvUrl }, jsmpeg returns ffmpeg command strings + ports.

Example: create a slot, go live, get the WHIP URL

const H = { 'Authorization': `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };

// 1. Create a WHIP slot (once)
const slot = await fetch('https://openvibe.live/api/streams/managed', {
  method: 'POST', headers: H,
  body: JSON.stringify({ title: 'Robot cam', streaming_method: 'whip', category: 'Technology' })
}).then(r => r.json());

// 2. Go live from the slot
const { stream, endpoint } = await fetch('https://openvibe.live/api/streams', {
  method: 'POST', headers: H,
  body: JSON.stringify({ managed_stream_id: slot.managed_stream.id })
}).then(r => r.json());

console.log(endpoint.whipUrlBase); // POST your SDP offer here (see WebRTC tab)

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://openvibe.live/ws/broadcast?streamId=ID&role=broadcaster|viewer&token=JWT

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

Viewer media is delivered exclusively through the Mediasoup SFU. There is no direct peer-to-peer relay: legacy offer / answer / ice-candidate messages are not supported.

RTMP Ingest (OBS)

Server: rtmp://openvibe.live/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://openvibe.live/ws/chat?stream=STREAM_ID with an Authorization: Bearer <token> header (a JWT or an hbt_ API token), then send { "type": "join", "streamId": STREAM_ID }. A client that cannot set headers (a browser) puts the token in that join instead: { "type": "join", "streamId": STREAM_ID, "token": "…" }.

Omit stream for global chat; omit the token to connect anonymously (assigned an anonXXXXX identity). A token in the URL does not sign the socket in: URLs end up in logs.

Client → Server Messages

Server → Client Messages

Chat Bot — Complete Example (Node.js)

const WebSocket = require('ws');

const STREAM_ID = 123;
const ws = new WebSocket(`wss://openvibe.live/ws/chat?stream=${STREAM_ID}`, {
  headers: { Authorization: 'Bearer hbt_YOUR_TOKEN' },
});

ws.on('open', () => {
  console.log('Bot connected');
  ws.send(JSON.stringify({ type: 'join', streamId: STREAM_ID }));
});

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 = 'hbt_YOUR_TOKEN'
STREAM_ID = 123
WS_URL = f'wss://openvibe.live/ws/chat?stream={STREAM_ID}'

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')
    ws.send(json.dumps({ 'type': 'join', 'streamId': STREAM_ID }))
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, header=[f'Authorization: Bearer {TOKEN}'],
        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

MONEY — Vibes, POINTS & PAYMENTS

The economy in one paragraph

Vibes are integer, "bit"-style units (like Twitch bits). 100 bucks = $1.00 of streamer cashout value (1 buck = 1 USD cent). Viewers buy at a premium with volume discounts (per-buck price $0.0150 down to $0.0110), streamers cash out at a flat $0.01/buck, and the spread is the platform margin. Each user has two balances: a spendable balance (bucks you bought — used to donate/subscribe) and a cashout balance (bucks you received as donations/sub share — the only balance you can cash out). Cashouts go to a 14-day escrow for admin review; minimum cashout is 500 bucks ($5.00). Two free currencies also exist: global GOLD and per-channel loyalty points (OpenCoins).

Vibes — /api/funds

Buying Vibes & subscriptions — /api/payments

Real-money purchases via Stripe, PayPal, CCBill, or crypto (NOWPayments). Off by default (payments_enabled). Every purchase creates an order, then a provider webhook fulfills it once (idempotent).

Packages: 100, 500, 1000, 2500, 5000, 10000, 25000 bucks. Per-buck price tiers: ≥25000→$0.0110, ≥10000→$0.0115, ≥5000→$0.0120, ≥2500→$0.0124, ≥1000→$0.0130, ≥500→$0.0140, else $0.0150. Streamers keep sub_streamer_share_pct (default 70%) of sub value into their cashout balance.

OpenCoins / Coins — /api/coins

Free currencies. GOLD is a global wallet (games, cosmetics, media requests). Channel points ("OpenCoins") are per-streamer loyalty points earned by watching/chatting a channel and spent on that streamer's rewards. Defaults: watch = 10/5min, chat = 5 (max 1/min), follow = 50 once; not earnable on your own stream.

Cosmetics — /api/cosmetics

Chat cosmetics (name effects, hats, particles, voices) unlocked from openvibe-quest game items and equipped per slot.

AI SYSTEMS

OpenVibe.Live runs a background AI layer over community content (chat, streams, VODs) using a shared platform key with a per-streamer daily budget, or a streamer's own BYO key. Two developer-facing surfaces:

Chat-AI insight (read-only) — /api/chat/ai and /api/chat-ai

Rolling LLM summaries of the chat, kept by OpenVibe.Chat: a global "community vibe", plus per-user / per-anon / per-relay-user insight (overview + running memory + a short timeline). A channel's AI timeline and a user's streamer side are OpenVibe.Live's and include the chatter insight. No auth required to read.

AI Chat Viewers — /api/ai-viewers

Persistent, context-aware AI chatter bots per channel. They read the streamer/user/global AI insight + live situation and post one at a time. All endpoints are requireAuth (streamer configures their own).

Budget gating (budgetStatus): shared_ai_disabled, over_daily_cap, or no_byo_key pause generation. Note: AI viewers inject chat lines server-side, so they don't appear as WS clients.

5. ROBOTS — OPENVIBE.BOT

Robots live on OpenVibe.Bot, the open control panel for robots: pairing, the drive panel, roles and turn queues, limits, the latched e-stop, video and the command audit are all there. OpenVibe.Live shows a channel's robot and lets its chat drive it; it has no control socket or hardware API of its own.

A robot on your channel

1. Add a robot on openvibe.bot/robots/new: a Raspberry Pi car, a Cozmo through a computer beside it, a phone (scan a QR code, nothing to install) or an ONVIF camera. Its pairing page has the one command (or the QR code) that brings it online.
2. On the robot's panel, turn on Let anyone watch where it is embedded, and choose who may drive: only you and people you add, people you invite, or anyone signed in taking timed turns.
3. In your dashboard (Robot & API), put the robot's id (rob_…). Its live panel shows under your stream: everyone sees its camera and readouts, and anyone allowed to drive presses Drive.

The binding is PUT /api/streams/channel/:username/bot with { "robot_id": "rob_…" } (or null to unbind), the channel owner only.

Chat commands

Each command goes to OpenVibe.Bot as the viewer who typed it, so the robot's rules decide: signed-in viewers only, the owner's access policy and turn queue, per-person cooldowns, and nothing while the e-stop is latched. A refusal is answered in chat ("It is not your turn at the robot yet").

Building for robots

Drivers, robot profiles, the device protocol, the REST API with the same gate, and a simulated rover to try it all are on OpenVibe.Bot: Build for OpenVibe.Bot · try the panel · supported models.

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 openvibe.network)

The Discord bot runs on openvibe.network (not OpenVibe.Live). When a stream goes live, OpenVibe.Live fires an internal event, and the bot posts an embed in the configured alerts channel.

Discord Admin API (openvibe.network)

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)

OpenVibe.Live emits events to openvibe.network through its internal API, with a service token scoped to the capability of each call.

Go-live alerts

When a stream starts, OpenVibe.Live publishes live.stream.started through OpenVibe.Events, and openvibe.network tells the streamer's followers: inbox, push, email and the Discord alert. Live makes no direct call.

Multistream / Restream — /api/restream

Relay a live stream out to YouTube / Twitch / Kick / custom RTMP. Manage destinations per slot (max 10); stream keys are masked on read. All requireAuth.

RobotStreamer — /api/robotstreamer

Publish a server-ingested stream to a RobotStreamer robot and (optionally) mirror its chat. Config is per stream slot only: a slot without its own config does not restream to RobotStreamer, and every call except GET needs managed_stream_id. All requireAuth.

PowerChat — /api/powerchat

Two-way bridge with PowerChat (alerts/overlays). OpenVibe.Live chat + viewer counts + point redemptions flow into PowerChat's overlays; signed webhooks flow out — a PowerChat donation.completed is mapped onto the Vibes donation pipeline (PowerChat cents = bucks 1:1) and credits the active goal.

7. VODS, CLIPS & PASTES

Recording mode is per slot: vod (kept + browsable), clips_only (ephemeral — recorded only to source live clips, deleted on stream end), or none. RTMP streams record losslessly to fragmented .mp4 (H.264/AAC); WebRTC/jsmpeg record to .webm. New-VOD and new-clip visibility follow the slot's default_vod_visibility / default_clip_visibility.

VODs — /api/vods

Clips — /api/clips

Comments — /api/comments (on VODs & clips)

Comments are OpenVibe.Community comment threads: the same thread shows on Community's page for it. When Community cannot be reached these routes answer 503 with code: "comments_unavailable".

Pastes — /api/pastes

Live Frame API — openvibe.media/live/:selector/frame.jpg

Grab a near-realtime JPEG frame of any actively-live stream slot — built for external APIs, bots, dashboards, and dev tooling. No auth, CORS-open (Access-Control-Allow-Origin: *), so you can hotlink it in an <img>, poll it from a script, or draw it onto a canvas.

?w=64..1920 scales the width (aspect kept) · responses are cached 5s per slot — that cache is the rate limit, so poll as fast as you like · frames are cut ~2s behind the live edge. Offline? You get a styled "OFFLINE" card image with a 404 status — embeds keep looking good, scripts key off the status code (or add ?format=json for JSON errors). 503 = live but no frame could be cut (retry next window).

# Is Goosely live? Grab a frame if so
curl -f -o now.jpg https://openvibe.media/live/@Goosely/frame.jpg && echo LIVE || echo OFFLINE

# 320px-wide preview for a status page — shows the OFFLINE card automatically when not live
<img src="https://openvibe.media/live/whip/frame.jpg?w=320">

Transcript & AI Timeline API — openvibe.media/live/:selector/transcript.json

The full audio transcription log and AI overview timeline for a stream slot or streamer — same selector grammar as the frame API, JSON out, no auth, CORS-open, cached 30s (that cache is the rate limit).

Response: { live, current, sessions[], streamer, user } — current is the in-progress recording when live; each session carries ai_overview, transcript (plain-text audio transcription), duration_seconds, created_at; streamer holds the AI streamer overview plus recent stream-memory moments (the AI timeline). ?limit=1..50 sessions (default 10).

VOD Transcript API — openvibe.media/v/:vodId/transcript.json

The same transcription + AI overview data for one existing VOD id: { vod_id, title, duration_seconds, ai_overview, transcript, ai_analyzed_at }. Private VODs return 404. Cached 30s, CORS-open.

Chat Insight API — openvibe.media/live/:user/chat-insight.json

A user's chat-related AI insight and timeline to feed bots/dashboards: :user is @username or a numeric user id. Returns { user, chat_insight, streamer } — chat_insight has today-vs-all-time chat overviews, condensed memory, and an event timeline; streamer adds the streamer overview + stream memories when they also stream. Cached 30s, CORS-open.

# What has Goosely's stream been about? (overviews + transcripts)
curl -s https://openvibe.media/live/@Goosely/transcript.json | jq ".sessions[0].ai_overview"

# Transcript of one specific VOD
curl -s https://openvibe.media/v/2028/transcript.json | jq ".transcript"

# Feed a chatter's AI insight into your bot
curl -s https://openvibe.media/live/@Goosely/chat-insight.json | jq ".chat_insight"

8. API REFERENCE — EVERYTHING ELSE

Chat REST — /api/chat

Emotes — /api/emotes (served by OpenVibe.Chat)

Sounds — /api/sounds (viewer !command sound clips)

Direct Messages — /api/dm

Analytics — /api/analytics

Media queue, News, Home & utility

Rate Limits

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