iOS Player SDK

API Reference

 

Initialize

initialize  |  destroy  |  load  |  source  

Playback Control

play  |  pause  |  seek  |  forward  |  rewind  | isPlaying

Set Player Parameters

SetVolume | SetAudioTrack

SetMaxSelectableBitrateSetSubtitle

Get Player Parameters

GetVolume  |  isMuted

GetCurrentTime  |  GetDuration

GetAvailableVideoQualities  |  GetVideoQuality  | 

GetAvailableAudioTracks  |  GetCurrentAudioTrack  |  

GetAvailableSubtitles  |  GetCurrentSubtitle  |  

thumbnail

playbackSpeed

Set Event Listener/Callback

 

Player View

fullScreen  |  managesPlaybackControlsAutomatically   |  showsPlaybackControls  | uiStyleConfig

 


Initialize

create

Initialize a player instance.

Sample code

let playerConfig = PlayerConfig()
player = PlayerFactory.create(playerConfig: playerConfig)

Class define

public class UniPlayerConfig {
    public var key: String?  // A BlendVision One license key that can be found in the BOP portal
    public var styleConfig: UniStyleConfig  // Configures visual presentation and behaviour of the Player UI. A default StyleConfig is set initially.
    public var playbackConfig: UniPlaybackConfig  // Configures playback behaviour. A default PlaybackConfig is set initially.
    public var bufferConfig: UniBufferConfig  // Configures buffer settings. A default BufferConfig is set initially.
    public var adaptationConfig: UniAdaptationConfig  // Configures adaptation logic. A default AdaptationConfig is set initially
    public var tweaksConfig: UniTweaksConfig  // Configures experimental features. A default TweaksConfig is set initially
}
public final class UniStyleConfig {  
    public var scalingMode: AVLayerVideoGravity
    public var uiStyleConfig: UniUIStyleConfig  // Set the property that will be used for the UI.
}
public class UniPlaybackConfig {
    public var isAutoplayEnabled: Bool  // Whether the player starts playing automatically after loading a source or not. Default value is false.
    public var isMuted: Bool  // Whether the sound is muted on startup or not. Default value is false.
}
public class UniBufferConfig {
    public var audioAndVideo: UniBufferMediaTypeConfig
}
public class UniBufferMediaTypeConfig {
    // The amount of data in seconds the player tries to buffer in advance.
    // If set to 0, the player will choose an appropriate forward buffer duration suitable for most use-cases.
    // Default value is 6.
    public var forwardDuration: TimeInterval
    public var audioTimePitchAlgorithm: AVAudioTimePitchAlgorithm
}
public final class UniAdaptationConfig {
    // The upper bitrate boundary in bits per second for network bandwidth consumption of the played source.
    // Can be set to 0 for no limitation.
    // Default value is 0.
    public var maxSelectableBitrate: UInt = 0
}
public final class UniTweaksConfig {
    var timeChangedInterval: TimeInterval // Default is 1. Minimum is 0.025.
    /// This is useful if the duration of the segments does not match the duration specified in the manifest.
    /// In this case, if we try to seek to the end,
    /// AVPlayer could get stuck and might stall forever Therefore increasing this value could help.
    var seekToEndThreshold: TimeInterval
}

since: 2.1.0

< back

destroy

Destroys the player and releases all allocated resources. The player instance must not be used after calling this method.

func destroy()

since: 2.1.0

< back

load

Sets a new video source and returns a promise which resolves to the player.

Sample code

player.load(sourceConfig)

Class define 


