[WebCodecs VideoFrame metadata registry] Introduce VideoFrame metadata

.github/workflows/auto-publish.yml

@@ -98,6 +98,11 @@ jobs:
             echidna_token: ECHIDNA_TOKEN_HEVC_REGISTRATION
             build_override: |
               status: NOTE-WD
+          - source: video_frame_metadata_registry.src.html
+            destination: video_frame_metadata_registry.html
+            echidna_token: ECHIDNA_TOKEN_VIDEOFRAMEMETADATA_REGISTRY
+            build_override: |
+              status: DRY
     steps:
       # See doc at https://github.com/actions/checkout#checkout-v2
       - name: Checkout repository

.gitignore

@@ -13,6 +13,7 @@ out/
 pcm_codec_registration.html
 ulaw_codec_registration.html
 ulaw_codec_registration.html
+video_frame_metadata_registry.html
 vorbis_codec_registration.html
 vp8_codec_registration.html
 vp9_codec_registration.html

index.src.html

@@ -99,6 +99,12 @@
 
 spec: webrtc-svc; urlPrefix: https://w3c.github.io/webrtc-svc/
     type: dfn; text: scalability mode identifier; url:#scalabilitymodes*
+
+spec: webcodecs-video-frame-metadata-registry; urlPrefix: https://w3c.github.io/webcodecs/video-frame-metadata-registry.html
+    type: dictionary; text: VideoFrameMetadata; url: dictdef-videoframemetadata
+
+spec: ECMASCRIPT; urlPrefix: https://tc39.es/ecma262/
+    type: dfn; text: the current Realm; url: #current-realm
 </pre>
 
 <pre class='biblio'>
@@ -108,6 +114,15 @@
     "title": "Coding-independent code points for video signal type identification",
     "publisher": "ITU",
     "date": "December 2016"
+  },
+  "WEBCODECS-VIDEO-FRAME-METADATA-REGISTRY": {
+    "href": "https://w3c.github.io/webcodecs/video_frame_metadata_registry.html",
+    "title": "WebCodecs VideoFrame Metadata Registry",
+    "publisher": "W3C",
+    "authors": [
+      "Youenn Fablet"
+    ],
+    "status": "ED"
   }
 }
 </pre>
@@ -3182,6 +3197,8 @@
   readonly attribute long long? timestamp;          // microseconds
   readonly attribute VideoColorSpace colorSpace;
 
