How Tos

Hacer blackout o sustituir el programa de un Live stream

Pasa a un frame negro, sustituye la salida con un fichero de medios o vuelve a la entrada en directo — sin detener la emisión.

Available in: UI · API

Usa este how-to cuando un Live stream en emisión deba dejar temporalmente de mostrar la entrada en directo — por una pausa no prevista, un evento de cumplimiento o una pizarra planificada. La operación de runtime es runtimeApplyBlackout; persiste el cambio y el encoder lo aplica en unos segundos.

Cuándo usar esto

Cuando la entrada en directo debe sustituirse por un frame negro o un fichero estático (slate, pizarra, sustitución por derechos), y luego reanudarse limpiamente. El blackout también soporta la opción Keep input audio during blackout que preserva el audio en directo mientras solo se sustituye el vídeo — para broadcasts de radio-como-vídeo, consulta Emitir radio como vídeo para el recorrido completo.

Prerrequisitos

Un Live stream actualmente en emisión (LiveStream.status = 2).
Un usuario con rol Operator o System Administrator.
El video codec del Encoding del Live stream es H.264, HEVC, o logo. La UI deshabilita la pestaña Blackout en otros codecs y la API rechaza la llamada. El codec logo produce vídeo H.264 por debajo, así que funciona con Blackout igual que H.264 — combinado con la opción Keep input audio during blackout abajo, habilita el patrón radio-como-vídeo.
Si vas a sustituir la salida por un fichero (mode = File): un Asset cuyo filename sea accesible para el encoder. Lista los assets candidatos con listAssets({ fileType: "files" }).

Compatibilidad — cuándo Blackout no está disponible

La UI deshabilita la pestaña Blackout cuando se cumple una de estas condiciones. El código de razón lo calcula RuntimeOperations.vue:

Código	Significado
`invalid_codec`	El video codec del Encoding enlazado no es H.264 ni HEVC.
`hevc_above_1080p`	El Encoding es HEVC por encima de 1080p. El relay de blackout corrompe el stream en esa combinación.
`hevc_hdr`	El Encoding es HEVC con HDR activo.
`hevc_hdr_above_1080p`	El Encoding es HEVC con HDR y por encima de 1080p.

Para usar Blackout en una escala HEVC UHD, baja la resolución del Encoding a 1080p o cambia el codec a H.264.

Via UI

Navegación: On air → <fila> → pestaña Blackout del panel de runtime.

Abre el panel de runtime

Pulsa la fila del Live stream en emisión en On air para desplegar su panel de runtime.

Cambia a la pestaña Blackout

Pulsa el icono Blackout (blackout.svg) en el cluster de runtime. El panel Blackout se renderiza inline; si el Live stream está en una configuración no soportada, el panel muestra el mensaje correspondiente en su lugar.

Elige el modo

Modo UI	Valor API	Efecto
Live	`Live`	Vuelve a la entrada en directo. Úsalo para salir de un blackout.
Black frame	`BlackFrame`	Sustituye la salida por un frame negro.
File	`File`	Sustituye la salida por el fichero de medios elegido (filename del asset obligatorio).

(Opcional) Conserva el audio en directo

Marca el checkbox Keep input audio during blackout para preservar el audio en directo del Channel de entrada mientras solo se sustituye el vídeo. El encoder genera el slate vídeo-only y el publish loop reenvía el audio en directo sin tocar. Útil para broadcasts de radio-como-vídeo y para situaciones de cumplimiento donde la locución debe continuar mientras el vídeo está retenido.

El checkbox está habilitado en los modos BlackFrame y File; se oculta en modo Live (volver al input en directo restaura siempre vídeo y audio).

Envía

Envía. El nuevo estado aparece en la salida en unos segundos.

Via API

Acción	Método + ruta	operationId
Aplicar blackout	`POST /c21apiv2/livestreams/{id}/runtimeOptions/blackout`	`runtimeApplyBlackout`

Frame negro:

curl -X POST "https://<tu-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/blackout" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "BlackFrame" }'

Sustituir con un fichero:

curl -X POST "https://<tu-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/blackout" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "File", "file": "intro_slate.mp4" }'

Volver a la entrada en directo:

curl -X POST "https://<tu-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/blackout" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "Live" }'

Sustituir solo el vídeo (conservar el audio en directo):

curl -X POST "https://<tu-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/blackout" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "File", "file": "weather_map.mp4", "keep_input_audio": true }'

Cuerpo:

Campo	Notas
`mode`	Uno de `Live`, `BlackFrame`, `File`. El alias aceptado-pero-obsoleto `Black Frame` (con espacio) se preserva por compatibilidad; las integraciones nuevas usan `BlackFrame`.
`file`	Obligatorio cuando `mode = File`. El handler rechaza la petición con `APIf517` si `file` se omite, contiene un separador de ruta o no se encuentra en disco.
`keep_input_audio`	Booleano opcional. Aplica en cualquier modo distinto de `Live`. Cuando es `true`, el slate se genera vídeo-only y el audio en directo del Channel se reenvía sin tocar. Por defecto `false` (el slate lleva vídeo y audio — comportamiento legacy). La idempotencia tiene en cuenta el flag — `(BlackFrame, false)` → `(BlackFrame, true)` es una transición real, no un skip.

Datos de respuesta. { mode, file, keep_input_audio, applied_at, changed, warning? }. changed: false significa que el broadcast ya estaba en el estado pedido (skip idempotente). warning aparece solo cuando el encoder no confirmó a tiempo; el nuevo estado queda persistido y el encoder reconcilia por sí mismo.

Verificar

La fila del Live stream en On air refleja el nuevo estado.
Un GET /c21apiv2/livestreams/{livestreamId}/status posterior devuelve el estado de blackout actualizado.
El siguiente keyframe de la salida lleva el nuevo programa.

FAQ

Hasta que vuelvas a llamar a la operación con mode = Live (o se pare el Live stream). El estado queda persistido en el broadcast.

El handler rechaza la llamada con APIf517 "With File mode of blackout must be select a file" y el broadcast mantiene su modo actual. Sube el fichero al encoder por el flujo estándar de Assets antes de reintentar.

El relay de blackout corrompe los streams HEVC por encima de 1080p o con HDR activo. La UI expone esto con los códigos hevc_above_1080p, hevc_hdr o hevc_hdr_above_1080p. Para usar Blackout, baja la resolución del Encoding a 1080p o cambia el codec a H.264.

Aplicar un logo a un Live stream en emisión

Pon o quita el logo de un Live stream mientras está al aire, sin detener la emisión.

Cambiar la fuente de un Live stream en emisión

Apunta un Live stream en emisión a un Channel distinto sin detener el broadcast.