Switch Live Stream - Android

Overview

The Switch Live Stream feature moves a participant from the current live stream to another one with switchTo(), without calling leave() and joining again.

switchTo()

Parameters

• roomId (String, required): ID of the live stream to move to
• token (String?, optional): VideoSDK token for authentication. If you don't pass one, the current token is used.

switchTo() is a suspend function, so call it from a coroutine. It throws a VideoSDKException when the switch request is refused or fails, and 3073 (ERROR_INVALID_PARAMETER) when roomId is empty or blank. Called before the live stream is joined, or while it is reconnecting, it does nothing and reports 3035 (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED) or 3065 (ERROR_ROOM_RECONNECTING) on onError instead of throwing.

class LiveStreamActivity : AppCompatActivity() {
    private lateinit var liveStream: Room

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        //Create the live stream room
        liveStream = VideoSDK.createRoom(... )
        //...
        val switchButton: Button = findViewById(R.id.switchLiveStreamButton)
        switchButton.setOnClickListener {
            lifecycleScope.launch {
                try {
                    liveStream.switchTo("liveStream-xyz-456")
                } catch (e: VideoSDKException) {
                    Log.e("VideoSDK", "Switch failed: ${e.code} ${e.name}")
                }
            }
        }
    }
}

Events associated with switchTo()

• When the switch completes, onRoomJoined() is called again, with switchRoomId set to the ID of the new live stream. On a regular join, and on a rejoin after reconnecting, switchRoomId is null. From then on, liveStream.id is the new live stream's ID.

private val liveStreamEventListener = object : RoomEventListener() {
    override fun onRoomJoined(switchRoomId: String?) {
        if (switchRoomId != null) {
            Log.d("VideoSDK", "Switched to liveStream: $switchRoomId")
        }
    }
}

Important Considerations

Live Stream Status

• The destination live stream must be active before you switch.
• If the destination live stream has no live session, switchTo() throws 4076 (SWITCH_ROOM_FAILED). It is not reported on onError, and the participant stays in the current live stream, still CONNECTED.

Participant Mode

• switchTo() always joins the new live stream in Mode.SEND_AND_RECV, whatever mode the participant was in. An audience member in RECV_ONLY arrives able to publish, like a host.
• A host's mic and camera come back on in the new live stream as they were before the switch.
• To move an audience member to another live stream, call leave(), then createRoom() with mode = Mode.RECV_ONLY and join() for the new live stream.

PubSub Subscriptions

• Your PubSub subscriptions carry over to the new live stream. Don't subscribe again in onRoomJoined(): subscribing the same listener to the same topic again throws 3073.

Room State

• recordingState, hlsState, liveStreamState, transcriptionState and translationState go back to their STOPPED values when the switch starts.

Token Management

• Token Expiry: Be careful with short-lived tokens when using the switch feature.
  • If you're using short-lived tokens for security reasons, always provide a new token in the switchTo method.
  • A token that expires during a live stream can disconnect the participant.
• Best Practice: For frequent switches, use tokens with reasonable expiry times or implement a token refresh mechanism.

API Reference

• switchTo
• onRoomJoined