Superposición de detección en tiempo real por LAN

Descripción general

El stream de video WebSocket del agente LAN incrusta los resultados de detección de IA directamente en el encabezado de encapsulación H.264. Cuando el pipeline de inferencia en la cámara produce una nueva detección, esta se inserta como un campo TLV en el siguiente frame de video saliente del mismo WebSocket — sin un canal de detección separado.

Esta guía cubre:

• El formato de encapsulación TLV y el esquema JSON dentro del campo AI_DETECTIONS
• La conexión al WebSocket H.264 por LAN en vivo y la lectura tanto de los frames binarios como del mensaje de texto de inicialización
• El dibujo de cuadros de detección sobre RhombusRealtimePlayer usando un WebSocket paralelo solo de detección
• Una referencia de parser desde cero para consumidores que no usan React

Conexión al stream en tiempo real por LAN

Obtener la URL del WebSocket

Llama a POST /api/camera/getMediaUris y lee:

• lanLiveH264Uris (array de strings) — URLs de LAN, cuando el cliente y la cámara comparten una red
• wanLiveH264Uri (string) — URL de WAN, enrutada a través de Rhombus

Para la variante de menor resolución, cambia /ws por /wsl en la ruta.

Autenticar

Ambos modos usan un token de sesión federada generado en tu backend mediante POST /api/org/generateFederatedSessionToken. Nunca pongas tu clave de API en el código del navegador.

Genera el token con un durationSec que no supere lo que necesita la sesión de visualización (una hora de forma predeterminada, 24 horas como máximo) y lee expiresAtMs en la respuesta de generación: abre la siguiente conexión con un token nuevo generado antes de ese momento. Si el token se revoca, o se elimina la clave de API que lo generó, un socket WAN abierto se cierra con el código 1008 en 60 segundos o menos.

El ejemplo completo de backend para generar tokens (Express, FastAPI, Next.js) está en la guía del React SDK — reutilízalo. Para la autenticación con encabezados, los tokens limitados a un dispositivo y otros streams LAN, consulta Streaming por LAN.

Qué envía el servidor

Inmediatamente después de la actualización del WebSocket y antes de cualquier frame binario, el servidor envía un único mensaje de texto que describe el stream:

{"action":"init","width":1920,"height":1080,"codec":"h264","framerate":15}

Lee las dimensiones si tu renderizador necesita la resolución de origen. Los cuadros delimitadores son independientes de la resolución (unidades permyriad), por lo que la mayoría de las superposiciones no lo necesitan.

Después del mensaje de inicialización, cada mensaje posterior es un frame binario que contiene el encabezado de encapsulación codificado en TLV seguido de los datos NAL H.264 sin procesar.

Encabezado de encapsulación (formato TLV)

Cada mensaje binario contiene una secuencia de TLVs. Cada TLV usa el mismo formato de cable:

[1 byte type] [3 bytes length, big-endian] [N bytes value]

Tipos de TLV

Disposición de cable

┌──────────────────────────────────────────────────┐
│ TIMESTAMP (0x02): 4 + 8 = 12 bytes               │  always present
├──────────────────────────────────────────────────┤
│ PTS_US (0x03): 4 + 8 = 12 bytes                  │  optional
├──────────────────────────────────────────────────┤
│ AI_DETECTIONS (0x04): 4 + N bytes                │  only when a new
│                                                  │  detection is available
├──────────────────────────────────────────────────┤
│ frame-data (0x00 or 0x01): 4 + N bytes           │  always last;
│                                                  │  value is raw H.264
└──────────────────────────────────────────────────┘

El TLV de datos de frame (0x00 o 0x01) es siempre la última entrada — el codificador del agente LAN inserta explícitamente los TLVs de metadatos antes de la entrada de frame. Un parser seguro deja de recorrer los TLVs en cuanto encuentra un tipo de datos de frame.

Análisis del encabezado de encapsulación

Recorre los campos TLV hasta que llegues al tipo 0x00 o 0x01 (la entrada de datos de frame):

type ParsedFrame = {
  timestampMs: number | null;
  ptsUs: number | null;
  detectionJson: string | null;
  isKeyframe: boolean;
  h264Data: Uint8Array;
};

