Docs / Módulo / Video

Módulo de Video

Transcodificación y streaming (VOD y live) con perfiles, procesamiento por jobs y entrega escalable.

Introducción

El módulo de Video permite crear trabajos de transcodificación (jobs) para convertir videos a distintos formatos y calidades, generar salidas para streaming (HLS) y obtener URLs listas para publicar.

Incluye

• Jobs asíncronos (cola + estado)
• Perfiles (renditions) configurables
• HLS (master + variants)
• Webhooks de progreso / finalización

Casos de uso

• VOD (catálogos, cursos, recetas)
• Live (eventos, transmisiones)
• Publicación multi-calidad

Conceptos

Asset

Video fuente (subido o referenciado por URL) del cual se generan las salidas.

Job

Trabajo de transcodificación asíncrono. Tiene estado: queued → processing → finished/failed.

Perfil

Define una salida: resolución, bitrate, fps, codec, audio, contenedor.

Playlist HLS

Master playlist + variants (.m3u8) para streaming adaptativo.

Quickstart

Flujo típico: crear job → consultar estado → obtener URLs (MP4/HLS) → publicar.

1) Crear job desde URL

POST /video/jobs
{
  "source_url": "https://tusitio.com/video.mp4",
  "profile": "hls_1080_720_480",
  "output": {
    "type": "hls",
    "path": "videos/recetas/abc123/"
  },
  "webhook_url": "https://tuapp.com/webhooks/video"
}

2) Consultar estado

GET /video/jobs/job_123

3) URL de salida

{
  "id": "job_123",
  "status": "finished",
  "outputs": {
    "hls_master": "https://cdn.webability.info/videos/recetas/abc123/master.m3u8",
    "mp4_720": "https://cdn.webability.info/videos/recetas/abc123/720p.mp4"
  }
}

Transcodificación (Jobs)

Endpoint	Método	Descripción
/video/jobs	GET/POST	Listar / crear jobs.
/video/jobs/{id}	GET	Detalle y estado del job.
/video/jobs/{id}/cancel	POST	Cancelar job (si es posible).

Sugerencia: usa webhooks para evitar “polling” constante de estado.

Perfiles

Los perfiles definen las salidas (renditions). Puedes usar perfiles predefinidos o crear los tuyos.

Ejemplo perfil

{
  "name": "hls_1080_720_480",
  "type": "hls",
  "renditions": [
    { "name": "1080p", "w": 1920, "h": 1080, "video_bitrate": 6000, "audio_bitrate": 128, "fps": 30 },
    { "name": "720p",  "w": 1280, "h": 720,  "video_bitrate": 3000, "audio_bitrate": 128, "fps": 30 },
    { "name": "480p",  "w": 854,  "h": 480,  "video_bitrate": 1500, "audio_bitrate": 96,  "fps": 30 }
  ],
  "segments": { "duration": 6 }
}

Endpoint	Método	Descripción
/video/profiles	GET/POST	Listar / crear perfiles.
/video/profiles/{id}	GET/PATCH/DELETE	Detalle / editar / eliminar.

Streaming (HLS)

Para VOD, el job genera un master.m3u8 y variantes por calidad. Para live, normalmente se integra con un origen (RTMP/SRT) y se publica un HLS de salida.

Master playlist

https://cdn.webability.info/videos/recetas/abc123/master.m3u8

Variante (ej.)

https://cdn.webability.info/videos/recetas/abc123/720p/index.m3u8

Embed típico (HLS.js)

<video id="v" controls></video>
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<script>
  if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource("https://cdn.webability.info/videos/recetas/abc123/master.m3u8");
    hls.attachMedia(document.getElementById("v"));
  }
</script>

Webhooks

Recibe eventos del job: queued, processing, progress, finished, failed.

Ejemplo evento

POST https://tuapp.com/webhooks/video
{
  "event": "progress",
  "job_id": "job_123",
  "progress": 42,
  "ts": "2026-01-07T22:25:10-06:00",
  "meta": { "eta_seconds": 120 }
}

Errores

HTTP	Código	Descripción
400	invalid_params	Parámetros faltantes o inválidos.
401	unauthorized	API key inválida o sin permisos.
404	source_not_found	Video fuente no accesible.
409	job_conflict	Ya existe job en proceso para ese asset.
500	transcode_error	Error interno de transcodificación.

SDKs

SDKs disponibles para integrar jobs, perfiles y consumo de salidas (Go, Node, PHP, etc.).

go get webability.info/wavideo

Node

npm i @webability/video

PHP

composer require webability/video