WebCodecs VideoFrame Sík Hozzáférés: Mélymerülés a Nyers Videóadatok Manipulációjában

Éveken át a nagy teljesítményű videófeldolgozás a webböngészőben távoli álomnak tűnt. A fejlesztők gyakran a <video> elem és a 2D Canvas API korlátai közé szorultak, amelyek, bár erősek, teljesítménybeli szűk keresztmetszeteket és korlátozott hozzáférést jelentettek az alapul szolgáló nyers videóadatokhoz. A WebCodecs API megjelenése alapjaiban változtatta meg ezt a helyzetet, alacsony szintű hozzáférést biztosítva a böngésző beépített média kodekjeihez. Egyik legforradalmibb funkciója az a képesség, hogy a VideoFrame objektumon keresztül közvetlenül hozzáférhetünk és manipulálhatjuk az egyes videókeretek nyers adatait.

Ez a cikk egy átfogó útmutató azoknak a fejlesztőknek, akik túl akarnak lépni az egyszerű videólejátszáson. Felfedezzük a VideoFrame sík hozzáférésének bonyodalmait, tisztázzuk az olyan fogalmakat, mint a színterek és a memóriaelrendezés, és gyakorlati példákat mutatunk be, hogy Ön is képes legyen a böngészőn belüli videoalkalmazások következő generációjának megalkotására, a valós idejű szűrőktől a kifinomult gépi látási feladatokig.

Előfeltételek

Ahhoz, hogy a legtöbbet hozza ki ebből az útmutatóból, alapos ismeretekkel kell rendelkeznie a következőkről:

• Modern JavaScript: Beleértve az aszinkron programozást (async/await, Promise-ok).
• Alapvető videó fogalmak: Hasznos, ha ismeri az olyan kifejezéseket, mint a képkockák (frame-ek), felbontás és kodekek.
• Böngésző API-k: A Canvas 2D vagy a WebGL API-kkal szerzett tapasztalat előnyös, de nem feltétlenül szükséges.

A Videókeretek, Színterek és Síkok Megértése

Mielőtt belemerülnénk az API-ba, először is egy szilárd mentális modellt kell alkotnunk arról, hogy hogyan is néz ki egy videókeret adata. A digitális videó állóképek, azaz képkockák (frame-ek) sorozata. Minden képkocka egy pixelrács, és minden pixelnek van egy színe. Hogy ez a szín hogyan tárolódik, azt a színtér és a pixel formátum határozza meg.

RGBA: A Web Natív Nyelve

A legtöbb webfejlesztő ismeri az RGBA színmodellt. Minden pixelt négy komponens képvisel: Vörös (Red), Zöld (Green), Kék (Blue) és Alfa (átlátszóság). Az adatok általában összefésülve (interleaved) tárolódnak a memóriában, ami azt jelenti, hogy egyetlen pixel R, G, B és A értékei egymás után következnek:

[R1, G1, B1, A1, R2, G2, B2, A2, ...]

Ebben a modellben a teljes kép egyetlen, folytonos memóriablokkban tárolódik. Ezt úgy foghatjuk fel, mintha egyetlen adat "síkkal" rendelkeznénk.

YUV: A Videótömörítés Nyelve

