Skip to main content
Version: 3.x.x

Initialize Room - Android

To create a VideoSDK room you need two things: a token, used for authentication, and a roomId, which specifies the room a participant joins. Let's look at each step.

Generating Token​

You can generate a token in two ways:

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

  2. Server : You can set up JWT on 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.

With Temporary Token
fun getToken(): String {
  // Update the token here from the VideoSDK dashboard
  return "YOUR_TOKEN"
}
Server
suspend fun getToken(): String = withContext(Dispatchers.IO) {
  val request = Request.Builder()
      .url("https://YOUR_TOKEN_SERVER/get-token") // your token server's endpoint
      .build()
  OkHttpClient().newCall(request).execute().use { response ->
      val body = response.body?.string().orEmpty()
      check(response.isSuccessful) { "HTTP ${response.code}: $body" }
      JSONObject(body).getString("token")
  }
}

Generating Room ID​

With the token ready, we can get the roomId from the VideoSDK's rooms API.

suspend fun getRoomId(token: String): String = withContext(Dispatchers.IO) {
  // We will use VideoSDK rooms API endpoint to create a roomId
  val request = Request.Builder()
      .url("https://api.videosdk.live/v2/rooms")
      .header("Authorization", token) // We will pass the token in the headers
      .post("".toRequestBody())
      .build()
  OkHttpClient().newCall(request).execute().use { response ->
      val body = response.body?.string().orEmpty()
      check(response.isSuccessful) { "HTTP ${response.code}: $body" }
      // We will return the roomId which we got from the response of the API
      JSONObject(body).getString("roomId")
  }
}
tip

These examples use OkHttp for the network calls. The SDK does not bring it into your app, so add it yourself: implementation "com.squareup.okhttp3:okhttp:4.12.0".

Initializing the Room​

  1. First, initialize the VideoSDK with the initialize() method. Call it once, for example in Application.onCreate(). Later calls do nothing. createRoom() and the track factories throw IllegalStateException until it has run.
initialize
fun initialize(context: Context)
  1. Now, create the room with the factory method createRoom().

createRoom() returns a Room configured with the roomId, the token, the participant's name and the other options below. Nothing reaches the network yet: add your listeners to the returned room, then call join() to connect.

Only roomId and token are required. The other parameters have default values, so pass the ones you need by name. Every option is fixed when you join. To change the mic, camera, mode or translation language later, use the Room methods instead of calling createRoom() again.

tip

For one-to-one calls, it is recommended to set multiStream = false. For more information on multistream, refer to the multistream documentation.

Let's take a deeper look at the available configuration options 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

  • roomId :

    • The unique ID of the room the participant joins.
    • It will accept String type value.
    • It will be in the format of xxx-yyy-zzz and will be generated using the VideoSDK's 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.
    • It will accept String type value.
    • 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:

    • The name shown to the other participants in the room.
    • It will accept String type value.
    • If you pass null or an empty string, the participant joins with a random 6-character name.

  • micEnabled:

    • This is a Boolean flag, indicating whether a participant's microphone will be automatically enabled when they join the room.
    • The RECORD_AUDIO permission must already be granted, or the mic does not start.

  • camEnabled:

    • This is a Boolean flag, indicating whether a participant's camera will be automatically enabled when they join the room.
    • The CAMERA permission must already be granted, or the camera does not start and the error is reported on onError.

  • participantId:

    • The unique identifier of the participant inside the room.
    • Use it to link the participant to a user in your own database.
    • It has to be of String type.
    • If you pass null or an empty string, VideoSDK will generate a unique id for the participant.
caution

