Streaming over LAN

Overview

When your client is on the same network as a Rhombus device, it can pull live video, recorded footage, and audio straight from the device instead of through the Rhombus cloud. You get lower latency and use no internet bandwidth.

This guide covers:

• How API tokens and federated tokens differ, and which one to use where
• Minting a federated token and finding a device's LAN URIs
• Authenticating LAN requests with headers or query parameters
• Live H.264 and two-way audio over WebSocket, plus DASH/HLS for live and recorded video
• Browser limitations and troubleshooting

API tokens vs federated tokens

These are two different credentials with different jobs.

A federated token is a bearer credential: anyone holding it can act with its role. For LAN streaming, mint device-scoped tokens with deviceUUid. A device-scoped token can only fetch that one device's media, and the cloud API rejects it. Also mint from an API token whose role is no broader than the viewer needs, and keep durationSec short.

Prerequisites

Implementation

1. Mint a federated token on your server

   Call generateFederatedSessionToken with your API key. Your API key never leaves your server.

   PythonNode.jscURL

   import requests
   
   API_HEADERS = {
       "x-auth-scheme": "api-token",
       "x-auth-apikey": "YOUR_API_KEY",
       "Content-Type": "application/json",
   }
   
   response = requests.post(
       "https://api2.rhombussystems.com/api/org/generateFederatedSessionToken",
       headers=API_HEADERS,
       json={
           "durationSec": 3600,               # token lifetime in seconds
           "deviceUUid": "YOUR_CAMERA_UUID",  # recommended: only this device's media
       },
   )
   response.raise_for_status()
   body = response.json()
   federated_token = body["federatedSessionToken"]
   expires_at_ms = body["expiresAtMs"]  # Unix ms; mint the next token before then

   Example response:

   json

   {
     "federatedSessionToken": "Q2gP7m1kTnWb3sXyZ4aJ8w",
     "expiresAtMs": 1791370800000
   }

   Field	Notes
   durationSec	Optional. The token's lifetime in seconds: 3600 (1 hour) if you leave it out, at most 86400 (24 hours; a larger value is reduced to that, and expiresAtMs shows the lifetime you got). Request only as long as the session needs.
   deviceUUid	Optional, recommended for LAN. Limits the token to media (LAN and WAN) for one device; the token can't call the cloud API. Note the casing: deviceUUid.
   domain	Optional. The browser origin allowed to use the token, as an absolute origin such as https://app.example.com. Requests to Rhombus cloud hosts from any other origin get 403 DOMAIN_NOT_ALLOWED. To limit a LAN token, use deviceUUid and a short durationSec.

   The response's expiresAtMs is when the token expires, in Unix milliseconds. Mint the next token before then.

   The token can never do more than the API token that minted it. If that role only allows live video, the device serves live streams and refuses recorded footage.

2. Get the device's LAN URIs

   On your server, call POST /api/camera/getMediaUris with cameraUuid, or /api/audiogateway/getMediaUris with gatewayUuid, using your API key. A device-scoped federated token can't call the cloud API.

   Python

   response = requests.post(
       "https://api2.rhombussystems.com/api/camera/getMediaUris",
       headers=API_HEADERS,
       json={"cameraUuid": "YOUR_CAMERA_UUID"},
   )
   response.raise_for_status()
   uris = response.json()

   Field	What it is	Example
   lanLiveH264Uris	Live H.264 over WebSocket (lowest latency)	wss://192-168-1-50.lan.rhombussystems.com:8000/DEVICE_UUID/ws
   lanLiveOpusUris	Live two-way audio over WebSocket	wss://192-168-1-50.lan.rhombussystems.com:8000/DEVICE_UUID/audio
   lanLiveMpdUris / lanLiveM3u8Uris	Live DASH / HLS	https://192-168-1-50.lan.rhombussystems.com:8000/DEVICE_UUID/live/live.mpd
   lanVodMpdUrisTemplates / lanVodM3u8UrisTemplates	Recorded footage from the device's own storage	https://192-168-1-50.lan.rhombussystems.com:8000/DEVICE_UUID/store/{START_TIME}_{DURATION}/clip.mpd
   lanCheckUrls	Reachability check	https://192-168-1-50.lan.rhombussystems.com:8000/DEVICE_UUID/

   • Each field is an array because a device can have more than one LAN address. Use the first one your client can reach.
   • In the VOD templates, replace {START_TIME} with a Unix timestamp in seconds and {DURATION} with a length in seconds.
   • The LAN hostname is public DNS that resolves to the device's private IP, and the device serves a publicly trusted certificate for it. Connect using the hostname exactly as returned, not the raw IP, and keep normal TLS verification on. Devices in the EU region use .lan.eu.rhombussystems.com hostnames (API Regions).
3. Present the federated token to the device

   Send the federated token on every request to the device, including each DASH/HLS segment and the WebSocket upgrade. Use whichever form your client supports:

   HeadersQuery parameters

   For native apps, servers, curl, and ffmpeg:

   x-auth-scheme: federated-token
   x-auth-ft: YOUR_FEDERATED_TOKEN

   The device checks the token with Rhombus: it must be unexpired, belong to the device's organization, and carry a role that can view this device. The device caches a successful check for up to 60 seconds, so a token can keep working for up to a minute after it expires or is revoked. When a viewer's session ends, revoke its token with POST /api/org/revokeFederatedSessionToken (body {"federatedSessionToken": "..."}), and keep durationSec short.

Code examples

Live DASH manifest

TOKEN="YOUR_FEDERATED_TOKEN"