A videó kodekek azonban ritkán dolgoznak közvetlenül RGBA-val. Előnyben részesítik a YUV (vagy pontosabban, Y'CbCr) színtereket. Ez a modell a képinformációt a következőkre bontja:

• Y (Luma): A fényerő vagy szürkeárnyalatos információ. Az emberi szem a luma változásaira a legérzékenyebb.
• U (Cb) és V (Cr): A krominancia vagy színkülönbségi információ. Az emberi szem kevésbé érzékeny a színrészletekre, mint a fényerő részleteire.

Ez a szétválasztás a hatékony tömörítés kulcsa. Az U és V komponensek felbontásának csökkentésével – ezt a technikát kroma alulmintavételezésnek (chroma subsampling) nevezik – jelentősen csökkenthetjük a fájlméretet minimális észrevehető minőségveszteséggel. Ez sík-alapú (planar) pixel formátumokhoz vezet, ahol az Y, U és V komponensek külön memóriablokkokban, vagy "síkokban" tárolódnak.

Egy gyakori formátum az I420 (egy YUV 4:2:0 típus), ahol minden 2x2 pixeles blokkra négy Y minta, de csak egy-egy U és V minta jut. Ez azt jelenti, hogy az U és V síkok szélessége és magassága fele az Y síkénak.

Ennek a különbségnek a megértése kritikus fontosságú, mivel a WebCodecs közvetlen hozzáférést biztosít pontosan ezekhez a síkokhoz, ahogyan azokat a dekóder szolgáltatja.

A VideoFrame Objektum: Kapu a Pixel Adatokhoz

Ennek a rejtvénynek a központi eleme a VideoFrame objektum. Ez egyetlen videókeretet képvisel, és nemcsak a pixel adatokat, hanem fontos metaadatokat is tartalmaz.

A VideoFrame Főbb Tulajdonságai

• format: Egy string, ami a pixel formátumot jelöli (pl. 'I420', 'NV12', 'RGBA').
• codedWidth / codedHeight: A képkocka teljes, memóriában tárolt méretei, beleértve a kodek által megkövetelt esetleges kitöltést (padding).
• displayWidth / displayHeight: A képkocka megjelenítéséhez használandó méretek.
• timestamp: A képkocka megjelenítési időbélyege mikroszekundumban.
• duration: A képkocka időtartama mikroszekundumban.

A Varázslatos Metódus: copyTo()

A nyers pixel adatok elérésének elsődleges metódusa a videoFrame.copyTo(destination, options). Ez az aszinkron metódus a képkocka sík adatait egy általunk megadott pufferbe másolja.

• destination: Egy ArrayBuffer vagy egy típusos tömb (mint a Uint8Array), ami elég nagy az adatok tárolásához.
• options: Egy objektum, ami meghatározza, mely síkokat kell másolni és azok memóriaelrendezését. Ha elhagyjuk, az összes síkot egyetlen folytonos pufferbe másolja.

A metódus egy Promise-t ad vissza, ami egy PlaneLayout objektumokból álló tömbbel oldódik fel, egyet a képkocka minden síkjához. Minden PlaneLayout objektum két kulcsfontosságú információt tartalmaz:

• offset: A bájt eltolás, ahol az adott sík adatai kezdődnek a célpufferen belül.
• stride: A bájtok száma egy pixelsor kezdete és a következő sor kezdete között az adott síkon.

Kritikus Fogalom: Stride vs. Szélesség

Ez az egyik leggyakoribb zavaró tényező az alacsony szintű grafikus programozásban újonc fejlesztők számára. Nem feltételezhetjük, hogy a pixelsorok adatai szorosan egymás után következnek.

• Szélesség (Width) a pixelek száma a kép egy sorában.
• Stride (más néven pitch vagy line step) a bájtok száma a memóriában egy sor elejétől a következő sor elejéig.

Gyakran a stride nagyobb lesz, mint a szélesség * bájtok_per_pixel. Ez azért van, mert a memória gyakran ki van egészítve (padding), hogy hardveres határokhoz (pl. 32 vagy 64 bájtos határok) igazodjon a CPU vagy GPU általi gyorsabb feldolgozás érdekében. Mindig a stride-ot kell használni egy adott sorban lévő pixel memória címének kiszámításához.

A stride figyelmen kívül hagyása torz vagy elcsúszott képekhez és helytelen adathozzáféréshez vezet.

1. Gyakorlati Példa: Egy Szürkeárnyalatos Sík Elérése és Megjelenítése

Kezdjünk egy egyszerű, de hatásos példával. A legtöbb videó a weben YUV formátumban, például I420-ban van kódolva. Az 'Y' sík gyakorlatilag a kép teljes szürkeárnyalatos reprezentációja. Kivonatolhatjuk csak ezt a síkot, és kirajzolhatjuk egy canvas-re.

async function displayGrayscale(videoFrame) {
  // Feltételezzük, hogy a videoFrame egy YUV formátumban van, mint pl. 'I420' vagy 'NV12'.
  if (!videoFrame.format.startsWith('I4')) {
    console.error('Ehhez a példához YUV 4:2:0 sík-alapú formátum szükséges.');
    videoFrame.close();
    return;
  }

  const yPlaneInfo = videoFrame.layout[0]; // Az Y sík mindig az első.

  // Létrehozunk egy puffert, ami csak az Y sík adatait tárolja.
  const yPlaneData = new Uint8Array(yPlaneInfo.stride * videoFrame.codedHeight);

  // Átmásoljuk az Y síkot a pufferünkbe.
  await videoFrame.copyTo(yPlaneData, {
    rect: { x: 0, y: 0, width: videoFrame.codedWidth, height: videoFrame.codedHeight },
    layout: [yPlaneInfo]
  });

  // Most a yPlaneData a nyers szürkeárnyalatos pixeleket tartalmazza.
  // Meg kell jelenítenünk. Létrehozunk egy RGBA puffert a canvas számára.
  const canvas = document.getElementById('my-canvas');
  canvas.width = videoFrame.displayWidth;
  canvas.height = videoFrame.displayHeight;
  const ctx = canvas.getContext('2d');
  const imageData = ctx.createImageData(canvas.width, canvas.height);

  // Végigiterálunk a canvas pixelein és feltöltjük őket az Y sík adataiból.
  for (let y = 0; y < videoFrame.displayHeight; y++) {
    for (let x = 0; x < videoFrame.displayWidth; x++) {
      // Fontos: a stride használatával találjuk meg a helyes forrás indexet!
      const yIndex = y * yPlaneInfo.stride + x;
      const luma = yPlaneData[yIndex];

      // Kiszámítjuk a cél indexet az RGBA ImageData pufferben.
      const rgbaIndex = (y * canvas.width + x) * 4;

      imageData.data[rgbaIndex] = luma;     // Vörös
      imageData.data[rgbaIndex + 1] = luma; // Zöld
      imageData.data[rgbaIndex + 2] = luma; // Kék
      imageData.data[rgbaIndex + 3] = 255;  // Alfa
    }
  }

  ctx.putImageData(imageData, 0, 0);

  // KRITIKUS: Mindig zárja be a VideoFrame-et a memória felszabadításához.
  videoFrame.close();
}

Ez a példa több kulcsfontosságú lépést emel ki: a megfelelő sík elrendezés azonosítása, egy célpuffer lefoglalása, a copyTo használata az adatok kinyeréséhez, és az adatok helyes bejárása a stride segítségével egy új kép létrehozásához.

2. Gyakorlati Példa: Helyben Történő Manipuláció (Szépia Szűrő)

Most végezzünk egy közvetlen adatmanipulációt. A szépia szűrő egy klasszikus effektus, amit könnyű implementálni. Ehhez a példához könnyebb RGBA kerettel dolgozni, amit egy canvas-ről vagy egy WebGL kontextusból nyerhetünk.

async function applySepiaFilter(videoFrame) {
  // Ez a példa feltételezi, hogy a bemeneti keret 'RGBA' vagy 'BGRA'.
  if (videoFrame.format !== 'RGBA' && videoFrame.format !== 'BGRA') {
    console.error('A szépia szűrő példához RGBA keret szükséges.');
    videoFrame.close();
    return null;
  }

  // Lefoglalunk egy puffert a pixel adatok tárolására.
  const frameDataSize = videoFrame.allocationSize();
  const frameData = new Uint8Array(frameDataSize);
  await videoFrame.copyTo(frameData);

  const layout = videoFrame.layout[0]; // Az RGBA egyetlen síkból áll

  // Most manipuláljuk az adatokat a pufferben.
  for (let y = 0; y < videoFrame.codedHeight; y++) {
    for (let x = 0; x < videoFrame.codedWidth; x++) {
      const pixelIndex = y * layout.stride + x * 4; // 4 bájt pixelenként (R,G,B,A)

      const r = frameData[pixelIndex];
      const g = frameData[pixelIndex + 1];
      const b = frameData[pixelIndex + 2];

      const tr = 0.393 * r + 0.769 * g + 0.189 * b;
      const tg = 0.349 * r + 0.686 * g + 0.168 * b;
      const tb = 0.272 * r + 0.534 * g + 0.131 * b;

      frameData[pixelIndex] = Math.min(255, tr);
      frameData[pixelIndex + 1] = Math.min(255, tg);
      frameData[pixelIndex + 2] = Math.min(255, tb);
      // Az Alfa (frameData[pixelIndex + 3]) változatlan marad.
    }
  }

  // Létrehozunk egy *új* VideoFrame-et a módosított adatokkal.
  const newFrame = new VideoFrame(frameData, {
    format: videoFrame.format,
    codedWidth: videoFrame.codedWidth,
    codedHeight: videoFrame.codedHeight,
    timestamp: videoFrame.timestamp,
    duration: videoFrame.duration
  });

  // Ne felejtse el bezárni az eredeti keretet!
  videoFrame.close();

  return newFrame;
}

Ez egy teljes olvasás-módosítás-írás ciklust mutat be: kimásoljuk az adatokat, a stride segítségével végigciklusozunk rajtuk, matematikai transzformációt alkalmazunk minden pixelre, majd létrehozunk egy új VideoFrame-et az eredményül kapott adatokkal. Ez az új keret aztán kirajzolható egy canvas-re, elküldhető egy VideoEncoder-nek, vagy továbbadható egy másik feldolgozási lépésnek.

A Teljesítmény Számít: JavaScript vs. WebAssembly (WASM)

Minden egyes képkockánál több millió pixelen (egy 1080p-s képkocka több mint 2 millió pixelt, azaz 8 millió adatpontot tartalmaz RGBA-ban) való iterálás JavaScriptben lassú lehet. Bár a modern JS motorok hihetetlenül gyorsak, a nagy felbontású videók (HD, 4K) valós idejű feldolgozásához ez a megközelítés könnyen túlterhelheti a fő szálat, ami szaggatott felhasználói élményhez vezet.

Itt válik a WebAssembly (WASM) nélkülözhetetlen eszközzé. A WASM lehetővé teszi, hogy C++, Rust vagy Go nyelven írt kódot futtassunk közel natív sebességgel a böngészőben. A videófeldolgozás munkafolyamata a következővé válik:

1. JavaScriptben: A videoFrame.copyTo() használatával kinyerjük a nyers pixel adatokat egy ArrayBuffer-be.
2. Átadás WASM-nak: Átadunk egy referenciát erre a pufferre a lefordított WASM modulnak. Ez egy nagyon gyors művelet, mivel nem jár adat másolással.
3. WASM-ban (C++/Rust): A magasan optimalizált képfeldolgozó algoritmusainkat közvetlenül a memóriapufferen futtatjuk. Ez nagyságrendekkel gyorsabb, mint egy JavaScript ciklus.
4. Visszatérés JavaScriptbe: Amint a WASM végzett, a vezérlés visszatér a JavaScripthez. Ekkor a módosított puffert felhasználhatjuk egy új VideoFrame létrehozásához.

Bármilyen komoly, valós idejű videómanipulációs alkalmazás – mint például virtuális hátterek, tárgyfelismerés vagy komplex szűrők – esetében a WebAssembly kihasználása nem csupán egy lehetőség, hanem szükségszerűség.

Különböző Pixel Formátumok Kezelése (pl. I420, NV12)

Bár az RGBA egyszerű, leggyakrabban sík-alapú YUV formátumú képkockákat fog kapni egy VideoDecoder-től. Nézzük meg, hogyan kezeljünk egy teljesen sík-alapú formátumot, mint az I420.

Egy I420 formátumú VideoFrame-nek három elrendezés leírója lesz a layout tömbjében:

• layout[0]: Az Y sík (luma). Méretei: codedWidth x codedHeight.
• layout[1]: Az U sík (kroma). Méretei: codedWidth/2 x codedHeight/2.
• layout[2]: A V sík (kroma). Méretei: codedWidth/2 x codedHeight/2.

Így másolná át mindhárom síkot egyetlen pufferbe:

async function extractI420Planes(videoFrame) {
  const totalSize = videoFrame.allocationSize({ format: 'I420' });
  const allPlanesData = new Uint8Array(totalSize);

  const layouts = await videoFrame.copyTo(allPlanesData);

  // a layouts egy 3 PlaneLayout objektumból álló tömb
  console.log('Y Sík Elrendezés:', layouts[0]); // { offset: 0, stride: ... }
  console.log('U Sík Elrendezés:', layouts[1]); // { offset: ..., stride: ... }
  console.log('V Sík Elrendezés:', layouts[2]); // { offset: ..., stride: ... }

  // Mostantól minden síkot elérhet az `allPlanesData` pufferen belül
  // a specifikus eltolás és stride használatával.

  const yPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[0].offset,
    layouts[0].stride * videoFrame.codedHeight
  );

  // Figyelem, a kroma méretek feleződnek!
  const uPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[1].offset,
    layouts[1].stride * (videoFrame.codedHeight / 2)
  );

  const vPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[2].offset,
    layouts[2].stride * (videoFrame.codedHeight / 2)
  );

  console.log('Elért Y sík mérete:', yPlaneView.byteLength);
  console.log('Elért U sík mérete:', uPlaneView.byteLength);

  videoFrame.close();
}

