RTMP Livestream - Android

RTMP lets you stream a room to platforms such as YouTube, Twitch and Facebook. You pass each platform's RTMP URL and stream key, and VideoSDK pushes the room to them.

You can also configure the livestream layout, either by setting a prebuilt layout in the configuration or by providing your own custom template.

This guide shows how to start and stop an RTMP livestream.

startLivestream()

Call startLivestream() on the Room to start the RTMP livestream. It takes two parameters:

• outputs: a list of LivestreamOutput objects, one per platform, each with the RTMP url and streamKey. Pass at least one output. The SDK doesn't check the URL or key; a wrong one fails on the server and is reported on onError as 4013 (START_LIVESTREAM_FAILED). Treat that 4013 as the end of the attempt: a LIVESTREAM_STARTING that arrives after it doesn't mean a start is still in progress, so call startLivestream() again to retry.

• config: a LivestreamConfig that sets the layout, the theme and, with recording = LivestreamRecordingConfig(enabled = true), whether the livestream is also recorded. Pass null (the default) for the default layout; a field left null takes the server's default. LivestreamConfig, LivestreamOutput and the Config* types are in the live.videosdk.rtc.android.model package.

note

• startLivestream() and stopLivestream() are suspend functions. Call them from a coroutine, such as lifecycleScope.launch (from androidx.lifecycle:lifecycle-runtime-ktx).
• They return once the request is sent, not when the livestream has started or stopped. Wait for onLivestreamStateChanged to report LiveStreamState.LIVESTREAM_STARTED or LiveStreamState.LIVESTREAM_STOPPED. liveStream.liveStreamState holds the latest state.
• If the request fails, they throw VideoSDKException.
• Called before the room is joined, or while it is reconnecting, they do nothing and report 3035 (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED) or 3065 (ERROR_ROOM_RECONNECTING) on onError instead of throwing.

val config = LivestreamConfig(
    // Layout Configuration
    layout = ConfigLayout(
        type = ConfigLayoutGrid.GRID, // SPOTLIGHT | SIDEBAR, Default : GRID
        priority = ConfigLayoutPriority.SPEAKER, // PIN, Default : SPEAKER
        gridSize = 4, // MAX : 4
    ),
    // Theme of livestream layout
    theme = ConfigTheme.DARK, // LIGHT | DEFAULT
)

val outputs: MutableList<LivestreamOutput> = ArrayList()
outputs.add(LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY))

lifecycleScope.launch {
    try {
        liveStream!!.startLivestream(outputs, config)
    } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Start livestream failed: ${e.code} ${e.name}")
    }
}

stopLivestream()

Call stopLivestream() on the Room to stop the livestream. onLivestreamStateChanged reports LIVESTREAM_STOPPED once it has stopped.

Example

findViewById<View>(R.id.btnLiveStream).setOnClickListener { view: View? ->
  lifecycleScope.launch {
    try {
      // liveStreamState holds the latest state from onLivestreamStateChanged
      if (liveStream!!.liveStreamState == LiveStreamState.LIVESTREAM_STOPPED) {
        val config = LivestreamConfig(
            layout = ConfigLayout(
                type = ConfigLayoutGrid.GRID,
                priority = ConfigLayoutPriority.SPEAKER,
                gridSize = 4,
            ),
            theme = ConfigTheme.DARK,
        )

        val outputs: MutableList<LivestreamOutput> = ArrayList()
        outputs.add(LivestreamOutput(RTMP_URL, RTMP_STREAM_KEY))

        // Start LiveStream
        liveStream!!.startLivestream(outputs, config)
      } else {
        // Stop LiveStream
        liveStream!!.stopLivestream()
      }
    } catch (e: VideoSDKException) {
      Log.e("VideoSDK", "Livestream request failed: ${e.code} ${e.name}")
    }
  }
}

Event associated with Livestream

• onLivestreamStateChanged - Called with a LiveStreamState every time the room's livestream state changes. liveStream.liveStreamState holds the latest state. It is LIVESTREAM_STOPPED until the first event, and again after you leave the room.

private val roomEventListener: RoomEventListener = object : RoomEventListener() {
  override fun onLivestreamStateChanged(state: LiveStreamState) {
    when (state) {
      LiveStreamState.LIVESTREAM_STARTING -> Log.d( "LivestreamStateChanged",
          "Room livestream is starting"
      )
      LiveStreamState.LIVESTREAM_STARTED -> Log.d( "LivestreamStateChanged",
          "Room livestream is started"
      )
      LiveStreamState.LIVESTREAM_STOPPING -> Log.d("LivestreamStateChanged",
          "Room livestream is stopping"
      )
      LiveStreamState.LIVESTREAM_STOPPED -> Log.d("LivestreamStateChanged",
          "Room livestream is stopped"
      )
    }
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  //...

  // add listener to room
  liveStream!!.addEventListener(roomEventListener)
}

API Reference

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

• startLivestream()
• stopLivestream()
• onLivestreamStateChanged