Traitement des vidéos avec WebCodecs

Manipulation des composants du flux vidéo

Eugene Zemtsov

François Beaufort

Les technologies Web modernes offrent de nombreuses possibilités pour travailler avec la vidéo. L'API Media Stream, l'API Media Recording, l'API Media Source et l'API WebRTC constituent un ensemble d'outils complet pour enregistrer, transférer et lire des flux vidéo. Bien qu'elles résolvent certaines tâches de haut niveau, ces API ne permettent pas aux programmeurs Web de travailler avec les composants individuels d'un flux vidéo, tels que les images et les segments de vidéo ou d'audio encodés non multiplexés. Pour obtenir un accès de bas niveau à ces composants de base, les développeurs ont utilisé WebAssembly afin d'intégrer des codecs vidéo et audio dans le navigateur. Toutefois, étant donné que les navigateurs modernes sont déjà livrés avec divers codecs (qui sont souvent accélérés par le matériel), les reconditionner en tant que WebAssembly semble être un gaspillage de ressources humaines et informatiques.

L'API WebCodecs élimine cette inefficacité en permettant aux programmeurs d'utiliser les composants multimédias déjà présents dans le navigateur. Plus spécifiquement :

• Décodeurs vidéo et audio
• Encodeurs vidéo et audio
• Images vidéo brutes
• Décodeurs d'images

L'API WebCodecs est utile pour les applications Web qui nécessitent un contrôle total sur la façon dont le contenu multimédia est traité, comme les éditeurs vidéo, les visioconférences, le streaming vidéo, etc.

Workflow de traitement des vidéos

Les images sont au cœur du traitement vidéo. Par conséquent, dans WebCodecs, la plupart des classes consomment ou produisent des images. Les encodeurs vidéo convertissent les images en fragments encodés. Les décodeurs vidéo font le contraire.

De plus, VideoFrame fonctionne bien avec les autres API Web, car il est CanvasImageSource et dispose d'un constructor qui accepte CanvasImageSource. Il peut donc être utilisé dans des fonctions telles que drawImage() et texImage2D(). Il peut également être créé à partir de canevas, de bitmaps, d'éléments vidéo et d'autres images vidéo.

L'API WebCodecs fonctionne bien en tandem avec les classes de l'API Insertable Streams, qui connectent WebCodecs aux pistes de flux multimédias.

• MediaStreamTrackProcessor divise les pistes multimédias en trames individuelles.
• MediaStreamTrackGenerator crée une piste multimédia à partir d'un flux d'images.

WebCodecs et Web workers

Par défaut, l'API WebCodecs effectue le plus gros du travail de manière asynchrone et en dehors du thread principal. Toutefois, comme les rappels de frame et de chunk peuvent souvent être appelés plusieurs fois par seconde, ils peuvent encombrer le thread principal et rendre le site Web moins réactif. Il est donc préférable de déplacer la gestion des frames individuels et des segments encodés dans un nœud de calcul Web.

Pour vous aider, ReadableStream fournit un moyen pratique de transférer automatiquement tous les frames provenant d'un canal multimédia vers le worker. Par exemple, MediaStreamTrackProcessor peut être utilisé pour obtenir un ReadableStream pour un flux multimédia provenant de la webcam. Ensuite, le flux est transféré vers un nœud de calcul Web, où les trames sont lues une par une et mises en file d'attente dans un VideoEncoder.

Avec HTMLCanvasElement.transferControlToOffscreen, le rendu peut même être effectué en dehors du thread principal. Toutefois, si tous les outils de haut niveau se révèlent peu pratiques, VideoFrame lui-même est transférable et peut être déplacé d'un nœud de calcul à l'autre.

WebCodecs en action

Encodage

Tout commence par un VideoFrame. Il existe trois façons de créer des images vidéo.

• À partir d'une source d'image (canevas, bitmap d'une image ou élément vidéo)

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

• Utiliser MediaStreamTrackProcessor pour extraire des frames d'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;
  }
  

• Créer un frame à partir de sa représentation binaire des pixels dans 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);
  

Quelle que soit leur origine, les cadres peuvent être encodés dans des objets EncodedVideoChunk avec un VideoEncoder.

Avant l'encodage, VideoEncoder doit recevoir deux objets JavaScript :

• Dictionnaire Init avec deux fonctions pour gérer les erreurs et les fragments encodés. Ces fonctions sont définies par le développeur et ne peuvent pas être modifiées une fois transmises au constructeur VideoEncoder.
• Objet de configuration de l'encodeur, qui contient les paramètres du flux vidéo de sortie. Vous pouvez modifier ces paramètres ultérieurement en appelant configure().

La méthode configure() génère une erreur NotSupportedError si la configuration n'est pas compatible avec le navigateur. Nous vous recommandons d'appeler la méthode statique VideoEncoder.isConfigSupported() avec la configuration pour vérifier au préalable si la configuration est compatible et attendre sa promesse.

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.
}

