BCOVPlaybackFacade.h

//
// BCOVPlaybackFacade.h
// BCOVPlayerSDK
//
// Copyright (c) 2013 Brightcove, Inc. All rights reserved.
// License: https://accounts.brightcove.com/en/terms-and-conditions
//

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import <AVFoundation/AVFoundation.h>

#import "BCOVCatalogService.h"
#import "BCOVPlaybackSession.h"


@protocol BCOVPlaybackController;
@protocol BCOVPlaybackFacadeDelegate;
@protocol BCOVPlaybackQueue;


/**
 * A high-level facade which provides a configured playback queue, playback
 * controller, and any other objects needed for basic video playback use cases.
 * A playback facade should be obtained from the shared Player SDK Manager
 * object. It is safe for multiple instances of BCOVPlaybackFacade to exist
 * simultaneously. Each facade will be responsible for loading its own
 * enqueued videos and exposing playback functionality via its own playback
 * controller.
 */
@protocol BCOVPlaybackFacade <NSObject>

@property (nonatomic, assign) id<BCOVPlaybackFacadeDelegate> delegate;

/**
 * Specifies whether the built-in video controls are enabled.
 *
 * @return Whether the built-in video controls are enabled.
 */
@property (nonatomic, assign, getter = isControlsEnabled) BOOL controlsEnabled;

/**
 * Returns a UIView to present playback in a view hierarchy. The view is reused
 * across all playback sessions managed by this facade.
 *
 * @return A UIView to present playback in a view hierarchy.
 */
@property (nonatomic, readonly, strong) UIView *view;

/**
 * Instructs this instance to advance this facade's queue, dequeueing a new
 * playback session for delivery on the queue's `playbackSessions` signal.
 * This may occur asynchronously.
 */
- (void)advanceToNext;

/**
 * Instructs this instance to advance the queue, and then play the dequeued
 * session. The session will be delivered via the `playbackSessions` signal.
 * Dequeueing may occur asynchronously, so this method waits for the session to
 * dequeue before playing it.
 */
- (void)advanceToNextAndPlay;

/**
 * Instructs this facade to play the session most recently dequeued and
 * delivered to its playback controller. If no session has been dequeued yet,
 * this method has no effect; use `-advanceToNextAndPlay` instead.
 */
- (void)play;

/**
 * Instructs this instance to pause the current session's content. If the
 * content is already paused, or if no content is playing, this method has no
 * effect.
 */
- (void)pause;

/**
 * Specifies the data source from which this instance will obtain
 * BCOVVideos for playback. Note that setting a new data source will not
 * automatically send a new playback session on `playbackSessions`; use
 * `-advanceToNext` to send a playback session for the first video in the
 * new data source. The reason for this behavior is to allow a new data source
 * to be specified while content is in the midst of playback.
 *
 * The data source is enumerated immediately upon being set, and each BCOVVideo
 * is defensively copied into this queue.
 *
 * @param videos The source of BCOVVideo objects from which this instance
 * should construct a queue for playback. This value is enumerated immediately,
 * and its elements are copied.
 */
- (void)setVideos:(id<NSFastEnumeration>)videos;

/**
 * The playback controller managed by this facade. Most of the basic
 * functionality of this playback controller is available in this facade's API.
 */
@property (nonatomic, readonly, strong) id<BCOVPlaybackController> controller;

/**
 * The playback queue managed by this facade. Most of the basic functionality
 * of this playback queue is available in this facade's API.
 */
@property (nonatomic, readonly, strong) id<BCOVPlaybackQueue> queue;

@end


/**
 * Methods which may be implemented for delegates of the playback facade. As
 * the facade encapsulates functionality of the playback queue and playback
 * controller, the playback facade delegate protocol offers a simplified API
 * for responding to the various changes and playback events in the playback
 * sessions generated by that queue and played by that controller. If you are
 * comfortable using ReactiveCocoa's signal API, the signal methods offered by
 * BCOVPlaybackSession offer the same or more functionality, and with better
 * flexibility. This delegate is intended for clients who do not wish to use
 * signals directly.
 */
@protocol BCOVPlaybackFacadeDelegate <NSObject>

@optional

