Permalink
Cannot retrieve contributors at this time
brightcove-player-sdk-ios/ios/dynamic/BrightcovePlayerSDK.framework/Headers/BCOVPlaybackSession.h
Go to file// | |
// BCOVPlaybackSession.h | |
// BrightcovePlayerSDK | |
// | |
// Copyright (c) 2021 Brightcove, Inc. All rights reserved. | |
// License: https://accounts.brightcove.com/en/terms-and-conditions | |
// | |
#import <AVFoundation/AVFoundation.h> | |
#import <Foundation/Foundation.h> | |
@class BCOVSessionProviderExtension; | |
@class BCOVSource; | |
@class BCOVVideo; | |
/** | |
* The video loaded successfully and is ready to play. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventReady; | |
/** | |
* The video failed to load. The event properties will contain the underlying error | |
* keyed by kBCOVPlaybackSessionEventKeyError. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventFail; | |
/** | |
* The video has been set to play mode, and the video will play when it is ready | |
* and has buffer. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventPlay; | |
/** | |
* The video has been set to pause mode, and the video will pause. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventPause; | |
/** | |
* A request to play the current video has been made. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventPlayRequest; | |
/** | |
* A request to pause the current video has been made. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventPauseRequest; | |
/** | |
* The video failed during playback and was unable to recover, possibly due to a | |
* network error. The event properties will contain the underlying error keyed | |
* by kBCOVPlaybackSessionEventKeyError. | |
* | |
* It may be possible to recover from this error once the network has recovered, | |
* by using the -[BCOVPlaybackController resumeVideoAtTime:withAutoPlay:] method. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventFailedToPlayToEndTime; | |
/** | |
* A call to -[BCOVPlaybackController resumeVideoAtTime:withAutoPlay:] was made | |
* and the player is attempting to reload the video. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventResumeBegin; | |
/** | |
* A call to -[BCOVPlaybackController resumeVideoAtTime:withAutoPlay:] was made | |
* and the player was able to reload the video. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventResumeComplete; | |
/** | |
* A call to -[BCOVPlaybackController resumeVideoAtTime:withAutoPlay:] was made | |
* and the player was unable to reload the video. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventResumeFail; | |
/** | |
* The end of the video has been reached. This event will come after any post-roll | |
* ads. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventEnd; | |
/** | |
* Playback of the video has stalled. When the video recovers, | |
* kBCOVPlaybackSessionLifecycleEventPlaybackRecovered will be sent. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventPlaybackStalled; | |
/** | |
* Playback has recovered after being stalled. This event will come after | |
* kBCOVPlaybackSessionLifecycleEventPlaybackStalled. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventPlaybackRecovered; | |
/** | |
* The playback buffer is empty. This will occur when the video initially loads, | |
* after a seek occurs, and when playback stops because of a slow or disabled | |
* network. When the buffer is full enough to start playback again, | |
* kBCOVPlaybackSessionLifecycleEventPlaybackLikelyToKeepUp will be sent. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventPlaybackBufferEmpty; | |
/** | |
* After becoming empty, this event is sent when the playback buffer has filled | |
* enough that it should be able to keep up with playback. This event will come after | |
* kBCOVPlaybackSessionLifecycleEventPlaybackBufferEmpty. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventPlaybackLikelyToKeepUp; | |
/** | |
* The session will be disposed of by the player. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventTerminate; | |
/** | |
* A generic error has occurred. The event properties may contain the underlying | |
* error keyed by kBCOVPlaybackSessionEventKeyError. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventError; | |
/** | |
* The video has entered an ad sequenece. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventAdSequenceEnter; | |
/** | |
* The video has exited an ad sequenece. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventAdSequenceExit; | |
/** | |
* The video has entered an ad. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventAdEnter; | |
/** | |
* The video has exited an ad. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventAdExit; | |
/** | |
* A progress event for the currently playing ad. | |
* Information about the current ad may be found in the properties dictionary. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventAdProgress; | |
/** | |
* The current ad has been paused. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventAdPause; | |
/** | |
* The current ad has been resumed. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventAdResume; | |
/** | |
* The current ad has been skipped. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionLifecycleEventAdSkipped; | |
/** | |
* The key for the error in the Event properties. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionEventKeyError; | |
/** | |
* The key for the didPassCuePoints: payload for the progress interval | |
* immediately preceding the cue points for which the payload was received. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionEventKeyPreviousTime; | |
/** | |
* The key for the didPassCuePoints: payload for the progress interval on or | |
* immediately after the cue points for which the payload was received. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionEventKeyCurrentTime; | |
/** | |
* The key for the didPassCuePoints: payload for the BCOVCuePointCollection of cue | |
* points for which the payload was received. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionEventKeyCuePoints; | |
/** | |
* Error domain for the SDK. | |
*/ | |
extern NSString * const kBCOVPlaybackSessionErrorDomain; | |
/** | |
* The video failed to load. | |
*/ | |
extern const NSInteger kBCOVPlaybackSessionErrorCodeLoadFailed; | |
/** | |
* The video failed during playback and was unable to recover, possibly due to a | |
* network error. | |
*/ | |
extern const NSInteger kBCOVPlaybackSessionErrorCodeFailedToPlayToEnd; | |
/** | |
* No playable Source was available for this Video. | |
*/ | |
extern const NSInteger kBCOVPlaybackSessionErrorCodeNoPlayableSource; | |
/** | |
* A playback session represents the playback of a single video. The session | |
* provides a single point of access for everything related to the playback | |
* experience for that video: the video and source selected for playback, the | |
* player within which the playback occurs, and events that occur during the | |
* playback session. Playback sessions are never reused for multiple videos | |
* (even separate enqueueings of the same video). | |
*/ | |
@protocol BCOVPlaybackSession <NSObject> | |
/** | |
* The video whose playback this session represents. | |
*/ | |
@property (nonatomic, readonly, copy) BCOVVideo *video; | |
/** | |
* The source in `self.video` this session uses to load content. | |
*/ | |
@property (nonatomic, readonly, copy) BCOVSource *source; | |
/** | |
* The player this session uses to present content. | |
*/ | |
@property (nonatomic, readonly, strong) AVPlayer *player; | |
/** | |
* The layer that hosts the visible video output. | |
*/ | |
@property (nonatomic, readonly, strong) AVPlayerLayer *playerLayer; | |
/** | |
* The AVMediaSelectionGroup of audible media selection options of the AVAsset of | |
* the AVPlayerItem of the AVPlayer of the current BCOVPlaybackSession. | |
* | |
* The AVMediaSelectionGroup is unsorted and can contain un-playable options. Use the | |
* +playableMediaSelectionOptionsFromArray: class method of AVMediaSeledtionGroup | |
* to return the list of playable media options. AVMediaSelectionGroup provides filtering | |
* methods to, for example, order the list of options according to the user’s | |
* language preferences. | |
*/ | |
@property (nonatomic, readonly) AVMediaSelectionGroup *audibleMediaSelectionGroup; | |
/** | |
* The selected audible media option. When setting this property, if | |
* selectedAudibleMediaOption is not a member of the AVMediaSelectionGroup of the | |
* current BCOVPlaybackSession’s AVPlayer, no change in presentation state will | |
* occur. | |
*/ | |
@property (nonatomic, readwrite) AVMediaSelectionOption *selectedAudibleMediaOption; | |
/** | |
* The AVMediaSelectionGroup of legible media selection options of the AVAsset of | |
* the AVPlayerItem of the AVPlayer of the current BCOVPlaybackSession. | |
* | |
* The AVMediaSelectionGroup is unsorted and can contain un-playable options. Use the | |
* +playableMediaSelectionOptionsFromArray: class method of AVMediaSelectionGroup | |
* to return the list of playable media options. AVMediaSelectionOption provides filtering | |
* methods to, for example, exclude forced subtitles from the legible options that are | |
* suitable to offer in a selection UI. | |
*/ | |
@property (nonatomic, readonly) AVMediaSelectionGroup *legibleMediaSelectionGroup; | |
/** | |
* The selected legible media option. When setting this property, if | |
* selectedLegibleMediaOption is not a member of the AVMediaSelectionGroup of the | |
* current BCOVPlaybackSession’s AVPlayer, no change in presentation state will | |
* occur. If selectedLegibleMediaOption is set to nil and the allowsEmptySelecton | |
* property of the AVMediaSelectionGroup of the current BCOVPlaybackSession's | |
* AVPlayer is YES, all media selection options in the group will be deselected. | |
*/ | |
@property (nonatomic, readwrite) AVMediaSelectionOption *selectedLegibleMediaOption; | |
/** | |
* The session provider extension for this session. The default value is nil. | |
* | |
* If a BCOVPlaybackSessionProvider is used that needs to expose plugin specific functionality, | |
* this property will return a BCOVSessionProviderExtension. | |
*/ | |
@property (nonatomic, readonly, strong) BCOVSessionProviderExtension *providerExtension; | |
/** | |
* Selects the audible media option in the audible media selection group that | |
* best matches the current AVPlayerItem's automatic selection criteria. | |
*/ | |
- (void)selectAudibleMediaOptionAutomatically; | |
/** | |
* Selects the legible media option in the legible media selection group which | |
* best matches the current AVPlayerItem's automatic selection criteria. | |
*/ | |
- (void)selectLegibleMediaOptionAutomatically; | |
/** | |
* Returns a descriptive display string for the audible selection option. The | |
* display name string is the stringValue of the option appended with the option | |
* locale if the locale differs from the stringValue. | |
* | |
* @param option A specific audio media selection option from the AVMediaSelectionGroup | |
*/ | |
- (NSString *)displayNameFromAudibleMediaSelectionOption:(AVMediaSelectionOption *)option; | |
/** | |
* Returns a descriptive display string for the legible selection option. The | |
* display name string is the stringValue of the option appended with the option | |
* locale if the locale differs from the stringValue. Legible option names are | |
* further appended with "SDH" when accessibility characteristics are present. | |
* | |
* @param option A specific legible media selection option from the AVMediaSelectionGroup | |
*/ | |
- (NSString *)displayNameFromLegibleMediaSelectionOption:(AVMediaSelectionOption *)option; | |
/** | |
* Terminates this playback session, indicating readiness for a new session to | |
* be dequeued. A terminated playback session should be discarded immediately. | |
* | |
* In a typical configuration using a BCOVPlaybackController, there is no need | |
* to call this method directly. Methods on the controller are the preferred | |
* mechanism for advancing to the next playback session. However, playback | |
* session provider configurations which do not use a BCOVPlaybackController | |
* may need to invoke this method to advance the queue. | |
*/ | |
- (void)terminate; | |
@end | |
/** | |
* A lifecycle event for a playback session. | |
*/ | |
@interface BCOVPlaybackSessionLifecycleEvent : NSObject <NSCopying> | |
/** | |
* This lifecycle event's type. | |
*/ | |
@property (nonatomic, readonly) NSString *eventType; | |
/** | |
* Contextual information related to this event instance. | |
*/ | |
@property (nonatomic, readonly) NSDictionary *properties; | |
/** | |
* Designated initializer. Returns an event with the specified type and properties. | |
* | |
* @param eventType Type of the event. | |
* @param properties Properties of the event | |
* @return Initialized event. | |
*/ | |
- (instancetype)initWithEventType:(NSString *)eventType properties:(NSDictionary *)properties; | |
/** | |
* Determines the equality of the events. | |
* | |
* @param event Event to check against. | |
* @return Returns YES if the events are equal and NO if the events are no equal. | |
*/ | |
- (BOOL)isEqualToPlaybackSessionLifecycleEvent:(BCOVPlaybackSessionLifecycleEvent *)event; | |
/** | |
* Returns a playback session lifecycle event of the specified type with no | |
* properties. | |
* | |
* @param eventType The event type of the lifecycle event to return. | |
* @return The playback session lifecycle event of the specified type. | |
*/ | |
+ (instancetype)eventWithType:(NSString *)eventType; | |
@end | |
/** | |
* A BCOVPlaybackSessionProvider will provide plugin specific functionality by | |
* adding methods to this object via categories. | |
*/ | |
@interface BCOVSessionProviderExtension : NSObject | |
@end |