+  VideoFrameMetadata metadata();
+
   unsigned long allocationSize(
       optional VideoFrameCopyToOptions options = {});
   Promise<sequence<PlaneLayout>> copyTo(
@@ -3204,6 +3221,8 @@
   // Default matches image unless visibleRect is provided.
   [EnforceRange] unsigned long displayWidth;
   [EnforceRange] unsigned long displayHeight;
+
+  VideoFrameMetadata metadata;
 };
 
 dictionary VideoFrameBufferInit {
@@ -3279,6 +3298,11 @@
 : <dfn attribute for=VideoFrame>[[color space]]</dfn>
 :: The {{VideoColorSpace}} associated with this frame.
 
+: <dfn attribute for=VideoFrame>\[[metadata]]</dfn>
+:: The {{VideoFrameMetadata}} associated with this frame.
+     {{VideoFrameMetadata}} is defined in [[webcodecs-video-frame-metadata-registry]].
+     By design, all {{VideoFrameMetadata}} properties are serializable.
+
 ### Constructors ###{#videoframe-constructors}
 
 <dfn constructor for=VideoFrame title="VideoFrame(image, init)">
@@ -3317,7 +3341,9 @@
             {{InvalidStateError}} {{DOMException}}.
         2. Let |currentPlaybackFrame| be the {{VideoFrame}} at the [=current
             playback position=].
-        3. Run the [=VideoFrame/Initialize Frame From Other Frame=] algorithm
+        3. If {{VideoFrameInit/metadata}} does not [=map/exist=] in |init|,
+            assign |currentPlaybackFrame|.{{VideoFrame/[[metadata]]}} to it.
+        4. Run the [=VideoFrame/Initialize Frame From Other Frame=] algorithm
             with |init|, |frame|, and |currentPlaybackFrame|.
 
     - {{HTMLCanvasElement}}
@@ -3426,6 +3452,8 @@
     9. Assign the result of running the [=VideoFrame/Pick Color Space=]
         algorithm, with |colorSpace| and {{VideoFrame/[[format]]}}, to
         {{VideoFrame/[[color space]]}}.
+    10. Assign the result of calling [=Copy VideoFrame metadata=]
+        with |init|'s {{VideoFrameInit/metadata}} to |frame|.{{VideoFrame/[[metadata]]}}.
 17. Return |frame|.
 
 ### Attributes ###{#videoframe-attributes}
@@ -3624,6 +3652,15 @@
 
     When invoked, run the [=Close VideoFrame=] algorithm with [=this=].
 
+: <dfn method for=VideoFrame>metadata()</dfn>
+:: Gets the {{VideoFrameMetadata}} associated with this frame.
+
+    When invoked, run these steps:
+    1. If {{platform object/[[Detached]]}} is <code>true</code>,
+        throw an {{InvalidStateError}} {{DOMException}}.
+    2. Return the result of calling [=Copy VideoFrame metadata=]
+        with {{VideoFrame/[[metadata]]}}.
+
 ### Algorithms ###{#videoframe-algorithms}
 : <dfn>Create a VideoFrame</dfn> (with |output|, |timestamp|, |duration|, |displayAspectWidth|, |displayAspectHeight|, and |colorSpace|)
 :: 1. Let |frame| be a new {{VideoFrame}}, constructed as follows:
@@ -3747,6 +3784,8 @@
         |otherFrame|.{{VideoFrame/timestamp}} to
         |frame|.{{VideoFrame/timestamp}}.
     11. Assign |format| to |frame|.{{VideoFrame/[[format]]}}.
+    12. Assign the result of calling [=Copy VideoFrame metadata=]
+        with |init|'s {{VideoFrameInit/metadata}} to |frame|.{{VideoFrame/[[metadata]]}}.
 
 : <dfn for=VideoFrame>Initialize Frame With Resource and Size</dfn> (with
     |init|,  |frame|, |resource|, |width| and |height|)
@@ -3825,6 +3864,7 @@
         and {{VideoFrame/[[display height]]}}.
     5. Assign `null` to |frame|'s {{VideoFrame/[[duration]]}} and
         {{VideoFrame/[[timestamp]]}}.
+    6. Assign a new {{VideoFrameMetadata}} to |frame|.{{VideoFrame/[[metadata]]}}.
 
 : <dfn for=VideoFrame>Parse VideoFrameCopyToOptions</dfn> (with |options|)
 ::  1. Let |defaultRect| be the result of performing the getter steps for
@@ -3998,6 +4038,13 @@
             [=combined buffer layout/allocationSize=].
     9. Return |combinedLayout|.
 
+: <dfn for=VideoFrame>Copy VideoFrame metadata</dfn> (with |metadata|)
+:: 1. Let |metadataCopySerialized| be [$StructuredSerialize$](|metadata|).
+    2. Let |metadataCopy| be [$StructuredDeserialize$](|metadataCopySerialized|, [=the current Realm=]).
+    3. return |metadataCopy|.
+
+The goal of this algorithm is to ensure that metadata owned by a {{VideoFrame}} is immutable.
+
 ### Transfer and Serialization ###{#videoframe-transfer-serialization}
 
 : The {{VideoFrame}} [=transfer steps=] (with |value| and |dataHolder|) are:

video_frame_metadata_registry.src.html

@@ -0,0 +1,70 @@
+<pre class='metadata'>
+Title: WebCodecs VideoFrame Metadata Registry
+Repository: w3c/webcodecs
+Status: DRY
+Shortname: webcodecs-video-frame-metadata-registry
+Level: none
+Group: mediawg
+ED: https://w3c.github.io/webcodecs/video-frame-metadata-registry.html
+TR: https://www.w3.org/TR/webcodecs-video-frame-metadata-registry/
+Editor: Youenn Fablet, w3cid 96458, Apple Inc., [email protected]
+
+Boilerplate: omit conformance
+
+Abstract: This registry is intended to enumerate the metadata fields that can be attached
+    to {{VideoFrame}} objects via the {{VideoFrameMetadata}} dictionary.
+
+Markup Shorthands:css no, markdown yes, dfn yes
+!Participate: <a href="https://github.com/w3c/webcodecs">Git Repository.</a>
+!Participate: <a href="https://github.com/w3c/webcodecs/issues/new">File an issue.</a>
+!Version History: <a href="https://github.com/w3c/webcodecs/commits">https://github.com/w3c/webcodecs/commits</a>
+</pre>
+
+<pre class='anchors'>
+spec: WEBCODECS; urlPrefix: https://w3c.github.io/webcodecs/#
+    type: dictionary
+        text: VideoFrame; url: dictdef-videoframe
+</pre>
+
+
+Registration Entry Requirements {#registration-entry-requirements}
+==================================================================
+
+A registration entry is a document describing one or several metadata entry,
+and has the following requirements:
+1. Each metadata entry is defined as a separate {{VideoFrameMetadata}}
+    dictionary member.
+2. Each metadata entry must be serializable.
+3. Each metadata must be defined by a W3C specification and have clearly defined semantics.
+    In particular, its interactions with the media processing pipeline
+    (encoders, decoders, renderers, etc.) should be well defined.
+4. A candidate registration entry must be announced by filing an issue in the
+    WebCodecs GitHub issue tracker so they can be discussed and evaluated for
+    compliance before being added to the registry. If the Media Working Group
+    reaches consensus to accept the candidate, a pull request should be drafted
+    (either by editors or by the party requesting the candidate registration)
+    to register the candidate. The registry editors will review and merge the
+    pull request.
+
+VideoFrameMetadata definition {#videoframemetadata-definition}
+=============================================================
+<xmp class='idl'>
+dictionary VideoFrameMetadata {
+};
+</xmp>
+
+VideoFrameMetadata members {#videoframemetadata-members}
+========================================================
+
+
+Privacy Considerations {#privacy-considerations}
+================================================
+
+Please refer to the section [[WEBCODECS#privacy-considerations|Privacy
+Considerations]] in [[WEBCODECS]].
+
+Security Considerations {#security-considerations}
+==================================================
+
+Please refer to the section [[WEBCODECS#security-considerations|Security
+Considerations]] in [[WEBCODECS]].