export function parseEncapHeader(buffer: ArrayBuffer): ParsedFrame {
  const view = new DataView(buffer);
  const bytes = new Uint8Array(buffer);
  let offset = 0;
  let timestampMs: number | null = null;
  let ptsUs: number | null = null;
  let detectionJson: string | null = null;

  while (offset + 4 <= buffer.byteLength) {
    const type = view.getUint8(offset);
    const len =
      (view.getUint8(offset + 1) << 16) |
      (view.getUint8(offset + 2) << 8) |
      view.getUint8(offset + 3);
    const valueStart = offset + 4;

    if (type === 0x00 || type === 0x01) {
      return {
        timestampMs,
        ptsUs,
        detectionJson,
        isKeyframe: type === 0x00,
        h264Data: bytes.subarray(valueStart, valueStart + len),
      };
    }

    if (type === 0x02) {
      const hi = view.getUint32(valueStart);
      const lo = view.getUint32(valueStart + 4);
      timestampMs = hi * 0x100000000 + lo;
    } else if (type === 0x03) {
      const hi = view.getUint32(valueStart);
      const lo = view.getUint32(valueStart + 4);
      ptsUs = hi * 0x100000000 + lo;
    } else if (type === 0x04) {
      detectionJson = new TextDecoder().decode(
        bytes.subarray(valueStart, valueStart + len)
      );
    }
    // Unknown types are skipped silently.

    offset = valueStart + len;
  }

  throw new Error("Encapsulation header missing frame-data TLV");
}

El React SDK de Rhombus usa un parser equivalente en parseRhombusH264Binary.ts — la referencia canónica del lado del cliente.

Esquema JSON de detección

AI_DETECTIONS transporta un array JSON de objetos de detección. Los objetos de detección no llevan un timestamp propio — todas las detecciones de un mensaje se analizaron a partir del mismo frame, así que usa el TLV TIMESTAMP (tipo 0x02) del frame envolvente como hora de análisis.

Campos obligatorios

Campos opcionales

Ejemplo

[
  {
    "t": 0,
    "c": 8500,
    "id": 3,
    "b": [1200, 3400, 4500, 8900],
    "rs": 2.5,
    "clr": {"red": 4000, "blue": 6000},
    "tight_crop_xxyy": [1500, 4200, 3700, 8500]
  }
]

Dibujo de cuadros delimitadores en un canvas

Las coordenadas de los cuadros delimitadores son permyriad (0–10000) e independientes de la resolución. Conviértelas a píxeles usando las dimensiones del canvas:

const TYPE_COLORS = {
  0: "#00ff00", // Human    — green
  1: "#0088ff", // Vehicle  — blue
  2: "#ff00ff", // Face     — magenta
  3: "#ffff00", // LPR      — yellow
  4: "#00ffff", // Pose     — cyan
  5: "#ff8800", // CLIP     — orange
};

const TYPE_LABELS = ["Human", "Vehicle", "Face", "LPR", "Pose", "CLIP"];

export function drawDetections(ctx, canvasWidth, canvasHeight, detections) {
  ctx.clearRect(0, 0, canvasWidth, canvasHeight);

  for (const det of detections) {
    const [left, top, right, bottom] = det.b;
    const x = (left / 10000) * canvasWidth;
    const y = (top / 10000) * canvasHeight;
    const w = ((right - left) / 10000) * canvasWidth;
    const h = ((bottom - top) / 10000) * canvasHeight;

    ctx.strokeStyle = TYPE_COLORS[det.t] ?? "#ffffff";
    ctx.lineWidth = 2;
    ctx.strokeRect(x, y, w, h);

    const conf = Math.round(det.c / 100);
    const label = `${TYPE_LABELS[det.t] ?? "Unknown"} ${conf}% #${det.id}`;
    ctx.fillStyle = ctx.strokeStyle;
    ctx.font = "12px monospace";
    ctx.fillText(label, x, Math.max(10, y - 4));
  }
}

Para un canvas de 1280×720 y b: [1200, 3400, 4500, 8900], esto produce (x=153.6, y=244.8, w=422.4, h=396.0).

