Update Calls simulcast API definition after feedback on 2025-02-27

Author: renandincer

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

@@ -140,33 +140,16 @@ paths:
                       sessionId: 2a45361d5fd7cc14eface0587c276c94
                       trackName: generated-audio
                       kind: "audio"
-              simulcast_track:
-                description: Share a track with simulcast configuration
+              remote_track_with_simulcast:
+                description: Pull a remote track with simulcast preferences
                 value:
-                  sessionDescription:
-                    sdp: |
-                      v=0
-                      o=- 0 0 IN IP4 127.0.0.1
-                      s=-
-                      c=IN IP4 127.0.0.1
-                      t=0 0
-                      m=audio 4000 RTP/AVP 111
-                      a=rtpmap:111 OPUS/48000/2
-                      m=video 4002 RTP/AVP 96
-                      a=rtpmap:96 VP8/90000
-                      a=simulcast:send f;h;q
-                      a=rid:f send
-                      a=rid:h send
-                      a=rid:q send
-                      ...
-                    type: offer
                   tracks:
-                    - location: local
+                    - location: remote
+                      sessionId: 2a45361d5fd7cc14eface0587c276c94
                       trackName: simulcast-video-track
-                      mid: "1"
                       simulcast:
                         preferredRid: "h"
-                        preferredRidNotAvailable: "leastbandwidth"
+                        fallbackStrategy: "leastBandwidth"
       security:
         - secret: []
       parameters:
@@ -234,6 +217,31 @@ paths:
                         a=rtpmap:96 VP8/90000
                         ...
                       type: offer
+                remote_tracks_with_simulcast:
+                  value:
+                    requiresImmediateRenegotiation: true
+                    tracks:
+                      - sessionId: 2a45361d5fd7cc14eface0587c276c94
+                        trackName: simulcast-video-track
+                        mid: "5"
+                        simulcast:
+                          preferredRid: "h"
+                          fallbackStrategy: "leastBandwidth"
+                    sessionDescription:
+                      sdp: |
+                        v=0
+                        o=- 0 0 IN IP4 127.0.0.1
+                        s=-
+                        c=IN IP4 127.0.0.1
+                        t=0 0
+                        m=video 4002 RTP/AVP 96
+                        a=rtpmap:96 VP8/90000
+                        a=simulcast:recv f;h;q
+                        a=rid:f recv
+                        a=rid:h recv
+                        a=rid:q recv
+                        ...
+                      type: offer
   /apps/{appId}/sessions/{sessionId}/renegotiate:
     put:
       tags:
@@ -356,8 +364,8 @@ paths:
                 requiresImmediateRenegotiation: false
                 tracks:
                   - mid: "7"
-  /apps/{appId}/sessions/{sessionId}/tracks/change:
-    post:
+  /apps/{appId}/sessions/{sessionId}/tracks/update:
+    put:
       tags:
         - Change tracks
       summary: Change tracks by reusing existing transceivers
@@ -387,7 +395,7 @@ paths:
                       mid: "8"
                       simulcast:
                         preferredRid: "h"
-                        preferredRidNotAvailable: "leastbandwidth"
+                        fallbackStrategy: "leastBandwidth"
       security:
         - secret: []
       parameters:
@@ -414,7 +422,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ChangeTracksResponse"
+                $ref: "#/components/schemas/UpdateTracksResponse"
               examples:
                 success:
                   value:
@@ -515,14 +523,14 @@ components:
             preferredRid:
               type: string
               description: Preferred RID (Resolution ID) for simulcast streams
-            preferredRidNotAvailable:
+            fallbackStrategy:
               type: string
               enum:
-                - leastbandwidth
+                - auto
+                - leastBandwidth
                 - none
-                - error
-              default: leastbandwidth
-              description: Fallback strategy when preferred RID is not available anymore from the remote peer
+              default: auto
+              description: General fallback strategy when any constraint (like preferredRid, minWidth, maxBandwidth, etc.) cannot be met. 'auto' will select the best quality possible within constraints.
     CloseTrackObject:
       type: object
       properties:
@@ -665,7 +673,7 @@ components:
           description: Map of track IDs to track objects for changing tracks
         sessionDescription:
           $ref: "#/components/schemas/SessionDescription"
-    ChangeTracksResponse:
+    UpdateTracksResponse:
       type: object
       properties:
         errorCode: