Procesamiento de videos con WebCodecs

Manipular componentes de la transmisión de video

Eugene Zemtsov

François Beaufort

Las tecnologías web modernas ofrecen muchas formas de trabajar con videos. La API de Media Stream, la API de Media Recording, la API de Media Source y la API de WebRTC se suman a un conjunto completo de herramientas para grabar, transferir y reproducir transmisiones de video por Internet. Si bien resuelven ciertas tareas de alto nivel, estas APIs no permiten que los programadores web trabajen con componentes individuales de una transmisión de video, como fotogramas y fragmentos de video o audio codificados sin unir. Para obtener acceso de bajo nivel a estos componentes básicos, los desarrolladores han estado usando WebAssembly para incorporar codecs de audio y video en el navegador. Sin embargo, dado que los navegadores modernos ya se envían con una variedad de códecs (que a menudo se aceleran con hardware), volver a empaquetarlos como WebAssembly parece un desperdicio de recursos humanos y de procesamiento.

La API de WebCodecs elimina esta ineficiencia, ya que les brinda a los programadores una forma de usar componentes multimedia que ya están presentes en el navegador. En particular, haz lo siguiente:

• Decodificadores de audio y video
• Codificadores de audio y video
• Fotogramas de video sin procesar
• Decodificadores de imágenes

La API de WebCodecs es útil para las aplicaciones web que requieren un control total sobre la forma en que se procesa el contenido multimedia, como editores de video, videoconferencias, transmisión de video por Internet, etcétera.

Flujo de trabajo del procesamiento de videos

Los fotogramas son el elemento central del procesamiento de video. Por lo tanto, en WebCodecs, la mayoría de las clases consumen o producen fotogramas. Los codificadores de video convierten fotogramas en fragmentos codificados. Los decodificadores de video hacen lo contrario.

Además, VideoFrame funciona bien con otras APIs web, ya que es un CanvasImageSource y tiene un constructor que acepta CanvasImageSource. Por lo tanto, se puede usar en funciones como drawImage() y texImage2D(). También se puede crear a partir de lienzos, mapas de bits, elementos de video y otros fotogramas de video.

La API de WebCodecs funciona bien en conjunto con las clases de la API de Insertable Streams, que conectan WebCodecs a las pistas de transmisión de contenido multimedia.

• MediaStreamTrackProcessor divide las pistas multimedia en fotogramas individuales.
• MediaStreamTrackGenerator crea una pista multimedia a partir de una transmisión de fotogramas.

WebCodecs y trabajadores web

Por diseño, la API de WebCodecs hace todo el trabajo pesado de forma asíncrona y fuera del subproceso principal. Sin embargo, como las devoluciones de llamada de fotogramas y fragmentos a menudo se pueden llamar varias veces por segundo, pueden desordenar el subproceso principal y, por lo tanto, hacer que el sitio web sea menos responsivo. Por lo tanto, es preferible mover el control de marcos individuales y fragmentos codificados a un trabajador web.

Para ayudar con eso, ReadableStream proporciona una forma conveniente de transferir automáticamente todos los fotogramas que provienen de una pista de contenido multimedia al trabajador. Por ejemplo, MediaStreamTrackProcessor se puede usar para obtener un ReadableStream para una pista de transmisión de contenido multimedia proveniente de la cámara web. Luego, la transmisión se transfiere a un trabajador web en el que los marcos se leen uno por uno y se ponen en cola en un VideoEncoder.

Con HTMLCanvasElement.transferControlToOffscreen, incluso la renderización se puede realizar fuera del subproceso principal. Sin embargo, si todas las herramientas de alto nivel resultan ser inconvenientes, VideoFrame es transferible y se puede mover entre los trabajadores.

WebCodecs en acción

Codificación

Todo comienza con un VideoFrame. Existen tres formas de construir fotogramas.