Comportamiento de temporización

• Las detecciones no están presentes en cada frame. El pipeline de IA analiza un subconjunto de frames (normalmente 2–10 fps). La mayoría de los frames no llevan un TLV AI_DETECTIONS.
• Las detecciones no llevan un timestamp propio. Alinea cada conjunto de detecciones según el TLV TIMESTAMP (tipo 0x02) del frame envolvente — la marca de tiempo en milisegundos del reloj de pared del servidor que el codificador escribe para ese frame. Como el pipeline de inferencia en la cámara y el codificador se ejecutan de forma independiente, una detección viaja en el frame que salga del codificador a continuación y puede corresponder a un frame capturado un poco antes; el stream no expone ese desfase, así que el TIMESTAMP del frame portador es el punto de referencia a usar, especialmente para VOD o reproducción con búfer.
• Persiste entre actualizaciones. Para mantener los cuadros visibles entre actualizaciones de detección, conserva el conjunto más reciente y sigue redibujándolo hasta que llegue un conjunto más nuevo o transcurra un TTL. Un TTL de 2 segundos es un valor predeterminado seguro.

Extender RhombusRealtimePlayer con renderizado de detecciones

El RhombusRealtimePlayer del React SDK no expone actualmente las detecciones de IA a la aplicación anfitriona. Hasta que lo haga, el patrón más sencillo es abrir un segundo WebSocket a la misma URL únicamente para leer AI_DETECTIONS, y dibujar el resultado en un <canvas> superpuesto sobre el reproductor.

import { RhombusRealtimePlayer } from "@rhombussystems/react";
import { useEffect, useRef, useState } from "react";
import { parseEncapHeader } from "./parseEncapHeader"; // from earlier in this guide
import { drawDetections } from "./drawDetections";     // from earlier in this guide

type Props = {
  cameraUuid: string;
  /** WebSocket URL for this camera (from getMediaUris + auth append) */
  detectionWsUrl: string;
  /** Optional: how long to keep boxes after the last update */
  detectionTtlMs?: number;
};

export function RhombusRealtimePlayerWithDetections({
  cameraUuid,
  detectionWsUrl,
  detectionTtlMs = 2000,
}: Props) {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const detectionsRef = useRef<any[]>([]);
  const lastTsRef = useRef(0);
  const [size, setSize] = useState({ width: 1920, height: 1080 });

  useEffect(() => {
    const ws = new WebSocket(detectionWsUrl);
    ws.binaryType = "arraybuffer";

    ws.onmessage = (event) => {
      // The server sends one text init message before any binary frames.
      if (typeof event.data === "string") {
        try {
          const init = JSON.parse(event.data);
          if (init.action === "init" && init.width && init.height) {
            setSize({ width: init.width, height: init.height });
          }
        } catch {
          // Ignore non-JSON text messages.
        }
        return;
      }

      try {
        const { detectionJson } = parseEncapHeader(event.data);
        if (!detectionJson) return;
        const dets = JSON.parse(detectionJson);
        detectionsRef.current = dets;
        lastTsRef.current = Date.now();
      } catch (err) {
        console.warn("Failed to parse encap header", err);
      }
    };

    return () => ws.close();
  }, [detectionWsUrl]);

  useEffect(() => {
    let raf = 0;

    const tick = () => {
      const canvas = canvasRef.current;
      if (canvas) {
        const ctx = canvas.getContext("2d");
        if (ctx) {
          const fresh = Date.now() - lastTsRef.current < detectionTtlMs;
          drawDetections(
            ctx,
            canvas.width,
            canvas.height,
            fresh ? detectionsRef.current : []
          );
        }
      }
      raf = requestAnimationFrame(tick);
    };

    raf = requestAnimationFrame(tick);
    return () => cancelAnimationFrame(raf);
  }, [detectionTtlMs]);

  return (
    <div style={{ position: "relative", width: size.width, height: size.height }}>
      <RhombusRealtimePlayer
        cameraUuid={cameraUuid}
        connectionMode="wan"
      />
      <canvas
        ref={canvasRef}
        width={size.width}
        height={size.height}
        style={{
          position: "absolute",
          inset: 0,
          width: "100%",
          height: "100%",
          pointerEvents: "none",
        }}
      />
    </div>
  );
}

