Realtime: replaced ridUnavailableStrategy with ridNotAvailable and other improvements (#21690)

Co-authored-by: Nils Ohlmeier <[email protected]>

Author: nils-ohlmeier

public/realtime/static/calls-api-2024-05-21.yaml

@@ -150,7 +150,7 @@ paths:
                       simulcast:
                         preferredRid: "h"
                         priorityOrdering: "asciibetical"
-                        ridUnavailableStrategy: "nextPriority"
+                        ridNotAvailabl: "asciibetical"
       security:
         - secret: []
       parameters:
@@ -228,7 +228,7 @@ paths:
                         simulcast:
                           preferredRid: "h"
                           priorityOrdering: "asciibetical"
-                          ridUnavailableStrategy: "nextPriority"
+                          ridNotAvailabl: "asciibetical"
                     sessionDescription:
                       sdp: |
                         v=0
@@ -396,7 +396,7 @@ paths:
                       simulcast:
                         preferredRid: "h"
                         priorityOrdering: "asciibetical"
-                        ridUnavailableStrategy: "nextPriority"
+                        ridNotAavailable: "asciibetical"
       security:
         - secret: []
       parameters:
@@ -530,13 +530,13 @@ components:
                 - asciibetical
               default: none
               description: Controls what happens if there is not enough network resources available to send the preferredRid. 'none' means keep sending even if not enough bandwidth, 'asciibetical' uses a-z order to determine priority where a is most desirable and z is least desirable.
-            ridUnavailableStrategy:
+            ridNotAvailable:
               type: string
               enum:
                 - none
-                - nextPriority
+                - asciibetical
               default: none
-              description: Controls what happens when the rid currently being used or preferredRid is no longer being sent by the publisher. 'none' means do nothing, 'nextPriority' uses the next on the priorityOrdering.
+              description: Controls what happens when the rid currently being used or preferredRid is no longer being sent by the publisher. 'none' means do nothing, 'asciibetical' uses the next available layer after sorting the layers a-z.
     CloseTrackObject:
       type: object
       properties:

src/content/docs/realtime/simulcast.mdx

@@ -5,11 +5,11 @@ sidebar:
   order: 8
 ---
 
-Simulcast is a feature of WebRTC that allows a publisher to send multiple streams of the same media at different qualities. For example, this is useful for scenarios where you want to send a high quality stream for desktop users and a lower quality stream for mobile users.
+Simulcast is a feature of WebRTC that allows a publisher to send multiple video streams of the same media at different qualities. For example, this is useful for scenarios where you want to send a high quality stream for desktop users and a lower quality stream for mobile users.
 
 ```mermaid
 graph LR
-    A[Publisher] -->|Low quality| B[Cloudflare Calls SFU]
+    A[Publisher] -->|Low quality| B[Cloudflare Realtime SFU]
     A -->|Medium quality| B
     A -->|High quality| B
 B -->|Low quality| C@{ shape: procs, label: "Subscribers"}
@@ -20,28 +20,27 @@ B -->|High quality| E@{ shape: procs, label: "Subscribers"}
 
 ### How it works
 
-Simulcast in WebRTC allows a single media source, like a camera or screen share, to be encoded at multiple quality levels and sent simultaneously, which is beneficial for subscribers with varying network conditions and device capabilities. The media source is encoded into multiple streams, each identified by RIDs (RTP Stream Identifiers) for different quality levels, such as low, medium, and high. These simulcast streams are described in the SDP you send to Cloudflare Calls SFU. It's the responsibility of the Cloudflare Calls SFU to ensure that the appropriate quality stream is delivered to each subscriber based on their network conditions and device capabilities.
+Simulcast in WebRTC allows a single video source, like a camera or screen share, to be encoded at multiple quality levels and sent simultaneously, which is beneficial for subscribers with varying network conditions and device capabilities. The video source is encoded into multiple streams, each identified by RIDs (RTP Stream Identifiers) for different quality levels, such as low, medium, and high. These simulcast streams are described in the SDP you send to Cloudflare Realtime SFU. It's the responsibility of the Cloudflare Realtime SFU to ensure that the appropriate quality stream is delivered to each subscriber based on their network conditions and device capabilities.
 
-Cloudflare Calls SFU will automatically handle the simulcast configuration based on the SDP you send to it from the publisher. The SFU will then automatically switch between the different quality levels based on the subscriber's network conditions. You can control the quality switching behavior using the `simulcast` configuration object when you send an API call to start pulling a remote track.
+Cloudflare Realtime SFU will automatically handle the simulcast configuration based on the SDP you send to it from the publisher. The SFU will then automatically switch between the different quality levels based on the subscriber's network conditions, or the qaulity level can be controlled manually via the API. You can control the quality switching behavior using the `simulcast` configuration object when you send an API call to start pulling a remote track.
 
 ### Quality Control
 
 The `simulcast` configuration object in the API call when you start pulling a remote track allows you to specify:
 
-- `preferredRid`: The preferred stream (RID for the simulcast stream. [RIDs can be specified by the publisher.](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpSender/setParameters#encodings))
-- `priorityOrdering`: Controls how the SFU handles bandwidth constraints
-  - `none`: Keep sending the preferred layer even if there's not enough bandwidth
-  - `asciibetical`: Use alphabetical ordering (a-z) to determine priority, where 'a' is most desirable and 'z' is least desirable
-- `ridUnavailableStrategy`: Controls what happens when the preferred RID is no longer available, for example when the publisher stops sending it
-
-  - `none`: Do nothing
-  - `nextPriority`: Switch to the next available RID based on the priority ordering
+- `preferredRid`: The preferred quality level for the video stream (RID for the simulcast stream. [RIDs can be specified by the publisher.](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpSender/setParameters#encodings))
+- `priorityOrdering`: Controls how the SFU handles bandwidth constraints.
+  - `none`: Keep sending the preferred layer, set via the preferredRid, even if there's not enough bandwidth.
+  - `asciibetical`: Use alphabetical ordering (a-z) to determine priority, where 'a' is most desirable and 'z' is least desirable.
+- `ridNotAvailable`: Controls what happens when the preferred RID is no longer available, for example when the publisher stops sending it.
+  - `none`: Do nothing.
+  - `asciibetical`: Switch to the next available RID based on the priority ordering, where 'a' is most desirable and 'z' is least desirable.
 
   You will likely want to order the asciibetical RIDs based on your desired metric, such as higest resoltion to lowest or highest bandwidth to lowest.
 
 ### Bandwidth Management across media tracks
 
-Cloudflare Calls treats all media tracks equally at the transport level. For example, if you have multiple video tracks (cameras, screen shares, etc.), they all have equal priority for bandwidth allocation. This means:
+Cloudflare Realtime treats all media tracks equally at the transport level. For example, if you have multiple video tracks (cameras, screen shares, etc.), they all have equal priority for bandwidth allocation. This means:
 
 1. Each track's simulcast configuration is handled independently
 1. The SFU performs automatic bandwidth estimation and layer switching based on network conditions independently for each track
@@ -50,9 +49,8 @@ Cloudflare Calls treats all media tracks equally at the transport level. For exa
 
 When a layer switch is requested (through updating `preferredRid`) with the `/tracks/update` API:
 
-1. The SFU will automatically generate a Picture Loss Indication (PLI)
-2. Layer switching only occurs when a keyframe arrives on the target layer
-3. PLI generation is debounced to prevent excessive requests
+1. The SFU will automatically generate a Full Intraframe Request (FIR)
+2. PLI generation is debounced to prevent excessive requests
 
 ### Publisher Configuration
 
@@ -65,23 +63,24 @@ a=rid:h send
 a=rid:q send
 ```
 
-You can include these by specifying `sendEncodings` when creating the transceiver:
+If the publisher endpoint is a browser you can include these by specifying `sendEncodings` when creating the transceiver like this:
 
 ```js
 const transceiver = peerConnection.addTransceiver(track, {
   direction: "sendonly",
   sendEncodings: [
-    { scaleResolutionDownBy: 1, rid: "a" },
-    { scaleResolutionDownBy: 2, rid: "b" },
-    { scaleResolutionDownBy: 4, rid: "c" }
+    { scaleResolutionDownBy: 1, rid: "f" },
+    { scaleResolutionDownBy: 2, rid: "h" },
+    { scaleResolutionDownBy: 4, rid: "q" }
   ]
 });
+```
 ## Example
 
-Here's an example of how to use simulcast with Cloudflare Calls:
+Here's an example of how to use simulcast with Cloudflare Realtime:
 
 1. Create a new local track with simulcast configuration. There should be a section in the SDP with `a=simulcast:send`.
-2. Use the [Cloudflare Calls API](/calls/https-api) to push this local track, by calling the /tracks/new endpoint.
-3. Use the [Cloudflare Calls API](/calls/https-api) to start pulling a remote track (from another browser or device), by calling the /tracks/new endpoint and specifying the `simulcast` configuration object along with the remote track ID you get from step 2.
+2. Use the [Cloudflare Realtime API](/realtime/https-api) to push this local track, by calling the /tracks/new endpoint.
+3. Use the [Cloudflare Realtime API](/realtime/https-api) to start pulling a remote track (from another browser or device), by calling the /tracks/new endpoint and specifying the `simulcast` configuration object along with the remote track ID you get from step 2.
 
-For more examples, check out the [Calls Examples GitHub repository](https://github.com/cloudflare/calls-examples/tree/main/simulcast).
+For more examples, check out the [Realtime Examples GitHub repository](https://github.com/cloudflare/calls-examples/tree/main/simulcast).