• Desde una fuente de imagen, como un lienzo, un mapa de bits de imagen o un elemento de video.

  const canvas = document.createElement("canvas");
  // Draw something on the canvas...
  
  const frameFromCanvas = new VideoFrame(canvas, { timestamp: 0 });
  

• Usa MediaStreamTrackProcessor para extraer marcos de un MediaStreamTrack.

  const stream = await navigator.mediaDevices.getUserMedia({…});
  const track = stream.getTracks()[0];
  
  const trackProcessor = new MediaStreamTrackProcessor(track);
  
  const reader = trackProcessor.readable.getReader();
  while (true) {
    const result = await reader.read();
    if (result.done) break;
    const frameFromCamera = result.value;
  }
  

• Crea un marco a partir de su representación de píxeles binarios en un BufferSource.

  const pixelSize = 4;
  const init = {
    timestamp: 0,
    codedWidth: 320,
    codedHeight: 200,
    format: "RGBA",
  };
  const data = new Uint8Array(init.codedWidth * init.codedHeight * pixelSize);
  for (let x = 0; x < init.codedWidth; x++) {
    for (let y = 0; y < init.codedHeight; y++) {
      const offset = (y * init.codedWidth + x) * pixelSize;
      data[offset] = 0x7f;      // Red
      data[offset + 1] = 0xff;  // Green
      data[offset + 2] = 0xd4;  // Blue
      data[offset + 3] = 0x0ff; // Alpha
    }
  }
  const frame = new VideoFrame(data, init);
  

Independientemente de su origen, los fotogramas se pueden codificar en objetos EncodedVideoChunk con un VideoEncoder.

Antes de la codificación, se deben proporcionar dos objetos JavaScript a VideoEncoder:

• Inicia el diccionario con dos funciones para controlar los errores y los fragmentos codificados. Estas funciones están definidas por el desarrollador y no se pueden cambiar después de pasarlas al constructor VideoEncoder.
• Es un objeto de configuración del codificador que contiene parámetros para la transmisión de video de salida. Puedes cambiar estos parámetros más adelante llamando a configure().

El método configure() arrojará NotSupportedError si el navegador no es compatible con la configuración. Te recomendamos que llames al método estático VideoEncoder.isConfigSupported() con la configuración para verificar de antemano si la configuración es compatible y esperar su promesa.

const init = {
  output: handleChunk,
  error: (e) => {
    console.log(e.message);
  },
};

const config = {
  codec: "vp8",
  width: 640,
  height: 480,
  bitrate: 2_000_000, // 2 Mbps
  framerate: 30,
};

const { supported } = await VideoEncoder.isConfigSupported(config);
if (supported) {
  const encoder = new VideoEncoder(init);
  encoder.configure(config);
} else {
  // Try another config.
}

Una vez que se configuró el codificador, está listo para aceptar fotogramas a través del método encode(). Tanto configure() como encode() se muestran de inmediato, sin esperar a que se complete el trabajo real. Permite que varios fotogramas se almacenen en una fila para su codificación al mismo tiempo, mientras que encodeQueueSize muestra cuántas solicitudes están esperando en la fila a que finalicen las codificaciones anteriores. Los errores se informan arrojando una excepción de inmediato, en caso de que los argumentos o el orden de las llamadas a métodos infrinjan el contrato de la API, o llamando a la devolución de llamada de error() para los problemas que se encuentren en la implementación del códec. Si la codificación se completa correctamente, se llama a la devolución de llamada output() con un nuevo fragmento codificado como argumento. Otro detalle importante aquí es que se debe indicar a los fotogramas cuándo ya no son necesarios llamando a close().

let frameCounter = 0;

const track = stream.getVideoTracks()[0];
const trackProcessor = new MediaStreamTrackProcessor(track);

