Planned actions

Una acción planificada (planned action) es una operación runtime de un solo disparo diferida a un instante fijo sobre un Live stream que ya está en emisión: activar o desactivar un Destination, aplicar o quitar un logo, entrar o salir de un blackout, cambiar la fuente de entrada, inyectar un valor de metadata o establecer los ad values.

Las acciones planificadas se componen con los Schedules en lugar de extenderlos: un Schedule decide cuándo un Live stream está en emisión; una acción planificada decide qué cambia durante esa ventana. Cada acción dispara como mucho una vez — no hay recurrencia. Para repetir una operación, crea varias acciones; un intervalo es una pareja (por ejemplo, un blackout de 10:00 a 10:30 es una acción blackout on a las 10:00 más una acción blackout off a las 10:30).

Cada acción es el equivalente diferido de una operación runtime que también puedes ejecutar de inmediato desde el panel de On air o sus endpoints runtimeOptions/* — mismos parámetros, mismo efecto, solo cambia el momento.

Qué puede hacer una acción

El selector Action del diálogo ofrece nueve operaciones. Cada una mapea 1:1 con un endpoint runtime disparado a la hora planificada:

Las acciones que cambian estado (Destinations, logo, blackout, source switch) se persisten en el Live stream al disparar — el estado aplicado sobrevive a un reinicio del encoder exactamente igual que la operación manual equivalente. Las acciones de metadata y ad values son pulsos puntuales sin estado persistido.

Crear una acción planificada

Bajo el formulario, la lista Planned for … muestra las acciones pendientes del Live stream con su Name, Action, Fire at y Status. Cuando existen acciones completadas o fallidas, un conmutador Show all / Show pending only revela el histórico reciente. Cada fila pendiente expone Edit, Enable / Disable y Delete.

En el calendario

Las acciones planificadas se renderizan en las vistas Week y Day del Scheduler como chips instantáneos de borde discontinuo en su hora de Fire at — distintos de los bloques sólidos con duración de las ocurrencias de Schedule. El color sigue el estado: ámbar mientras está pendiente, verde al completarse, rojo en error; una acción deshabilitada se atenúa con el nombre tachado. Pulsar un chip abre el gestor.

Ciclo de vida y reglas

El status de una acción pasa de pending a exactamente un estado terminal:

• El Live stream debe estar en emisión al disparar. Una acción cuya emisión no está en marcha cuando llega su hora termina en error — nunca se rearma para un arranque posterior.
• Ventana de ejecución. Una acción dispara dentro de [fireAt, fireAt + catchUpSeconds] (catchUpSeconds por defecto 120, acepta 0–86400). Si la plataforma no pudo dispararla dentro de la ventana — por ejemplo con el host de Control caído — la acción expira a error en lugar de disparar tarde: un blackout o un ad cue tardío puede ser peor que ninguno.
• Granularidad. Las acciones vencidas se recogen dentro del minuto siguiente a su hora de Fire at. Las acciones del mismo instante disparan en orden determinista: primero las que cambian estado, después los pulsos de metadata/ad values.
• Las acciones terminales son inmutables. Editar, habilitar o deshabilitar una acción completed o error devuelve 409. Borrar está permitido en cualquier estado.
• Retención. Las acciones terminales se eliminan automáticamente 24 horas después de su hora de disparo — como los Schedules de un solo uso, se limpian solas.

Superficie API

Las acciones planificadas son un recurso REST de primera clase — todo lo que hace el diálogo está disponible para integradores:

El objeto PlannedAction lleva livestreamId, name, command, payload (validado por comando en la creación), fireAt (ISO-8601 — envía offset de zona horaria para ser explícito), catchUpSeconds, enabled, más los campos de solo lectura status, resultDetail, firedAt, createdBy y createdAt. Los fallos de validación devuelven 400; un Live stream o acción desconocidos devuelven 404; mutar una acción terminal devuelve 409.

Ejemplo — planificar un blackout que conserva el audio en directo, esta noche a las 22:00:

curl -X POST "https://<your-host>/c21apiv2/livestreams/<livestreamId>/actions" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Evening cartela",
    "command": "blackout_on",
    "payload": { "mode": "File", "file": "cartela.mp4", "keep_input_audio": true },
    "fireAt": "2026-07-03T22:00:00+02:00"
  }'

Desde un agente de voz o chat

El perfil voice del servidor MCP expone la superficie de acciones planificadas a los agentes: addLivestreamAction, getLivestreamActions, getPlannedAction, updatePlannedAction y deletePlannedAction. Un operador puede crear, replanificar («muévela a las 22:30») o cancelar una acción por voz; enablePlannedAction / disablePlannedAction quedan en los perfiles grandes.

FAQ