Resuelve detectionWsUrl en tu backend de la misma forma que lo hace el SDK: llama a getMediaUris, elige el wanLiveH264Uri o la entrada de LAN adecuada, luego agrega ?x-auth-scheme=federated-token&x-auth-ft=<TOKEN> (tanto WAN como LAN) antes de pasar la URL al navegador.

Referencia de parser desde cero

Para clientes que no usan React (una página web pura, Node, Electron), el mismo parser impulsa una superposición mínima. Decodificar el H.264 en sí requiere WebCodecs (navegador) o ffmpeg/libav (Node) y queda fuera del alcance, pero leer las detecciones del WebSocket solo necesita el parser anterior:

<canvas id="overlay" width="1920" height="1080"
  style="position:absolute; inset:0; pointer-events:none;"></canvas>

<script type="module">
  import { parseEncapHeader } from "./parseEncapHeader.js";
  import { drawDetections } from "./drawDetections.js";

  // Resolve detectionWsUrl from your backend after calling
  // /api/camera/getMediaUris and appending the federated token.
  const ws = new WebSocket(detectionWsUrl);
  ws.binaryType = "arraybuffer";

  const canvas = document.getElementById("overlay");
  const ctx = canvas.getContext("2d");
  let lastDetections = [];
  let lastTs = 0;
  const TTL_MS = 2000;

  ws.onmessage = (event) => {
    if (typeof event.data === "string") return; // skip init handshake
    const { detectionJson } = parseEncapHeader(event.data);
    if (!detectionJson) return;
    lastDetections = JSON.parse(detectionJson);
    lastTs = Date.now();
  };

  function tick() {
    const fresh = Date.now() - lastTs < TTL_MS;
    drawDetections(ctx, canvas.width, canvas.height, fresh ? lastDetections : []);
    requestAnimationFrame(tick);
  }
  requestAnimationFrame(tick);
</script>

Streams HTTP vs WebSocket

La variante de stream HTTP video/h264 elimina por completo el encabezado de encapsulación y entrega únicamente datos NAL H.264 sin procesar. Las detecciones viajan solo por el transporte WebSocket. Usa las URLs de WebSocket de getMediaUris (lanLiveH264Uris / wanLiveH264Uri) para cualquier flujo que necesite detecciones.

Solución de problemas

Los cuadros aparecen en la ubicación incorrecta

Las coordenadas de bbox son permyriad (0–10000), no píxeles y no 0–1. Asegúrate de que el renderizador divida entre 10000 antes de multiplicar por las dimensiones del canvas.

Los cuadros parecen retrasarse respecto al video

Las detecciones no tienen un timestamp propio — alinea cada conjunto según el TLV TIMESTAMP (tipo 0x02) del frame envolvente. La detección viaja en el frame que salga del codificador a continuación, por lo que puede ir un poco por detrás del frame analizado; el TIMESTAMP del frame portador es el único punto de referencia de temporización que ofrece el stream.

Los cuadros desaparecen durante unos cientos de milisegundos y luego reaparecen

El pipeline de IA produce resultados a 2–10 fps y las detecciones no viajan en cada frame de video. Conserva el conjunto de detección más reciente con un TTL (p. ej. 2 s) para que la superposición se mantenga estable entre actualizaciones.

El receptor solo recibe frames binarios; nunca ve el mensaje de inicialización

Confirma que tu manejador de WebSocket acepte frames de texto antes que los frames binarios. La inicialización es un único mensaje de texto que se envía una vez por conexión.

La autenticación en LAN falla localmente

La autenticación en LAN se agrega a la URL del WebSocket como parámetros de consulta (igual que en WAN), por lo que funciona desde cualquier origen, incluido localhost. Si LAN falla, la causa habitual es la accesibilidad de red: el navegador debe alcanzar directamente el host de LAN de la cámara (se aplican reglas de enrutamiento, firewall y de contenido mixto HTTPS-vs-HTTP). Si el host de LAN no es accesible, conéctate por WAN en su lugar, o usa un proxy a través de tu backend.

Próximos pasos