Stream Live and Recorded Video from Cameras - Rhombus Developer Documentation

Overview

Rhombus cameras expose multiple ways to access video content through the public API:

Live streaming for real-time monitoring, embedded as a Rhombus-hosted iframe
HLS manifests (.m3u8) for direct playback in your own player
Thumbnail images for dashboards and quick previews
Frame captures at any historical timestamp

For downloading recorded footage as MP4 files, see Recorded Video Access.

Getting camera thumbnails

All Rhombus cameras automatically upload thumbnail images. These are perfect for dashboards, monitoring interfaces, and quick status checks.

Thumbnail endpoint

Retrieve camera thumbnails using a GET request to:

https://media.rhombussystems.com/media/{cameraUuid}/{mediaRegion}/snapshot.jpeg

Note

Media URLs carry no credential, so authenticate every media.rhombussystems.com request. From a server, send your API key headers (x-auth-scheme: api-token and x-auth-apikey), or Authorization: Bearer <token> for an OAuth access token whose grant includes the read scope. In a browser, append a federated token as query parameters instead: ?x-auth-scheme=federated-token&x-auth-ft=<token> (clients that can set headers may send the same names as headers). See Media and streams.

To get the cameraUuid and mediaRegion for a camera, call POST /api/camera/getMinimalCameraStateList. The response contains a cameraStates array; each entry has uuid and mediaRegion fields.

Basic implementation

cURLbash

# 1. List cameras to get UUIDs and media regions
curl -X POST \
  "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

cURLbash

# 2. Fetch the thumbnail using a camera's UUID and media region
curl -X GET \
  "https://media.rhombussystems.com/media/{CAMERA_UUID}/{MEDIA_REGION}/snapshot.jpeg" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  --output thumbnail.jpg

Getting frames at specific times

To get a JPEG image at a specific historical timestamp, call POST /api/video/getExactFrameUri. The response contains a frameUri. It isn't signed and carries no credential: download it with the same authentication headers from a server, or append the federated-token query parameters in a browser.

javascript

// Server-side: this uses your API key
async function getFrameAtTime(cameraUuid, timestampMs, apiKey) {
  // Get the frame URI (it isn't signed, so the download needs auth too)
  const frameUriResponse = await fetch('https://api2.rhombussystems.com/api/video/getExactFrameUri', {
    method: 'POST',
    headers: {
      'x-auth-scheme': 'api-token',
      'x-auth-apikey': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      cameraUuid: cameraUuid,
      timestampMs: timestampMs // epoch milliseconds
    })
  });

  const { frameUri } = await frameUriResponse.json();

  // Fetch the actual JPEG
  const frameResponse = await fetch(frameUri, {
    headers: {
      'x-auth-scheme': 'api-token',
      'x-auth-apikey': apiKey
    }
  });

  return frameResponse.blob();
}

The request also accepts optional downscaleFactor, jpgQuality, and permyriadCropX/permyriadCropY/permyriadCropWidth/permyriadCropHeight fields (each in 1/10000ths of the image dimensions, where 10000 = 100%).

Live video streaming

Rhombus offers two ways to play live video in your application:

Embed the Rhombus player as an iframe — easiest path; analytics and timeline events render automatically.
Play the HLS manifest directly — use your own player (hls.js, Safari native, etc.) for full UI control.

Both come from the same API call: POST /api/camera/createSharedLiveVideoStream. The response contains both URLs:

Field	Description
`sharedLiveVideoStreamUrl`	Hosted Rhombus player URL — embed in an iframe
`sharedLiveM3U8StreamUrl`	HLS (`.m3u8`) manifest — play directly with any HLS player
`sharedLiveVideoStreamUuid`	UUID of the created share, useful for revoking later

Embedding shared streams as iframes (recommended)

Create a shared stream on your server, then drop the returned URL into an iframe. The browser needs no Rhombus credential because the link itself grants access: anyone who has it can watch, unless you create it with createProtectedSharedLiveVideoStream (password-protected). Set expirationTimeSecs and delete the share when you no longer need it. See Shared stream links.

