Interactive Livestream (HLS) - Android

Interactive live streaming (HLS) refers to a type of live streaming where viewers can actively engage with the content being streamed and with other viewers in real-time.

In an interactive live stream (HLS), viewers can take part in a variety of activities like live polling, Q&A sessions, and even sending virtual gifts to the content creator or each other.

You can set the interactive livestream layout with a prebuilt layout in the configuration, or with your own custom template.

This guide shows how to start and stop interactive live streaming (HLS).

important

To initiate automatic Interactive live streaming (HLS) at the beginning of a session, simply provide the autoStartConfig feature hls during room creation. For more information on configuring the autoStartConfig, please refer to the provided documentation here.

startHls()

startHls() can be used to start a interactive livestream of the meeting which can be accessed from the Meeting class. This method accepts two parameter:

• config: This parameter will define how the interactive livestream layout should look like. Pass null to use the defaults. The values are case-sensitive, so write them exactly as shown below.

• transcription: This parameter lets you start post transcription for the Livestreaming. Pass null to skip it.

note

• startHls() and stopHls() 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 stream has started or stopped. Wait for onHlsStateChanged to report HLS_PLAYABLE before you play the stream.
• If the request fails, they throw VideoSDKException.
• Called before the meeting 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 = JSONObject()

// Layout Configuration
val layout = JSONObject()
layout.put("type", "GRID") // "SPOTLIGHT" | "SIDEBAR",  Default : "GRID"
layout.put("priority", "SPEAKER") // "PIN", Default : "SPEAKER"
layout.put("gridSize", 4) // MAX : 25
config.put("layout", layout)

// Theme of interactive livestream layout
config.put("theme", "DARK") //  "LIGHT" | "DEFAULT"

// `mode` is used to either interactive livestream video & audio both or only audio.
config.put("mode", "video-and-audio") // "audio", Default : "video-and-audio"

// Quality of interactive livestream and is only applicable to `video-and-audio` type mode.
config.put("quality", "high") /* Default : "med"
   "low" (SD HLS) | "med" (HD HLS) | "high" (FHD HLS) */

// This mode refers to orientation of interactive livestream.
// landscape : Start interactive livestream of the meeting in horizontally
// portrait : Start interactive livestream of the meeting in vertically (Best for mobile view)
config.put("orientation", "portrait") // "landscape",  Default : "landscape"

// Post Transcription Configuration
val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
val summaryConfig = SummaryConfig(true, prompt)
val modelId = "raman_v1"
val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

lifecycleScope.launch {
    try {
        meeting.startHls(config, transcription)
    } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Start HLS failed: ${e.code} ${e.name}")
    }
}

stopHls()

• stopHls() is used to stop interactive livestream of the meeting which can be accessed from the Meeting class.

Example

// keep track of hls, updated in onHlsStateChanged below
var isHlsStarted = false

findViewById<View>(R.id.btnHls).setOnClickListener { view: View? ->
  lifecycleScope.launch {
    try {
      if (!isHlsStarted) {
        val config = JSONObject()
        val layout = JSONObject()
        layout.put("type", "GRID")
        layout.put("priority", "SPEAKER")
        layout.put("gridSize", 4)
        config.put("layout", layout)
        config.put("theme", "DARK")
        config.put("mode", "video-and-audio")
        config.put("quality", "high")
        config.put("orientation", "portrait")

        // Post Transcription Configuration
        val prompt = "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
        val summaryConfig = SummaryConfig(true, prompt)
        val modelId = "raman_v1"
        val transcription = PostTranscriptionConfig(true, summaryConfig, modelId)

        // Start Hls
        meeting!!.startHls(config, transcription)
      } else {
        // Stop Hls
        meeting!!.stopHls()
      }
    } catch (e: VideoSDKException) {
      Log.e("VideoSDK", "HLS request failed: ${e.code} ${e.name}")
    }
  }
}

tip

If you want to learn more about the Interactive Livestream and how you can implement it in your own platform, you can check out this guide.

Event associated with HLS

• onHlsStateChanged - Whenever meeting HLS state changes, then onHlsStateChanged event will trigger.

• You can get the playableUrl of the HLS to play it on the Viewer side when the state changes to HLS_PLAYABLE.

note

The playable URL arrives as playableUrl. The playbackHlsUrl, livestreamUrl and downstreamUrl keys are not sent, so read playableUrl instead.

private val meetingEventListener: MeetingEventListener = object : MeetingEventListener() {
  override fun onHlsStateChanged(HlsState: JSONObject) {
    when (HlsState.getString("status")) {
        "HLS_STARTING" -> Log.d("onHlsStateChanged", "Meeting hls is starting")
        "HLS_STARTED" -> {
            isHlsStarted = true
            Log.d("onHlsStateChanged", "Meeting hls is started")
        }
        "HLS_PLAYABLE" -> {
            Log.d("onHlsStateChanged", "Meeting hls is playable now")
            // on hls playable you will receive playableUrl
            val playableUrl = HlsState.optString("playableUrl")
        }
        "HLS_STOPPING" -> Log.d("onHlsStateChanged", "Meeting hls is stopping")
        "HLS_STOPPED" -> {
            isHlsStarted = false
            Log.d("onHlsStateChanged", "Meeting hls is stopped")
        }
    }
  }
}

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

  // add listener to meeting
  meeting!!.addEventListener(meetingEventListener)
}

Custom Template

With VideoSDK, you can also use your own custom designed layout template to livestream the meetings. In order to use the custom template, you need to create a template for which you can follow this guide. Once you have setup the template, you can use the REST API to start the livestream with the templateUrl parameter.

API Reference

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

• startHls()
• stopHls()
• onHlsStateChanged
• autoStartConfig