HLS Playback

The HMSHLSPlayer is an HLS player offered by 100ms that can be used to play HLS streams. The player takes a URL to play the stream. It also provides the ability to send analytics events related to the HLS playback to the 100ms dashboard when provided with 100ms SDK instance with an active room.

How to integrate HLS Player SDK

You can either use Swift Package Manager or Cocoapods to add HMSHLSPlayerSDK iOS SDK to your project.

Use Swift Package Manager

Add HMSHLSPlayerSDK iOS SDK through Swift Package Manager in Xcode. Use https://github.com/100mslive/100ms-ios-hls-sdk.git as the package source.

Use Cocoapods

Assuming your project name is "basicvideocall", create "Podfile" in the project folder with the following contents then run pod install

platform :ios, '13.0'

target 'basicvideocall' do
  use_frameworks!
  pod 'HMSHLSPlayerSDK'

end

Open .xcworkspace

How to use Play HLS stream

You create an instance of HMSHLSPlayer like below:

import HMSHLSPlayerSDK

let hlsPlayer = HMSHLSPlayer()

Next, you call play on this hlsPlayer instance passing the hls stream url like below:

let url = URL(string: "HLS-URL-HERE")
hmsPlayer.play(url)

How do I get the HLS URL of the room?

There can be 2 cases:

1. HLS streaming is already in progress when you join the room
2. HLS stream is started after you have joined the session

You should handle both cases by listening to onJoin and onRoomUpdate callbacks respectively, like below:

// Case 1 - play the hls stream if room has an active hls URL
func on(join room: HMSRoom) {
  if let hlsUrl = room.hlsStreamingState.variants.first?.url {
    hmsPlayer.play(hlsUrl)
  }
}

// Case 2 - hls stream is started after you have joined the session
func on(room: HMSRoom, update: HMSRoomUpdate) {
  switch update {
  case .hlsStreamingStateUpdated:
    if let hlsUrl = room.hlsStreamingState.variants.first?.url {
      hmsPlayer.play(hlsUrl)
    }
  }
}

How to show video player UI

You can get access to video player view as a UIView. So that you can add it as a subview to any other view in your app's UI.

You call videoPlayerViewController method on hls player instance to get AVPlayerViewController. You use this AVPlayerViewController instance to show the video player view in your own UIView. Below we show an example of how you can subview the video player view in your own UIViewController.

class HLSStreamViewController: UIViewController {

...

    override func viewDidAppear(_ animated: Bool) {
    
    ...
    
        let playerViewController = hmsPlayer.videoPlayerViewController(showsPlayerControls: true)
        playerViewController.view.frame = self.view.bounds
        self.view.addSubview(playerViewController.view)
    }
}

How to stop the playback

You call stop on the hlsPlayer instance like below:

hmsPlayer.stop()

How to pause and resume the playback

You call pause/resume on the hlsPlayer instance like below:

hmsPlayer.pause()
hmsPlayer.resume()

How to seek forward or backward

You use seekForward and seekBackward methods on the hlsPlayer instance like below:

hmsPlayer.seekForward(seconds: 5)
hmsPlaye.seekBackward(seconds: 5)

How to seek to live position

You use seekToLivePosition methods on the hlsPlayer instance to go to the live poition like below:

hmsPlayer.seekToLivePosition()

How to change volume of HLS playback

Use volume property to change the volume of HLS player. The volume level is between 0-100. Volume is set to 100 by default.

hmsPlayer.volume = 50

How to know the stats related to HLS playback

HMSHLSPlayer exposes statMonitor interface to know about the statistics about current HLS playback. For more information about how to use this HLS Stats Monitor check it's documentation here The following snippet shows how you check check how far is the current HLS playback from live position. To monitor stats continuously you can use a timer to check the values of different stats.

Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { _ in
    let distanceFromLivePosition = hmsPlayer.statMonitor.distanceFromLiveEdge
}

How to know when player changes state during playback

The player can be in one of the following states: playing, stopped, paused, buffering, failed, unknown during playback.

You can assign a class that follows HMSHLSPlayerDelegate protocol as delegate to the hlsPlayer instance. And listen for onPlaybackStateChanged callback to know about the state change event during the playback.

class HLSStreamViewController: HMSHLSPlayerDelegate {
    ...
    
    hlsPlayer.delegate = self
    ...

    func onPlaybackStateChanged(state: HMSHLSPlaybackState) {
        // Do player UI related changes
    }
}

How to know when there is an error during hls playback

You can assign a class that follows HMSHLSPlayerDelegate protocol as delegate to the hlsPlayer instance. And listen for onPlaybackFailure callback to know about the errors that happen during playback.

class HLSStreamViewController: HMSHLSPlayerDelegate {
    ...
    
    hlsPlayer.delegate = self
    ...

    func onPlaybackFailure(error: Error) {
        guard let error = error as? HMSHLSError else { return }
        
        if error.isTerminal {
            print("Player has encountered a terminal error, we need to restart the player: \(error.localizedDescription)")
        }
        else {
            print("Player has encountered an error, but it's non-fatal and player might recover \(error.localizedDescription)")
        }
    }
}

