Skip to main content
Version: 4.x.x

Creating a Room - iOS

createRoom()​

Create a room with the factory method VideoSDK.createRoom(). It returns a new Room that has not joined yet. Call join() on it to join.

Pass your token to createRoom(). There is no separate config step. To generate a token, see this documentation.

createRoom() throws ERROR_INVALID_PARAMETER when roomId or token is empty, so call it with try. Only roomId and token are required. Pass the other arguments you need by name, in the order shown below. Swift requires that order.

createRoom
static func createRoom(
    roomId: String,
    token: String,
    participantName: String? = nil,
    micEnabled: Bool = true,
    camEnabled: Bool = true,
    participantId: String? = nil,
    mode: Mode? = nil,
    multiStream: Bool? = nil,
    customCameraTrack: CustomStreamTrack? = nil,
    customMicrophoneTrack: CustomStreamTrack? = nil,
    metaData: [String: Any]? = nil,
    signalingBaseUrl: String? = nil,
    preferredProtocol: PreferredProtocol? = nil,
    codecSwitchEnabled: Bool = true,
    enableBatching: Bool = true,
    translationLanguage: String? = nil,
    speakingLanguage: String? = nil,
    maxResolution: MaxResolution? = nil,
    defaultCamera: FacingMode = .front,
    autoConsume: Bool = true,
    dynaCast: Bool = false
) throws -> Room
Swift
var room: Room?

do {
    room = try VideoSDK.createRoom(
        roomId: "abcd-efgh-xyzw",
        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)
        customCameraTrack: customCameraTrack, // optional
        customMicrophoneTrack: customMicrophoneTrack // optional
    )
} catch {
    print("Failed to create the room: \(error)")
}

Room Parameters​

roomId​

  • Unique Id of the room where that participant will be joining.

    • type : String
    • REQUIRED

To create a room, see this documentation.

An empty roomId throws ERROR_INVALID_PARAMETER.

token​

  • The authentication token. To generate a token, see this documentation.

    • type : String
    • REQUIRED

An empty token throws ERROR_INVALID_PARAMETER.

participantName​

  • Name of the participant who will be joining the room, this name will be displayed to other participants in the same room. If it is nil or empty, the SDK creates a random 6-character name.

  • When you pass none, the local participant's displayName is empty until onRoomJoined().

    • type : String?
    • defaultValue : nil
    • OPTIONAL

micEnabled​

  • Whether mic of the participant will be on while joining the room. If it is set to false, then mic of that participant will be disabled by default, but can be enabled or disabled later.

  • If the mic can't start, for example because the user denied microphone access, the error is sent to onError(error:).

    • type: Bool
    • defaultValue : true
    • OPTIONAL

camEnabled​

  • Whether the camera of the participant will be on while joining the room. If it is set to false, then the camera of that participant will be disabled by default, but can be enabled or disabled later.

  • If the camera can't start, for example because the user denied camera access, the error is sent to onError(error:).

    • type: Bool
    • defaultValue : true
    • OPTIONAL

participantId​

  • Unique Id of the participant. If it is nil or empty, the SDK creates a random 8-character Id.

  • When you pass none, the local participant's id is empty until onRoomJoined().

    • type : String?
    • defaultValue : nil
    • OPTIONAL

mode​

  • There are 3 types of modes:

    1. SEND_AND_RECV : Sends and receives audio and video.
    2. SIGNALLING_ONLY : Sends and receives no audio or video.
    3. RECV_ONLY : Receives audio and video, and sends none.

  • It has to be of Mode? type.

  • If you pass nil, VideoSDK uses SEND_AND_RECV mode.

    • defaultValue : nil
    • OPTIONAL
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.

multiStream​

  • Whether your camera is sent as multiple resolution layers or as a single layer. If you pass nil, it is true.

    • type: Bool?
    • defaultValue : nil
    • OPTIONAL

customCameraTrack​

  • If you want to set the initial custom camera track, then you can pass the track created using the createCameraVideoTrack method of VideoSDK class.

customMicrophoneTrack​

  • If you want to set the initial custom microphone track, then you can pass the track created using the createMicrophoneAudioTrack method of VideoSDK class.

metaData​

  • Additional details about the participant, such as a profile image. Other participants can read them from the metaData property of this participant.

  • Use only values that can be converted to JSON (strings, numbers, booleans, arrays and dictionaries). Otherwise the metadata is not sent.

    • type: [String: Any]?
    • defaultValue : nil
    • OPTIONAL

signalingBaseUrl​

  • If you want to use a proxy server with the VideoSDK, you can specify your base URL here. Pass it without https://, for example proxy.yourwebsite.com. See Cloud Proxy.

    • type: String?
    • defaultValue : nil
    • OPTIONAL
note

If you plan to use a proxy server with VideoSDK, tell us first at support@videosdk.live.

preferredProtocol​

  • The network protocol to prefer for the connection. If you pass nil, it is UDP_OVER_TCP.

    1. UDP_OVER_TCP : Tries UDP first, and switches to TCP if UDP fails.
    2. UDP_ONLY : Uses only UDP.
    3. TCP_ONLY : Uses only TCP.
    • type: PreferredProtocol?
    • defaultValue : nil
    • OPTIONAL

codecSwitchEnabled​

  • If true, the SDK switches your video to VP8 when another participant cannot decode the current codec, and reports the switch through onCodecChanged(info:) of RoomEventListener.

    • type: Bool
    • defaultValue : true
    • OPTIONAL

enableBatching​

  • If true, the server may group participant updates into batches, which helps in large rooms. Your listeners still receive each event one by one.

    • type: Bool
    • defaultValue : true
    • OPTIONAL

translationLanguage​

  • The language this participant receives real-time translations in, as a language code such as "en". Translations start with startTranslation(config:) and arrive through onTranslationText(_:). You can change the language later with changeTranslationLanguage(_:).

  • See Realtime Translation for the supported language codes.

    • type: String?
    • defaultValue : nil
    • OPTIONAL

speakingLanguage​

maxResolution​

  • .hd opens the default camera at 1280x720. .sd opens it at 960x540. If you pass nil, it is .hd.

  • .sd also makes Participant.setQuality(_:) ask for one simulcast layer lower.

  • A customCameraTrack keeps its own encoderConfig.

    • type: MaxResolution?
    • defaultValue : nil
    • OPTIONAL

defaultCamera​

  • The camera the default video opens on: .front or .back.

  • A customCameraTrack keeps its own facingMode.

    • type: FacingMode
    • defaultValue : .front
    • OPTIONAL

autoConsume​

  • If true, the audio and video of every remote participant are received as soon as they publish them.

  • If false, a participant's audio and video are not received until you call consumeMicStreams() or consumeWebcamStreams() on that Participant. This saves bandwidth in large rooms.

  • consumeMicStreams(), consumeWebcamStreams(), stopConsumingMicStreams() and stopConsumingWebcamStreams() take effect only when the room was created with autoConsume set to false.

    • type: Bool
    • defaultValue : true
    • OPTIONAL

dynaCast​

  • If true, the server lowers the quality of the camera video you send while no one is watching its larger layers, and raises it again when someone is. This saves upload bandwidth and battery.

  • It has no effect when multiStream is off.

    • type: Bool
    • defaultValue : false
    • OPTIONAL

Returns​

room​

  • createRoom() returns a new Room instance that has not joined yet.

To turn on end-to-end encryption, call VideoSDK.setKeyProvider(_:) before join(). See E2EE Setup.

Got a Question? Ask us on discord

Last updated on by Vaibhavdixit14
Previous
Intro to Video SDK Class
Next

Was this helpful?

Not helpfulHelpful