Procesamiento de videos con WebCodecs

Manipular componentes de la transmisión de video

Eugene Zemtsov
Eugene Zemtsov
GitHub
François Beaufort
François Beaufort
GitHub

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 conforman un conjunto de herramientas enriquecido para grabar, transferir y reproducir transmisiones de video. 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 aplicaciones web que requieren control total sobre la forma en que se procesa el contenido multimedia, como editores de video, videoconferencias, transmisión de video, etcétera.

Flujo de trabajo de procesamiento de videos

Los fotogramas son la pieza 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 los 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() ytexImage2D(). 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 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

De forma predeterminada, la API de WebCodecs realiza 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 manejo de fotogramas 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. Después de eso, la transmisión se transfiere a un trabajador web, donde las tramas se leen una por una 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

La ruta de acceso de un Canvas o un ImageBitmap a la red o al almacenamiento
La ruta de acceso de un Canvas o un ImageBitmap a la red o al almacenamiento

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

  • 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 son definidas por el desarrollador y no se pueden cambiar después de que se pasan al constructor VideoEncoder.
  • 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() si se producen problemas 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 los 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

Es la ruta de acceso desde la red o el almacenamiento a un lienzo o un ImageBitmap.
La ruta de acceso desde la red o el almacenamiento a un Canvas o un ImageBitmap.

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 los parámetros del códec se le proporcionan 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 de forma independiente de los fragmentos anteriores
    • delta si el fragmento solo se puede decodificar después de decodificar 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. Dibuja el marco en el lienzo.

Una vez que ya no se necesite un marco, 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.

Captura de pantalla del panel Media para depurar WebCodecs
Panel de medios en las Herramientas para desarrolladores de Chrome para 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

Consulta también nuestras otras demostraciones:

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 necesitas para implementar tu idea? ¿Tienes una pregunta o un 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 es excelente para compartir reproducciones rápidas y fáciles.

Cómo mostrar compatibilidad con la API

¿Piensas usar la API de WebCodecs? Tu apoyo público ayuda al equipo de Chrome a priorizar las funciones y les muestra a otros proveedores de navegadores lo importante que es brindarles asistencia.

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.