How to use HLS Timed Metadata with 100ms HLS player

Timed Metadata can be embeded in the HLS stream using 100ms SDK. When you use 100ms HLS player to play this HLS stream, onCue(cue: HMSHLSCue) callback is triggered when the player's current time matches that of a timed event in the HLS stream. You can utilise this callback to know about any HLS Timed Metadata cue and use it's data to show any UI like quizes, poll etc. to HLS viewers.

class HLSStreamViewController: HMSHLSPlayerDelegate {
    ...
    
    hlsPlayer.delegate = self
    ...

    func onCue(cue: HMSHLSCue) {
        // Handle the hls timed metadata cue
    }
}

Note: following information on HMSHLSCue can be used to know more about what timed event is triggered and show UI accordingly:

class HMSHLSCue: NSObject {
    
    /// Unique id of the timed event
    public let id: String
    
    /// startDate of the timed event
    public let startDate: Date
    
    /// endDate of the timed event
    public let endDate: Date?
    
    /// String payload of the timed event
    public let payload: String?
    
}

How to configure hls player to send analytics events

If your app already has an hmsSDK instance that you are using to join the 100ms room, you can assign this instance to HLS player's analytics interface to enable the player to sent analytics events. Currently only hard failure events (where the player encounters an unrecoverable error and playback can't continue) are sent to analytics.

hlsPlayer.analytics = hmsSDK

👀 To see an example iOS HLS Player implementation using 100ms SDK, checkout our example project.

How to show video player UI that plays HLS stream of the Room

You instantiate HMSHLSPlayerView() instance to render the HLS stream from the room you are in.

HMSHLSPlayerView()

How to play HLS stream when you have a URL of hls stream

You instantiate HMSHLSPlayerView() instance passing the URL as parameter to render the HLS stream from the URL.

HMSHLSPlayerView(url: /* pass stream URL here */)

How to overlay buttons/UI on top of the HLS player

You can use a view builder as overlay parameter to HMSHLSPlayerView.

HMSHLSPlayerView() { player in
    // player here is an instance of HMSHLSPlayer
    // custom overlay controls for HLS playback
    HStack {
        // pause hls stream
        Button(action: {
            player.pause()
        }, label: {
            Text("Pause")
        })
        
        // resume hls stream
        Button(action: {
            player.resume()
        }, label: {
            Text("Resume")
        })
    }
}

import SwiftUI
import HMSRoomModels

struct MeetingView: View {
    
    @ObservedObject var roomModel = HMSRoomModel(roomCode: "qdw-mil-sev")
    
    var body: some View {
        
        switch roomModel.roomState {
        case .notJoined, .leftMeeting:
            // Button to join the room
            Button {
                Task {
                    try await roomModel.joinSession(userName: "iOS User")
                }
            } label: {
                Text("Join")
            }
        case .inMeeting:
            VStack {
                if roomModel.hlsVariants.first?.url != nil {
                    HMSHLSPlayerView() { player in
                        // custom overlay controls for HLS playback
                        HStack {

                            // pause hls stream
                            Button(action: {
                                player.pause()
                            }, label: {
                                Text("Pause")
                            })
                            
                            // resume hls stream
                            Button(action: {
                                player.resume()
                            }, label: {
                                Text("Resume")
                            })

                            // stop hls stream playback
                            Button(action: {
                                hmsPlayer.stop()
                            }, label: {
                                Text("Stop")
                            })

                            // seek forward
                            Button(action: {
                                hmsPlayer.seekForward(seconds: 5)
                            }, label: {
                                Text("Seek forward")
                            })

                            // seek forward
                            Button(action: {
                                hmsPlaye.seekBackward(seconds: 5)
                            }, label: {
                                Text("Seek backward")
                            })

                            // seek to live position
                            Button(action: {
                                hmsPlayer.seekToLivePosition()
                            }, label: {
                                Text("Seek to Live")
                            })

                            // change volume
                            Button(action: {
                                hmsPlayer.volume = 50
                            }, label: {
                                Text("Half Volume")
                            })
                        }
                    }
                    .onResolutionChanged { size in
                        print("resolution: \(size)")
                    }
                    .onPlaybackFailure { error in
                        print("hlsError: \(error.localizedDescription)")
                    }
                    .onCue { cue in
                        // use HMSHLSCue to overlay metadata information
                    }
                    .onPlaybackStateChanged { playbackState in
                        // handle HMSHLSPlaybackState enum here
                        // where HMSHLSPlaybackState is
                        ///  @objc public enum HMSHLSPlaybackState: Int {
                        ///      case playing, stopped, paused, buffering, failed, unknown
                        ///  }
                    }
                }
                else {
                    // view to show when stream is yet to start
                }
                
                HStack {
                    
                    // Button to leave the room
                    Image(systemName: "phone.down.fill")
                        .onTapGesture {
                            Task {
                                try await roomModel.leaveSession()
                            }
                        }
                }
            }
        }
    }
}