const reader = trackProcessor.readable.getReader();
while (true) {
  const result = await reader.read();
  if (result.done) break;

  const frame = result.value;
  if (encoder.encodeQueueSize > 2) {
    // Too many frames in flight, encoder is overwhelmed
    // let's drop this frame.
    frame.close();
  } else {
    frameCounter++;
    const keyFrame = frameCounter % 150 == 0;
    encoder.encode(frame, { keyFrame });
    frame.close();
  }
}

Por último, es hora de terminar de codificar el código escribiendo una función que controle fragmentos de video codificado a medida que salen del codificador. Por lo general, esta función envía fragmentos de datos a través de la red o los muxa en un contenedor de contenido multimedia para su almacenamiento.

function handleChunk(chunk, metadata) {
  if (metadata.decoderConfig) {
    // Decoder needs to be configured (or reconfigured) with new parameters
    // when metadata has a new decoderConfig.
    // Usually it happens in the beginning or when the encoder has a new
    // codec specific binary configuration. (VideoDecoderConfig.description).
    fetch("/upload_extra_data", {
      method: "POST",
      headers: { "Content-Type": "application/octet-stream" },
      body: metadata.decoderConfig.description,
    });
  }

  // actual bytes of encoded data
  const chunkData = new Uint8Array(chunk.byteLength);
  chunk.copyTo(chunkData);

  fetch(`/upload_chunk?timestamp=${chunk.timestamp}&type=${chunk.type}`, {
    method: "POST",
    headers: { "Content-Type": "application/octet-stream" },
    body: chunkData,
  });
}

Si en algún momento necesitas asegurarte de que se hayan completado todas las solicitudes de codificación pendientes, puedes llamar a flush() y esperar su promesa.

await encoder.flush();

Decodificación

La configuración de un VideoDecoder es similar a lo que se hizo para VideoEncoder: se pasan dos funciones cuando se crea el decodificador, y se proporcionan parámetros de códec a configure().

El conjunto de parámetros de códec varía de un códec a otro. Por ejemplo, el códec H.264 podría necesitar un blob binario de AVCC, a menos que esté codificado en el llamado formato del Anexo B (encoderConfig.avc = { format: "annexb" }).

const init = {
  output: handleFrame,
  error: (e) => {
    console.log(e.message);
  },
};

const config = {
  codec: "vp8",
  codedWidth: 640,
  codedHeight: 480,
};

const { supported } = await VideoDecoder.isConfigSupported(config);
if (supported) {
  const decoder = new VideoDecoder(init);
  decoder.configure(config);
} else {
  // Try another config.
}

Una vez que se inicialice el decodificador, puedes comenzar a alimentarlo con objetos EncodedVideoChunk. Para crear un fragmento, necesitarás lo siguiente:

• Un BufferSource de datos de video codificados
• La marca de tiempo de inicio del fragmento en microsegundos (tiempo medio del primer fotograma codificado en el fragmento)
• El tipo de fragmento, uno de los siguientes:
  • key si el fragmento se puede decodificar independientemente de los fragmentos anteriores.
  • delta si el fragmento solo se puede decodificar después de que se decodificaron uno o más fragmentos anteriores.

Además, cualquier fragmento que emita el codificador está listo para el decodificador tal como está. Todo lo que se dijo anteriormente sobre los informes de errores y la naturaleza asíncrona de los métodos del codificador también es cierto para los decodificadores.

const responses = await downloadVideoChunksFromServer(timestamp);
for (let i = 0; i < responses.length; i++) {
  const chunk = new EncodedVideoChunk({
    timestamp: responses[i].timestamp,
    type: responses[i].key ? "key" : "delta",
    data: new Uint8Array(responses[i].body),
  });
  decoder.decode(chunk);
}
await decoder.flush();

Ahora es el momento de mostrar cómo se puede mostrar un fotograma recién decodificado en la página. Es mejor asegurarse de que la devolución de llamada de salida del decodificador (handleFrame()) se muestre rápidamente. En el siguiente ejemplo, solo se agrega un fotograma a la cola de fotogramas listos para la renderización. La renderización se realiza por separado y consta de dos pasos:

