BMPPlayerAPI

Objective-C

@protocol BMPPlayerAPI <NSObject>

Swift

protocol PlayerAPI : NSObjectProtocol

Defines the public API of the BitmovinPlayer. See the documentation of each single API method for further information. All calls to the public player API must be done from the main thread. Calling API methods from multiple threads concurrently is not guaranteed to result in consistent and stable behavior.

  • Flag to indicate if the player is destroyed.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isDestroyed) BOOL destroyed;

    Swift

    var isDestroyed: Bool { get }

  • Returns YES if the player has been muted.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isMuted) BOOL muted;

    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 YES if the player has started playback but is currently paused.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isPaused) BOOL paused;

    Swift

    var isPaused: Bool { get }

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

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isPlaying) BOOL playing;

    Swift

    var isPlaying: Bool { get }

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

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isLive) BOOL live;

    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 configuration object of this player instance.

    Declaration

    Objective-C

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

    Swift

    var config: PlayerConfiguration { 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 BMPPlayerAPI#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 BMPPlayerAPI#maxTimeShift.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval timeShift;

    Swift

    var timeShift: TimeInterval { get set }

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

    Declaration

    Objective-C

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

    Swift

    var availableSubtitles: [SubtitleTrack] { get }

  • Returns the currently used BMPSubtitleTrack.

    Declaration

    Objective-C

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

    Swift

    var subtitle: SubtitleTrack { get }

  • Returns an array containing all available audio tracks.

    Declaration

    Objective-C

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

    Swift

    var availableAudio: [AudioTrack] { get }

  • Returns the currently used audio track.

    Declaration

    Objective-C

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

    Swift

    var audio: AudioTrack? { get }
  • ad

    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, getter=isAd) BOOL ad;

    Swift

    var isAd: Bool { get }

  • Returns true when media is played externally using AirPlay.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isAirPlayActive) BOOL airPlayActive;

    Swift

    var isAirPlayActive: Bool { get }

  • Returns true when AirPlay is available.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isAirPlayAvailable) BOOL airPlayAvailable;

    Swift

    var isAirPlayAvailable: 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: [VideoQuality] { 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: VideoQuality? { get }

    Return Value

    The currently selected video quality.

  • Get/set the playback speed of the player. Fast forward as well as slow motion is supported. Slow motion is used by values between 0 and 1, fast forward by values between 1 and 2. Values less or equal zero are ignored.

    Declaration

    Objective-C

    @property (nonatomic) float playbackSpeed;

    Swift

    var playbackSpeed: Float { get set }

  • Returns the currently used streaming technology.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BMPMediaSourceType streamType;

    Swift

    var streamType: BMPMediaSourceType { get }

  • The upper bitrate boundary in bits per second for network bandwidth consumption of the currently played source. Can be set to 0 for no limitation. The value set here is only valid for the currently played source and will not be carried over to subsequently loaded sources. Use BMPAdaptationConfiguration#maxSelectableBitrate to set a value which is persistent for all loaded sources of one BitmovinPlayer instance.

    Default value is 0.

    Declaration

    Objective-C

    @property (nonatomic) NSUInteger maxSelectableBitrate;

    Swift

    var maxSelectableBitrate: UInt { get set }

  • Get/set metadata for the currently loaded source. All existing metadata will be completely replaced by the provided metadata when the setter is called. For example, if sourceMetadata is an empty object, all existing source metadata will be deleted. Setting new metadata results in a BMPSourceMetadataChanged event to be fired.

    Declaration

    Objective-C

    @property (nonatomic) NSDictionary<NSString *, id<NSObject, NSCopying>> *_Nonnull sourceMetadata;

    Swift

    var sourceMetadata: [String : NSCopying & NSObjectProtocol] { 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 }

  • Provides access to the buffer API.

    Declaration

    Objective-C

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

    Swift

    var buffer: BufferApi { get }

  • Sets up player instance with the given configuration.

    Declaration

    Objective-C

    - (void)setup:(nonnull BMPPlayerConfiguration *)configuration;

    Swift

    func setup(configuration: PlayerConfiguration)

    Parameters

    configuration

    The configuration used to setup the player

  • Deprecated

    Use PlayerApi#load(sourceItem:) instead.

    Loads a new media source.

    Declaration

    Objective-C

    - (void)load:(nonnull BMPSourceConfiguration *)sourceConfiguration;

    Swift

    func load(sourceConfiguration: SourceConfiguration)

    Parameters

    sourceConfiguration

    The source configuration used to set a new media source.

  • Loads a new media source.

    Declaration

    Objective-C

    - (void)loadSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func load(sourceItem: SourceItem)

    Parameters

    sourceItem

    The source item used to set a new media source.

  • Starts preloading the content of the currently loaded source.

    Declaration

    Objective-C

    - (void)preload;

    Swift

    func preload()

  • Unloads the current video source.

    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 SourceItem#add(subtitleTrack:) instead.

    Adds a new external subtitle file. The BMPSubtitleTrack is only added to the available tracks, but is not set active. Use BMPPlayerAPI#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: SubtitleTrack)

    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 BMPPlayerAPI#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 BMPPlayerAPI#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 BMPPlayerAPI#availableAudio.

    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 a certain time, or nil if there is no thumbnail available. Requires a configured BMPThumbnailTrack in the corresponding BMPSourceItem.

    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 if no thumbnail is available.

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

    Declaration

    Objective-C

    - (void)skipAd;

    Swift

    func skipAd()

  • Schedules an ad for playback.

    Declaration

    Objective-C

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

    Swift

    func scheduleAd(adItem: AdItem)

    Parameters

    adItem

    the ad item to be scheduled.

  • Shows the AirPlay playback target picker.

    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.