Skip to main content
Version: 3.x.x

Creating a Room - Android

initialize()​

Call VideoSDK.initialize() before you create a room. Call it once, for example in Application.onCreate(). Later calls do nothing.

Parameters​

  • context: Context

Returns​

  • Unit
initialize
fun initialize(context: Context)

createRoom()​

  • createRoom() returns a new Room for you to join.
  • Only roomId and token are required. Pass the other arguments by name.
  • Nothing is sent to the server until you call join() on the returned room.
  • VideoSDK.initialize() must have run first, or it throws IllegalStateException.
  • Only one room at a time: a second createRoom() takes over from the first.
createRoom
fun createRoom(
    roomId: String,
    token: String,
    participantName: String? = null,
    micEnabled: Boolean = true,
    camEnabled: Boolean = true,
    participantId: String? = null,
    mode: Mode? = null,
    multiStream: Boolean? = null,
    customCameraTrack: CustomStreamTrack? = null,
    customMicrophoneTrack: CustomStreamTrack? = null,
    metaData: JSONObject? = null,
    signalingBaseUrl: String? = null,
    preferredProtocol: PreferredProtocol? = null,
    codecSwitchEnabled: Boolean = true,
    enableBatching: Boolean = true,
    translationLanguage: String? = null,
    speakingLanguage: String? = null,
    maxResolution: MaxResolution? = null,
    defaultCamera: FacingMode = FacingMode.front,
    autoConsume: Boolean = true,
    dynaCast: Boolean = false,
): Room

Parameters​

roomId​

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

    • type : String
    • REQUIRED

To create a room, see the Create Room API.

An empty roomId throws VideoSDKException with code 3073 (ERROR_INVALID_PARAMETER).

token​

  • The authentication token, generated on your server with your VideoSDK API key and secret.

    • type : String
    • REQUIRED

To generate a token, see Authentication.

An empty token throws VideoSDKException with code 3073 (ERROR_INVALID_PARAMETER). A malformed or expired token is not checked here: the server rejects it when you call join().

participantName​

  • Name of the participant who will be joining the room. This name is displayed to the other participants. If it is null or empty, the participant joins with a random 6-character name.

    • type : String?
    • default: null
    • OPTIONAL

micEnabled​

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

  • The RECORD_AUDIO permission must already be granted, or the mic does not start.

    • type: Boolean
    • default: true
    • OPTIONAL

camEnabled​

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

  • The CAMERA permission must already be granted, or the camera does not start and the error is reported on onError.

    • type: Boolean
    • default: true
    • OPTIONAL

participantId​

  • Unique Id of the participant. If you pass null or an empty string, the SDK creates an Id by itself and uses it.

    • type : String?
    • default: null
    • OPTIONAL

mode​

There are three modes available:

  • Mode.SEND_AND_RECV: In this mode, the participant sends and receives audio and video.

  • Mode.SIGNALLING_ONLY: In this mode, the participant neither sends nor receives audio or video, but stays in the room.

  • Mode.RECV_ONLY: In this mode, the participant receives audio and video but sends none.

Mode is in the live.videosdk.rtc.android.lib package.

  • type: Mode?
  • default: null, which uses Mode.SEND_AND_RECV
  • OPTIONAL

multiStream​

  • If true, the camera is sent as several resolution layers, so each viewer can receive the layer its connection can carry. If false, it is sent as a single layer.

    • type: Boolean?
    • default: null, which uses true
    • OPTIONAL

customCameraTrack​

  • A camera track from createCameraVideoTrack() to publish instead of the default camera.

    • type : CustomStreamTrack?
    • default: null, which uses the default camera
    • OPTIONAL

customMicrophoneTrack​

  • A microphone track from createMicrophoneAudioTrack() to publish instead of the default mic.

    • type : CustomStreamTrack?
    • default: null, which uses the default mic
    • OPTIONAL

See Custom Tracks.

