Technical review: Document VideoFrame.metadata()

files/en-us/web/api/videoframe/index.md

@@ -70,6 +70,8 @@ Created frames may then turned into a media track, for example with the {{domxre
   - : Creates a new `VideoFrame` object with reference to the same media resource as the original.
 - {{domxref("VideoFrame.close()")}}
   - : Clears all states and releases the reference to the media resource.
+- {{domxref("VideoFrame.metadata()")}}
+  - : Returns the metadata asssociated with the `VideoFrame`.
 
 ## Examples
 

files/en-us/web/api/videoframe/metadata/index.md

@@ -0,0 +1,47 @@
+---
+title: "VideoFrame: metadata() method"
+short-title: metadata()
+slug: Web/API/VideoFrame/metadata
+page-type: web-api-instance-method
+browser-compat: api.VideoFrame.metadata
+---
+
+{{APIRef("Web Codecs API")}}{{AvailableInWorkers("window_and_dedicated")}}
+
+The **`metadata()`** method of the {{domxref("VideoFrame")}} interface returns the metadata asssociated with the frame.
+
+## Syntax
+
+```js-nolint
+metadata()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+An object containing metadata describing the video frame, as specified by the [WebCodecs VideoFrame Metadata Registry](https://w3c.github.io/webcodecs/video_frame_metadata_registry.html).
+This can contain the following properties:
+
+- `rtpTimestamp` {{optional_inline}}
+  - : The RTP timestamp of the corresponding encoded frame. Video frames originating from [WebRTC](/en-US/docs/Web/API/WebRTC_API) 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.
+
+If the video frame doesn't have any of the listed metadata items associated with it, `metadata()` will return an empty object.
+
+## Examples
+
+### Basic usage
+
+```js
+const metadata = frame.metadata();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/videoframe/videoframe/index.md

@@ -15,12 +15,13 @@ The **`VideoFrame()`** constructor creates a new {{domxref("VideoFrame")}} objec
 ```js-nolint
 new VideoFrame(image)
 new VideoFrame(image, options)
+
 new VideoFrame(data, options)
 ```
 
 ### Parameters
 
-The first type of constructor (see above) creates a new {{domxref("VideoFrame")}} from an image. Its parameters are:
+The first type of constructor creates a new {{domxref("VideoFrame")}} from an image. Its parameters are:
 
 - `image`
   - : An image containing the image data for the new `VideoFrame`. It can be one of the following objects:
@@ -32,14 +33,26 @@ The first type of constructor (see above) creates a new {{domxref("VideoFrame")}
     or another {{domxref("VideoFrame")}}.
 - `options` {{Optional_Inline}}
   - : An object containing the following:
-    - `duration` {{Optional_Inline}}
-      - : An integer representing the duration of the frame in microseconds.
-    - `timestamp`
-      - : An integer representing the timestamp of the frame in microseconds.
     - `alpha` {{Optional_Inline}}
       - : A string, describing how the user agent should behave when dealing with alpha channels. The default value is "keep".
         - `"keep"`: Indicates that the user agent should preserve alpha channel data.
         - `"discard"`: Indicates that the user agent should ignore or remove alpha channel data.
+    - `displayHeight` {{Optional_Inline}}
+      - : The height of the `VideoFrame` when displayed after applying aspect-ratio adjustments.
+    - `displayWidth` {{Optional_Inline}}
+      - : The width of the `VideoFrame` when displayed after applying aspect-ratio adjustments.
+    - `duration` {{Optional_Inline}}
+      - : An integer representing the duration of the frame in microseconds.
+    - `flip` {{optional_inline}}
+      - : A boolean. If `true`, horizontal mirroring is applied. Defaults to `false`.
+    - `metadata` {{optional_inline}}
+      - : An object containing metadata describing the video frame, specified by the [WebCodecs VideoFrame Metadata Registry](https://w3c.github.io/webcodecs/video_frame_metadata_registry.html), which can contain the following properties:
+        - `rtpTimestamp` {{optional_inline}}
+          - : The RTP timestamp of the corresponding encoded frame.
+    - `rotation` {{optional_inline}}
+      - : An integer representing the rotation (0, 90, 180, or 270) in degrees clockwise. Defaults to `0`. Arbitrary numbers (including negatives) are rounded to the next quarter turn.
+    - `timestamp`
+      - : An integer representing the timestamp of the frame in microseconds.
     - `visibleRect` {{Optional_Inline}}
       - : An object representing the visible rectangle of the `VideoFrame`, containing the following:
         - `x`
@@ -50,21 +63,35 @@ The first type of constructor (see above) creates a new {{domxref("VideoFrame")}
           - : The width of the frame.
         - `height`
           - : The height of the frame.
-    - `displayWidth` {{Optional_Inline}}
-      - : The width of the `VideoFrame` when displayed after applying aspect-ratio adjustments.
-    - `displayHeight` {{Optional_Inline}}
-      - : The height of the `VideoFrame` when displayed after applying aspect-ratio adjustments.
-    - `flip` {{optional_inline}}
-      - : A boolean. If `true`, horizontal mirroring is applied. Defaults to `false`.
-    - `rotation` {{optional_inline}}
-      - : An integer representing the rotation (0, 90, 180, or 270) in degrees clockwise. Defaults to `0`. Arbitrary numbers (including negatives) are rounded to the next quarter turn.
 
-The second type of constructor (see above) creates a new {{domxref("VideoFrame")}} from an {{jsxref("ArrayBuffer")}}. Its parameters are:
+The second type of constructor creates a new {{domxref("VideoFrame")}} from an {{jsxref("ArrayBuffer")}}. Its parameters are:
 
 - `data`
   - : An {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, or a {{jsxref("DataView")}} containing the data for the new `VideoFrame`.
 - `options`
   - : An object containing the following:
+    - `codedHeight`
+      - : Height of the `VideoFrame` in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.
+    - `codedWidth`
+      - : Width of the `VideoFrame` in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.
+    - `colorSpace`
+      - : An object representing the color space of the `VideoFrame`, containing the following:
+        - `primaries`
+          - : A string representing the video color primaries, described on the page for the {{domxref("VideoColorSpace.primaries")}} property.
+        - `transfer`
+          - : A string representing the video color transfer function, described on the page for the {{domxref("VideoColorSpace.transfer")}} property.
+        - `matrix`
+          - : A string representing the video color matrix, described on the page for the {{domxref("VideoColorSpace.matrix")}} property.
+        - `fullRange`
+          - : A Boolean. If `true`, indicates that full-range color values are used.
+    - `displayHeight` {{Optional_Inline}}
+      - : The height of the `VideoFrame` when displayed after applying aspect ratio adjustments.
+    - `displayWidth` {{Optional_Inline}}
+      - : The width of the `VideoFrame` when displayed after applying aspect ratio adjustments.
+    - `duration` {{Optional_Inline}}
+      - : An integer representing the duration of the frame in microseconds.
+    - `flip` {{optional_inline}}
+      - : A boolean. If `true`, horizontal mirroring is applied. Defaults to `false`.
     - `format`
       - : A string representing the video pixel format. One of the following strings, which are fully described on the page for the {{domxref("VideoFrame.format","format")}} property:
         - `"I420"`
@@ -76,21 +103,23 @@ The second type of constructor (see above) creates a new {{domxref("VideoFrame")
         - `"RGBX"`
         - `"BGRA"`
         - `"BGRX"`
-    - `codedWidth`
-      - : Width of the `VideoFrame` in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.
-    - `codedHeight`
-      - : Height of the `VideoFrame` in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.
-    - `timestamp`
-      - : An integer representing the timestamp of the frame in microseconds.
-    - `duration` {{Optional_Inline}}
-      - : An integer representing the duration of the frame in microseconds.
     - `layout` {{Optional_Inline}}
       - : A list containing the following values for each plane in the `VideoFrame`:
         - `offset`
           - : An integer representing the offset in bytes where the given plane begins.
         - `stride`
           - : An integer representing the number of bytes, including padding, used by each row of the plane.
             Planes may not overlap. If no `layout` is specified, the planes will be tightly packed.
+    - `metadata` {{optional_inline}}
+      - : An object containing metadata describing the video frame, specified by the [WebCodecs VideoFrame Metadata Registry](https://w3c.github.io/webcodecs/video_frame_metadata_registry.html), which can contain the following properties:
+        - `rtpTimestamp` {{optional_inline}}
+          - : The RTP timestamp of the corresponding encoded frame.
+    - `rotation` {{optional_inline}}
+      - : An integer representing the rotation (0, 90, 180, or 270) in degrees clockwise. Defaults to `0`. Arbitrary numbers (including negatives) are rounded to the next quarter turn.
+    - `timestamp`
+      - : An integer representing the timestamp of the frame in microseconds.
+    - `transfer`
+      - : An array of {{jsxref("ArrayBuffer")}}s that `VideoFrame` will detach and take ownership of. If the array contains the {{jsxref("ArrayBuffer")}} backing `data`, `VideoFrame` will use that buffer directly instead of copying from it.
     - `visibleRect` {{Optional_Inline}}
       - : An object representing the visible rectangle of the `VideoFrame`, containing the following:
         - `x`
@@ -101,26 +130,6 @@ The second type of constructor (see above) creates a new {{domxref("VideoFrame")
           - : The width of the frame.
         - `height`
           - : The height of the frame.
-    - `displayWidth` {{Optional_Inline}}
-      - : The width of the `VideoFrame` when displayed after applying aspect ratio adjustments.
-    - `displayHeight` {{Optional_Inline}}
-      - : The height of the `VideoFrame` when displayed after applying aspect ratio adjustments.
-    - `colorSpace`
-      - : An object representing the color space of the `VideoFrame`, containing the following:
-        - `primaries`
-          - : A string representing the video color primaries, described on the page for the {{domxref("VideoColorSpace.primaries")}} property.
-        - `transfer`
-          - : A string representing the video color transfer function, described on the page for the {{domxref("VideoColorSpace.transfer")}} property.
-        - `matrix`
-          - : A string representing the video color matrix, described on the page for the {{domxref("VideoColorSpace.matrix")}} property.
-        - `fullRange`
-          - : A Boolean. If `true`, indicates that full-range color values are used.
-    - `transfer`
-      - : An array of {{jsxref("ArrayBuffer")}}s that `VideoFrame` will detach and take ownership of. If the array contains the {{jsxref("ArrayBuffer")}} backing `data`, `VideoFrame` will use that buffer directly instead of copying from it.
-    - `flip` {{optional_inline}}
-      - : A boolean. If `true`, horizontal mirroring is applied. Defaults to `false`.
-    - `rotation` {{optional_inline}}
-      - : An integer representing the rotation (0, 90, 180, or 270) in degrees clockwise. Defaults to `0`. Arbitrary numbers (including negatives) are rounded to the next quarter turn.
 
 ## Examples