public class UniSourceConfig {
    public let url: URL
    public let type: UniSourceType
    public var title: String? // The title of the video source.
    public var sourceDescription: String? // The description of the video source. 
    public var posterSource: URL? // The URL to a preview image displayed until the video starts.
    public var drmConfig: UniDrmConfig? // The DRM config for the source.
    public var thumbnailTrack: UniThumbnailTrack? // The thumbnail track for this source config.
    public let isPSEEnabled: Bool 
    public var sharedURL: URL? 
    public var features: [UniFeature] = []
}
public class UniDrmConfig { 
    public var licenseUrl: URL? // The DRM license acquisition URL.
}
public class UniFairPlayConfig: UniDrmConfig {
    public var certificateUrl: URL?  // The URL to the FairPlay Streaming certificate of the license server.
    public var licenseRequestHeaders: [String: String]?  // A dictionary to specify custom HTTP headers for the license request.
    public var certificateRequestHeaders: [String: String]?  // A dictionary to specify custom HTTP headers for the certificate request.
}
public class UniThumbnailTrack: UniTrack {
    // Refer to UniTrack
}
public enum UniFeature: String {
    case d3 = "D3"
    case pse = "PSE"
}

since: 2.1.0

< back

source

Get stream content all metadata that sets into player.

Sample code

