PlayerAPI Protocol

public protocol PlayerAPI : ViewBasedAPI

Control and manage the video player instance.

  • Returns the engine used by this player instance.

    Declaration

    Swift

    var engine: PlayerEngine { get }

  • Returns current stream playback state.

    Declaration

    Swift

    var playbackState: PlaybackState? { get }

  • Returns stream current position.

    Declaration

    Swift

    var position: Float64? { get }

  • Get current overall state.

    Declaration

    Swift

    func getState() -> PlayerState

  • Triggered when something in the overall state has changed.

    Declaration

    Swift

    var onState: ((_ previous: PlayerState, _ state: PlayerState) -> Void)? { get set }

  • Set callback for current time changes at a desired rate. Rate is specified in seconds with milliseconds precision. Min: 0.1.

    Declaration

    Swift

    func onCurrentTime(rate: TimeInterval, onChange: @escaping ((Float64) -> Void))

  • Returns current duration in seconds.

    Declaration

    Swift

    func getDuration() -> TimeInterval

  • Returns the live start time in seconds since the epoch or nil if unknown or not applicable.

    Remark

    Available when player is in state PlaybackState.ready.

    Declaration

    Swift

    func getLiveStartTime() -> TimeInterval?

  • Returns the current track model.

    Declaration

    Swift

    var tracks: Tracks { get }

  • Load new player configuration.

    Declaration

    Swift

    func load(config: PlayerConfiguration)

    Parameters

    config

    Player configuration.

  • Return the currently selected video track or null if no track is active and selected.

    Declaration

    Swift

    func getVideoTrack() -> VideoTrack?

  • Return the rendition that is currently selected by ABR or manually.

    Remark

    This may return nil for streams played by PlayerEngine.apple due to a limitation of the underlying player.

    Declaration

    Swift

    func getSelectedVideoRendition() -> VideoRendition?

  • Return the currently rendered rendition.

    Declaration

    Swift

    func getRenderedVideoRendition() -> VideoRendition?

  • Return the currently selected audio track or null if no track is active and selected.

    Declaration

    Swift

    func getAudioTrack() -> AudioTrack?

  • Return the currently selected audio rendition or null if no audio track is active and selected.

    Remark

    This may return nil for streams played by PlayerEngine.apple due to a limitation of the underlying player.

    Declaration

    Swift

    func getSelectedAudioRendition() -> AudioRendition?

  • Return the currently rendered audio rendition or null if no audio track is active and selected.

    Declaration

    Swift

    func getRenderedAudioRendition() -> AudioRendition?

  • Return the currently selected text track or null if no track is active and selected.

    Declaration

    Swift

    func getTextTrack() -> TextTrack?

  • Selects the given rendition and disables ABR mode. If nil is passed, ABR becomes enabled.

    Remark

    Not availble for PlayerEngine.apple.

    Declaration

    Swift

    func setVideoRendition(_ rendition: VideoRendition?)

    Parameters

    rendition

    Video rendition.

  • Selects the given video track.

    Declaration

    Swift

    func setVideoTrack(_ track: VideoTrack)

    Parameters

    track

    Video track.

  • Selects the given audio track.

    Declaration

    Swift

    func setAudioTrack(_ track: AudioTrack)

    Parameters

    track

    Audio track.

  • Selects the given subtitles track. Passing nil disables subtitles.

    Declaration

    Swift

    func setTextTrack(_ track: TextTrack?)

  • Side-load subtitles content from a URL.

    Downloads and parses the subtitles content (if a supported format types). Creates a new subtitle track appended after any existing subtitle tracks.

    This requires the CastlabsSubtitles plugin. Subtitle tracks exist only during playback, therefore this function can only create tracks during that time-frame. The text track should define the following properties:

    • sourceUrl: Location where to download the subtitle content file.
    • format: Type of subtitle (webvtt, ttml etc).
    • language: String defined in RFC5646.

    • label: Display name of the track.

      Remark

      The player must be at least in PlaybackState.ready for this to have effect. Sideloaded subtitles will not render in Airplay and Picture in Picture modes.
      • track: Text track.
      • completionHandler: Called track has been downloaded, parsed and is ready to use.

    Declaration

    Swift

    func addTextTrack(_ track: TextTrack, completionHandler: ((CLError?) -> Void)?)

    Parameters

    track

    Text track.
    completionHandler

    Called track has been downloaded, parsed and is ready to use.

  • Returns true is manual video rendition is enabled, false if ABR is enabled.

    Declaration

    Swift

    var isAdaptationModeManual: Bool { get }

  • Initalise the AVPictureInPictureController and returns a reference of it.

    Remark

    Works only with PlayerEngine.apple. From our tests, the PiP playback becomes available on most devices when the player moves to PlaybackState.playing.

    Declaration

    Swift

    @available(tvOS 14.0, *)
