Autenticar medios y transmisiones

Los medios (instantáneas, fotogramas, clips, video en vivo y grabado, audio) provienen de los hosts de medios, no de la API REST, y las URL que devuelve la API no llevan ninguna credencial. Tú agregas una a cada solicitud. Tres reglas cubren casi todo:

1. Desde tu servidor o una app nativa, envía tu clave de API como encabezados (x-auth-scheme: api-token y x-auth-apikey), o un access token de OAuth como Authorization: Bearer <token>.
2. Desde un navegador (un <img>, un <video>, un reproductor de JavaScript o un WebSocket), envía un token federado como parámetros de consulta: ?x-auth-scheme=federated-token&x-auth-ft=<token>. Las claves de API y los access tokens de OAuth no se pueden enviar en una URL.
3. Las cámaras de tu red local aceptan solo tokens federados. Es una decisión deliberada: en la red local, cada solicitud lleva un token de corta duración que puedes limitar a una cámara. Consulta Streaming por LAN.

Hosts

Las credenciales están vinculadas a una región: una clave o un token de EE. UU. no funciona en hosts de la UE.

Instantáneas y fotogramas exactos

La instantánea más reciente de una cámara:

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

cameraUuid y mediaRegion provienen de getMinimalCameraStateList.

curl "https://media.rhombussystems.com/media/CAMERA_UUID/MEDIA_REGION/snapshot.jpeg" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -o snapshot.jpeg

curl "https://media.rhombussystems.com/media/CAMERA_UUID/MEDIA_REGION/snapshot.jpeg" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -o snapshot.jpeg

<img src="https://media.rhombussystems.com/media/CAMERA_UUID/MEDIA_REGION/snapshot.jpeg?x-auth-scheme=federated-token&x-auth-ft=TOKEN" />

Para un fotograma en un momento específico, llama a getExactFrameUri (marcas de tiempo en milisegundos). La URI que devuelve no está firmada: solicítala con los mismos encabezados o, en un navegador, agrégale los mismos parámetros de consulta.

Descargas de clips guardados

Los clips guardados (de spliceV3 o de la consola) se descargan del host de medios según la región y el UUID del clip. Toma la región del clipLocation del clip:

curl "https://media.rhombussystems.com/media/metadata/{clipLocation.region}/{clipUuid}.mp4" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -o clip.mp4

Para reproducirlo en línea, usa en su lugar /media/play/{region}/{clipUuid}.mp4 (admite solicitudes Range). El rol de la credencial necesita permiso para ver video guardado. Un token federado limitado a un dispositivo puede obtener un clip guardado solo cuando todas las cámaras del clip son el dispositivo del token.

Video en vivo y grabado

POST /api/camera/getMediaUris devuelve las URL de transmisión de una cámara:

Llama a getMediaUris con la credencial que usará tu reproductor y luego autentica cada formato como se indica a continuación.

HLS

Agrega el token a la URL de la playlist. En los hosts de la nube, la playlist lleva los parámetros de consulta del token a cada URL de segmento, así que los reproductores no necesitan nada más:

const url = `${wanLiveM3u8Uri}?x-auth-scheme=federated-token&x-auth-ft=${token}`;
if (video.canPlayType("application/vnd.apple.mpegurl")) {
  video.src = url; // Safari
} else {
  const hls = new Hls();
  hls.loadSource(url);
  hls.attachMedia(video);
}

Desde una app nativa o un servidor, envía en su lugar los encabezados de la clave de API o Authorization: Bearer en cada solicitud.

DASH

Agrega el token a la URL del manifiesto. En los hosts de la nube, los manifiestos DASH en vivo y grabados (y los manifiestos de clips de alertas) llevan los parámetros de consulta del token a cada URL de segmento, así que una sola URL funciona en cualquier reproductor:

const url = `${wanLiveMpdUri}?x-auth-scheme=federated-token&x-auth-ft=${encodeURIComponent(token)}`;
const player = dashjs.MediaPlayer().create();
player.initialize(video, url, true);

Solo los parámetros de consulta de tokens federados y de enlaces compartidos se llevan a los segmentos. Las claves de API y x-auth-org nunca se copian en las URL de segmento, así que un cliente de servidor o nativo envía sus encabezados en cada solicitud.

Para las transmisiones desde una cámara de tu LAN, agrega tú mismo el token a cada solicitud. Con dash.js 5, un interceptor de solicitudes lo hace, y no modifica ninguna URL que ya lleve el token:

const auth = `x-auth-scheme=federated-token&x-auth-ft=${encodeURIComponent(token)}`;
const withAuth = (url) => (url.includes("x-auth-ft=") ? url : `${url}${url.includes("?") ? "&" : "?"}${auth}`);

const player = dashjs.MediaPlayer().create();
player.addRequestInterceptor((request) => {
  request.url = withAuth(request.url);
  return Promise.resolve(request);
});
player.initialize(video, lanLiveMpdUris[0], true);

WebSocket (H.264 y audio)

En un navegador, pon el token en la URL; desde un servidor o una app nativa, también funcionan los encabezados, igual que un access token de OAuth en Authorization: Bearer:

const ws = new WebSocket(`${wanLiveH264Uri}?x-auth-scheme=federated-token&x-auth-ft=${token}`);
ws.binaryType = "arraybuffer";

Un token generado con domain funciona aquí: los navegadores envían Origin en el handshake del WebSocket. Consulta El campo domain.

Los sockets de medios abiertos (video en vivo, audio bidireccional, robot y PTZ) se cierran con el código 1008 en un máximo de 60 segundos cuando se revoca su credencial o cambia su acceso. Con un token de OAuth, el audio bidireccional se verifica en cada mensaje, y enviar audio sin el scope physical cierra el socket con 1008 (Scopes de OAuth).

El socket en vivo del robot acepta claves de API, access tokens de OAuth y tokens federados de la misma forma.

Claves de partner

Un partner que llama desde un servidor a los medios de una organización cliente envía su credencial de partner como encabezados (x-auth-scheme: api-token con x-auth-apikey, o Authorization: Bearer con un token de OAuth de partner) más x-auth-org: <client org UUID>. x-auth-org es solo un encabezado y nunca se copia en las URL de segmento. Para un navegador, genera un token federado para la organización cliente (envía x-auth-org al generarlo).

Enlaces de transmisión compartida

createSharedLiveVideoStream crea un enlace al video en vivo de una cámara que funciona sin ninguna credencial de Rhombus:

• sharedLiveVideoStreamUrl abre una página de reproductor de Rhombus; insértala en un <iframe>.
• sharedLiveM3U8StreamUrl es una playlist HLS sin procesar para tu propio reproductor.

Cualquiera que tenga el enlace puede ver la transmisión, así que trátalo como una contraseña:

• expirationTimeSecs es el tiempo Unix (en segundos) en que el enlace deja de funcionar, no una duración. Si lo omites, el enlace nunca vence.
• Enlaces protegidos con contraseña (createProtectedSharedLiveVideoStream): la página del reproductor pide la contraseña; para la URL HLS sin procesar, envía Authorization: Basic <base64(":" + password)> (con un nombre de usuario vacío). Una contraseña faltante o incorrecta devuelve 401 con WWW-Authenticate: Basic.
• Elimina el enlace compartido (deleteSharedLiveVideoStream) para detenerlo de inmediato.

Solución de problemas