BMPPlayer

Objective-C

@protocol BMPPlayer <NSObject, BMPPlayerEventHandler, BMPRemoteControlApi>

Swift

protocol Player : PlayerEventHandler, RemoteControlApi

Loads, controls and renders audio and video content represented through Sources. A player instance can be created via the PlayerFactory.create function and will idle until one or more Sources are loaded. Once load is called, the player becomes active and initiates necessary downloads to start playback of the loaded source(s).

In case multiple sources were loaded into the player, Source.isActive identifies which source is currently active in the player (i.e. being played back). Only one source can be active at any time and API calls on the player will act on that source. More information on how to manage multiple sources can be found on the PlaylistApi.

The player emits events during a player session. See PlayerEventHandler on how to subscribe to events. Events are divided into PlayerEvent and SourceEvent, depending on if they are specific to a player session or a source. While SourceEvents are naturally emitted from a source, they are also emitted from the player for the active source. This allows for all event handling to be done through the player in case only a single source is loaded, enabling the same workflows as on v2 of the Bitmovin Player SDK, where it was not possible to load multiple sources and where each event was a PlayerEvent.

The player implements the RemoteControlApi, which offers the ability to connect to a cast-compatible device, allowing remote playback of the loaded sources.

By default, a player instance does not provide any UI components. To use the default Bitmovin Player Web UI, a player instance can be attached to a PlayerView. The PlayerView already comes with a Layer to render video into, the Bitmovin Player Web UI and handling for standard UI use-cases. If a custom UI is preferred, an AVPlayerLayer or an AVPlayerViewController can be registered via registerPlayerLayer / registerPlayerViewController. See PlayerView for more details.

  • Flag to indicate if the player is destroyed.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isDestroyed;

    Swift

    var isDestroyed: Bool { get }

  • Returns true if the player is muted.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isMuted;

    Swift

    var isMuted: Bool { get }

  • 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.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger volume;

    Swift

    var volume: Int { get set }

  • Returns true if the player has started playback but is currently paused.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isPaused;

    Swift

    var isPaused: Bool { get }

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

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isPlaying;

    Swift

    var isPlaying: Bool { get }

  • Returns true if the displayed video is a live stream.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isLive;

    Swift

    var isLive: Bool { get }

  • Returns the total duration in seconds of the current video or INFINITY if it’s a live stream.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSTimeInterval duration;

    Swift

    var duration: TimeInterval { get }

  • 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.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSTimeInterval currentTime;

    Swift

    var currentTime: TimeInterval { get }

  • Returns the current player config object of this player instance.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nonnull) BMPPlayerConfig *config;

    Swift

    var config: BMPPlayerConfig { get }

  • Returns the currently active source or null if no source is active.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) id<BMPSource> source;

    Swift

    var source: (any BMPSource)? { get }

  • Returns the limit in seconds for time shift. Is either negative or 0. Is applicable for live streams only.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSTimeInterval maxTimeShift;

    Swift

    var maxTimeShift: TimeInterval { get }

  • When set, shifts the time to the given offset in seconds from the live edge. Has to be within Player#maxTimeShift (which is a negative value) and 0. Only works in live streams. The offset can be positive and is then interpreted as a UNIX timestamp in seconds. The value has to be within the timeShift window, as specified by Player#maxTimeShift.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval timeShift;

    Swift

    var timeShift: TimeInterval { get set }

  • Returns an array containing SubtitleTrack objects for all available subtitle tracks.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSArray<BMPSubtitleTrack *> *_Nonnull availableSubtitles;

    Swift

    var availableSubtitles: [BMPSubtitleTrack] { get }

  • Returns the currently used SubtitleTrack.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BMPSubtitleTrack *_Nonnull subtitle;

    Swift

    var subtitle: BMPSubtitleTrack { get }

  • Returns an array containing all available audio tracks.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSArray<BMPAudioTrack *> *_Nonnull availableAudio;

    Swift

    var availableAudio: [BMPAudioTrack] { get }

  • Returns the currently used audio track.

    @Note: Before the Source finished loading (SourceLoadedEvent) this method will always return nil.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) BMPAudioTrack *audio;

    Swift

    var audio: BMPAudioTrack? { get }

  • Returns true while an ad is played back or content playback has been paused for ad playback, false otherwise.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isAd;

    Swift

    var isAd: Bool { get }

  • Returns true when media is played externally using AirPlay. Only available on iOS. Result in a no-op on tvOS.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isAirPlayActive;

    Swift

    var isAirPlayActive: Bool { get }

  • Deprecated

    Use allowsAirPlay instead.

    Returns true when AirPlay is available.

    • Only available on iOS. Result in a no-op on tvOS.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isAirPlayAvailable;

    Swift

    var isAirPlayAvailable: Bool { get }

  • Get/set whether AirPlay is allowed.

    Default value is the configured value from RemoteControlConfig.allowsAirPlay.

    Note

    Disallowing AirPlay will also visually disable the AirPlay target selector button, which additionally serves selecting an audio output. Audio output can still be changed via the Control Center.

    Note

    Only supported on iOS. Results in a no-op on tvOS.

    Declaration

    Objective-C

    @property (nonatomic) BOOL allowsAirPlay;

    Swift

    var allowsAirPlay: Bool { get set }

    Return Value

    true when AirPlay is allowed.

  • Indicates whether visual output is obscured by the Player due to insufficient external protection for the active Source.

    A Source that incorporates copy protection or other forms of security may have its visual content obscured if the current device configuration does not meet the requirements for protecting the Source. Current device configuration includes connection to an external display with a High-Definition Multimedia Interface (HDMI) cable. The Source may not support playback on an external display, or the HDMI cable may provide insufficient protection due to a lower High-bandwidth Digital Content Protection (HDCP) version.

    Note that the external protection requirements of the active Source determines the value of this property. These requirements are ingrained in the content itself, and cannot be externally specified. If the active Source does not require external protection or if the device configuration sufficiently protects the active Source, the value of this property will be false.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isOutputObscured;

    Swift

    var isOutputObscured: Bool { get }

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

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSArray<BMPVideoQuality *> *_Nonnull availableVideoQualities;

    Swift

    var availableVideoQualities: [BMPVideoQuality] { get }

    Return Value

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

  • Returns the currently selected video quality.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) BMPVideoQuality *videoQuality;

    Swift

    var videoQuality: BMPVideoQuality? { get }

    Return Value

    The currently selected video quality.

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

    Note

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

    Note

    Negative values are ignored during Casting.

    Note

    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. No PlaybackFinishedEvent will be emitted in this case.

    Declaration

    Objective-C

    @property (nonatomic) float playbackSpeed;

    Swift

    var playbackSpeed: Float { get set }

  • The maximum bitrate in bits per second for network bandwidth consumption of the current playlist’s sources. Set to 0 for no limitation. This value only applies to the sources in the currently loaded playlist and will not affect any future playlists or sources. To set a persistent value across multiple Player.load calls, use AdaptationConfig.maxSelectableBitrate.

    Default value is 0.

    Note

    Has no effect if there is no source loaded.

    Note

    Does not apply to sources added later via Player.playlist.add(source:).

    Declaration

    Objective-C

    @property (nonatomic) NSUInteger maxSelectableBitrate;

    Swift

    var maxSelectableBitrate: UInt { get set }

  • Returns the currently playing video frame rate in units of frames per second.

    Declaration

    Objective-C

    @property (nonatomic, readonly) float currentVideoFrameRate;

    Swift

    var currentVideoFrameRate: Float { get }

  • The BufferApi for interactions regarding the buffer.

    Declaration

    Objective-C

    @property (nonatomic, readonly) id<BMPBufferApi> _Nonnull buffer;

    Swift

    var buffer: any BufferApi { get }

  • The PlaylistApi for interactions regarding the playlist.

    Declaration

    Objective-C

    @property (nonatomic, readonly) id<BMPPlaylistApi> _Nonnull playlist;

    Swift

    var playlist: any BMPPlaylistApi { get }

  • The SharePlayApi for interactions regarding Apple SharePlay. This API is only available for usage from Swift.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BMPSharePlayApi *_Nonnull sharePlay;

    Swift

    var sharePlay: BMPSharePlayApi { get }

  • The _PlayerModulesApi for interactions regarding modules.

    Declaration

    Objective-C

    @property (nonatomic, readonly) _BMPPlayerModulesApi *_Nonnull _modules;

    Swift

    var _modules: _BMPPlayerModulesApi { get }

  • The PlayerEventsApi for interactions regarding event publishers. This API is only available for usage from Swift.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BMPPlayerEventsApi *_Nonnull events;

    Swift

    var events: BMPPlayerEventsApi { get }

  • The LatencyApi for interactions regarding latency specific APIs for live-streams.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BMPLatencyApi *_Nonnull latency;

    Swift

    var latency: BMPLatencyApi { get }

  • Loads a new Source based on the provided SourceConfig into the player.

    Declaration

    Objective-C

    - (void)loadSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func load(sourceConfig: BMPSourceConfig)

    Parameters

    sourceConfig

    The source config used to set a new media source.

  • Loads a new Source into the player.

    Declaration

    Objective-C

    - (void)loadSource:(nonnull id<BMPSource>)source;

    Swift

    func load(source: any BMPSource)

    Parameters

    source

    The source used to set a new media source.

  • Loads a playlist containing multiple Sources into the player. The first source in the PlaylistConfig becomes active immediately.

    Declaration

    Objective-C

    - (void)loadPlaylistConfig:(nonnull BMPPlaylistConfig *)playlistConfig;

    Swift

    func load(playlistConfig: BMPPlaylistConfig)

    Parameters

    playlistConfig

    The playlist config used to set a queue of media sources.

  • Unloads all Sources in the player.

    Declaration

    Objective-C

    - (void)unload;

    Swift

    func unload()

  • Destroys the player and releases all allocated resources.

    The player instance must not be used after calling this method.

    Declaration

    Objective-C

    - (void)destroy;

    Swift

    func destroy()

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

    Declaration

    Objective-C

    - (void)play;

    Swift

    func play()

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

    Declaration

    Objective-C

    - (void)pause;

    Swift

    func pause()

  • 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.

    Declaration

    Objective-C

    - (void)seek:(NSTimeInterval)time;

    Swift

    func seek(time: TimeInterval)

    Parameters

    time

    The time to seek to.

  • Mutes the player if an audio track is available. Has no effect if the player is already muted.

    Declaration

    Objective-C

    - (void)mute;

    Swift

    func mute()

  • Unmutes the player it it is already muted. Has no effect if the player is not muted.

    Declaration

    Objective-C

    - (void)unmute;

    Swift

    func unmute()

  • Deprecated

    Use SourceConfig#add(subtitleTrack:) instead.

    Adds a new external subtitle file. The BMPSubtitleTrack is only added to the available tracks, but is not set active. Use BMPPlayer#subtitle: to active it. If the ID already exists, the existing BMPSubtitleTrack is overwritten with the new one.

    Declaration

    Objective-C

    - (void)addSubtitle:(nonnull BMPSubtitleTrack *)subtitleTrack;

    Swift

    func addSubtitle(track subtitleTrack: BMPSubtitleTrack)

    Parameters

    subtitleTrack

    The BMPSubtitleTrack to be added to the available subtitles.

  • Removes the existing BMPSubtitleTrack with the track ID specified by subtitleTrackID. If the track is currently active, it will be deactivated and then removed. If no BMPSubtitleTrack with the given ID exists, the call will be ignored. The BMPSubtitleTrack is removed from the available tracks, use BMPPlayer#subtitle:nil to disable an active BMPSubtitleTrack.

    Declaration

    Objective-C

    - (void)removeSubtitle:(nonnull NSString *)subtitleTrackID;

    Swift

    func removeSubtitle(trackIdentifier subtitleTrackID: String)

    Parameters

    subtitleTrackID

    The ID of the BMPSubtitleTrack to be removed.

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

    Declaration

    Objective-C

    - (void)setSubtitleWithIdentifier:(nullable NSString *)subtitleTrackID;

    Swift

    func setSubtitle(trackIdentifier subtitleTrackID: String?)

    Parameters

    subtitleTrackID

    The id of the BMPSubtitleTrack which should be set.

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

    @Note: Before the Source finished loading (SourceLoadedEvent) calling this method will result in a no-op.

    Declaration

    Objective-C

    - (void)setAudioWithIdentifier:(nonnull NSString *)audioTrackID;

    Swift

    func setAudio(trackIdentifier audioTrackID: String)

    Parameters

    audioTrackID

    The ID of the BMPAudioTrack which should be set.

  • Returns the thumbnail image for the active Source at a certain time. Requires a configured ThumbnailTrack in the corresponding SourceConfig.

    Note

    This function returns nil
    • If there is no active source
    • If the thumbnails were not loaded yet
    • If there are no ThumbnailTrack provided in the corresponding SourceConfig

    • If there is no thumbnail available at the provided time

    Declaration

    Objective-C

    - (nullable BMPThumbnail *)thumbnailForTime:(NSTimeInterval)time;

    Swift

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

    Parameters

    time

    The time for which the thumbnail should be returned.

    Return Value

    An instance of BMPThumbnail for the given time, or nil.

  • Skips the current ad. A successful skip is signaled via an AdSkippedEvent.

    Has no effect if the current ad is not skippable or if no ad is being played back.

    ## Limitations Programmatically skipping the current ad is not supported for ads of type AdSourceType.ima if IMA renders the ‘Skip ad’ button. In this case, ad skipping can only be initiated by clicking the ‘Skip ad’ button on the UI.

    For ads of type AdSourceType.ima the ‘Skip ad’ button can be hidden by setting ImaAdvertisingConfig.preferredUiType to ImaUiType.disabled on supported ads.

    Declaration

    Objective-C

    - (void)skipAd;

    Swift

    func skipAd()

  • Schedules an ad for playback.

    Note

    Calling this API has no effect when the player has no active source.

    Declaration

    Objective-C

    - (void)scheduleAd:(nonnull BMPAdItem *)adItem;

    Swift

    func scheduleAd(adItem: BMPAdItem)

    Parameters

    adItem

    the ad item to be scheduled.

  • Shows the AirPlay playback target picker. Only available on iOS. Result in a no-op on tvOS.

    Declaration

    Objective-C

    - (void)showAirPlayTargetPicker;

    Swift

    func showAirPlayTargetPicker()

  • 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 it can be specified if an absolute unix timestamp or a value relative to the playback start should be returned.

    Note

    During a casting session, with a live stream, passing .absoluteTime returns an approximated unix timestamp value. This is because the Cast SDK does not offer access to precise timestamp-based timing information.

    Declaration

    Objective-C

    - (NSTimeInterval)currentTime:(BMPTimeMode)timeMode;

    Swift

    func currentTime(_ timeMode: TimeMode) -> TimeInterval

    Parameters

    timeMode

    to specify if an absolute unix timestamp or a relative time should be returned.

  • Registers the internal AVPlayer instance to an existing AVPlayerLayer. Calling this method has no effect if the AVPlayer instance is already registered on the given playerLayer.

    Declaration

    Objective-C

    - (void)registerPlayerLayer:(nonnull AVPlayerLayer *)playerLayer;

    Swift

    func register(_ playerLayer: AVPlayerLayer)

    Parameters

    playerLayer

    a AVPlayerLayer instance to which the internal AVPlayer instance should be assigned.

  • Unregisters the internal AVPlayer instance from an existing AVPlayerLayer.

    Declaration

    Objective-C

    - (void)unregisterPlayerLayer:(nonnull AVPlayerLayer *)playerLayer;

    Swift

    func unregisterPlayerLayer(_ playerLayer: AVPlayerLayer)

    Parameters

    playerLayer

    a AVPlayerLayer instance from which the internal AVPlayer instance should be unregistered.

  • Registers the internal AVPlayer instance to an existing AVPlayerViewController. Calling this method has no effect if the AVPlayer instance is already registered on the given playerViewController.

    Declaration

    Objective-C

    - (void)registerPlayerViewController:
    (nonnull AVPlayerViewController *)playerViewController;

    Swift

    func register(_ playerViewController: AVPlayerViewController)

    Parameters

    playerViewController

    a AVPlayerViewController instance to which the internal AVPlayer instance should be assigned.

  • Unregisters the internal AVPlayer instance from an existing AVPlayerViewController.

    Declaration

    Objective-C

    - (void)unregisterPlayerViewController:
    (nonnull AVPlayerViewController *)playerViewController;

    Swift

    func unregisterPlayerViewController(_ playerViewController: AVPlayerViewController)

    Parameters

    playerViewController

    a AVPlayerViewController instance from which the internal AVPlayer instance should be unregistered.

  • Registers the container for displaying ads.

    Declaration

    Objective-C

    - (void)registerAdContainer:(nonnull UIView *)adContainer;

    Swift

    func registerAdContainer(_ adContainer: UIView)

    Parameters

    adContainer

    the container view which should contain the rendered ads.

  • Sets subtitle styles on the current AVPlayerItem.

    Declaration

    Objective-C

    - (void)setSubtitleStyles:(nullable NSArray<AVTextStyleRule *> *)subtitleStyles;

    Swift

    func setSubtitleStyles(_ subtitleStyles: [AVTextStyleRule]?)

    Parameters

    subtitleStyles

    The subtitle styles which should be set

  • Checks the possibility to play the media at specified playback speed.

    Declaration

    Objective-C

    - (BOOL)canPlayAtPlaybackSpeed:(float)playbackSpeed;

    Swift

    func canPlay(atPlaybackSpeed playbackSpeed: Float) -> Bool

    Parameters

    playbackSpeed

    The playback speed to check.