javascript

// Server-side: this uses your API key
async function createSharedStream(cameraUuid, apiKey) {
  const response = await fetch('https://api2.rhombussystems.com/api/camera/createSharedLiveVideoStream', {
    method: 'POST',
    headers: {
      'x-auth-scheme': 'api-token',
      'x-auth-apikey': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ cameraUuid })
  });

  const data = await response.json();
  return data.sharedLiveVideoStreamUrl;
}

Embed the returned URL:

html

<iframe
  allow="fullscreen"
  frameborder="0"
  height="100%"
  width="100%"
  src="SHARED_STREAM_URL_GOES_HERE">
</iframe>

React component example

The component calls /api/shared-stream, a route on your own backend that calls createSharedLiveVideoStream with your API key and returns the response.

jsx

import React, { useEffect, useState } from 'react';

const RhombusSharedStream = ({
  cameraUuid,
  width = "100%",
  height = "400px",
  options = {}
}) => {
  const [streamUrl, setStreamUrl] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    let cancelled = false;

    (async () => {
      try {
        setLoading(true);
        // Your backend creates the share with its API key and returns the response
        const response = await fetch('/api/shared-stream', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ cameraUuid })
        });

        if (!response.ok) throw new Error('Failed to create shared stream');
        const data = await response.json();

        const url = new URL(data.sharedLiveVideoStreamUrl);
        Object.entries(options).forEach(([key, value]) => {
          url.searchParams.set(key, value);
        });

        if (!cancelled) {
          setStreamUrl(url.toString());
          setError(null);
        }
      } catch (err) {
        if (!cancelled) setError(err.message);
      } finally {
        if (!cancelled) setLoading(false);
      }
    })();

    return () => { cancelled = true; };
  }, [cameraUuid, options]);

  if (loading) return <div>Loading stream...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <iframe
      src={streamUrl}
      width={width}
      height={height}
      frameBorder="0"
      allow="fullscreen"
      title={`Camera ${cameraUuid} Stream`}
    />
  );
};

export default RhombusSharedStream;

URL parameters for enhanced control

Customize the embedded player with URL parameters. All parameters can be set to true or false:

Parameter	Description
`disableautoplay`	Enable or disable video autoplay upon loading
`hideevents`	Enable or disable the timeline and related events
`realtime`	Enable or disable real-time streaming by default
`showheader`	Enable or disable zoom & streaming buttons at the top
`showfooter`	Enable or disable camera name and timestamp at bottom
`lowRes`	Force low resolution on the video stream
`performanceMode`	Force performance mode allowing GPU usage
`t`	Timestamp (epoch milliseconds) where video should start

Parameter usage

Append parameters to the shared stream URL: https://{{url}}/?{{variable}}=true&{{variable}}=false

Example:

https://console.rhombussystems.com/share/live/ehrF58ABSj2VT8QzXh7GVA?disableautoplay=true&hideevents=true&realtime=true

React usage with parameters

jsx

<RhombusSharedStream
  cameraUuid="your-camera-uuid"
  options={{
    disableautoplay: 'true',
    hideevents: 'true',
    realtime: 'true',
    showheader: 'false',
    lowRes: 'false'
  }}
/>

Embedding HLS streams directly

If you want to render live video in your own player rather than the hosted iframe, use sharedLiveM3U8StreamUrl from the same createSharedLiveVideoStream response. The manifest is a standard HLS .m3u8. It isn't signed: the URL contains only the share's ID, and anyone who has it can watch, so no x-auth-apikey header is needed. For a password-protected share, send Authorization: Basic <base64(":" + password)> (an empty user name).

Note

The HLS URL is a bearer link to one camera: unless the share is password-protected, anyone who has it can watch until it expires or you delete the share. It expires only if you set expirationTimeSecs (a Unix time in seconds, not a duration). Treat it as a credential.

Safari plays HLS natively. For other browsers, use hls.js:

html

<video id="rhombus-live" controls autoplay muted style="width: 100%;"></video>

