Merge pull request #215 from w3c/keyframe-api

Add an API for a "keyframe has been requested" event

Author: alvestrand

index.bs

@@ -750,18 +750,28 @@ partial interface DedicatedWorkerGlobalScope {
 };
 
 [Exposed=DedicatedWorker]
-interface RTCRtpScriptTransformer {
+interface RTCRtpScriptTransformer : EventTarget {
+    // Attributes and methods related to the transformer source
     readonly attribute ReadableStream readable;
-    readonly attribute WritableStream writable;
-    readonly attribute any options;
     Promise<unsigned long long> generateKeyFrame(optional DOMString rid);
     Promise<undefined> sendKeyFrameRequest();
+    // Attributes and methods related to the transformer sink
+    readonly attribute WritableStream writable;
+    attribute EventHandler onkeyframerequest;
+    // Attributes for configuring the Javascript code
+    readonly attribute any options;
 };
 
 [Exposed=Window]
 interface RTCRtpScriptTransform {
     constructor(Worker worker, optional any options, optional sequence<object> transfer);
 };
+
+[Exposed=DedicatedWorker]
+interface KeyFrameRequestEvent : Event {
+  constructor(DOMString type, optional DOMString rid);
+  readonly attribute DOMString? rid;
+};
 </pre>
 
 ## Operations ## {#RTCRtpScriptTransform-operations}
@@ -795,12 +805,12 @@ Each RTCRtpScriptTransform has the following set of [$association steps$], given
     1. Set |transformer|.`[[encoder]]` to |encoder|.
     1. Set |transformer|.`[[depacketizer]]` to |depacketizer|.
 
-The <dfn method for="RTCRtpScriptTransformer">generateKeyFrame(|rid|)</dfn> method steps are:
+The <dfn method for="RTCRtpScriptTransform">generateKeyFrame(|rid|)</dfn> method steps are:
 1. Let |promise| be a new promise.
 1. Run the [$generate key frame algorithm$] with |promise|, |this|.`[[encoder]]` and |rid|.
 1. Return |promise|.
 
-The <dfn method for="RTCRtpScriptTransformer">sendKeyFrameRequest()</dfn> method steps are:
+The <dfn method for="RTCRtpScriptTransform">sendKeyFrameRequest()</dfn> method steps are:
 1. Let |promise| be a new promise.
 1. Run the [$send request key frame algorithm$] with |promise| and |this|.`[[depacketizer]]`.
 1. Return |promise|.
@@ -814,12 +824,34 @@ This allows algorithms to go from an {{RTCRtpScriptTransformer}} object to its {
 The <dfn attribute for="RTCRtpScriptTransformer">options</dfn> getter steps are:
 1. Return [=this=].`[[options]]`.
 
-The <dfn attribute for="RTCRtpScriptTransformer">readable</dfn> getter steps are:
+The <dfn attribute for="RTCRtpScriptTransform">readable</dfn> getter steps are:
 1. Return [=this=].`[[readable]]`.
 
-The <dfn attribute for="RTCRtpScriptTransformer">writable</dfn> getter steps are:
+The <dfn attribute for="RTCRtpScriptTransform">writable</dfn> getter steps are:
 1. Return [=this=].`[[writable]]`.
 
+The <dfn attribute for="RTCRtpScriptTransform">onbandwidthestimate</dfn> EventHandler has type bandwidthestimate.
+
+The <dfn attribute for="RTCRtpScriptTransform">onkeyframerequest</dfn> EventHandler has type keyframerequest.
+
+## Events ## {#RTCRtpScriptTransformer-events}
+
+The following event fires on an {{RTCRtpScriptTransformer}}:
+
+* keyframerequest of type {{KeyFrameRequestEvent}} - fired when the sink determines that a key frame has been requested.
+
+The steps that generate an event of type {{KeyFrameRequestEvent}} are as follows:
+
+Given a {{RTCRtpScriptTransformer}} |transform|:
+
+When |transform|'s `[[encoder]]` receives a keyframe request, for instance from an incoming RTCP Picture Loss Indication (PLI)
+or Full Intra Refresh (FIR), queue a task to perform the following steps:
+
+1. Set |rid| to the RID of the appropriate layer, or undefined if the request is not for a specific layer.
+1. [=Fire an event=] named `keyframerequest` at |transform| using {{KeyFrameRequestEvent}} with its {{Event/cancelable}} attribute initialized to "true", and with {{KeyFrameRequestEvent/rid}} set to |rid|.
+1. If the event's [=Event/canceled flag=] is true, abort these steps.
+1. Run the [$generate key frame algorithm$] with a new promise, |transform|.`[[encoder]]` and |rid|.
+
 ## KeyFrame Algorithms ## {#KeyFrame-algorithms}
 
 The <dfn abstract-op>generate key frame algorithm</dfn>, given |promise|, |encoder| and |rid|, is defined by running these steps: