Using Your Own Player (iOS)

HotMicMediaPlayer allows you to integrate your own player into your application. In order do to this, you must:

• Include the player in your application to be played. (e.g. Bitmovin, JWPlayer, Exo).
• Use our protocol to forward commands to your player when the HotMic protocol dictates (e.g. pause the player).
• Send to HotMic various player events (e.g. notify HotMic the player is paused).

The HMPlayer protocol defines variables and functions you must implement in order to provide a custom player. Your implementation must also store a reference to an HMPlayerDelegate and call its functions to inform the delegate when various events occur.

Provide a view to display on-screen.

var view: UIView { playerView }

Provide the playing status.

var isPlaying: Bool { player.isPlaying }

Provide the paused status.

var isPaused: Bool { player.isPaused }

Provide the seeking status.

var isSeeking: Bool { activelySeeking }

Provide the mute status.

var isMuted: Bool { player.isMuted }

Provide the current audio level as a value between 0 and 100.

var volume: Int { player.volume }

Provide the total duration in seconds of the VoD stream or infinity if it’s a live stream.

var duration: TimeInterval { player.duration }

Provide the current playback position in seconds. For a VoD stream, the time ranges between 0 and the duration of the asset. For a live stream, the time is a Unix timestamp denoting the current playback position.

var time: TimeInterval { player.currentTime }

Provide the current playback rate as a value between 0 and 2.

var playbackSpeed: Float { player.playbackSpeed }

Store the delegate in a weak optional variable to call its functions in the future.

func setDelegate(_ delegate: HMPlayerDelegate) { self.delegate = delegate }

Invoke play.

func play() { player.play() }

Invoke pause.

func pause() { player.pause() }

Turn on volume muted.

func mute() { player.mute() }

Turn off volume muted.

func unmute() { player.unmute() }

Change the audio level.

func updateVolume(_ volume: Int) { player.volume = volume }

Seek to the given playback position for the VoD stream.

func seek(to time: TimeInterval) {
    guard !player.isLive else { return }
    
    player.seek(time: time)
}

Seek by the given time shift offset in seconds from the live edge for the live stream, or seek to the current time plus the given time shift offset for the VoD stream. Return an HMPlayerLiveTimeShiftError if the new time shift is too far behind or ahead of the live position.

@discardableResult func seek(by timeShiftOffset: TimeInterval) -> HMPlayerLiveTimeShiftError? {
    guard player.isLive else {
        seek(to: time + timeShiftOffset)
        return nil
    }
    
    let newTimeShift = player.timeShift + timeShiftOffset
    
    guard newTimeShift >= player.maxTimeShift else {
        player.timeShift = 0
        return .tooFarBehind
    }
    guard newTimeShift <= 0 else {
        player.timeShift = 0
        return .tooFarAhead
    }
    
    player.timeShift = newTimeShift
    return nil
}

Seek the live stream to its 'now' playback time.

func seekToLive() { player.timeShift = 0 }

Change the playback rate. A value between 0 and 1 enables slow motion and a value between 1 and 2 enables fast forward.

func updatePlaybackSpeed(_ playbackSpeed: Float) { player.playbackSpeed = playbackSpeed }

Prepare for device rotation to begin.

func beginRotation() { playerView.willRotate() }

Handle device rotation ended.

func endRotation() { playerView.didRotate() }

Prepare to enter fullscreen mode.

func enterFullscreen() { playerView.enterFullscreen() }

Prepare to exit fullscreen mode.

func exitFullscreen() { playerView.exitFullscreen() }

Player Delegate

The HMPlayerDelegate protocol defines functions your HMPlayer implementation calls to inform HotMic when various events occur.

Inform the delegate the player invoked play with intention to start/resume playback.

delegate?.playerDidInvokePlay(self)

Inform the delegate the player state changed to playing.

delegate?.playerPlaying(self)

Inform the delegate the player state changed to paused.

delegate?.playerPaused(self)

Inform the delegate the player state changed to buffering.

delegate?.playerBuffering(self)

Inform the delegate the player finished seeking in a live stream by adjusting the time shift.

delegate?.playerDidFinishSeekByTimeShift(self)

Inform the delegate the player recovered from a stall due to sufficient buffer.

delegate?.playerDidRecoverFromStall(self)

Inform the delegate the player's playback position changed.

delegate?.player(self, timeChanged time: player.currentTime)

Inform the delegate the player's duration changed.

delegate?.player(self, durationChanged duration: player.duration)

Inform the delegate the player encountered an error.

delegate?.player(self, errorOccurredWithCode code: error.code, message: error.localizedDescription)