<script type="module">
  import Hls from 'https://cdn.jsdelivr.net/npm/hls.js@latest/dist/hls.min.js';

  async function startLive(cameraUuid) {
    // Your backend creates the share with its API key and returns the response
    const response = await fetch('/api/shared-stream', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ cameraUuid })
    });

    const { sharedLiveM3U8StreamUrl } = await response.json();
    const video = document.getElementById('rhombus-live');

    if (Hls.isSupported()) {
      const hls = new Hls();
      hls.loadSource(sharedLiveM3U8StreamUrl);
      hls.attachMedia(video);
    } else if (video.canPlayType('application/vnd.apple.mpegurl')) {
      video.src = sharedLiveM3U8StreamUrl;
    }
  }

  startLive('YOUR_CAMERA_UUID');
</script>

To play a camera's own streams instead of a share, call getMediaUris on your server and give the player wanLiveM3u8Uri (or the DASH wanLiveMpdUri) with a federated token appended as query parameters. On the cloud hosts, HLS playlists and DASH manifests (live and recorded) carry that query string to every segment URL they list, so the one URL works in any player. API keys and x-auth-org are never copied into segment URLs. See Media and streams.

Because creating a shared stream requires an API key, /api/shared-stream is a route on a server you control: it calls createSharedLiveVideoStream and passes only the resulting sharedLiveM3U8StreamUrl (or sharedLiveVideoStreamUrl) to the browser. Keep the API key out of client code.

Recorded video access

To export recorded footage as a clip, use the public clip API. Clip creation is asynchronous:

Call POST /api/video/spliceV3 with the cameras and time range you want. Provide deviceUuids (array), startTimeMillis (epoch milliseconds), and durationSec. Set audioIncluded: true to mux in audio from an associated audio gateway. The response returns a clipUuid.
Poll POST /api/event/getClipsWithProgress to track processing — each clip reports percentComplete and status — and retrieve the finished clip once it is ready.

cURLbash

# 1. Request a clip for a time range
curl -X POST \
  "https://api2.rhombussystems.com/api/video/spliceV3" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "deviceUuids": ["CAMERA_UUID"],
    "startTimeMillis": 1700000000000,
    "durationSec": 60,
    "title": "Incident clip"
  }'

cURLbash

# 2. Poll for progress until the clip is ready
curl -X POST \
  "https://api2.rhombussystems.com/api/event/getClipsWithProgress" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

As a convenience, the Rhombus CLI can also play recorded footage and download alert clips without wiring up this flow yourself:

bash

# Open a camera's recorded footage in your browser, starting an hour ago
rhombus footage CAMERA_UUID --start "1h ago"

# Download the clip associated with a specific alert
rhombus alert download ALERT_UUID --output alert.mp4

For alert-driven workflows, configure a webhook to deliver alert events to your service, then create a clip for the alert's time range.

To list recent alerts programmatically, use POST /api/event/getPolicyAlerts — the previous getPolicyAlertsV2 endpoint is deprecated.

Complete implementation example