Make sure each participantId is used only once in a room. If a second participant joins with the same participantId, VideoSDK removes the participant who joined first.

  • mode:

    • There are 3 types of modes:

      1. Mode.SEND_AND_RECV : The participant sends and receives audio and video.

      2. Mode.SIGNALLING_ONLY : The participant neither sends nor receives audio and video.

      3. Mode.RECV_ONLY: The participant only receives audio and video, and sends none.

    • It has to be of Mode type, from the live.videosdk.rtc.android.lib package.

    • If you pass null, VideoSDK uses Mode.SEND_AND_RECV.

  • multiStream:

    • It will specify if the camera should send multiple resolution layers or a single resolution layer.

    • It has to be of Boolean type. If you pass null (the default), it is true.

  • customCameraTrack:

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

    • It has to be of CustomStreamTrack type. If you pass null, the default camera is used.

  • customMicrophoneTrack:

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

    • It has to be of CustomStreamTrack type. If you pass null, the default microphone is used.

  • metaData:

    • Extra details about the participant, such as a profile image URL.

    • It has to be of JSONObject type.

    • Every participant, you included, reads it from participant.metaData. It is null if you pass none, and it stays the same for the whole session.

  • signalingBaseUrl:

    • If you want to use a proxy server with the VideoSDK, you can specify your base URL here.

    • It has to be of String type.

    • It is optional.

note

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

  • preferredProtocol:

    • If you want to provide a preferred network protocol for communication, you can specify that in PreferredProtocol, with options including UDP_ONLY, UDP_OVER_TCP, and TCP_ONLY.

    • It has to be of VideoSDK.PreferredProtocol type.

    • It is optional. If you pass null, UDP_OVER_TCP is used.

  • codecSwitchEnabled:

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

    • It has to be of Boolean type. Default is true.

  • enableBatching:

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

    • It has to be of Boolean type. Default is true.

  • translationLanguage:

    • The language this participant receives live translations in. If you pass null, translation is off.

    • It has to be of String type.

  • speakingLanguage:

    • The language this participant speaks.

    • It has to be of String type.

  • maxResolution:

    • The size the default camera opens at: MaxResolution.hd (1280x720) or MaxResolution.sd (960x540).

    • It has to be of MaxResolution type. If you pass null (the default), it is MaxResolution.hd.

    • A customCameraTrack keeps its own encoderConfig.

  • defaultCamera:

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

    • It has to be of FacingMode type. Default is FacingMode.front.

    • A customCameraTrack keeps its own camera.

  • 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, for example from onParticipantJoined, and again from ParticipantEventListener.onMediaStatusChanged when they turn their media on. Both are suspend functions, so call them from a coroutine, for example lifecycleScope.launch { participant.consumeMicStreams() }. This saves bandwidth in large rooms. The consume methods take effect only when the room was created with autoConsume set to false.

    • It has to be of Boolean type. Default is true.

  • dynaCast:

    • If true, the server lowers the quality of the camera stream you send while no one is watching its larger layers, which saves upload bandwidth.

    • It only works when the camera sends multiple layers: multiStream on and the VP8 codec.

    • It has to be of Boolean type. Default is false.

With all the configuration options explained, here is how you can create the room.

class MainActivity : AppCompatActivity() {

  private var room: Room? = null

  suspend fun getToken(): String {
    ...
  }

  suspend fun getRoomId(token: String): String {
    ...
  }

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // initialize the VideoSDK
    VideoSDK.initialize(applicationContext)

    lifecycleScope.launch {
      //We will fetch token and roomId and store it in local variables
      val token = getToken()
      val roomId = getRoomId(token)

      try {
        // create a new room instance
        room = VideoSDK.createRoom(
            roomId = roomId,
            token = token,
            participantName = "NAME HERE",
            micEnabled = true,
            camEnabled = true,
            multiStream = false,
        )
      } catch (e: VideoSDKException) {
        // 3073: the token or the roomId is empty
        Log.e("VideoSDK", "createRoom failed: ${e.code} ${e.name}")
      }

      Log.d("VideoSDK", "onCreate: $roomId")
    }
  }
}

API Reference​

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

Got a Question? Ask us on discord

Last updated on by saksham-videosdk
Previous
Join Room
Next

Was this helpful?

Not helpfulHelpful