Interactive Livestream (HLS) - iOS

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.

VideoSDK also allows you to configure the interactive livestream layouts by choosing a prebuilt layout in the configuration or by providing your own custom template for the livestream.

This guide will provide an overview of how to implement 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 an interactive livestream of the room which can be accessed from the Room class. This method accepts two optional parameters:

• config (optional): This parameter defines how the interactive livestream layout should look.

• transcription(optional): This parameter will be used to enable post transcription for the recording with the given config.

startHLS() is async throws. Call it with try await inside a Task, after you join the room.

Swift

let config: HLSConfig = HLSConfig(

  // Layout Configuration
  layout: ConfigLayout(
    type: .GRID, // .SPOTLIGHT | .SIDEBAR,  Default : .GRID
    priority: .SPEAKER, // .PIN, Default : .SPEAKER
    gridSize: 4 // MAX : 25
  ),

  // Theme of livestream
  theme: .DARK, //  .LIGHT | .DEFAULT

  // `mode` is used to either interactive livestream video & audio both or only audio.
  mode: .video_and_audio, // .audio, Default : .video_and_audio

  // Quality of livestream and is only applicable to `video-and-audio` type mode.
  quality: .high,  // .low | .med,  Default : .med

  // Orientation of the livestream.
  // landscape: horizontal
  // portrait: vertical (best for mobile)
  orientation: .portrait  // .landscape,  Default : .landscape
)

let transcription: PostTranscriptionConfig = PostTranscriptionConfig(
  enabled: true,
  summary: SummaryConfig(
    enabled: true,
    prompt: "Write summary in sections like Title, Agenda, Speakers, Action Items, Outlines, Notes and Summary"
  )
)

Task {
  do {
    try await room?.startHLS(config: config, transcription: transcription)
  } catch {
    print("Failed to start HLS: \(error)")
  }
}

note

• Before you join the room, or after you leave it, startHLS() throws ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED (3035). While the room is reconnecting, it throws ERROR_ROOM_RECONNECTING (3065). Call it again after the room reconnects.
• If the server refuses the request, the call throws and onError(error:) also receives START_HLS_FAILED (4016).

stopHLS()

• stopHLS() is used to stop interactive livestream of the room which can be accessed from the Room class. It is also async throws, so call it with try await inside a Task.
• If the server refuses the request, the call throws and onError(error:) also receives STOP_HLS_FAILED (4017).

Example

Swift

Task {
  do {
    try await room?.stopHLS()
  } catch {
    print("Failed to stop HLS: \(error)")
  }
}

Event associated with HLS

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

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

  • playbackHlsUrl - Live HLS with playback support
  • livestreamUrl - Live HLS without playback support

Swift

func onHlsStateChanged(state: HLSState, hlsUrl: HLSUrl?) {
    switch(state) {
        case .HLS_STARTING:
            print("HLS Starting")

        case .HLS_STARTED:
            self.hlsStreamStarted = true
            print("HLS Started")

        case .HLS_PLAYABLE:
            // URLs to play the stream on the viewer side
            print("HLS Playable: \(hlsUrl?.playbackHlsUrl ?? "")")
            print("Livestream URL: \(hlsUrl?.livestreamUrl ?? "")")

        case .HLS_STOPPING:
            print("HLS Stopping")

        case .HLS_STOPPED:
            self.hlsStreamStarted = false
            print("HLS Stopped")

        @unknown default:
            break
        }
}

API Reference

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

• startHLS()
• stopHLS()
• onHlsStateChanged()
• autoStartConfig