Start HLS - Android

Before starting HLS, you need a running VideoSDK room to use for the interactive livestream. To learn more about setting up interactive live streaming, you can follow the steps here in the quick start guide.

Starting HLS

Once the room is joined, call startHLS() on the Room to start the HLS stream. It takes two parameters:

• config: An HLSConfig that defines how the interactive livestream layout should look. Pass null (the default) to use the defaults. A field left null takes the server's default.
• transcription: This parameter lets you turn on post transcription and summary for the interactive livestream, as a PostTranscriptionConfig. Pass null (the default) to skip it. To learn more, follow the Post Transcription & Summary guide.

HLSConfig and the Config* types it uses are in the live.videosdk.rtc.android.model package.

note

• startHLS() is a suspend function. Call it from a coroutine, such as lifecycleScope.launch (from androidx.lifecycle:lifecycle-runtime-ktx).
• It returns once the request is sent, not when the stream is live. Wait for onHlsStateChanged to report HLSState.HLS_PLAYABLE before you play the stream.
• If the request fails, it throws VideoSDKException.
• Called before the room 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.

val config = HLSConfig(
    // Layout Configuration
    layout = ConfigLayout(
        type = ConfigLayoutGrid.GRID, // SPOTLIGHT | SIDEBAR, Default : GRID
        priority = ConfigLayoutPriority.SPEAKER, // PIN, Default : SPEAKER
        gridSize = 4, // MAX : 25
    ),
    // Theme of interactive livestream layout
    theme = ConfigTheme.DARK, // LIGHT | DEFAULT
    // VIDEO_AND_AUDIO streams video and audio; AUDIO streams audio only.
    mode = ConfigMode.VIDEO_AND_AUDIO, // AUDIO, Default : VIDEO_AND_AUDIO
    // Quality of interactive livestream and is only applicable to `VIDEO_AND_AUDIO` mode.
    quality = ConfigQuality.HIGH,
    // LOW (SD HLS) | MED (HD HLS) | HIGH (FHD HLS)
    // This mode refers to orientation of interactive livestream.
    // LANDSCAPE : Start interactive livestream of the room horizontally
    // PORTRAIT : Start interactive livestream of the room vertically (Best for mobile view)
    orientation = ConfigOrientation.PORTRAIT, // LANDSCAPE, Default : LANDSCAPE
)

lifecycleScope.launch {
    try {
        // pass null as transcription to skip post transcription
        room!!.startHLS(config, null)
    } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Start HLS failed: ${e.code} ${e.name}")
    }
}

note

If you want only the SEND_AND_RECV participants to be seen in the livestream, you can pin all the participants in the SEND_AND_RECV mode and start the livestream with the SPOTLIGHT layout and PIN as the priority.

Example

// keep track of hls
findViewById<View>(R.id.btnStartHls).setOnClickListener { view: View? ->
    val config = HLSConfig(
        layout = ConfigLayout(
            type = ConfigLayoutGrid.SPOTLIGHT,
            priority = ConfigLayoutPriority.PIN,
            gridSize = 4,
        ),
        theme = ConfigTheme.DARK,
        mode = ConfigMode.VIDEO_AND_AUDIO,
        quality = ConfigQuality.HIGH,
        orientation = ConfigOrientation.PORTRAIT,
    )

    lifecycleScope.launch {
        try {
            // Start HLS
            room!!.startHLS(config)
        } catch (e: VideoSDKException) {
            Log.e("VideoSDK", "Start HLS failed: ${e.code} ${e.name}")
        }
    }
}

Understanding Layouts

1. GRID Layout

This layout is default layout if no participants are pinned, it will look same as a normal room grid layout, when any participant is pinned that participant will be moved on top of the main screen grid above all non pinned participants

While screenshare as well the main view will contain only screenshare media but the side panel view of participant grid will maintain same order of pinned and unpinned participants.

Grid	Grid with Screenshare

2. SIDEBAR Layout

This layout will have one main screen view and other sidebar grid layout. Only pinned participant will be visible in this layout, all unpinned participants will not be visible in this layout. If more than one participant is pinned then the first participant who was pinned will appear in main screen layout and all other remaining pinned participants will be visible in sidebar.

If any pinned participant started screenshare then the screenshare media will be visible in main screen layout and all other pinned participants webcam view will be visible in sidebar

Sidebar	Sidebar with Screenshare

3. SPOTLIGHT Layout

This layout will only contain main screen layout, multiple pinned participants will be visible in main screen view. Same as SIDEBAR layout only pinned participants will be visible in main screen.

If any pinned participant started screenshare then only screenshare view will be visible in main screen, no webcam view will be visible when any pinned participant started screenshare.

Spotlight	Spotlight with Screenshare

Event associated with HLS

• onHlsStateChanged - Whenever the room's HLS state changes, the onHlsStateChanged event will trigger with an HLSState.

• When the state changes to HLSState.HLS_PLAYABLE, the event also carries an HLSUrl. Play its playbackHlsUrl on the viewer side; livestreamUrl follows the live edge. Either can be null if the server sent none, and hlsUrl is null for the other states.

private val roomEventListener: RoomEventListener = object : RoomEventListener() {
  override fun onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
    when (state) {
        HLSState.HLS_STARTING -> Log.d("onHlsStateChanged", "Room hls is starting")
        HLSState.HLS_STARTED -> Log.d("onHlsStateChanged", "Room hls is started")
        HLSState.HLS_PLAYABLE -> {
            Log.d("onHlsStateChanged", "Room hls is playable now")
            // on hls playable you will receive the playback URL
            val playbackHlsUrl = hlsUrl?.playbackHlsUrl
        }
        HLSState.HLS_STOPPING -> Log.d("onHlsStateChanged", "Room hls is stopping")
        HLSState.HLS_STOPPED -> Log.d("onHlsStateChanged", "Room hls is stopped")
    }
  }
}

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

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

Custom Template

You can also stream the room with your own layout template. Create the template by following this guide, then use the REST API to start the livestream with the templateUrl parameter.

API Reference

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

• startHLS()
• stopHLS()
• onHlsStateChanged