metaData​

  • Extra details about this participant, such as a profile image URL. Every participant, you included, can read it from that participant's metaData property, for example room.localParticipant.metaData.

    • type: JSONObject?
    • default: null
    • OPTIONAL

signalingBaseUrl​

  • The base URL of your proxy server, if you route signaling through one.

    • type: String?
    • default: null, which uses the VideoSDK signaling server
    • OPTIONAL
note

If you intend to use a proxy server with VideoSDK, let us know first at support@videosdk.live.

If your proxy already works with Android SDK 2.x, contact support before you upgrade. Android SDK 3.0.0 fetches its configuration from a different path on the proxy than 2.x did.

preferredProtocol​

  • The network protocol to prefer for media:

    • UDP_ONLY: lowest latency, but no connection on a network that blocks UDP.

    • UDP_OVER_TCP: UDP, falling back to TCP when UDP can't get through.

    • TCP_ONLY: works on restrictive corporate networks, at the cost of latency.

    • type: VideoSDK.PreferredProtocol?

    • default: null, which uses UDP_OVER_TCP

    • OPTIONAL

codecSwitchEnabled​

  • If true, the video codec you send switches to VP8 when a remote participant cannot decode it, and onCodecChanged is called on your RoomEventListener.

    • type: Boolean
    • default: true
    • OPTIONAL

enableBatching​

  • If true, notifications from the server are received in batches.

    • type: Boolean
    • default: true
    • OPTIONAL

translationLanguage​

  • The language this participant receives live translations in, as a language code such as "en". If it is null, translation is off.

  • To switch language once translation has started, call changeTranslationLanguage(). It throws VideoSDKException with code 4044 (CHANGE_TRANSLATION_LANGUAGE_FAILED) if the server refuses, for example before translation has started.

    • type: String?
    • default: null
    • OPTIONAL

speakingLanguage​

  • The language this participant speaks, as a language code such as "en".

    • type: String?
    • default: null
    • OPTIONAL

maxResolution​

  • The size the default camera opens at. MaxResolution.hd opens it at 1280x720. MaxResolution.sd opens it at 960x540, or the largest 16:9 size below it that the camera offers.

  • A track passed as customCameraTrack keeps its own encoderConfig.

    • type: MaxResolution?
    • default: null, which uses MaxResolution.hd
    • OPTIONAL

defaultCamera​

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

  • A track passed as customCameraTrack keeps its own facingMode.

    • type: FacingMode
    • default: FacingMode.front
    • OPTIONAL

autoConsume​

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

  • If false, a participant's mic and camera are not received until you call consumeMicStreams() or consumeWebcamStreams() on that Participant. This saves bandwidth in large rooms. Screen shares have no consume call. The consume methods take effect only when the room was created with autoConsume set to false. See Selective Subscription.

    • type: Boolean
    • default: true
    • OPTIONAL

dynaCast​

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

  • It has no effect on a camera that sends a single layer: multiStream off, or a codec other than VP8.

    • type: Boolean
    • default: false
    • OPTIONAL

Returns​

room​

  • createRoom() returns a new Room instance.

Throws​

  • IllegalStateException if VideoSDK.initialize() has not run.
  • VideoSDKException with code 3073 (ERROR_INVALID_PARAMETER) if roomId or token is empty.

Example​

createRoom

VideoSDK.initialize(applicationContext)

// Create the room with the token generated on your server
val room = VideoSDK.createRoom(
    roomId = "abc-1234-xyz",
    token = token,
    participantName = "John Doe",
    micEnabled = true,
    camEnabled = true,
    multiStream = false,
)

// Register your listener, then join from a coroutine
room.addEventListener(roomEventListener)
lifecycleScope.launch {
    try {
        room.join()
    } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Join failed: ${e.code} ${e.name}")
    }
}

Got a Question? Ask us on discord

Last updated on by Vaibhavdixit14
Previous
Intro to VideoSDK Class
Next

Was this helpful?

Not helpfulHelpful