From 71a237268e8a60658314d3470332300179a50240 Mon Sep 17 00:00:00 2001
From: Florent Castelli <florent.castelli@gmail.com>
Date: Thu, 2 May 2024 15:05:42 +0200
Subject: [PATCH] Add captureTimestamp and senderCaptureTimeOffset to frame
 metadata

Fixes #225
---
 index.bs | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/index.bs b/index.bs
index 3d15bda..0405603 100644
--- a/index.bs
+++ b/index.bs
@@ -48,6 +48,11 @@ spec:webidl; type:dfn; text:resolve
    "CloneArrayBuffer": {
     "href": "https://tc39.es/ecma262/#sec-clonearraybuffer",
     "title": "CloneArrayBuffer"
+   },
+   "RTP-EXT-CAPTURE-TIME": {
+    "href": "https://webrtc.googlesource.com/src/+/refs/heads/main/docs/native-code/rtp-hdrext/abs-capture-time",
+    "title": "RTP Header Extension for Absolute Capture Time",
+    "publisher": "WebRTC Project"
    }
 }
 </pre>
@@ -293,6 +298,10 @@ The <dfn method for="SFrameTransform">setEncryptionKey(|key|, |keyID|)</dfn> met
 
 # RTCRtpScriptTransform # {#scriptTransform}
 
+In this section, the capture system refers to the system where media is sourced from and the sender system
+refers to the system that is sending RTP and RTCP packets to the receiver system where {{RTCEncodedVideoFrameMetadata}} data
+or {{RTCEncodedAudioFrameMetadata}} data is populated.
+
 ## <dfn enum>RTCEncodedVideoFrameType</dfn> dictionary ## {#RTCEncodedVideoFrameType}
 <pre class="idl">
 // New enum for video frame types. Will eventually re-use the equivalent defined
@@ -358,6 +367,8 @@ dictionary RTCEncodedVideoFrameMetadata {
     sequence&lt;unsigned long&gt; contributingSources;
     long long timestamp;    // microseconds
     unsigned long rtpTimestamp;
+    DOMHighResTimeStamp captureTimestamp;
+    DOMHighResTimeStamp senderCaptureTimeOffset;
     DOMString mimeType;
 };
 </pre>
@@ -430,6 +441,51 @@ dictionary RTCEncodedVideoFrameMetadata {
             The RTP timestamp identifier is an unsigned integer value per [[RFC3550]]
             that reflects the sampling instant of the first octet in the RTP data packet.
         </p>
+    </dd>
+        <dt>
+        <dfn dict-member>captureTimestamp</dfn> <span class="idlMemberType">DOMHighResTimeStamp</span>
+    </dt>
+    <dd>
+        <p>
+            The {{captureTimestamp}} is the timestamp that, the most recent frame (from an RTP packet
+            originating from this source) delivered to the {{RTCRtpReceiver}}'s {{MediaStreamTrack}}, was
+            originally captured. Its reference clock is the capture system's NTP clock (same clock used
+            to generate NTP timestamps for RTCP sender reports on that system).
+
+            On populating this member, the user agent MUST run the following steps:
+                1. If the relevant RTP packet contains the [[RTP-EXT-CAPTURE-TIME|RTP Header Extension for
+                    Absolute Capture Time]], return the value of the
+                    [[RTP-EXT-CAPTURE-TIME#absolute-capture-timestamp|absolute capture timestamp]] field and
+                    abort these steps.
+                1. Otherwise, if the relevant RTP packet does not contain the RTP Header Extension for
+                    Absolute Capture Time but a previous RTP packet did, return the result of calculating the
+                    absolute capture timestamp according to [[RTP-EXT-CAPTURE-TIME#timestamp-interpolation|
+                    timestamp interpolation]] and abort these steps.
+                1. Otherwise, return undefined.
+
+        </p>
+    </dd>
+        <dt>
+        <dfn dict-member>senderCaptureTimeOffset</dfn> <span class="idlMemberType">DOMHighResTimeStamp</span>
+    </dt>
+    <dd>
+        <p>
+            The {{senderCaptureTimeOffset}} is the sender system's estimate of the offset between its own
+            NTP clock and the capture system's NTP clock, for the same frame that the {{captureTimestamp}} was
+            originated from.
+
+            On populating this member, the user agent MUST run the following steps:
+                1. If the relevant RTP packet contains the [[RTP-EXT-CAPTURE-TIME|RTP Header Extension for Absolute
+                    Capture Time]] and the estimated [[RTP-EXT-CAPTURE-TIME#estimated-capture-clock-offset|capture
+                    clock offset field]] is present, return the value of the estimated capture clock offset field
+                    and abort these steps.
+                1. Otherwise, if the relevant RTP packet does not contain the [[RTP-EXT-CAPTURE-TIME|RTP Header
+                    Extension for Absolute Capture Time]]'s [[RTP-EXT-CAPTURE-TIME#estimated-capture-clock-offset|
+                    estimated capture clock offset]] field, but a previous RTP packet did, return the most recent
+                    value that was present and abort these steps.
+                1. Otherwise, return undefined.
+
+        </p>
     </dd>
     <dt>
         <dfn dict-member>mimeType</dfn> <span class="idlMemberType">DOMString</span>