curl -H "x-auth-scheme: federated-token" -H "x-auth-ft: $TOKEN" \
  "https://192-168-1-50.lan.rhombussystems.com:8000/YOUR_CAMERA_UUID/live/live.mpd"

A valid token returns the DASH manifest (200). A missing, expired, or unauthorized token returns 401.

Recorded footage with ffmpeg

ffmpeg passes -headers on to every playlist and segment request. This saves 60 seconds of footage starting at 1767225600 (2026-01-01 00:00:00 UTC):

ffmpeg -headers $'x-auth-scheme: federated-token\r\nx-auth-ft: '"$TOKEN"$'\r\n' \
  -i "https://192-168-1-50.lan.rhombussystems.com:8000/YOUR_CAMERA_UUID/store/1767225600_60/clip.m3u8" \
  -c copy clip.mp4

Live H.264 over WebSocket

import asyncio
import json
from urllib.parse import urlencode

import requests
import websockets  # pip install websockets

API_HEADERS = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
CAMERA_UUID = "YOUR_CAMERA_UUID"


def mint_device_token(device_uuid: str) -> tuple[str, int]:
    response = requests.post(
        "https://api2.rhombussystems.com/api/org/generateFederatedSessionToken",
        headers=API_HEADERS,
        json={"durationSec": 3600, "deviceUUid": device_uuid},
    )
    response.raise_for_status()
    body = response.json()
    # Mint the next token before expiresAtMs (Unix milliseconds)
    return body["federatedSessionToken"], body["expiresAtMs"]


def lan_h264_uri(camera_uuid: str) -> str:
    response = requests.post(
        "https://api2.rhombussystems.com/api/camera/getMediaUris",
        headers=API_HEADERS,
        json={"cameraUuid": camera_uuid},
    )
    response.raise_for_status()
    uris = response.json().get("lanLiveH264Uris") or []
    if not uris:
        raise SystemExit("The camera reported no LAN address")
    return uris[0]


async def watch(uri: str, token: str, max_frames: int = 30) -> None:
    auth = urlencode({"x-auth-scheme": "federated-token", "x-auth-ft": token})
    async with websockets.connect(f"{uri}?{auth}") as ws:
        frames = 0
        async for message in ws:
            if isinstance(message, str):  # one text init message comes first
                print("init:", json.loads(message))
                continue
            timestamp_ms, offset = None, 0
            while offset + 4 <= len(message):
                tlv_type = message[offset]
                length = int.from_bytes(message[offset + 1 : offset + 4], "big")
                value = message[offset + 4 : offset + 4 + length]
                offset += 4 + length
                if tlv_type == 0x02:
                    timestamp_ms = int.from_bytes(value, "big")
                elif tlv_type in (0x00, 0x01):  # frame data is always last
                    kind = "keyframe" if tlv_type == 0x00 else "delta"
                    print(f"{kind}: {len(value)} bytes at {timestamp_ms}")
                    frames += 1
                    break
            if frames >= max_frames:
                break


token, expires_at_ms = mint_device_token(CAMERA_UUID)
asyncio.run(watch(lan_h264_uri(CAMERA_UUID), token))

// federatedToken comes from your server (Step 1), never your API key
const url = new URL(lanLiveH264Uri);
url.searchParams.set('x-auth-scheme', 'federated-token');
url.searchParams.set('x-auth-ft', federatedToken);

const ws = new WebSocket(url);
ws.binaryType = 'arraybuffer';
ws.onmessage = (event) => {
  if (typeof event.data === 'string') {
    console.log('init', JSON.parse(event.data));
    return;
  }
  handleH264Message(event.data); // see the TLV format linked below
};

Example output from the Python script:

init: {'action': 'init', 'width': 1920, 'height': 1080, 'codec': 'h264', 'framerate': 15}
keyframe: 48213 bytes at 1791158465584
delta: 3120 bytes at 1791158465651

Each binary message is a sequence of TLV records (1-byte type, 3-byte big-endian length, value) ending with the H.264 frame data. The full type table, including embedded AI detections, is in LAN Realtime Detection Overlay. For a ready-made browser player, use RhombusRealtimePlayer with connectionMode="lan" from the React SDK.

Audio over WebSocket

The lanLiveOpusUris socket carries audio in both directions and uses the same federated token authentication.

Listening

Each binary message from the device holds three TLV records. Each record header is 1 bit (echo flag), 7 bits (type), and a 24-bit big-endian length, followed by the value.

Talking

To play audio on the device's speaker, send binary messages on the same socket. Each record is a 4-byte ASCII type, a 4-byte big-endian length, then the payload. Each audio record carries exactly 20 ms of audio.

By default the device plays every Opus packet, even late ones, and drops late PCM to stay real time.

Browser apps

• WebSocket streams (lanLiveH264Uris, lanLiveOpusUris) work from any origin with the token in the query string.
• LAN DASH and HLS (lanLive* and lanVod* URLs) can't be loaded by browser JavaScript such as dash.js or hls.js on your own domain, because devices only allow Rhombus origins for cross-origin requests. Play LAN DASH/HLS from a native app or server, or use the WebSocket stream in the browser.
• Never put an API key in browser code. Mint federated tokens on your server and hand only those to the browser.

Devices on older firmware

Devices running firmware released before mid-April 2026 only read the token from a cookie. If a native client must support them, also send:

Cookie: RSESSIONID=RFT:YOUR_FEDERATED_TOKEN

Current firmware accepts this cookie too, so a native client can send it alongside the headers.

Troubleshooting

Next steps