On air

La vista On air es la lista en runtime de cada Live stream actualmente en emisión. Cada fila conecta un Channel, un Encoding (o Encoding group) y un Destination (o Destination group). Al seleccionar una fila se expande un panel de runtime con cinco pestañas — Destinations, Preview, Logo, Blackout, Source switch — que dirigen la superficie de control en tiempo de ejecución del broadcast sin detenerlo.

Para integradores, la misma superficie de runtime es accesible mediante ocho endpoints POST /c21apiv2/livestreams/{id}/runtimeOptions/*, incluyendo la inyección de metadatos para introducir cues SCTE-35 y etiquetas ID3 en un broadcast en emisión. Los ocho endpoints, los tres que son solo-API y la semántica de respuesta común se documentan al final de esta página.

Acceso

• Ruta: /liveStreams/onAir.
• Rol requerido: cualquier usuario autenticado (Operator o System Administrator).

Cómo se refresca la lista

La lista sondea el servidor cada 5 segundos. La cadencia está fijada por código — no hay un ajuste por usuario ni un botón de refresco manual. Las filas se filtran en servidor para mostrar:

• todo Live stream cuyo LiveStream.status sea 1 (en emisión), más
• todo broadcast C21 Live Cloud que aún esté aprovisionando su encoder en la nube (la fila aparece con el indicador de cloud hasta que el encoder esté disponible).

Un Live stream arrancado por el Scheduler muestra un icono de calendario junto al nombre del encoder en su fila.

Búsqueda

La barra superior expone un campo de búsqueda libre — escribe una subcadena y las filas se actualizan tras una pausa breve. La única clave de búsqueda es name — no hay chips de filtrado por estado, encoder, destino o tag.

Columnas de la lista

Seis columnas, en este orden:

Cuando un destino tiene ambas rutas primary y backup configuradas y el encoder reporta un problema upstream en una ruta que está activa, el tooltip de destino de la fila antepone el mensaje upstream con "Primary: " o "Backup: ".

Estado vacío

Cuando no hay Live streams en emisión y ningún broadcast cloud aprovisionándose, la página muestra:

No live streams running Start a live stream from the Live streams tab to see it here.

Selección de fila

Pulsa una fila para seleccionarla. Al seleccionar una fila se expande su panel de runtime debajo. Una segunda pulsación sobre la misma fila colapsa el panel. Solo una fila a la vez puede tener el panel desplegado.

Detener un Live stream

Desde On air solo se detienen Live streams en marcha; el arranque vive en la lista de Live streams.

La acción Stop muestra un diálogo distinto según si el broadcast se arrancó a mano o por el Scheduler.

Live stream normal.

Do you want to stop this Live stream?

Al confirmar, la UI desmonta el pipeline de preview (si estaba abierto) y detiene el broadcast.

Live stream programado.

Do you want to stop this Scheduled Live stream? The associated Schedule will be deleted.

Para un broadcast programado, confirmar borra además el Schedule activo — el broadcast lo mantenía el Scheduler, así que al eliminar el Schedule el broadcast se detiene como efecto colateral. La entrada del Scheduler desaparece tras esto; para recuperar la misma recurrencia, recréala desde el Scheduler.

Equivalente de la API pública. POST /c21apiv2/livestreams/{id}/stop (operationId stopLivestream). El endpoint público detiene el broadcast pero no toca ningún Schedule. Para detener un broadcast programado y eliminar su Schedule en un solo paso, replica el flujo de la UI: lista los Schedules del Live stream, borra el activo, y el broadcast se detiene como efecto colateral.

Panel de runtime por fila

Cuando se selecciona una fila, debajo se despliega un panel con cinco pestañas. El orden de las pestañas coincide con el orden de los iconos del cluster de runtime de la fila:

Cada pestaña se describe en su propio apartado a continuación.

Destinations — alternar primary / backup por destino

Alternar por Destination las rutas primary y backup en el broadcast en emisión.

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/publishings — operationId runtimeTogglePublishings.
• Cuerpo: { "toggles": [{ "entry_point_id": <id>, "primary": <bool>, "backup": <bool> }, …] }.
• División de capacidad. Un Destination con backup URL configurada (típicamente RTMP, SRT, FMS, HLS, IPTV y STREAM) tiene flags primary y backup independientes — ambos pueden estar a true a la vez. Un Destination de canal único cuya backup URL está vacía (Record, SDIOUT, STREAM sin backup) usa primary como on/off y acepta backup solo por simetría.
• Pertenencia en runtime. Los Destinations añadidos al Destination group enlazado mientras el broadcast emite aparecen aquí automáticamente — el panel se refresca cada pocos segundos — entrando apagados. Activa uno para engancharlo en directo, sin reinicio. Ver Editar un grupo en uso.
• Restricción. Solo el estado on/off es mutable mientras el broadcast emite. Para cambiar las renditions que emite un Destination o las pistas de audio que lleva, detén el Live stream con POST /c21apiv2/livestreams/{id}/stop, edítalo con PUT /c21apiv2/livestreams/{id} y arráncalo de nuevo.

Ver también: Activar / desactivar un Destination en mitad de la emisión.

Preview — visor embebido para operador

La pestaña Preview abre un visor embebido dentro del panel de runtime. El renderer lo arranca la UI y se desmonta cuando la pestaña se cierra o la fila se colapsa.

No forma parte de la API pública. El endpoint que sirve la preview se mantiene deliberadamente fuera del OpenAPI público — el contrato está reservado al visor en producto, donde la UI gestiona el ciclo de vida del renderer. Los integradores que necesiten una preview externa de un broadcast en emisión deben añadir un Destination real (HLS, DASH o uno de los destinos de streaming) sobre el Live stream y leerlo desde la URL publicada.

Logo — aplicar o quitar la superposición de logo

Aplicar o quitar un logo overlay en el broadcast en emisión.

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/logo — operationId runtimeApplyLogo.
• Cuerpo: { "logo": { "filename": "<filename de asset>", "position": "<LogoPosition>" } }.
• Valores de posición. Enum canónico: Center, Left, Right, Top, Bottom, Top-Left, Top-Right, Bottom-Left, Bottom-Right. El entero bitmask legacy se sigue aceptando en entrada por compatibilidad con la UI Vue; las respuestas usan la cadena canónica.
• Limpiar el logo. Envía filename vacío y conserva la position. La posición se preserva por si más tarde se quiere volver a aplicar el logo.
• Respuesta. Envelope estándar con data: null — las operaciones de runtime no devuelven el estado aplicado. Para confirmar el logo aplicado, llama a GET /c21apiv2/livestreams/{id} e inspecciona la propiedad Logo del Live stream.

La pestaña Logo usa el catálogo de Logos como fuente de filenames.

Ver también: Aplicar un logo a un Live stream en emisión.

Blackout — alternar entre directo, frame negro y fichero

Sustituye la salida en directo por un frame negro o un fichero estático, o vuelve al input en directo. El blackout puede opcionalmente preservar el audio en directo mientras solo se sustituye el vídeo — útil para broadcasts de radio-como-vídeo donde la pista visual cambia a lo largo del día pero el audio es siempre el input en directo (consulta Emitir radio como vídeo).

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/blackout — operationId runtimeApplyBlackout.
• Cuerpo: { "mode": "Live" | "BlackFrame" | "File", "file"?: "<filename>", "keep_input_audio"?: <bool> }.
• Live — vuelve al input en directo.
• BlackFrame — sustituye la salida por un frame negro.
• File — sustituye la salida por el fichero de medios referenciado en file; file es obligatorio en este modo.
• keep_input_audio — flag opcional, aplicable 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. Cuando se omite o es false, el slate lleva vídeo y audio (comportamiento legacy). La idempotencia tiene en cuenta este flag — cambiar de (BlackFrame, false) a (BlackFrame, true) es una transición real, no un skip.
• El alias aceptado-pero-obsoleto Black Frame (con espacio) se preserva en escritura por compatibilidad. Las integraciones nuevas usan BlackFrame.
• Código de error. Omitir file en modo File, incluir un separador de ruta o apuntar a un fichero que el encoder no puede leer devuelve APIf517.
• 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 estado queda persistido y el encoder reconcilia por sí mismo.

Compatibilidad. La UI deshabilita la pestaña Blackout con un mensaje de "no soportado" cuando el broadcast en emisión no puede aceptar un blackout. Razones que se exponen hoy:

Ver también: Hacer blackout o sustituir el programa de un Live stream.

Source switch — cambiar la entrada de un broadcast en emisión

Cambia el Channel de entrada del broadcast en emisión sin detener los Destinations.

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/sourceSwitch — operationId runtimeApplySourceSwitch.
• Cuerpo: { "channelId": <id entero del Channel> }.
• Respuesta. { channelId, applied_at, changed, warning? }. changed: false significa que el broadcast ya apuntaba a ese Channel. warning aparece solo cuando el encoder no confirmó a tiempo; el nuevo Channel queda persistido en el Live stream en emisión y el encoder reconcilia por sí mismo.

Reglas de elegibilidad. El backend aplica todas las reglas con HTTP 422. La UI las refleja para deshabilitar la pestaña cuando un cambio no es posible.

1. El Live stream está en emisión. LiveStream.status debe ser 1 (Live). Un broadcast detenido no se puede cambiar de fuente online — edita el Channel enlazado en la configuración del Live stream y arráncalo de nuevo.
2. El Channel destino es alcanzable desde el encoder que corre el broadcast. Un Channel anclado a otro Device falla con APIf526. Los valores virtuales de Channel.type — SRT, Stream, RTMP-Push, SRT Cloud, UDP-R Cloud, NDI y Youtube Live — no tienen anclaje a encoder y son alcanzables desde cualquier encoder.
3. El Channel destino tiene el mismo tipo de Channel que la fuente actual. Los cambios cruzando tipos (SRT → Youtube Live, Stream → NDI, …) no se soportan online y fallan con APIf527. Para cambiar de tipo, detén el broadcast, edita el Channel enlazado y arráncalo de nuevo.
4. El tipo de la fuente actual es uno de los soportados online. Valores soportados de Channel.type como fuente actual: SRT, Stream, RTMP-Push, SRT Cloud, UDP-R Cloud, NDI, Youtube Live. No soportados: SDI, AES/EBU, File — un intento de cambio mientras uno de estos es la fuente en directo falla con APIf528.

La UI agrupa las tres variantes cloud-push (RTMP-Push, SRT Cloud, UDP-R Cloud) bajo la etiqueta umbrella Stream – C21 Live Cloud en el picker de Channel type; las comprobaciones de elegibilidad anteriores resuelven contra los valores reales del enum. Consulta Sources para el enum completo Channel.type.

Idempotencia. Hacer POST con el mismo channelId que ya está en directo devuelve 200 con changed: false y no genera tráfico al encoder.

Sin efecto sobre la fuente configurada. El switch solo escribe el espejo runtime de la fuente. Un stop y start posterior vuelve a la fuente configurada en el Live stream — para mantener el nuevo Channel tras un reinicio, edita también el Channel enlazado del Live stream.

Ver también: Cambiar la fuente de un Live stream en emisión.

Superficie API — todos los endpoints de runtime en una página

Ocho endpoints POST viven bajo /c21apiv2/livestreams/{livestreamId}/… y cubren tanto las opciones a nivel configuración (persistidas en el Live stream) como las operaciones solo-runtime que controlan un broadcast en emisión. La tabla siguiente las agrupa, da el operationId canónico y marca cuáles expone la UI — tres son solo-API y no tienen un caller UI de primera clase hoy.

Para la referencia API completa de cada endpoint consulta API → Live streams reference. Para la configuración persistida de logo, overlay y scte en tiempo de definición, consulta Live stream options.

Autenticación y roles

Cada endpoint de runtime requiere una sesión autenticada. La cabecera es el bearer estándar:

Authorization: Bearer <YOUR_API_TOKEN>

Los dos roles de producto que pueden mutar Live streams son System Administrator y Operator — ambos pueden llamar a todos los endpoints de runtime listados arriba. No hay scopes por endpoint más allá del gate de rol. Para el modelo de roles y cómo emitir tokens, consulta Autenticación.

Semántica de respuesta (compartida)

Dos endpoints — runtimeApplyBlackout y runtimeApplySourceSwitch — devuelven un envelope con dos campos que los integradores deben conocer:

• changed — false cuando el estado pedido ya coincidía con el persistido. La llamada es un skip idempotente y no se genera tráfico al encoder.
• warning — aparece solo cuando el encoder no confirmó a tiempo. El nuevo estado queda persistido en el Live stream y el encoder reconcilia por sí mismo; trata la respuesta como un éxito soft.

El resto de endpoints de runtime devuelven el envelope estándar con data: null (o, para runtimeTogglePublishings, un pequeño bloque de confirmación listando los entry points actualizados).

Inyección de metadatos — runtimePushMetadata

Inyecta un único evento de metadatos en un broadcast en emisión. El handler reenvía la carga al pipeline de metadatos del encoder y devuelve el envelope estándar con data: [] — la llamada es fire-and-forget y la carga inyectada no se devuelve.

• Endpoint: POST /c21apiv2/livestreams/{id}/runtimeOptions/metadata.
• Cuerpo:

{
  "type": "<uno de los ocho valores de type>",
  "metadata": { "name": "<string>", "value": "<string>" }
}

• Valores de type (exactamente ocho, sensibles a mayúsculas):

• Objeto metadata. Se serializa como name=value en el comando del encoder. Obligatorio para Metadata, CuePoint, DateRange e ID3Tag; opcional para los cuatro límites de cue (CueIn, CueOut, ScteIn, ScteOut).

Ejemplos.

Cue de ad para el player vía metadata genérica:

curl -X POST "https://<tu-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/metadata" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Metadata",
    "metadata": { "name": "adbreak", "value": "preroll-30s" }
  }'

Par splice SCTE-35 alrededor de una pausa publicitaria:

# entrar a la pausa
curl -X POST "https://<tu-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/metadata" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "type": "ScteOut" }'

# salir de la pausa
curl -X POST "https://<tu-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/metadata" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "type": "ScteIn" }'

Emisión de tag ID3 en HLS:

curl -X POST "https://<tu-host>/c21apiv2/livestreams/<livestreamId>/runtimeOptions/metadata" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ID3Tag",
    "metadata": { "name": "TXXX:show", "value": "evening-news" }
  }'

La inyección ocurre en el siguiente tick del encoder; el marcador aparece en el stream de salida en pocos segundos.

FAQ