Egy másik gyakori formátum az NV12, ami félig sík-alapú. Két síkja van: egy az Y-nak, és egy második sík, ahol az U és V értékek összefésülve találhatók (pl. [U1, V1, U2, V2, ...]). A WebCodecs API ezt transzparensen kezeli; egy NV12 formátumú VideoFrame-nek egyszerűen két elrendezése lesz a layout tömbjében.

Kihívások és Bevált Gyakorlatok

Ilyen alacsony szinten dolgozni hatékony, de felelősséggel jár.

A Memóriakezelés Elsődleges Fontosságú

Egy VideoFrame jelentős mennyiségű memóriát foglal, amit gyakran a JavaScript szemétgyűjtőjének heap-jén kívül kezel a rendszer. Ha nem szabadítja fel explicit módon ezt a memóriát, memóriaszivárgást okoz, ami a böngésző fül összeomlásához vezethet.

Mindig, de mindig hívja meg a videoFrame.close() metódust, amikor végzett egy képkockával.

Aszinkron Természet

Minden adathozzáférés aszinkron. Az alkalmazás architektúrájának helyesen kell kezelnie a Promise-ok és az async/await folyamatát, hogy elkerülje a versenyhelyzeteket (race conditions) és biztosítsa a zökkenőmentes feldolgozási folyamatot.

