BMPPlayer
Objective-C
@protocol BMPPlayer <NSObject, BMPPlayerEventHandler, BMPRemoteControlApi>
Swift
protocol Player : PlayerEventHandler, RemoteControlApi
Loads, controls and renders audio and video content represented through Source
s. A player instance can be created
via the PlayerFactory.create
function and will idle until one or more Source
s 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. Event
s are divided
into PlayerEvent
and SourceEvent
, depending on if they are specific to a player session or a source. While
SourceEvent
s 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 byPlayer#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 returnnil
.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 }
-
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 }
-
Indicates whether visual output is obscured by the
Player
due to insufficient external protection for the activeSource
.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 theSource
. Current device configuration includes connection to an external display with a High-Definition Multimedia Interface (HDMI) cable. TheSource
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 activeSource
does not require external protection or if the device configuration sufficiently protects the activeSource
, the value of this property will befalse
.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. NoPlaybackFinishedEvent
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 multiplePlayer.load
calls, useAdaptationConfig.maxSelectableBitrate
.Default value is
0
.Note
Has no effect if there is no source loaded.Note
Does not apply to sources added later viaPlayer.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
Source
s into the player. The first source in thePlaylistConfig
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
Source
s 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 configuredThumbnailTrack
in the correspondingSourceConfig
.Note
This function returnsnil
- If there is no active source
- If the thumbnails were not loaded yet
- If there are no
ThumbnailTrack
provided in the correspondingSourceConfig
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 settingImaAdvertisingConfig.preferredUiType
toImaUiType.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.
Declaration
Objective-C
- (NSTimeInterval)currentTime:(BMPTimeMode)timeMode;
Swift
func currentTime(_ timeMode: TimeMode) -> TimeInterval
Parameters
timeMode
to specify if an absolute unix timestamp or an 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.