Procesamiento de videos con WebCodecs

Cómo manipular los componentes de la transmisión de video

Eugene Zemtsov

François Beaufort

Las tecnologías web modernas proporcionan muchas formas de trabajar con video. Las APIs de Media Stream, Media Recording, Media Source, y WebRTC se suman a 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 no multiplexados de audio o video codificado. Para obtener acceso de bajo nivel a estos componentes básicos, los desarrolladores han estado usando WebAssembly para incorporar códecs de audio y video al 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 computadoras.

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. Específicamente, son las siguientes:

• 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, etcétera.

Flujo de trabajo de procesamiento de video

Los fotogramas son la pieza central en el 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() y texImage2D(). También se puede construir a partir de lienzos, mapas de bits, elementos de video y otros fotogramas.

La API de WebCodecs funciona bien en conjunto con las clases de la API de Insertable Streams que conecta WebCodecs a las pistas de transmisión de medios.

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

WebCodecs y trabajadores web

Por diseño, la API de WebCodecs realiza todo el trabajo pesado de forma asíncrona y fuera del subproceso principal. Sin embargo, dado que 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 medios al trabajador. Por ejemplo, se puede usar MediaStreamTrackProcessor para obtener un ReadableStream para una pista de transmisión de medios que proviene de la cámara web. Después de eso, la transmisión se transfiere a un trabajador web donde los fotogramas se leen de a 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 inconvenientes, VideoFrame se puede transferir y se puede mover entre 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 fotogramas 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 fotograma 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);
  

Sin importar de dónde provengan, los fotogramas se pueden codificar en objetos EncodedVideoChunk con un VideoEncoder.

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

• Diccionario de inicialización con dos funciones para controlar fragmentos y errores codificados. Estas funciones están 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() mostrará NotSupportedError si el navegador no admite la configuración. Te recomendamos que llames al método estático VideoEncoder.isConfigSupported() con la configuración para verificar de antemano si se admite 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 configura el codificador, está listo para aceptar fotogramas a través del método encode(). configure() y encode() se muestran de inmediato sin esperar a que se complete el trabajo real. Permite que varios fotogramas se pongan en cola para la codificación al mismo tiempo, mientras que encodeQueueSize muestra cuántas solicitudes están esperando en la cola para que finalicen las codificaciones anteriores. Los errores se informan de inmediato con una excepción, en caso de que los argumentos o el orden de las llamadas al método infrinjan el contrato de la API, o llamando a la devolución de llamada error() para los problemas que se encuentran 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 es que se debe informar a los fotogramas cuando 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 enviaría fragmentos de datos a través de la red o los multiplexaría en un contenedor de medios para el 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 el 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 objeto binario de AVCC, a menos que esté codificado en el formato denominado 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 inicializa 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 de medios 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 que se decodificaron uno o más fragmentos anteriores

Además, cualquier fragmento emitido por el codificador está listo para el decodificador. 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 válido 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 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 fotograma
2. Dibujar el fotograma en el lienzo

Una vez que ya no se necesite un fotograma, llama a close() para liberar la memoria subyacente antes de que llegue el recolector de elementos no utilizados. 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 de medios en las Herramientas para desarrolladores de Chrome para ver los registros de medios y depurar WebCodecs.

Demostración

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

• Capturados a 25 fps en un ReadableStream por MediaStreamTrackProcessor
• Transferidos a un trabajador web
• Codificados en formato de video H.264
• Decodificados nuevamente en una secuencia de fotogramas
• Renderizados en el segundo lienzo con transferControlToOffscreen()

Otras demostraciones

También revisa nuestras otras demostraciones:

• Decodificación de GIFs con ImageDecoder
• Captura la entrada de la cámara en un archivo
• Reproducción de MP4
• Otras muestras

Cómo usar la API de WebCodecs

Detección de funciones

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.

Más información

Si eres nuevo en WebCodecs, WebCodecs Fundamentals proporciona artículos detallados con muchos ejemplos para ayudarte a obtener más información.

Comentarios

El equipo de Chrome quiere conocer tu experiencia con la API de WebCodecs.

Cuéntanos sobre el diseño de la API

¿Hay algo sobre la API que no funciona como esperabas? ¿Faltan métodos o propiedades que necesitas 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 ideas a un problema existente.

Informa 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 puedas, instrucciones simples para reproducir el error y, luego, ingresa Blink>Media>WebCodecs en el cuadro Componentes.

Muestra compatibilidad con la API

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

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