MediaStreamTrackProcessor frame counters

at a glance

why it exists

MediaStreamTrackProcessor exposes a MediaStreamTrack (camera, screen capture, audio) as a ReadableStream of VideoFrame or AudioData objects. If the consuming code (e.g. a WebCodecs encoder or a canvas-drawing loop) cannot keep up with the incoming frame rate, the processor silently drops frames rather than buffering indefinitely.

Before Chrome 150 there was no way to tell how many frames had been dropped. Developers building WebRTC pipelines, video effects, or recording applications had no visibility into whether their processing was keeping up. The new discardedFrames and totalFrames counters surface this information directly on the processor, making it possible to detect back-pressure problems and measure pipeline health.

shape of the API

Both properties are read-only and increase monotonically. The drop rate can be computed as discardedFrames / totalFrames.

example

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const processor = new MediaStreamTrackProcessor({ track });
const reader = processor.readable.getReader();

let frameCount = 0;

async function processFrames() {
  while (true) {
    const { value: frame, done } = await reader.read();
    if (done) break;

    // Do something with the frame (e.g. encode, draw to canvas)
    frame.close();
    frameCount++;

    // Chrome 150+: monitor pipeline health
    if (frameCount % 60 === 0) {
      const total = processor.totalFrames;
      const dropped = processor.discardedFrames;
      const dropRate = total > 0 ? (dropped / total * 100).toFixed(1) : 0;
      console.log(`Frames: ${total} total, ${dropped} dropped (${dropRate}%)`);
      if (dropped / total > 0.1) {
        console.warn('High frame drop rate — processing pipeline too slow');
      }
    }
  }
}

processFrames();

browser support

see also

• Chrome Platform Status — MediaStreamTrackProcessor frame counters
• Media Capture Transform — W3C spec