A React component supporting both thumbnail and live-stream view types. Your API key stays on your backend, which serves three routes, each wrapping one Rhombus call: /api/camera-states (getMinimalCameraStateList), /api/federated-token (generateFederatedSessionToken, as in Federated tokens, returning the mint response with its expiresAtMs; durationSec defaults to one hour and can't exceed 24 hours) and /api/shared-stream (createSharedLiveVideoStream):

jsx

import React, { useEffect, useRef, useState, useCallback } from 'react';

const RhombusCameraViewer = ({
  cameraUuid,
  viewType = 'thumbnail', // 'thumbnail' | 'stream'
  autoRefresh = true,
  refreshInterval = 5000,
  streamOptions = {},
  width = "100%",
  height = "400px"
}) => {
  const [thumbnailUrl, setThumbnailUrl] = useState(null);
  const [streamUrl, setStreamUrl] = useState(null);
  const [cameraDetails, setCameraDetails] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState(null);
  const lastObjectUrl = useRef(null);

  const getCameraDetails = useCallback(async () => {
    // Your backend calls getMinimalCameraStateList with its API key
    const response = await fetch('/api/camera-states', { method: 'POST' });

    if (!response.ok) throw new Error('Failed to list cameras');
    const data = await response.json();
    const camera = (data.cameraStates || []).find(c => c.uuid === cameraUuid);
    if (!camera) throw new Error('Camera not found');
    return camera;
  }, [cameraUuid]);

  // Your backend mints a short-lived federated token for this camera and
  // returns the mint response, including expiresAtMs
  const getFederatedToken = useCallback(async () => {
    const response = await fetch('/api/federated-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ cameraUuid })
    });
    if (!response.ok) throw new Error('Failed to get a token');
    const { federatedSessionToken, expiresAtMs } = await response.json();
    return { token: federatedSessionToken, expiresAtMs };
  }, [cameraUuid]);

  const loadThumbnail = useCallback(async (camera, token) => {
    const auth = `x-auth-scheme=federated-token&x-auth-ft=${encodeURIComponent(token)}`;
    const response = await fetch(
      `https://media.rhombussystems.com/media/${camera.uuid}/${camera.mediaRegion}/snapshot.jpeg?${auth}`,
      { cache: 'no-store' }
    );
    if (!response.ok) throw new Error('Failed to load thumbnail');

    const blob = await response.blob();
    const url = URL.createObjectURL(blob);
    if (lastObjectUrl.current) URL.revokeObjectURL(lastObjectUrl.current);
    lastObjectUrl.current = url;
    setThumbnailUrl(url);
  }, []);

  const createSharedStream = useCallback(async () => {
    // Your backend creates the share with its API key and returns the response
    const response = await fetch('/api/shared-stream', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ cameraUuid })
    });
    if (!response.ok) throw new Error('Failed to create shared stream');

    const data = await response.json();
    const url = new URL(data.sharedLiveVideoStreamUrl);
    Object.entries(streamOptions).forEach(([key, value]) => {
      url.searchParams.set(key, value);
    });
    setStreamUrl(url.toString());
  }, [cameraUuid, streamOptions]);

  useEffect(() => {
    let cancelled = false;
    let interval = null;

    (async () => {
      try {
        setIsLoading(true);
        const camera = await getCameraDetails();
        if (cancelled) return;
        setCameraDetails(camera);

        if (viewType === 'thumbnail') {
          let auth = await getFederatedToken();
          await loadThumbnail(camera, auth.token);
          if (autoRefresh) {
            interval = setInterval(async () => {
              try {
                // Mint a new token a minute before this one expires
                if (Date.now() > auth.expiresAtMs - 60_000) auth = await getFederatedToken();
                await loadThumbnail(camera, auth.token);
              } catch (err) {
                setError(err.message);
              }
            }, refreshInterval);
          }
        } else if (viewType === 'stream') {
          await createSharedStream();
        }

        setError(null);
      } catch (err) {
        if (!cancelled) setError(err.message);
      } finally {
        if (!cancelled) setIsLoading(false);
      }
    })();

    return () => {
      cancelled = true;
      if (interval) clearInterval(interval);
      if (lastObjectUrl.current) {
        URL.revokeObjectURL(lastObjectUrl.current);
        lastObjectUrl.current = null;
      }
    };
  }, [viewType, autoRefresh, refreshInterval, getCameraDetails, getFederatedToken, loadThumbnail, createSharedStream]);

  if (error) {
    return (
      <div style={{ padding: '20px', border: '1px solid #ff6b6b', borderRadius: '4px' }}>
        <p>Error: {error}</p>
      </div>
    );
  }

  if (isLoading) {
    return <div style={{ padding: '20px', textAlign: 'center' }}>Loading camera...</div>;
  }

  return (
    <div style={{ width, height }}>
      {viewType === 'thumbnail' && thumbnailUrl && (
        <img
          src={thumbnailUrl}
          alt={cameraDetails?.name || `Camera ${cameraUuid}`}
          style={{ width: '100%', height: '100%', objectFit: 'cover' }}
        />
      )}
      {viewType === 'stream' && streamUrl && (
        <iframe
          src={streamUrl}
          width="100%"
          height="100%"
          frameBorder="0"
          allow="fullscreen"
          title={`Camera ${cameraUuid} Stream`}
        />
      )}
    </div>
  );
};

