Subscribe Track

Overview

With the Subscribe Track API, you can subscribe to a track that is currently being published to the Metered Global SFU.

You can query the tracks that are currently being published using the "Fetch Sessions" and "Fetch Tracks" APIs, and then obtain the sessionId and the trackId of the tracks you wish to subscribe to.

Authentication

You must provide bearer token in the Authorization header. The bearer token in the secret of the SFU App that you have created in the dashboard. When you create an SFU app, you will get the SFU App Id and the Secret.

• Header: Authorization: Bearer {secret}

HTTP Request

POST

https://global.sfu.metered.ca/api/sfu/:sfu_app_id/session/:session_id/track/subscribe

URL Parameters

Parameter Name	Type	Description
sfu_app_id	string	The unique identifier of your SFU app. This parameter is required to specify which SFU app the session should be created for. You can find the SFU app ID in the dashboard after creating the SFU app.
session_id	string	The unique identifier of the session. This parameter is required to specify which session the track should be subscribed to. You can find the session ID in the response of the session creation API.

Headers

Header	Value	Description
Authorization	Bearer {secret}	The bearer token which is the secret of the SFU App created in the dashboard.
Content-Type	application/json	Indicates that the request body format is JSON.

Request Body

In the request body you have to send the array of trackId and the sessionId that track belong to of the remote tracks you wish to subscribe to.

{
    tracks: [{
        "remoteSessionId": "...",
        "remoteTrackId": "..."
    }]
}

Field	Type	Required	Description
tracks	array	Yes	An array of objects, each containing remoteSessionId and remoteTrackId of the remote tracks you want to subscribe to.

Each object in the tracks array should have the following fields:

Field	Type	Required	Description
remoteSessionId	string	Yes	The unique identifier of the remote session you want to subscribe to.
remoteTrackId	string	Yes	The unique identifier of the remote track you want to subscribe to.

Response

{
    "immediateRenegotiationRequired": true,
    "sessionDescription": {
        "type": "offer",
        "sdp": "v=0\r\no=- 7684479339383422378 1723218508 ..."
    },
    "sessionId": "session-101-5666e439-6660-414b-adc1-050ed4e8d666"
}

You should add the sessionDescription as the remote descriptor to the peerConnection and then call the re-negotiate api.

Code Example

Here is a complete code example on how to subscribe to a track, including sending the re-negotiate request and fetch track request.

const subscribeResponse = await fetch(
    `${host}/api/sfu/${sfuAppId}/session/${sessionIdA}/track/subscribe`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${secret}`
        },
        body: JSON.stringify({
            tracks: [{
                "remoteSessionId": sessionIdB,
                "remoteTrackId": trackIdB
            }]
        })
    });
const subscribeJson = await subscribeResponse.json();
console.log("Subscribe track response", subscribeJson);
await peerConnection.setRemoteDescription(new RTCSessionDescription(subscribeJson.sessionDescription));
const answer = await peerConnection.createAnswer();
await peerConnection.setLocalDescription(answer);

// We need to call the renegotiate API to send the Answer SDP to the SFU.
await fetch(`${host}/api/sfu/${sfuAppId}/session/${sessionIdA}/renegotiate`, {
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${secret}`
    },
    body: JSON.stringify({
        sessionDescription: answer
    })
});