Böngésző Kompatibilitás

A WebCodecs egy modern API. Bár minden nagyobb böngésző támogatja, mindig ellenőrizze a rendelkezésre állását, és legyen tisztában az esetleges gyártóspecifikus implementációs részletekkel vagy korlátozásokkal. Használjon funkcióészlelést (feature detection), mielőtt megpróbálná használni az API-t.

Konklúzió: Új Határvonal a Webes Videóban

Az a képesség, hogy a WebCodecs API-n keresztül közvetlenül hozzáférhetünk és manipulálhatjuk egy VideoFrame nyers sík adatait, paradigmaváltást jelent a web alapú médiaalkalmazások számára. Eltávolítja a <video> elem fekete dobozát, és a fejlesztőknek azt a részletes vezérlést adja a kezébe, ami korábban csak a natív alkalmazások kiváltsága volt.

A videó memóriaelrendezésének – síkok, stride és színformátumok – alapjainak megértésével, valamint a WebAssembly erejének kihasználásával a teljesítménykritikus műveletekhez, most már hihetetlenül kifinomult videófeldolgozó eszközöket építhet közvetlenül a böngészőben. A valós idejű színkorrekciótól és egyedi vizuális effektusoktól kezdve a kliensoldali gépi tanuláson át a videóelemzésig a lehetőségek tárháza hatalmas. A nagy teljesítményű, alacsony szintű videó korszaka a weben valóban elkezdődött.