1. Esperar el momento adecuado para mostrar el marco
2. Dibujando el marco en el lienzo.

Una vez que ya no se necesite un fotograma, llama a close() para liberar la memoria subyacente antes de que el recolector de elementos no utilizados llegue a ella. Esto reducirá la cantidad promedio de memoria que usa la aplicación web.

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
let pendingFrames = [];
let underflow = true;
let baseTime = 0;

function handleFrame(frame) {
  pendingFrames.push(frame);
  if (underflow) setTimeout(renderFrame, 0);
}

function calculateTimeUntilNextFrame(timestamp) {
  if (baseTime == 0) baseTime = performance.now();
  let mediaTime = performance.now() - baseTime;
  return Math.max(0, timestamp / 1000 - mediaTime);
}

async function renderFrame() {
  underflow = pendingFrames.length == 0;
  if (underflow) return;

  const frame = pendingFrames.shift();

  // Based on the frame's timestamp calculate how much of real time waiting
  // is needed before showing the next frame.
  const timeUntilNextFrame = calculateTimeUntilNextFrame(frame.timestamp);
  await new Promise((r) => {
    setTimeout(r, timeUntilNextFrame);
  });
  ctx.drawImage(frame, 0, 0);
  frame.close();

  // Immediately schedule rendering of the next frame
  setTimeout(renderFrame, 0);
}

Sugerencias para desarrolladores

Usa el Panel multimedia en las Herramientas para desarrolladores de Chrome para ver los registros multimedia y depurar WebCodecs.

Demostración

En la siguiente demostración, se muestra cómo son los fotogramas de animación de un lienzo:

• capturado a 25 fps en un ReadableStream por MediaStreamTrackProcessor
• se transfiere a un trabajador web.
• codificados en formato de video H.264
• se vuelve a decodificar en una secuencia de fotogramas de video.
• y se renderiza en el segundo lienzo con transferControlToOffscreen().

Otras demostraciones

Echa un vistazo también a nuestras otras demostraciones:

• Cómo decodificar GIFs con ImageDecoder
• Cómo capturar la entrada de la cámara en un archivo
• Reproducción en MP4
• Otros ejemplos

Cómo usar la API de WebCodecs

Detección de atributos

Para verificar la compatibilidad con WebCodecs, haz lo siguiente:

if ('VideoEncoder' in window) {
  // WebCodecs API is supported.
}

Ten en cuenta que la API de WebCodecs solo está disponible en contextos seguros, por lo que la detección fallará si self.isSecureContext es falsa.

Comentarios

El equipo de Chrome quiere conocer tus experiencias con la API de WebCodecs.

Cuéntanos sobre el diseño de la API

¿Hay algo en la API que no funciona como esperabas? ¿O faltan métodos o propiedades que necesites para implementar tu idea? ¿Tienes alguna pregunta o comentario sobre el modelo de seguridad? Informa un problema de especificación en el repositorio de GitHub correspondiente o agrega tus comentarios a un problema existente.

Denuncia un problema con la implementación

¿Encontraste un error en la implementación de Chrome? ¿O la implementación es diferente de la especificación? Informa un error en new.crbug.com. Asegúrate de incluir tantos detalles como sea posible, instrucciones simples para reproducirlo y, luego, ingresa Blink>Media>WebCodecs en el cuadro Componentes. Glitch funciona muy bien para compartir repros rápidos y fáciles.

Demuestra compatibilidad con la API

¿Piensas usar la API de WebCodecs? Tu asistencia pública ayuda al equipo de Chrome a priorizar funciones y les muestra a otros proveedores de navegadores la importancia de admitirlas.

Envía correos electrónicos a media-dev@chromium.org o twittea a @ChromiumDev con el hashtag #WebCodecs y cuéntanos dónde y cómo lo usas.

Imagen hero de Denise Jans en Unsplash.