Initialize Live Stream - iOS

To configure livestreaming with VideoSDK you require two things, first the token which will be used for Authentication purpose and a streamId which will be used to specify where the hosts and audience will join.

Generating Token

You can generate a token in two ways:

1. Temporary Token : You can visit Dashboard's API Key section and generate a temporary token from there.

2. Server : You can set up JWT in your backend and make an API call to get the token from your server.

To learn more about Authentication and token in detail you can follow this guide.

Swift

// Update server url here.
let LOCAL_SERVER_URL = "http://192.168.0.101:9000"

class APIService {

    class func getToken(completion: @escaping (Result<String, Error>) -> Void) {
        var url = URL(string: LOCAL_SERVER_URL)!
        url = url.appendingPathComponent("get-token")

        URLSession.shared.dataTask(with: url) { data, response, error in
            if let data = data,
               let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
               let token = json["token"] as? String {
                completion(.success(token))
            } else if let err = error {
                completion(.failure(err))
            }
        }
        .resume()
    }
}

Generating Stream Id

With the token ready, you can now get the streamId from the VideoSDK's rooms API.

Swift

extension APIService {

    class func createStreamId(token: String, completion: @escaping (Result<String, Error>) -> Void) {
        var url = URL(string: LOCAL_SERVER_URL)!
        url = url.appendingPathComponent("create-meeting")

        let params = ["token": token]

        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.httpBody = try? JSONSerialization.data(withJSONObject: params, options: [])

        URLSession.shared.dataTask(with: request) { data, response, error in
            if let data = data,
               let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
               let roomId = json["meetingId"] as? String {
                completion(.success(roomId))
            } else if let err = error {
                completion(.failure(err))
            }
        }
        .resume()
    }
}

Initialization of Live Stream

To initialize the live stream, call the factory method VideoSDK.createRoom(). It takes the roomId and your token, plus any other options you need, and returns a new Room object. It throws ERROR_INVALID_PARAMETER when roomId or token is empty, so call it with try.

Let's take a deeper look at the available configuration options first.

createRoom

var room: Room?

do {
    room = try VideoSDK.createRoom(
        roomId: "abcd-efgh-hijk",
        token: "<your token>",
        participantName: "John Doe", //optional
        micEnabled: true,
        camEnabled: true,
        participantId: "JD", //optional
        mode: .SEND_AND_RECV //optional (default mode is SEND_AND_RECV)
    )
} catch {
    print("Failed to initialize the live stream: \(error)")
}

• roomId :

  • This is a unique identifier that allows participants to join a specific live stream.
  • It will be in the format of xxx-yyy-zzz and will be generated using the VideoSDK's Room API.

• token :

  • The token you generated above. It is used to authenticate the participant.

• mode :

  • This parameter defines the mode the participant will enter the live stream with.
  • SEND_AND_RECV: For hosts/co-hosts who can send and receive media.
  • RECV_ONLY: For audience members who can only receive media.
  • It has to be of Mode type. The default is SEND_AND_RECV.

note

CONFERENCE and VIEWER were removed in 4.0.0. Use SEND_AND_RECV instead of CONFERENCE, and SIGNALLING_ONLY instead of VIEWER. RECV_ONLY is a different mode: it receives media, and VIEWER received none.

• participantName:

  • This represents the name of the participant in the live streams.
  • It will accept String type value.
  • This is an OPTIONAL parameter. If you pass none, the SDK picks a random name. The local participant's name stays empty until onRoomJoined fires.

• micEnabled:

  • This is a Bool flag, indicating whether a participant's microphone will be automatically enabled when they join the live stream. Audience members in RECV_ONLY mode cannot publish audio, so their mic stays off when they join. If an audience member later switches to SEND_AND_RECV with changeMode(), the mic turns on when this flag is true. The default is true.

• camEnabled:

  • This is a Bool flag, indicating whether a participant's camera will be automatically enabled when they join the live stream. Audience members in RECV_ONLY mode cannot publish video, so their camera stays off when they join. If an audience member later switches to SEND_AND_RECV with changeMode(), the camera turns on when this flag is true. The default is true.

• customCameraTrack and customMicrophoneTrack:

  • Custom camera and microphone tracks for a host, created with VideoSDK.createCameraVideoTrack(...) and VideoSDK.createMicrophoneAudioTrack(...). Both have to be of CustomStreamTrack type.
  • These are OPTIONAL parameters. See Custom Video Sources and Custom Audio Sources.

• metaData:

  • If you want to provide additional details about the participants joining the live stream, such as their profile image, you can pass that information in this parameter.
  • It has to be of [String: Any] type.
  • This is an OPTIONAL parameter. The default is nil.

• participantId:

  • This is a unique identifier for the participant inside the live stream.

    • It can be used to specify the unique identifier which can be linked with your own database service.
    • It has to be of String type.
    • This is an OPTIONAL parameter. If you pass none, VideoSDK generates a random id. The local participant's id stays empty until onRoomJoined fires.

• multiStream:

  • This is a Bool flag, indicating whether the host's media stream should send multiple resolution layers or a single resolution layer. This is an OPTIONAL parameter; when you pass none, the SDK uses true.

For the other options, such as defaultCamera, maxResolution, autoConsume and dynaCast, see createRoom().

caution

Use a different participantId for each participant in a live stream. If a second participant joins with a participantId that is already in the live stream, the participant who joined first is removed from the live stream and gets onRoomLeft(reason:).

API Reference

The API references for all the methods and events utilised in this guide are provided below.

• createRoom()