Calls: Introduce simulcast API

Author: renandincer

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

@@ -140,6 +140,33 @@ paths:
                       sessionId: 2a45361d5fd7cc14eface0587c276c94
                       trackName: generated-audio
                       kind: "audio"
+              simulcast_track:
+                description: Share a track with simulcast configuration
+                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
+                      trackName: simulcast-video-track
+                      mid: "1"
+                      simulcast:
+                        preferredRid: "h"
+                        preferredRidNotAvailable: "leastbandwidth"
       security:
         - secret: []
       parameters:
@@ -329,6 +356,75 @@ paths:
                 requiresImmediateRenegotiation: false
                 tracks:
                   - mid: "7"
+  /apps/{appId}/sessions/{sessionId}/tracks/change:
+    post:
+      tags:
+        - Change tracks
+      summary: Change tracks by reusing existing transceivers
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ChangeTracksRequest"
+            examples:
+              reuse_transceiver:
+                description: Reuse an existing transceiver for a new track
+                value:
+                  tracks:
+                    some-track-name:
+                      location: "remote"
+                      sessionId: "2a45361d5fd7cc14eface0587c276c94"
+                      trackName: "other-track-name"
+                      mid: "7"
+              reuse_with_simulcast:
+                description: Reuse an existing transceiver with simulcast preferences
+                value:
+                  tracks:
+                    trackID2:
+                      location: "remote"
+                      sessionId: "2a45361d5fd7cc14eface0587c276c94"
+                      trackName: "simulcast-track"
+                      mid: "8"
+                      simulcast:
+                        preferredRid: "h"
+                        preferredRidNotAvailable: "leastbandwidth"
+      security:
+        - secret: []
+      parameters:
+        - in: path
+          name: appId
+          schema:
+            type: string
+          required: true
+          description: WebRTC application ID
+        - in: path
+          name: sessionId
+          schema:
+            type: string
+          required: true
+          description: Current PeerConnection session ID
+      responses:
+        "200":
+          description: OK
+          headers:
+            vary:
+              schema:
+                type: string
+                example: Origin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChangeTracksResponse"
+              examples:
+                success:
+                  value:
+                    requiresImmediateRenegotiation: false
+                    tracks:
+                      trackID1:
+                        mid: "7"
+                        sessionId: "2a45361d5fd7cc14eface0587c276c94"
+                        trackName: "new-track-name"
+
   /apps/{appId}/sessions/{sessionId}:
     get:
       tags:
@@ -412,6 +508,21 @@ components:
         kind:
           type: string
           description: Give a hint to the SFU about the transceiver kind. This is required when the SFU generates the offer
+        simulcast:
+          type: object
+          description: Simulcast configuration for the track
+          properties:
+            preferredRid:
+              type: string
+              description: Preferred RID (Resolution ID) for simulcast streams
+            preferredRidNotAvailable:
+              type: string
+              enum:
+                - leastbandwidth
+                - none
+                - error
+              default: leastbandwidth
+              description: Fallback strategy when preferred RID is not available anymore from the remote peer
     CloseTrackObject:
       type: object
       properties:
@@ -543,3 +654,34 @@ components:
           type: string
         sessionDescription:
           $ref: "#/components/schemas/SessionDescription"
+    ChangeTracksRequest:
+      type: object
+      properties:
+        tracks:
+          type: object
+          additionalProperties:
+            allOf:
+              - $ref: "#/components/schemas/TrackObject"
+          description: Map of track IDs to track objects for changing tracks
+        sessionDescription:
+          $ref: "#/components/schemas/SessionDescription"
+    ChangeTracksResponse:
+      type: object
+      properties:
+        errorCode:
+          type: string
+        errorDescription:
+          type: string
+        requiresImmediateRenegotiation:
+          type: boolean
+        tracks:
+          type: object
+          additionalProperties:
+            allOf:
+              - $ref: "#/components/schemas/TrackObject"
+              - properties:
+                  errorCode:
+                    type: string
+                  errorDescription:
+                    type: string
+          description: Map of track IDs to track objects with results