Technical review: Document VideoFrame.metadata()

[chrisdavidmills]

Description

Chrome 145 adds support for the VideoFrame.metadata() method; see https://chromestatus.com/feature/5186046555586560.

This PR documents that method, and also adds information about the metadata option to the VideoFrame() constructor page.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs (3 pages)

• /en-US/docs/Web/API/VideoFrame/VideoFrame
• /en-US/docs/Web/API/VideoFrame/metadata
• /en-US/docs/Web/API/VideoFrame

External URLs (2)

URL: /en-US/docs/Web/API/VideoFrame/metadata
Title: VideoFrame: metadata() method

• https://w3c.github.io/webcodecs/video_frame_metadata_registry.html (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/VideoFrame/VideoFrame
Title: VideoFrame: VideoFrame() constructor

• https://w3c.github.io/webcodecs/video_frame_metadata_registry.html (2 times) (Note! This may be a new URL 👀)

(comment last updated: 2026-03-23 11:07:18)

[dalecurtis]

Because the only frames which have this must come from WebRTC, frames decoded by WebCodecs won't have the value. So you'll instead want to say something about "custom encoding pipelines"

You may want to drop the only for "generally" since user generated frames may add this value at will.

[chrisdavidmills]

OK, I've updated this description to:

The RTP timestamp of the corresponding encoded frame. Video frames originating from WebRTC sources will have rtpTimestamp metadata. This allows applications using a {{domxref("MediaStreamTrackProcessor")}} (for example, to render decoded WebRTC frames to a <canvas>) or a custom decoding pipeline to correlate each exposed frame with its original RTP transport timestamp. This is useful for example when aligning video with audio segments or debugging latency issues.

So I've removed "only", and the mention of WebCodecs, and kept the bit about custom pipelines. Does that address your concern here?

[dalecurtis]

Defer to you but image in this case is a CanvasImageSource so there may be a more helpful comment to have here and below.

[chrisdavidmills]

Ah, I can see the porential for confusion here. I've sidestepped this by just removing the comments (we don't tend to have comments in the syntax code block anyway) and leaving a line break between the first constructor type and the second, to provide the indication that there are two different types. I think this is enough.

[dalecurtis]

Not helpful to say this here since this dictionary is user controlled and can have whatever the caller wants in it. I.e., even if the frame is not from WebRTC they could add this value.

[chrisdavidmills]

OK, that's fair enough. I've removed the second sentence from the description; in each case, it now reads "The RTP timestamp of the corresponding encoded frame." Does that answer your concern?

[dalecurtis]

Ditto on limitation text

[chrisdavidmills]

updated as per above comment.

[dalecurtis]

lgtm, but can't approve!

[dalecurtis]

I'd just delete the "... or a custom ..." part since it doesn't really make logical sense. I.e., RTC must have done the decoding or the site attached the metadata to its already decoded frames afterwards. In which case, they probably wouldn't bother with attaching the metadata since it's already known to the site.