public class UniSourceConfig {
    public let url: URL
    public let type: UniSourceType
    public var title: String? // The title of the video source.
    public var sourceDescription: String?  // The description of the video source. 
    public var posterSource: URL?  // The URL to a preview image displayed until the video starts.
    public var drmConfig: UniDrmConfig?  // The DRM config for the source.
    public var thumbnailTrack: UniThumbnailTrack?  // The thumbnail track for this source config.
    public let isPSEEnabled: Bool 
public var sharedURL: URL? public var features: [UniFeature] = [] } public class UniDrmConfig { public var licenseUrl: URL? // The DRM license acquisition URL. } public class UniFairPlayConfig: UniDrmConfig { public var certificateUrl: URL? // The URL to the FairPlay Streaming certificate of the license server. public var licenseRequestHeaders: [String: String]? // A dictionary to specify custom HTTP headers for the license request. public var certificateRequestHeaders: [String: String]? // A dictionary to specify custom HTTP headers for the certificate request. } public class UniThumbnailTrack: UniTrack { // Refer to UniTrack } public enum UniFeature: String { case d3 = "D3" case pse = "PSE" } public var source: UniSource? public final class UniSource { public var sourceConfig: UniSourceConfig public func thumbnail(forTime time: TimeInterval) } let UniSource = player.source

since: 2.1.0

< back

Playback Control

play

Starts playback or resumes after being paused. Has no effect if the player is already playing.

func play()

since: 2.1.0

< back

pause

Pauses the video if it is playing. Has no effect if the player is already paused.

func pause()

since: 2.1.0

< back

seek

Seeks to the given playback time.

Seeks to the given playback time specified by the parameter time in seconds. Must not be greater than the total duration of the video. Has no effect when watching a live stream as seeking is not possible.

func seek(time: TimeInterval)

since: 2.1.0

< back

forward

Forward to the given playback time specified by the parameter time in seconds. Must not be greater than the total duration of the video. 

func forward(_offset: TimeInterval)

since: 2.1.0

< back

rewind

Rewind to the given playback time specified by the parameter time in seconds. Must not be greater than the total duration of the video. 

func rewind(_offset: TimeInterval)

since: 2.1.0

< back

isPlaying

Returns true if the player is currently playing, i.e. has started and is not paused.

var isPlaying: Bool { get }

since: 2.1.0

< back

Player Parameters

volume

Get/set the player’s volume between 0 (silent) and 100 (max volume). This property is used to control the player audio volume relative to the system volume.

var volume: Int { get set }

since: 2.1.0

< back

isMuted

Returns true if the player is muted.

var isMuted: Bool { get set }

since: 2.1.0

< back

currentTime

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

var currentTime: TimeInterval { get }

since: 2.1.0

< back

duration

The duration of the source in seconds if it’s a VoD or Double.infinity if it’s a live stream. The default value is 0 if the duration is not available or not known.

var duration: TimeInterval { get }

since: 2.1.0

< back

availableVideoQualities

Returns an array containing all available video qualities the player can adapt between.

var availableVideoQualities: [UniVideoQuality] { get }

since: 2.1.0

< back

videoQuality

Returns the currently selected video quality.

var videoQuality: UniVideoQuality? { get }

since: 2.1.0

< back

maxSelectableBitrate

The upper bitrate boundary is in bits per second for network bandwidth consumption of the currently played source. Can be set to 0 for auto profile change. The value set here is only valid for the currently played source and will not be carried over to subsequently loaded sources. 

The default value is 0.

var maxSelectableBitrate: UInt { set }

Note: Not allow sets the quality to 1080p or higher when PSE is enabled.

since: 2.1.0

< back

availableAudio

Returns an array containing all available audio tracks.

var availableAudio: [UniAudioTrack] { get }

since: 2.1.0

< back

audio

Returns the currently used audio track.

var audio: UniAudioTrack? { get }

since: 2.1.0

< back

setAudio

Sets the audio track to the ID specified by audioTrackID. A list can be retrieved by calling availableAudio.

func setAudio(track identifier: String)

since: 2.1.0

< back

availableSubtitles

Returns an array containing UniSubtitleTrack objects for all available subtitle tracks.

var availableSubtitles: [UniSubtitleTrack] { get }

since: 2.1.0

< back

subtitle

Returns the currently used UniSubtitleTrack.

var subtitle: UniSubtitleTrack { get }

since: 2.1.0

< back

setSubtitle

Sets the subtitle track to the ID specified by trackID. A list can be retrieved by calling availableSubtitles. Using nil as ID disables subtitles.

func setSubtitle(track identifier: String)

since: 2.1.0

< back

playbackSpeed

Get/set the playback speed of the player. Fast forward, slow motion and reverse playback are supported.

  • Slow motion is used by values between 0 and 1, fast forward by values greater than 2, slow reverse is used by values between 0 and -1, and fast reverse is used by values less than -1.

  • Negative values are ignored during Casting.

  • During reverse playback, the playback will continue until the beginning of the active source is reached. When reaching the beginning of the source, playback will be paused and the playback speed will be reset to its default value of 1. 

var playbackSpeed: Float { get set }

since: 2.1.0

< back

UniSource - thumbnail

Indicates a track containing thumbnail data like the UniThumbnail.

func thumbnail(forTime time: TimeInterval) -> UniThumbnail?

UniThumbnail

let start: TimeInterval { get }
let end: TimeInterval { get }
let text: String { get }
let url: URL { get }
let px: UInt { get }
let py: UInt { get }
let width: UInt { get }
let height: UInt { get }

since: 2.1.0

< back

Playback/ Error Event Callback Listener

Listen to the playback callback event that happened during playback. This method provides the function callback and listener to get the state of the player. Then, you can implement the customization by those states. i.e., After getting the state of buffering, you can get its preferred icon.

Playback Event Listener

// Listen to playback events (includes error events)
player.add(UniPlayerListener)

// Implement delegate didReceiveOnEvent
public func player(_ player: UniPlayer, didReceiveOnEvent event: UniEvent) {
    // do something
}

public protocol UniPlayerListener{
    func player(_ player: UniPlayer, didReceiveOnEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveOnReadyEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveOnPlayingEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveOnPausedEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveOnTimeChangedEvent event: UniTimeChangedEvent)
    func player(_ player: UniPlayer, didReceiveOnSeekEvent event: UniSeekEvent)
    func player(_ player: UniPlayer, didReceiveOnSeekedEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveOnStallStartedEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveOnStallEndedEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveOnPlaybackFinishedEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveOnAudioChangedEvent event: UniAudioChangedEvent)
    func player(_ player: UniPlayer, didReceiveOnSubtitleChangedEvent event: UniSubtitleChangedEvent)
    func player(_ player: UniPlayer, didReceiveOnSourceLoadEvent event: UniSourceLoadEvent)
    func player(_ player: UniPlayer, didReceiveOnSourceLoadedEvent event: UniSourceLoadedEvent)
    func player(_ player: UniPlayer, didReceiveOnVideoQualityChangedEvent event: UniVideoPlaybackQualityChangedEvent)
    func player(_ player: UniPlayer, didReceivePlaybackSpeedChangedEvent event: UniPlaybackSpeedChangedEvent)
    func player(_ player: UniPlayer, didReceiveSourceErrorEvent event: UniSourceErrorEvent)
    func player(_ player: UniPlayer, didReceiveMutedEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveUnmutedEvent event: UniEvent)
    func player(_ player: UniPlayer, didReceiveAudioVolumeChangedEvent event: UniAudioVolumeChangedEvent)
    func player(_ player: UniPlayer, didReceiveSourceUnloadEvent event: UniSourceUnloadEvent)
    func player(_ player: UniPlayer, didReceiveSourceUnloadedEvent event: UniSourceUnloadedEvent)
    func player(_ player: UniPlayer, didReceiveErrorEvent event: UniPlayerErrorEvent)
    func player(_ player: UniPlayer, didReceiveTimeShiftEvent event: UniTimeShiftEvent)
    func player(_ player: UniPlayer, didReceiveTimeShiftedEvent event: UniEvent)
}

Playlog event callback

This method allows you to get the log information, and then you can integrate to the log service 

event list

UniLogger.shared.add(UniLoggerListener)
extension AppDelegate: UniLoggerListener {
    func logEvent(_ event: UniLogEvent) {
    }
}
public class UniLogEvent: UniLogEventProtocol {
    public var name: EventName { return .none }
    public var properties: [UniLogEvent.PropertyName: Any]
}

since: 2.1.0

< back

Player View

fullScreen

Sets the player view to a full screen.

var orientation: UIInterfaceOrientationMask = .portrait
var fullscreen: Bool = false

// Handling view transition
override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) {
    coordinator.animate { _ in
        if size.width > size.height {
            self.playerView?.enterFullscreen() // Will enter landscape
        } else {
            self.playerView?.exitFullscreen()  // Will enter portrait
        }
    }
    super.viewWillTransition(to: size, with: coordinator)
}