export default RhombusCameraViewer;

Usage examples

jsx

// Thumbnail view with auto-refresh
<RhombusCameraViewer
  cameraUuid="your-camera-uuid"
  viewType="thumbnail"
  autoRefresh={true}
  refreshInterval={3000}
  width="640px"
  height="480px"
/>

// Live stream with custom options
<RhombusCameraViewer
  cameraUuid="your-camera-uuid"
  viewType="stream"
  streamOptions={{
    disableautoplay: 'false',
    hideevents: 'false',
    realtime: 'true',
    showheader: 'true',
    showfooter: 'true'
  }}
  width="100%"
  height="600px"
/>

Best practices

Performance optimization

Thumbnail caching: Cache thumbnails client-side and refresh on a sensible interval rather than polling continuously.
Lazy loading: Load video content only when needed or when in viewport.
Quality selection: Use lowRes=true on the iframe player for grids and dashboards.

Security considerations

Keep API keys server-side: Never expose x-auth-apikey in browser code. Call createSharedLiveVideoStream from your backend and pass only the resulting URLs to the client. For thumbnails and frames in the browser, use a federated token.
Keep federated tokens short-lived: Mint them for minutes or hours (never more than 24 hours), read expiresAtMs from the mint response, and mint a new one before it passes. Revoke a token you no longer need with POST /api/org/revokeFederatedSessionToken.
HTTPS only: Always use HTTPS for API calls and shared stream URLs.
Scope keys narrowly: Limit each API key to the minimum permissions required.
Set expirations on shared streams: Pass expirationTimeSecs, the Unix time in seconds when the link stops working (not a duration), so URLs don't outlive the use case. Without it, a shared link never expires.

Error handling

javascript

class RhombusVideoError extends Error {
  constructor(message, code, cameraUuid) {
    super(message);
    this.name = 'RhombusVideoError';
    this.code = code;
    this.cameraUuid = cameraUuid;
  }
}

async function fetchWithRetry(url, init, retries = 3) {
  for (let attempt = 1; attempt <= retries; attempt++) {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), 10000);
    try {
      const response = await fetch(url, { ...init, signal: controller.signal });
      clearTimeout(timer);
      if (!response.ok) {
        throw new RhombusVideoError(`HTTP ${response.status}`, response.status, init?.cameraUuid);
      }
      return response;
    } catch (error) {
      clearTimeout(timer);
      if (attempt === retries) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

Accessibility

jsx

<video
  controls
  aria-label={`Live feed from camera ${cameraName}`}
  poster={thumbnailUrl}
>
  <track kind="captions" src="captions.vtt" srcLang="en" label="English" />
  Your browser does not support the video tag.
</video>

Troubleshooting

Thumbnail not loading

Verify cameraUuid and mediaRegion came from a recent getMinimalCameraStateList response — mediaRegion can change.
Check that the credential's role has access to the camera's location.
In a browser, check the token: an expired or revoked federated token gets 401, and a token minted with domain gets 403 DOMAIN_NOT_ALLOWED on pages from any other origin.
Confirm the camera is online (connectionStatus in the camera state response).

Stream connection failures

Check network connectivity to *.rhombussystems.com.
For HLS playback, confirm the browser supports HLS natively or that hls.js is loaded.
Inspect firewall/proxy rules — corporate proxies frequently block media segment requests.

Poor video quality

Pass lowRes=true for bandwidth-constrained clients.
Check upstream bandwidth at the camera site.

Next steps

Video Player

Build a custom video player with HLS playback and timeline controls.

LAN Realtime Detection

Parse AI bounding boxes from the LAN H.264 WebSocket stream and overlay them on live video.

Streaming over LAN

Stream live video, recorded footage, and audio directly from devices on your network.

Backup Footage

Download and archive camera footage to local storage.