func getPictureInPictureController() -> AVPictureInPictureController?

    Return Value

    An initiliazed AVPictureInPictureController object.

  • Indicates whether the player should continue the playback in the background. The default value is false.

    Besides setting this flag to true please add the UIBackgroundModes key in your app’s Info.plist file. Its value is an array that contains one or more strings that identify which background tasks your application supports. Specify the string value audio.

    Remark

    Works only for audio-only streams. Must be called before state .open.

    Declaration

    Swift

    var continueAudioPlaybackInBackground: Bool { get set }

  • A value of 1.0 (default) plays the current item at its natural rate. Setting to values lower than 1 slow down the playback; values higher than 1 speed it up.

    Remark

    Content played at playbackRate lower than 0.0 or higher than 2.0 will have audio muted.

    Remark

    Expects frame drops for high values.

    Remark

    Negative rates only work with PlayerEngine.apple. The player will use the I-Frame playlist if present otherwise it would try to play it anyways (which usually result in a sketcky playback). In both cases audio is muted.

    Declaration

    Swift

    var playbackRate: Float64 { get set }

  • The playback volume of the player instance, ranging from 0.0 through 1.0 on a linear scale. A value of 0.0 indicates silence; a value of 1.0 (the default) indicates full volume for the audio queue instance.

    Remark

    This value does not impact the device overall volume. Setting it at 1.0 (default) means: “play at the device current max volume”.

    Remark

    Must be called after the player transitions to PlaybackState.ready.

    Remark

    When used with PlayerEngine.apple, please consider this note from Apple: “Do not use this property to implement a volume slider for media playback. For that purpose, use MPVolumeView, which is customizable in appearance and provides standard media playback behaviors that users expect.

    This property is most useful on iOS to control the volume of the AVPlayer relative to other audio output, not for volume control by end users.

    Declaration

    Swift

    var playbackVolume: Float64 { get set }

  • Starts loading the content. The player will transition to PlaybackState.opening until it has enough meta-data loaded to build up a track model and then transition to PlaybackState.ready.

    Declaration

    Swift

    func open(autoplay: Bool)

    Parameters

    autoplay

    Whether the content shall start play automatically after the player reaches the PlaybackState.ready.

  • Start playback. The player will transition into PlaybackState.play and into PlaybackState.playing once the frames appear on screen. Calling this method when player is PlaybackState.idle is equivalent to open(autoplay:true).

    Declaration

    Swift

    func play()

  • Pause playback. The player will transition into PlaybackState.pausing and then into PlaybackState.paused once the frames pause on screen.

    Declaration

    Swift

    func pause()

  • Stop playback. The player will transition into PlaybackState.stopping state and then into PlaybackState.ended once the playback stops.

    Declaration

    Swift

    func stop()

  • Starts loading the content. The player will transition to PlaybackState.seeking. The player can either reach the new position in its buffer and will transition back to PlaybackState.play or PlaybackState.pausing depending on where it came from or it will first transition into PlaybackState.buffering if the requested position is not found in the current buffer.

    Declaration

    Swift

    func seek(_ time: CMTime)

    Parameters

    time

    Seeking position.

  • A collection of time ranges that the player can seek to. The ranges provided might be discontinous.

    Declaration

    Swift

    var seekableTimeRanges: [CMTimeRange] { get }

  • Minimum buffer required until playback begins (default: 6 seconds)

    Remark

    remark Works only for DASH and SmoothStreaming streams

    Declaration

    Swift

    var minPrebufferTime: Double { get set }

  • Maximum buffer size allowed (default: 60 seconds). When filled to maximum, new downloads will be paused

    Remark

    Works only for content played with player engine .castlabs

    Declaration

    Swift

    var maxPrebufferTime: Double { get set }

  • Minimum buffer required after buffer underruns (default: 12 seconds) Works only for content played with player engine .castlabs

    Declaration

    Swift

    var minRebufferTime: Double { get set }

  • Return true for live streams, false otherwise.

    Declaration

    Swift

    var isLive: Bool { get }

  • Initial live latency target - how many seconds before the live edge the playback should start (default: 10 seconds).

    Remark

    Works only when engine is PlayerEngine.castlabs.

    Declaration

    Swift

    var liveEdgeDelay: Double { get set }

  • Enable to make player attempt to move as closer to live edge as possible. Default is .disabled

    Declaration

    Swift

    var chaseLiveEdge: ChaseLiveEdge { get set }

  • Maximum time to stay behind live edge, seconds Default is 10.0

    Declaration

    Swift

    var chaseLiveEdgeCatchupThreshold: Float64 { get set }

  • Nominal time to stay behind live edge, seconds Default is 5.0

    Declaration

    Swift

    var chaseLiveEdgeCutoffThreshold: Float64 { get set }

  • Duration of HLS segment in seconds Used when live edge chasing is set to .skipFrames. Default is 10.0

    Declaration

    Swift

    var chaseLiveEdgeHLSSegmentDuration: Float64 { get set }

  • Playback speed increase Used when live edge chasing is set to .speedupPlayback Default is 1.1

    Declaration

    Swift

    var chaseLiveEdgeSpeedupRatio: Float64 { get set }

  • Get stream duration.

    Declaration

    Swift

    var duration: Float64 { get }

  • Custom Subtitle Style. It can be used to override (ignore) style properties specified in media.

    Declaration

    Swift

    var subtitlesStyle: SubtitlesStyle? { get set }
  • drm

    Returns the drm component in use by the player (if any).

    Declaration

    Swift

    var drm: DrmAPI? { get }

  • Video gravity determines how the video content is scaled or stretched within the player bounds.

    Remark

    Default value is AVLayerVideoGravityResizeAspect.

    The player layer supports the following video gravity values:

    • AVLayerVideoGravityResizeAspect: Player should preserve the video’s aspect ratio and fit the video within the bounds.
    • AVLayerVideoGravityResizeAspectFill: Player should preserve the video’s aspect ratio and fill the bounds.
    • AVLayerVideoGravityResize: Video should be stretched to fill the bounds.

    Declaration

    Swift

    var videoGravity: AVLayerVideoGravity { get set }

  • Returns underlining AVPLayer.

    Remark

    Works only with PlayerEngine.apple.

    Remark

    Should be used for debugging purpose mainly. Using this object to modify the playback may lead to unexpected and conflicting behaviour with our API.

    Declaration

    Swift

    var avPlayerInstance: AVPlayer? { get }