Cloudflare Stream: vídeo bajo demanda y en directo

El vídeo se parece a una imagen solo hasta que intentas servirlo. Un fichero de vídeo útil no es un fichero: es una familia de codificaciones a distintas resoluciones y tasas de bits, troceada en segmentos de pocos segundos, descrita por un manifiesto que el reproductor consulta para saltar de un escalón a otro cuando la red del espectador se estrecha en mitad de un túnel. Construir esa maquinaria a mano —una granja de transcodificación, un empaquetador, un almacén de renditions, un reproductor que implemente bien la lógica adaptativa— es un proyecto de varios trimestres y una guardia permanente. Stream propone lo mismo que Images pero un orden de magnitud más arriba: tú subes o emites el original, y todo lo demás pasa a ser un contrato en vez de un repositorio.

Subir un vídeo y olvidarse del transcodificado

Antes de la mecánica conviene fijar qué desaparece. Un vídeo servido con dignidad exige varias codificaciones a resoluciones y tasas de bits distintas, un troceado en segmentos de pocos segundos y un manifiesto que las describa; sin eso, o sirves una calidad única que se atasca en cuanto la red flaquea, o sirves un fichero enorme que tarda una eternidad en empezar. Stream toma ese trabajo entero por contrato: tú entregas un original y recibes la escalera completa, sin decidir perfiles, sin dimensionar codificadores y sin escribir un empaquetador.

Hay cuatro caminos de entrada y conviene conocerlos porque resuelven situaciones distintas: la subida directa de un fichero, el protocolo reanudable tus para piezas grandes o redes malas, la ingesta a partir de un enlace del que Cloudflare descarga el original, y las subidas de un solo uso que hará el cliente y que ocupan la lección siguiente. La ingesta por enlace es la más cómoda cuando el vídeo ya está en un bucket tuyo.

curl --request POST \
  https://api.cloudflare.com/client/v4/accounts/$CUENTA/stream/copy \
  --header "Authorization: Bearer $TOKEN" \
  --data '{"url":"https://mi-bucket.ejemplo.com/clase-07.mp4","meta":{"name":"Clase 07"}}'

Lo que devuelve esa llamada no es un vídeo listo, y ese matiz es el que estructura toda la integración. Devuelve un identificador y un estado, porque detrás va a ocurrir un trabajo real: descargar, analizar, transcodificar a varias calidades y empaquetar. El estado recorre una secuencia previsible —descargando, en cola, en proceso, listo o con error— y hay un indicador booleano que resume lo único que tu interfaz necesita saber para decidir si puede pintar un reproductor o debe pintar un aviso de que el vídeo se está preparando.

Consultar ese estado en bucle es la solución obvia y la mala. La buena es suscribir un webhook: Cloudflare avisa cuando el vídeo queda listo o cuando falla, la notificación trae el identificador, y tu sistema pasa de preguntar cada pocos segundos a reaccionar una vez. Esa diferencia deja de ser cosmética en cuanto tienes miles de subidas al día.

El límite de tamaño por fichero es holgado —del orden de treinta gigabytes—, pero conviene no acercarse a él con una subida simple. Para piezas grandes o redes poco fiables, el protocolo reanudable trocea la carga y permite retomarla donde se cortó, y ese detalle marca la diferencia entre una subida que falla al noventa por ciento y una que termina. Es la misma decisión que veremos con más detalle en la lección siguiente, cuando quien sube no es tu servidor sino el usuario final.

Desde un Worker hay además un binding que evita las llamadas autenticadas: sube desde una URL, consulta y edita metadatos, y genera tokens de reproducción firmados sin que tengas que custodiar una clave de firma. Es la vía natural cuando el vídeo lo produce tu propio sistema y no una persona.

const video = await env.STREAM.upload(urlDelOriginal);
const token = await env.STREAM.video(video.uid).generateToken();
await env.STREAM.video(video.uid).update({ meta: { name: "Clase 07" } });

Directo: entradas en vivo, ingesta y grabación

El directo se organiza alrededor de un objeto persistente llamado entrada en vivo. No es una emisión: es un punto de conexión estable con su propio identificador, su URL de ingesta y su clave secreta, que sobrevive a todas las emisiones que pasen por él. Esa distinción es lo que permite dedicar una entrada a un creador o a un programa recurrente y que la página del canal apunte siempre al mismo sitio.

curl --request POST \
  https://api.cloudflare.com/client/v4/accounts/$CUENTA/stream/live_inputs \
  --header "Authorization: Bearer $TOKEN" \
  --data '{"meta":{"name":"canal-principal"},"recording":{"mode":"automatic"},"deleteRecordingAfterDays":90}'

La respuesta trae la URL RTMPS y la clave que el emisor pega en su programa de emisión. Hay una segunda vía de ingesta, SRT, que soporta códecs más modernos y facilita subtítulos y varias pistas de audio; el protocolo elegido no cambia nada aguas abajo. El ajuste que más consecuencias tiene es el modo de grabación: en automático, la emisión queda disponible en directo y además se conserva como vídeo bajo demanda cuando termina, lo cual convierte cada directo en un elemento del catálogo sin ninguna acción por tu parte. Apagado, ni se graba ni se puede ver.

Otros parámetros afinan el comportamiento. Un tiempo de espera de desconexión decide cuántos segundos de caída se toleran antes de considerar que empezó una emisión nueva. Un plazo de borrado automático de grabaciones, entre treinta días y unos tres años, evita que el archivo crezca para siempre. Y un modo de baja latencia en pruebas activa una variante del protocolo que recorta segundos a costa de exigirle más disciplina al emisor.