// Conforming to UniFullscreenHandler protocol
extension UniBasicPlaybackViewController: UniFullscreenHandler {
    var isFullscreen: Bool {
        return fullscreen
    }
    func onFullscreenRequested() {
        updateLayoutOnFullscreenChange(fullscreen: true)
    }
    func onFullscreenExitRequested() {
        updateLayoutOnFullscreenChange(fullscreen: false)
    }
    private func updateLayoutOnFullscreenChange(fullscreen: Bool) {
        self.fullscreen = fullscreen
        orientation = fullscreen ? .landscape : .portrait
        bottomConstraint.isActive = fullscreen ? true : false
        if #available(iOS 16.0, *) {
            setNeedsUpdateOfSupportedInterfaceOrientations()
        } else {
            UIViewController.attemptRotationToDeviceOrientation()
        }
    }
}

since: 2.1.0

< back

managesPlaybackControlsAutomatically

Sets the UI state automatically. Shows controller when the user interacts with and did when no interaction in 3 seconds. The controller includes a progress bar, seek function, title, back button, play, pause, rewind, thumbnail, and so on.

  • True: The default value
  • False: Set this property to false if you don't want the player to manage the playback controls automatically
var managesPlaybackControlsAutomatically: Bool

since: 2.1.0

< back

showsPlaybackControls

Set this property to false if you don’t want the system-provided playback controls visible over your content. Hiding the playback controls can be useful in situations where you need a non-interactive video presentation, such as a video splash screen. The default value is true.

var showsPlaybackControls: Bool

since: 2.1.0

< back

UniStyleConfig

Contains config values that can be used to alter the visual presentation and behavior of the player UI.

  • ScalingMode: Determines how the video content is scaled or stretched within the parent container’s bounds. 
  • uiStyleConfig
var scalingMode: AVLayerVideoGravity { get set }
var uiStyleConfig: UniUIStyleConfig { get set }
  • UniUIStyleConfig.trackTintColor: change controller color
var trackTintColor: UIColor { get set }

since: 2.1.0

< back

Updated