Une fois l'encodeur configuré, il est prêt à accepter des images via la méthode encode(). configure() et encode() renvoient tous deux immédiatement un résultat sans attendre la fin de la tâche. Il permet à plusieurs frames d'être mis en file d'attente pour l'encodage en même temps, tandis que encodeQueueSize indique le nombre de requêtes en attente dans la file d'attente pour que les encodages précédents soient terminés. Les erreurs sont signalées en générant immédiatement une exception, si les arguments ou l'ordre des appels de méthode ne respectent pas le contrat de l'API, ou en appelant le rappel error() en cas de problème rencontré lors de l'implémentation du codec. Si l'encodage aboutit, le rappel output() est appelé avec un nouveau bloc encodé en tant qu'argument. Un autre détail important est que les frames doivent être informés de leur inutilité en appelant 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();
  }
}

Enfin, il est temps de terminer l'encodage du code en écrivant une fonction qui gère les fragments de vidéo encodée à mesure qu'ils sortent de l'encodeur. En règle générale, cette fonction envoie des blocs de données sur le réseau ou les multiplexe dans un conteneur multimédia pour les stocker.

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, à un moment donné, vous devez vous assurer que toutes les requêtes d'encodage en attente ont été effectuées, vous pouvez appeler flush() et attendre sa promesse.

await encoder.flush();

Décodage

La configuration d'un VideoDecoder est semblable à celle du VideoEncoder : deux fonctions sont transmises lors de la création du décodeur, et les paramètres du codec sont transmis à configure().

L'ensemble des paramètres de codec varie d'un codec à l'autre. Par exemple, le codec H.264 peut nécessiter un blob binaire d'AVCC, sauf s'il est encodé au format Annexe 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.
}

Une fois le décodeur initialisé, vous pouvez commencer à le nourrir avec des objets EncodedVideoChunk. Pour créer un fragment, vous avez besoin des éléments suivants:

• BufferSource de données vidéo encodées
• L'horodatage de début du fragment en microsecondes (heure multimédia de la première trame encodée dans le fragment)
• le type de bloc, l'un des suivants :
  • key si le segment peut être décodé indépendamment des segments précédents
  • delta si le segment ne peut être décodé qu'après le décodage d'un ou de plusieurs segments précédents

De plus, tous les segments émis par l'encodeur sont prêts pour le décodeur tels quels. Tout ce qui a été dit ci-dessus sur le signalement des erreurs et la nature asynchrone des méthodes de l'encodeur est également vrai pour les décodeurs.

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();

Il est maintenant temps de montrer comment un frame fraîchement décodé peut être affiché sur la page. Il est préférable de s'assurer que le rappel de sortie du décodeur (handleFrame()) renvoie rapidement. Dans l'exemple ci-dessous, il n'ajoute qu'un seul frame à la file d'attente des frames prêts à être affichés. Le rendu se produit séparément et comprend deux étapes :

1. Attend que le moment soit opportun pour afficher le frame.
2. Dessin du cadre sur le canevas.

Une fois qu'un frame n'est plus nécessaire, appelez close() pour libérer la mémoire sous-jacente avant que le garbage collector ne s'en occupe. Cela réduira la quantité moyenne de mémoire utilisée par l'application 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);
}

Conseils pour les développeurs

Utilisez le panneau multimédia dans les outils pour les développeurs Chrome pour afficher les journaux multimédias et déboguer WebCodecs.

Démo

La démonstration ci-dessous montre le rendu des images d'animation à partir d'un canevas:

• capturé à 25 FPS dans un ReadableStream par MediaStreamTrackProcessor
• transféré à un worker Web ;
• encodé au format vidéo H.264 ;
• décodé à nouveau en séquence d'images vidéo ;
• et affiché sur le deuxième canevas à l'aide de transferControlToOffscreen()

Autres démonstrations

Découvrez également nos autres démonstrations :

• Décoder des GIF avec ImageDecoder
• Capturer l'entrée de l'appareil photo dans un fichier
• Lecture MP4
• Autres exemples

Utiliser l'API WebCodecs

Détection de fonctionnalités

Pour vérifier la compatibilité avec WebCodecs :

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

N'oubliez pas que l'API WebCodecs n'est disponible que dans les contextes sécurisés. La détection échoue donc si self.isSecureContext est défini sur "false".

Commentaires

L'équipe Chrome souhaite connaître votre expérience avec l'API WebCodecs.

Parlez-nous de la conception de l'API

L'API ne fonctionne-t-elle pas comme prévu ? Ou manque-t-il des méthodes ou des propriétés dont vous avez besoin pour mettre en œuvre votre idée ? Vous avez une question ou un commentaire sur le modèle de sécurité ? Signalez un problème de spécification dans le dépôt GitHub correspondant ou ajoutez vos commentaires à un problème existant.

Signaler un problème d'implémentation

Avez-vous trouvé un bug dans l'implémentation de Chrome ? Ou l'implémentation est-elle différente de la spécification ? Signalez un bug sur new.crbug.com. Veillez à inclure autant de détails que possible, des instructions simples pour reproduire le problème et saisissez Blink>Media>WebCodecs dans le champ Composants. Glitch est idéal pour partager des reproductions rapidement et facilement.

Apportez votre soutien à l'API

Comptez-vous utiliser l'API WebCodecs ? Votre assistance publique aide l'équipe Chrome à hiérarchiser les fonctionnalités et montre aux autres fournisseurs de navigateurs à quel point il est essentiel de les prendre en charge.

Envoyez un e-mail à media-dev@chromium.org ou tweetez à @ChromiumDev en utilisant le hashtag #WebCodecs et indiquez-nous où et comment vous l'utilisez.

Image principale par Denise Jans sur Unsplash.