/**
 * Called when the facade's playback queue dequeues a new playback session,
 * which happens when `-advanceToNext` or `-advanceToNextAndPlay` are called.
 * When a delegate is set on a playback facade, this method is called with
 * the most recently dequeued playback session (if one has been dequeued).
 *
 * @param facade The playback facade whose queue dequeued the session.
 * @param session The playback session that was most recently advanced.
 */
- (void)playbackFacade:(id<BCOVPlaybackFacade>)facade didAdvanceToPlaybackSession:(id<BCOVPlaybackSession>)session;

/**
 * Called when a playback session's duration is updated. When a delegate is set
 * on a playback facade, this method is called with the most recently updated
 * duration for the session. A session duration can change as the media playback
 * continues to load, as it is refined with more precise information.
 *
 * @param facade The playback facade to which this instance serves as delegate.
 * @param session The playback session whose duration changed.
 * @param duration The most recently updated session duration.
 */
- (void)playbackFacade:(id<BCOVPlaybackFacade>)facade playbackSession:(id<BCOVPlaybackSession>)session didChangeDuration:(NSTimeInterval)duration;

/**
 * Called when a playback session's external playback active status is updated.
 * When a delegate is set on a playback facade, this method is called with the
 * current external playback active status for the session.
 *
 * @param facade The playback facade to which this instance serves as delegate.
 * @param session The playback session whose external playback status changed.
 * @param externalPlaybackActive Whether external playback is active.
 */
- (void)playbackFacade:(id<BCOVPlaybackFacade>)facade playbackSession:(id<BCOVPlaybackSession>)session didChangeExternalPlaybackActive:(BOOL)externalPlaybackActive;

/**
 * Called when a session's playhead passes cue points registered with its video.
 * This will occur regardless of whether the playhead passes the cue point time
 * for standard progress (playback), or seeking (forward or backward) through
 * the media. When a delegate is set on a playback facade, this method will only
 * be called for future cue point events (any events that have already occurred
 * will not be reported).
 *
 * If multiple cue points are registered to a time or times that fall between
 * the "previous time" and "current time" for a cue point event, all cue points
 * after the "previous time" and before or on "current time" will be included
 * in the cue point collection. Put differently, multiple cue points at the
 * same time are aggregated into a single cue point event whose collection will
 * contain all of those cue points. The most likely scenario in which this
 * would happen is when seeking across a time range that includes multiple cue
 * points (potentially at different times) -- this will result in a single cue
 * point event whose previous time is the point at which seek began, whose
 * current time is the destination of the seek, and whose cue points are all of
 * the cue points whose time fell within that range.
 *
 * The cuePointInfo dictionary will contain the following keys and values for
 * each cue point event:
 *
 *   kBCOVPlaybackSessionEventKeyPreviousTime: the progress interval immediately
 *     preceding the cue points for which this event was received.
 *   kBCOVPlaybackSessionEventKeyCurrentTime: the progress interval on or
 *     immediately after the cue points for which this event was received.
 *   kBCOVPlaybackSessionEventKeyCuePoints: the BCOVCuePointCollection of cue
 *     points for which this event was received.
 *
 * @param facade The playback facade to which this instance serves as delegate.
 * @param session The playback session whose cue points were passed.
 * @param cuePointInfo A dictionary of information about the cue point event.
 */
- (void)playbackFacade:(id<BCOVPlaybackFacade>)facade playbackSession:(id<BCOVPlaybackSession>)session didPassCuePoints:(NSDictionary *)cuePointInfo;

/**
 * Called with the playback session's playback progress. As the session's
 * media plays, this method is called periodically with the latest progress
 * interval. When a delegate is set on a playback facade, this method will only
 * be called with progress information that has not yet occurred.
 *
 * @param facade The playback facade to which this instance serves as delegate.
 * @param session The playback session making progress.
 * @param progress The time interval of the session's current playback progress.
 */
- (void)playbackFacade:(id<BCOVPlaybackFacade>)facade playbackSession:(id<BCOVPlaybackSession>)session didProgressTo:(NSTimeInterval)progress;