Del lado del emisor hay requisitos que no son negociables y que conviene documentar a tus creadores antes de la primera queja: solo se aceptan vídeo H.264 y audio AAC, los grupos de imágenes deben ser cerrados, el intervalo entre fotogramas clave debe quedar entre dos y ocho segundos, y una tasa de bits constante da mejor experiencia que una variable. Ese intervalo de fotogramas clave es además la palanca directa de latencia: más corto significa que el espectador ve antes lo que ocurre, y también que la codificación es menos eficiente. Es un compromiso del vídeo, no una limitación de la plataforma.

Dos límites más conviene tenerlos escritos antes de prometer nada a nadie. Una emisión que se alargue más de siete días se graba solo hasta ese punto, así que un canal permanente necesita cortes deliberados si quieres archivo completo. Y las marcas de agua, que sí funcionan sobre vídeo bajo demanda, todavía no se aplican al directo. Hay además una palanca operativa muy útil y poco conocida: la entrada en vivo se puede deshabilitar por API, lo que rechaza cualquier conexión entrante y te da una forma programática de cortar la emisión de un creador sin borrar nada.

flowchart LR
Emisor[programa de emision] -->|rtmps o srt| Entrada[entrada en vivo]
Entrada --> Codif[codificacion automatica en escalera]
Codif --> Manif[manifiesto hls y dash]
Manif --> Player[reproductor del espectador]
Codif --> Grab[grabacion como video bajo demanda]
Grab --> Cat[catalogo]

Reproducción adaptativa y el reproductor

Cada vídeo y cada entrada en vivo tienen su propio manifiesto en los dos formatos estándar de la industria, y ahí acaba la magia: cualquier reproductor compatible sabe consumirlos. El manifiesto lista las calidades disponibles, y la lógica adaptativa del reproductor estima el ancho de banda del espectador y elige el escalón, cambiando sobre la marcha sin cortar la reproducción.

<iframe
  src="https://customer-CODIGO.cloudflarestream.com/ID_DEL_VIDEO/iframe"
  style="border: none"
  height="720"
  width="1280"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>

Hay además una palanca poco conocida para forzar una calidad concreta desde el propio manifiesto, pensada para cuando tu reproductor no expone su lógica adaptativa. Úsala como último recurso: casi siempre es preferible configurar el reproductor, porque tú desarrollas con fibra y buena parte de tus espectadores no.

El reproductor embebido es cero trabajo y cubre la mayoría de los casos, incluidos directos y grabaciones. Si necesitas control sobre la interfaz, la analítica o los subtítulos, tomas el manifiesto y lo pasas a tu reproductor propio en web, en iOS o en Android. Hay una regla que no se puede saltar y que rompe integraciones a menudo: los manifiestos son documentos vivos que pueden cambiar en cualquier momento, así que no se cachean, no se proxifican y no se copian; se leen siempre desde el origen.

Al apuntar el reproductor hay una decisión de producto escondida. Si usas el identificador de la entrada en vivo, la página muestra siempre la emisión activa y un aviso cuando no hay ninguna: es lo que quieres en la página de un canal. Si usas el identificador del vídeo, la página muestra una emisión concreta y después su grabación: es lo que quieres en la página de un evento con fecha.

Alrededor de la reproducción hay un conjunto de piezas que suelen darse por supuestas y que también vienen resueltas: miniaturas generadas a partir de un instante que eliges, subtítulos que subes por pista e idioma, pistas de audio adicionales para doblajes, marcas de agua aplicadas a la codificación, recortes de un fragmento como vídeo independiente y descarga en fichero cuando el producto la necesita. Nada de eso exige tocar el original ni volver a codificar tú.

El control de acceso tiene dos palancas complementarias. La primera exige un token firmado para ver el vídeo, con caducidad y con la posibilidad de fijar restricciones dentro del propio token; es lo que separa un catálogo de pago de uno abierto. La segunda limita desde qué dominios se permite la reproducción, lo que corta el uso más molesto y menos sofisticado: incrustar tu reproductor en otra web y servirse de tu factura. Cuando esas opciones se fijan en una entrada en vivo, se heredan a todas las grabaciones que salgan de ella.

Minutos, no bytes

El modelo de coste tiene dos ejes y ninguno es la transferencia. Los minutos almacenados se compran por adelantado en tramos y se consumen por la duración de los originales y de las grabaciones, con independencia del tamaño del fichero: un máster de treinta gigabytes y un montaje comprimido de la misma duración cuestan lo mismo. Los minutos entregados se facturan a posteriori por lo que se consume realmente, sumando a través de todos los espectadores; dos personas viendo media hora son sesenta minutos.

Las consecuencias prácticas de esa unidad son poco intuitivas y conviene tenerlas presentes. Un directo sin espectadores no cuesta entrega, pero su grabación sí ocupa almacenamiento. El precargado y el búfer del reproductor cuentan como entregados aunque el espectador se marche, mientras que lo que se reproduce desde la caché del navegador —un vídeo corto en bucle, por ejemplo— no vuelve a contar. Y quedarse sin almacenamiento no degrada nada de lo publicado: simplemente impide subir vídeos nuevos o iniciar directos hasta que compres más o borres.

Hay además dos comportamientos que no consumen nada y que conviene conocer para no sobredimensionar la compra: los vídeos que quedaron en estado de error no ocupan almacenamiento, y los ficheros de descarga que Stream genera a partir de un original tampoco. La cuenta se hace siempre sobre duración de contenido reproducible, redondeada al segundo.