Codificación

Convierte un máster en las calidades que un reproductor necesita, empaquetado para streaming adaptativo y cifrado si quieres. Las salidas aparecen en tu almacenamiento, listas para servir.

Cómo funciona #

Envías un trabajo diciendo qué fichero codificar y a qué calidades. Contestamos 202 con un trabajo en cola: la codificación tarda minutos, así que no se espera a que termine. Cuando acaba, cada salida aparece como un fichero tuyo en el almacenamiento y ya se puede servir con una URL firmada.

El origen puede ser un fichero que ya tengas en tu almacenamiento (sourceFileId) o una URL pública (sourceUrl). Si es tuyo, se lo entregamos al codificador con un permiso temporal — tu fichero no se hace público en ningún momento, y ese tirón no te cuenta como transferencia.

El frame rate es un techo

Por defecto limitamos la salida a 30 fps. Un máster que ya esté por debajo no se toca — una película a 24 fps sale a 24 — y solo se baja lo que venga más rápido. Subir el techo a 60 con fps: 60 duplica el precio del vídeo y su peso; y tampoco inventa fotogramas: de un máster a 30 salen 30, y se cobran 30.

No se escala hacia arriba

Pedir 1080p de un máster de 720p produce 720p, no un 1080p borroso. Y se te cobra el 720p que sale, no el 1080p que pediste: el presupuesto es un techo, y la factura se liquida contra lo que realmente se produjo.

Enviar un trabajo #

Dos calidades, empaquetado HLS y DASH, cifrado con tus claves

curl -X POST https://kms.airi.live/v1/encoding/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "sourceFileId": "a1b2c3d4-…",
    "heights": [1080, 720],
    "durationSeconds": 600,
    "package": "hls+dash",
    "drm": true
  }'

Campo	Qué hace
`heights`	Las calidades: 240, 360, 480, 720, 1080, 1440 o 2160
`codec`	`h264` (por defecto) o `hevc`. HEVC ocupa ~40% menos y cuesta el doble
`fps`	Un techo, no un objetivo: 30 por defecto, 60 si lo subes. Una película a 24 fps se queda en 24
`package`	`none`, `hls`, `dash` o `hls+dash`. Un paquete es lo que permite cambiar de calidad sobre la marcha
`mp4`	Si además quieres un MP4 suelto por calidad. Por defecto sí
`drm`	Cifrar los paquetes con una clave de tu propio KMS
`durationSeconds`	Cuánto dura el máster. Solo dimensiona la reserva — ver abajo
`customId`	Tu identificador. Sirve de clave de idempotencia

El customId hace que reenviar el mismo trabajo sea seguro: una petición idéntica que se cortó por red devuelve el trabajo que ya empezó, y se paga una vez. Reusar el mismo identificador con otra escalera choca, en vez de ignorar en silencio lo que pediste.

Qué cuesta #

Se cobra por minuto de salida, por calidad, y una vez por cada formato entregable. Diez minutos a 1080p y 720p son veinte minutos de salida, no diez. Y si además pides MP4, HLS y DASH, son tres pasadas de esa escalera.

Calidad	H.264	HEVC
Hasta 480p	$0.0065 /min	$0.013 /min
720p y 1080p	$0.013 /min	$0.026 /min
1440p	$0.0325 /min	$0.065 /min
4K	$0.0585 /min	$0.117 /min
Audio (por salida)	$0.0013 /min	$0.0013 /min

Antes de gastar nada puedes preguntar el precio exacto, con el mismo código que luego cobra:

ejemplo

curl "https://kms.airi.live/v1/encoding/quote?heights=1080,720&durationSeconds=600" \
  -H "Authorization: Bearer $TOKEN"

Reserva al enviar, liquidación al terminar

El precio se reserva de tu saldo antes de llamar al codificador, porque una codificación no se puede deshacer. Al terminar se liquida contra la duración que midió el codificador y las calidades que realmente salieron: si sobró, se te devuelve. Por eso durationSeconds solo dimensiona la reserva — declarar de menos no abarata la factura.

Se cobra por fracción de minuto, no por minuto empezado: un clip de diez segundos paga un sexto de minuto. Un trabajo cifrado cuesta además una clave, a la tarifa habitual de DRM. Y un trabajo que falla no te cuesta nada: se borra lo que hubiera salido y se te devuelve la reserva entera.

Paquetes y DRM #

Un paquete HLS o DASH es una carpeta con un manifiesto y sus segmentos. En tu almacenamiento aparece como un solo fichero que pesa la carpeta entera, y su URL firmada cubre toda la carpeta automáticamente — es lo que hace que los segmentos resuelvan.

Con drm: true pedimos una clave a tu propio KMS y se la pasamos al codificador, así que el paquete sale ya cifrado y con la URL de licencia dentro del manifiesto. Señaliza Widevine y PlayReady a la vez, en una sola pasada.

Un trabajo cifrado entrega dos paquetes

Los tres DRM no caben en un solo empaquetado, así que un trabajo con drm: true produce dos, bajo la misma clave: un DASH cifrado con CENC para Widevine y PlayReady (Chrome, Edge, Firefox, Android) y un HLS cifrado con SAMPLE-AES para FairPlay (Safari, iOS, tvOS). No es un rodeo: Apple exige SAMPLE-AES y los otros dos exigen CENC. Pidas hls, dash o los dos, recibes ambos — de nada sirve entregarte medio catálogo de plataformas.

Lo comprobamos, no lo suponemos

Antes de entregarte un paquete cifrado leemos su segmento de inicialización y verificamos que lleva la caja tenc, que es lo que dice que los datos están realmente cifrados. Si no la lleva, el trabajo se marca fallido, se borra lo producido y se te devuelve el dinero. Preferimos un fallo visible a un paquete que parece protegido y no lo está.

Los MP4 sueltos no se cifran

Solo se cifran los paquetes: una descarga progresiva no es un formato de entrega protegida, y fingir lo contrario sería peor que no ofrecerlo. Si pides drm: true sin paquete, el trabajo se rechaza en vez de salir en claro sin avisar.

Seguir el trabajo #

ejemplo

curl "https://kms.airi.live/v1/encoding/jobs/$ID" -H "Authorization: Bearer $TOKEN"

queued: Aceptado, esperando en el proveedor
running: Codificando
finalising: Terminó; estamos midiendo y creando tus ficheros
completed: Listo. outputFileIds son tus ficheros
failed: Falló. No se te ha cobrado nada
cancelled: Lo cancelaste

Cancelar no detiene la codificación

El proveedor no ofrece forma de abortar una tarea en marcha, así que el trabajo termina igual y lo pagamos nosotros. Cancelar significa que a ti dejamos de cobrártelo, y se borra lo que hubiera salido.

Permisos #

`encoding:write`: Enviar y cancelar trabajos.
`encoding:read`: Consultar trabajos y pedir presupuestos.
`storage:read`: Necesario si el origen es un fichero tuyo.