@@ -611,6 +667,8 @@ dictionary RTCEncodedAudioFrameMetadata {
     sequence&lt;unsigned long&gt; contributingSources;
     short sequenceNumber;
     unsigned long rtpTimestamp;
+    DOMHighResTimeStamp captureTimestamp;
+    DOMHighResTimeStamp senderCaptureTimeOffset;
     DOMString mimeType;
 };
 </pre>
@@ -664,6 +722,51 @@ dictionary RTCEncodedAudioFrameMetadata {
             that reflects the sampling instant of the first octet in the RTP data packet.
         </p>
     </dd>
+    <dt>
+        <dfn dict-member>captureTimestamp</dfn> <span class="idlMemberType">DOMHighResTimeStamp</span>
+    </dt>
+    <dd>
+        <p>
+            The {{captureTimestamp}} is the timestamp that, the most recent frame (from an RTP packet
+            originating from this source) delivered to the {{RTCRtpReceiver}}'s {{MediaStreamTrack}}, was
+            originally captured. Its reference clock is the capture system's NTP clock (same clock used
+            to generate NTP timestamps for RTCP sender reports on that system).
+
+            On populating this member, the user agent MUST run the following steps:
+                1. If the relevant RTP packet contains the [[RTP-EXT-CAPTURE-TIME|RTP Header Extension for
+                    Absolute Capture Time]], return the value of the
+                    [[RTP-EXT-CAPTURE-TIME#absolute-capture-timestamp|absolute capture timestamp]] field and
+                    abort these steps.
+                1. Otherwise, if the relevant RTP packet does not contain the RTP Header Extension for
+                    Absolute Capture Time but a previous RTP packet did, return the result of calculating the
+                    absolute capture timestamp according to [[RTP-EXT-CAPTURE-TIME#timestamp-interpolation|
+                    timestamp interpolation]] and abort these steps.
+                1. Otherwise, return undefined.
+
+        </p>
+    </dd>
+        <dt>
+        <dfn dict-member>senderCaptureTimeOffset</dfn> <span class="idlMemberType">DOMHighResTimeStamp</span>
+    </dt>
+    <dd>
+        <p>
+            The {{senderCaptureTimeOffset}} is the sender system's estimate of the offset between its own
+            NTP clock and the capture system's NTP clock, for the same frame that the {{captureTimestamp}} was
+            originated from.
+
+            On populating this member, the user agent MUST run the following steps:
+                1. If the relevant RTP packet contains the [[RTP-EXT-CAPTURE-TIME|RTP Header Extension for Absolute
+                    Capture Time]] and the estimated [[RTP-EXT-CAPTURE-TIME#estimated-capture-clock-offset|capture
+                    clock offset field]] is present, return the value of the estimated capture clock offset field
+                    and abort these steps.
+                1. Otherwise, if the relevant RTP packet does not contain the [[RTP-EXT-CAPTURE-TIME|RTP Header
+                    Extension for Absolute Capture Time]]'s [[RTP-EXT-CAPTURE-TIME#estimated-capture-clock-offset|
+                    estimated capture clock offset]] field, but a previous RTP packet did, return the most recent
+                    value that was present and abort these steps.
+                1. Otherwise, return undefined.
+
+        </p>
+    </dd>
     <dt>
         <dfn dict-member>mimeType</dfn> <span class="idlMemberType">DOMString</span>
     </dt>