/**
 * Called when a playback session receives a lifecycle event. When a delegate
 * is set on a playback facade, this method is called with the entire history
 * of lifecycle events that have transpired since the beginning of the session.
 * (This means that if the delegate is added mid-way through an active playback
 * session, it may be called multiple times, once for each lifecycle event that
 * has been received, and will continue to be called for future lifecycle
 * events.)
 *
 * The lifecycle event types are listed along with the
 * BCOVPlaybackSessionLifecycleEvent class.
 
 * @param facade The playback facade to which this instance serves as delegate.
 * @param session The playback session whose lifecycle events were received.
 * @param lifecycleEvent The lifecycle event received by the session.
 */
- (void)playbackFacade:(id<BCOVPlaybackFacade>)facade playbackSession:(id<BCOVPlaybackSession>)session didReceiveLifecycleEvent:(BCOVPlaybackSessionLifecycleEvent *)lifecycleEvent;

@end


/**
 * The functionality of the finder methods added in these category methods is
 * similar to the core finder methods in BCOVCatalogService, except that rather
 * than return a signal that delivers the results (or an error), these methods
 * return void but take a block which is called with the results (or an error).
 * If you are comfortable using ReactiveCocoa's signal API, the signal methods
 * offered by BCOVCatalogService offer better flexibility. These category
 * methods are intended for clients who do not wish to use signals directly.
 */
@interface BCOVCatalogService (BCOVImperativeCallbacks)

/**
 * Retrieves a BCOVPlaylist from the Media API service by its playlist ID.
 *
 * If the Media API returns a standard JSON-formatted error response, the
 * deserialized response will be the callback's error's `userInfo`.
 *
 * If a JSON parse error occurs, the raw NSData response will be included in the
 * callback's error's `userInfo`, keyed by kBCOVCatalogJSONDeserializationErrorRawDataKey.
 *
 * @param playlistID The ID of the playlist to find.
 * @param parameters Additional NSString query parameters to add to the Media
 * API requests. These values will override the default values if they conflict.
 * @param completionHandler block which will be invoked when the request
 * finishes. Execution of the completionHandler will occur on the main thread.
 */
- (void)findPlaylistWithPlaylistID:(NSString *)playlistID parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;

/**
 * Retrieves a BCOVPlaylist from the Media API service by its reference ID.
 *
 * If the Media API returns a standard JSON-formatted error response, the
 * deserialized response will be the callback's error's `userInfo`.
 *
 * If a JSON parse error occurs, the raw NSData response will be included in the
 * callback's error's `userInfo`, keyed by kBCOVCatalogJSONDeserializationErrorRawDataKey.
 *
 * @param referenceID The reference ID of the playlist to find.
 * @param parameters Additional NSString query parameters to add to the Media
 * API requests. These values will override the default values if they conflict.
 * @param completionHandler block which will be invoked when the request
 * finishes. Execution of the completionHandler will occur on the main thread.
 */
- (void)findPlaylistWithReferenceID:(NSString *)referenceID parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;

/**
 * Retrieves a BCOVVideo from the Media API service by its video ID.
 *
 * If the Media API returns a standard JSON-formatted error response, the
 * deserialized response will be the callback's error's `userInfo`.
 *
 * If a JSON parse error occurs, the raw NSData response will be included in the
 * callback's error's `userInfo`, keyed by kBCOVCatalogJSONDeserializationErrorRawDataKey.
 *
 * @param videoID The ID of the video to find.
 * @param parameters Additional NSString query parameters to add to the Media
 * API requests. These values will override the default values if they conflict.
 * @param completionHandler block which will be invoked when the request
 * finishes. Execution of the completionHandler will occur on the main thread.
 */
- (void)findVideoWithVideoID:(NSString *)videoID parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

/**
 * Retrieves a BCOVVideo from the Media API service by its reference ID.
 *
 * If the Media API returns a standard JSON-formatted error response, the
 * deserialized response will be the callback's error's `userInfo`.
 *
 * If a JSON parse error occurs, the raw NSData response will be included in the
 * callback's error's `userInfo`, keyed by kBCOVCatalogJSONDeserializationErrorRawDataKey.
 *
 * @param referenceID The reference ID of the video to find.
 * @param parameters Additional NSString query parameters to add to the Media
 * API requests. These values will override the default values if they conflict.
 * @param completionHandler block which will be invoked when the request
 * finishes. Execution of the completionHandler will occur on the main thread.
 */
- (void)findVideoWithReferenceID:(NSString *)referenceID parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

@end