Self-hosting: video relay

​

How it works

RTSP source (camera / mediamtx on the agent)
  |
  v
ffmpeg -rtsp_transport tcp -c:v copy -an -f mp4 -movflags frag_keyframe+empty_moov+default_base_moof pipe:1
  |
  v
WebSocket binary frames  ->  browser MSE SourceBuffer

• Each device gets one ffmpeg process, started on the first viewer and stopped when the last viewer leaves. An idle relay runs no ffmpeg.
• The relay caches the stream’s init segment and replays it to a viewer that joins a running session.
• A viewer whose send backlog exceeds VIDEO_RELAY_MAX_BACKLOG is closed with code 1013 and reconnects.
• The GCS player reads the codec from the stream’s init segment, so H.264 profiles other than High play without changes.

​

Viewer tokens

• Convex mints tokens in the cmdVideoRelayTokens.mint action. It checks that the signed-in operator owns the paired device, then signs a token with VIDEO_RELAY_SECRET.
• A token has the form <exp>.<mac>: the expiry in Unix seconds and a hex HMAC-SHA256 of <deviceId>|<exp>. It lasts five minutes. The relay refuses tokens that are expired, dated more than ten minutes ahead, or scoped to another device.
• The token is checked once at upgrade. An open stream keeps running after the token expires.
• Pass it as ?token=<token> (a browser WebSocket cannot set headers) or as Authorization: Bearer <token>.

​

Configuration

​

Endpoints

• ws://<host>:3001/ws/stream/{deviceId}?token=<viewer token> opens a stream. The device ID must match [a-zA-Z0-9_-]+; anything else gets 400.
• A plain GET on any path is a liveness probe and returns only:
  {"status":"ok"}
  

​

Run locally

cd tools/video-relay
npm install
VIDEO_RELAY_SECRET="$(openssl rand -hex 32)" npm run dev

​

Deploy with Docker

cd tools/video-relay/deploy
cp .env.example .env

RTSP_URL_PATTERN=rtsp://host.docker.internal:8554/{deviceId}
PORT=3001
VIDEO_RELAY_SECRET=<openssl rand -hex 32>
CLOUDFLARE_TUNNEL_TOKEN=<your tunnel token>

docker compose up -d

npx convex env set VIDEO_RELAY_URL "wss://video.cloud.example.com" \
  --url <client-api-origin> --admin-key <admin-key>
npx convex env set VIDEO_RELAY_SECRET "<same value as .env>" \
  --url <client-api-origin> --admin-key <admin-key>

1. video-relay: the Node.js relay with ffmpeg.
2. cloudflared: a tunnel that exposes the relay on a public hostname. WebSocket upgrades pass through it with no extra configuration.

​

Browser client

const token = await convex.action(api.cmdVideoRelayTokens.mint, { deviceId: "drone1" });
const ws = new WebSocket(
  `wss://video.cloud.example.com/ws/stream/drone1?token=${encodeURIComponent(token.token)}`,
);
const mediaSource = new MediaSource();
const video = document.querySelector("video");
video.src = URL.createObjectURL(mediaSource);

mediaSource.addEventListener("sourceopen", () => {
  // Example codec: H.264 High 4.1. Read the real one from the init segment.
  const buf = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.640029"');
  ws.binaryType = "arraybuffer";
  ws.onmessage = (e) => {
    if (!buf.updating) {
      buf.appendBuffer(e.data);
    }
  };
});

​

Next steps