diff --git a/CHANGELOG.md b/CHANGELOG.md index ac75e0ca..0366db10 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,487 +1,25 @@ -## Release 6.7.7 ## - -#### Breaking Changes - -* Several Brightcove Player SDK Podspecs have been renamed which might affect your project Podfile. Refer to the *Noteworthy* section of the SDK Core README. - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Updates the `Brightcove-Player-Core` podspec to install the dynamic SDK Core framework. To install the static framework, reference the `Brightcove-Player-SDK-static` podspec instead. - -* Fixes an issue where use of a custom layout prevented scrubbing. - -* Fixes an issue where occasionally, a downloaded video could not be played while off-line. - -### IMA Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds support for IMA pre-roll ads with SSAI live streams on iOS and tvOS. - -* Adds support for version 3.11.4 of the Google IMA SDK for iOS. - -* Adds support for version 4.2.3 of the Google IMA SDK for tvOS. - -### SSAI Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Updates the `Brightcove-Player-SSAI` podspec to install the dynamic SSAI framework. To install the static framework, reference the `Brightcove-Player-SSAI-static` podspec instead. - -* Improves the behavior of seeking around ads and Seek Without Ads. - -### GoogleCast Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Updates the `Brightcove-Player-GoogleCast` podspec to install the dynamic Core framework. To install the static Core framework, reference the `Brightcove-Player-GoogleCast-static` podspec instead. - -## Release 6.7.6 ## - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Adds the optional `BCOVPUIPlayerViewDelegate` methods `progressSliderDidTouchDown:`, `progressSliderDidChangeValue:` and `progressSliderDidTouchUp:` for iOS. - -* Adds the optional `BCOVTVPlayerViewDelegate` methods `progressViewPanGestureStateBegan:`, `progressViewPanGestureStateChanged:` and `progressViewPanGestureStateEnded:` for tvOS. - -* Adds support for dual expiry for offline FairPlay protected videos. Refer to the _Download a Video_ section of OfflinePlayback.md for more information. - -* Fixes an issue on tvOS where audio would continue to play after a player view had been removed from the view heirarchy. - -### IMA Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds support for pre-roll and post-roll ad playback over AirPlay. Set `enableBackgroundPlayback` to `YES` on `IMASettings` along with enabling AirPlay on your `BCOVPlaybackController`. Refer to the _AirPlay_ section of the README for more information. - -## Release 6.7.5 ## - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Fixes a fatal exception on tvOS caused by multiple app launches. - -* Adds support for preloading content keys for online FairPlay protected videos. See `preloadContentKeysForVideos:` on `BCOVFairPlayManager` for more information. - -* Improves support for right-to-left languages. - -* Adds support for localized number values. - -* Fixes an issue where the Captions button was hidden after changing the controls layout. - -* Fixes an issue where `offlineVideoToken:aggregateDownloadTask:didProgressTo:forMediaSelection:` was not being called after an app was moved from the background to the foreground. - -### Pulse Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds the ability to pause and resume ads with support for Pulse PauseAd. - -* Supports seeking without ads (resume). - -* Fixes post-roll ad playback on tvOS. - -* Improves handling for various error conditions such as bad ad paths. - -* Improves support for right-to-left languages. - -## Release 6.7.4 +## Release 6.3.12 ### Brightcove Player SDK for iOS (Core) #### Additions and Improvements -* Adds support for the Brightcove Playback Rights Management Service. - -* Adds support for HEVC and HLSv7 video playback. - -* Adds new localizations for Arabic (ar), French (fr), German (de), Japanese (ja), Korean (ko) and Spanish (es). - -### Pulse Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds new support for integrating Pulse Video Advertising with your iOS and tvOS apps. - -### IMA Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Supports version 3.11.3 of the Google IMA SDK for iOS. - -* Supports version 4.2.1 of the Google IMA SDK for tvOS. - -* Fixes an issue where `kBCOVIMALifecycleEventAdsLoaderLoaded` was not triggered for VAST ad profiles. - -## Release 6.7.3 - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Adds improvements to some video analytics. - -## Release 6.7.2 +* Removes references to UIWebView. -#### Breaking Changes - -* The minimum Deployment Target for all Brightcove Native Player for iOS frameworks is now iOS 11.0 and tvOS 11.0. Details are available [here](https://sdks.support.brightcove.com/support/announcements/native-sdk-ios-eol-support-iostvos-10.html). - -#### Additions and Improvements - -* Fixes an issue with apps crashing during launch on iOS Simulators running iOS 11 and 12 (`dyld: Symbol not found: _OBJC_CLASS_$_AVAssetDownloadURLSession`). The exception to the fix is apps built with the Google Cast SDK for iOS CocoaPod due to an issue with the google-cast-sdk Podspec. To work around the issue, for example in the Brightcove BasicCastPlayer sample project for Objective-C, follow these steps: - -1. Run `pod install` -1. Open the BasicCastPlayer.xcworkspace document -1. In the Xcode Project Navigator, navigate to Pods -> Target Support Files -> Pods-BasicCastPlayer -1. In the files Pods-BasicCastPlayer.debug.xcconfig and Pods-BasicCastPlayer.release.xcconfig change this line: - -``` -OTHER_LDFLAGS = $(inherited) -ObjC -l"c++" -framework "AVFoundation" -framework "Accelerate" -framework "AudioToolbox" -framework "BrightcoveGoogleCast" -framework "BrightcovePlayerSDK" -framework "CFNetwork" -framework "CoreBluetooth" -framework "CoreData" -framework "CoreGraphics" -framework "CoreMedia" -framework "CoreText" -framework "Foundation" -framework "GoogleCast" -framework "MediaAccessibility" -framework "MediaPlayer" -framework "QuartzCore" -framework "Security" -framework "SystemConfiguration" -framework "UIKit" -framework "protobuf" -``` - - to this: - -``` -OTHER_LDFLAGS = $(inherited) -ObjC -l"c++" -framework "BrightcovePlayerSDK" -framework "BrightcoveGoogleCast" -framework "GoogleCast" -framework "protobuf" -``` -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Adds support for short-duration license renewal for FairPlay protected videos. See `updateLicenseRenewalInterval:` on `BCOVPlaybackController` for more information. - -## Release 6.7.1 - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Fixes an issue that could prevent downloads from starting immediately when using `BCOVOfflineVideoManager`. - -* Adds the `playbackController:determinedVideoType:forVideo:` delegate method to `BCOVPlaybackController`. See the `BCOVPlaybackController` header for more information, including all available types of `BCOVVideoType`. - -* Updates header documentation for the `BCOVVideo.playableOffline` property which can have an unexpected value when the video is loaded for playback. +* Fixes an issue where the status information of offline video downloads was being deleted. This issue is present only in Release 6.3.11. ### IMA Plugin for Brightcove Player SDK for iOS #### Additions and Improvements -* Adds support for setting Audience Segment Targeting information on ad requests. See `updateAudienceSegmentTargetingValues:` in `BCOVPlaybackController` for more information. *This is currently only supported when using IMA + VAST.* - -### SSAI Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Fixes scrubbing behavior when using BCOVPlayerUI player controls and the SSAI plugin to play back VOD. +* Supports IMA 3.11.3 for iOS which, among other improvements, removes references to UIWebView. When running on an iOS 9.x device, configure IMAAdsRenderingSettings to use Safari when opening landing pages in response to taps on "Learn More" or companions ads. -### Google Cast Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Fixes bitcode embedding. - -## Release 6.7.0 - -#### Additions and Improvements - -* Adds support for the Brightcove Playback Rights Management Service which is in Limited Availability. - -* Deprecates support for iOS 10 and tvOS 10 in the Core SDK and all plugin frameworks. Support for iOS 10 and tvOS 10 will end in the near future. - -#### Breaking Changes - -* Removes strings generated by Xcode Project Versioning as those settings are not used for SDK versioning. Version strings were declared in the SDK framework umbrella headers, for example, in BrightcovePlayerSDK.h: - -```c -FOUNDATION_EXPORT const unsigned char BrightcovePlayerSDKVersionString[]; -``` - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Deprecates support for downloading secondary tracks as a separate download request (`requestVideoDownload:parameters:completion:` and `requestMediaSelectionsDownload:offlineVideoToken:`). Update your apps to the newest download method described in the "*Downloading Secondary Tracks*" section of OfflinePlayback.md. - -#### Breaking Changes - -* Removes deprecated method `renewFairPlayLicense:parameters:completion` from `BCOVOfflineVideoManager`. - -#### Known Issues - -* After requesting a video download, the download can delay for several minutes. To work around this issue, implement the BCOVOfflineVideoManagerDelegate method, `didCreateSharedBackgroundSesssionConfiguration:`, and set the `discretionary` property of the `backgroundSessionConfiguration` object to `NO`. A permanent fix will be released in the near future. - -```c -- (void)didCreateSharedBackgroundSesssionConfiguration:(NSURLSessionConfiguration *)backgroundSessionConfiguration -{ - backgroundSessionConfiguration.discretionary = NO; -} +```objc +IMAAdsRenderingSettings *renderSettings = [[IMAAdsRenderingSettings alloc] init]; +renderSettings.webOpenerPresentingController = nil; +renderSettings.webOpenerDelegate = self; // optional ``` - -### IMA Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds support for tvOS. - -### Google Cast Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds the `prepareForReuse` method to clean up state of a `BCOVGoogleCastManager` instance if shared across view controllers. - -#### Breaking Changes - -* Deprecates support for `sharedManager`. In a future release, `BCOVGoogleCastManager` will need to be instantiated explicitly. - -## Release 6.6.2 - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Fixes an issue where the `didChangeSeekableRanges` delegate method was not being called. This issue first appeared in SDK release 6.6.0. - -* Fixes an issue where the `kBCOVPlaybackSessionLifecycleEventReady` lifecycle event might be sent in response to seek starts and ends. - -## Release 6.6.1 - -#### Additions and Improvements - - * Fixes an issue where successive calls to `BCOVPlaybackController -setVideos:` on a single `BCOVPlaybackController` caused resource leaks which could result in an app crash. - -## Release 6.6.0 - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Reduces the file size of the dynamic framework by ~10MB, and ~20MB for the static framework. - -* Reduces CPU load up to 40% when playing video, decreases memory usage by up to 10%, and decreases energy usage by up to 30%. - -* Fixes an issue causing **default** captions to not be automatically selected. Note that the **default** caption may not be selected when the user has enabled "Closed Captions + SDH". - -* Fixes an issue where tapping the LIVE button on a paused live video did not begin playback after seeking to the live edge. - -* Fixes an issue when retrying a download of secondary tracks after a previous attempt resulted in a failure. - -* Enables playback of an IMA pre-roll ad with Live HLS streams. - -* Adds functionality to specify an initial selection when setting bitrate options along with the ability to programmatically set a preferred bitrate. Refer to the "*Setting a Preferred Bitrate*" section of the README for more information. - -* Removes a reference to the deprecated UIWebKit. - -#### Breaking Changes - -* The Offline Downloads API has changed for iOS 13+. Refer to the "*Downloading Secondary Tracks*" section of OfflinePlayback.md for details. - -* The minimum tvOS Deployment Target for all Brightcove Native Player for tvOS frameworks is now tvOS 10.0. - -* Support for `BCOVBasicSessionLoadingPolicy` has been removed. Refer to the "*Preloading Videos*" section of the README for guidance on using multiple playback controllers to achieve a preloading effect. - -* Requires Xcode 11+. - -### IMA Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Fixes an issue where the delegate method `playbackController:playbackSession:didExitAd:` was not being triggered when an applicable IMA ad was skipped. - -* Fixes an issue where ads were not replayed when `ignoringPreviouslyProcessedCuePoints` on `BCOVCuePointProgressPolicy` was disabled. - -## Release 6.5.0 - -#### Breaking Changes - -* Support for Xcode 10 has been deprecated and Brightcove SDK releases after 6.5.0 will require you to build your apps with Xcode 11+. - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Adds support for Live streams with FairPlay DRM. Refer to the [Live DRM](https://live.support.brightcove.com/general/live-drm.html) support pages. - -* Adds localizations for traditional Chinese (zh-hant) and simplified Chinese (zh-hans) language scripts. - -* Fixes an issue causing the duration and progress labels to display in Times New Roman on devices running iOS 13. - -* Fixes the public declarations of Playback Session lifecycle event types `kBCOVPlaybackSessionLifecycleEventPlayRequest`, `kBCOVPlaybackSessionLifecycleEventPauseRequest`, `kBCOVPlaybackSessionLifecycleEventAdSequenceEnter`, `kBCOVPlaybackSessionLifecycleEventAdSequenceExit`, `kBCOVPlaybackSessionLifecycleEventAdEnter`, `kBCOVPlaybackSessionLifecycleEventAdExit`, `kBCOVPlaybackSessionLifecycleEventAdProgress`, `kBCOVPlaybackSessionLifecycleEventAdPause` and `kBCOVPlaybackSessionLifecycleEventAdResume` which can be found in the framework header BCOVPlaybackSession.h. - -### Google Cast Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Supports version 4.4.5 of the Google Cast SDK for iOS. - -### SSAI Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds support for Live Streams with Server-Side Ad Insertion. Refer to the [Overview: Advanced Player Toolkit for Live SSAI](https://live.support.brightcove.com/live-api/ssai/overview-player-enhancements-live-ssai.html) pages for details. - -## Release 6.4.5 - -### SSAI Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Fixes an exception which occurred when calling `setVideos:` more than once for a single `BCOVPlaybackController` object. The exception error message includes the text `Exception 'Cannot remove an observer...`. - -## Release 6.4.4 - -### Brightcove Player SDK for tvOS (Core) - -#### Additions and Improvements - -* Extends support for Picture-in-Picture by adding `showPictureInPictureButton` to `BCOVPUIPlayerViewOptions`. When set to true, a Picture-in-Picture button will be added to the player controls on supported devices. Refer to the VidoCloudBasicPlayer sample project for example code. - -* Adds support for AirPlay 2. Refer to the AirPlay section of the SDK Core README for details on adding AirPlay 2 support to your apps. - -* Adds the optional BCOVTVPlayerViewDelegate method `- (BOOL)playerViewShouldRequireLinearPlayback:(BCOVTVPlayerView *)playerView;`. Refer to the [BCOVTVPlayerViewDelegate](https://docs.brightcove.com/ios-sdk/Protocols/BCOVTVPlayerViewDelegate.html) reference. - -* Fixes an issue where setting the BCOVPlaybackController `shutter` property from a non-main thread generated an exception. - -#### Breaking Changes - -* Removes the `defaultControlsViewStrategy` option on `BCOVPlayerSDKManager`. Use the built-in PlayerUI controls instead; see the Built-In PlayerUI Controls section in the README for details. - -### FreeWheel Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Fixes a crash which occurred when getting or setting the `shutter` property of the BCOVPlaybackController from a non-main thread. - -## Release 6.4.3 - -#### Breaking Changes - -* Release 6.4.3 of the Brightcove Player SDK for iOS deprecates BrightcoveOUX, replacing it with the SSAI Plugin for Brightcove Player SDK for iOS. Refer to the OnceUX or SSAI README for instructions on migrating your app to the new BrightcoveSSAI framework. - -### Brightcove Player SDK for tvOS (Core) - -#### Additions and Improvements - -* Adds support for VoiceOver to the built-in BCOVTVPlayerUI controls. - -* Adds the `BCOVTVAccessibilityDelegate` protocol to allow customization of some accessibility labels. - -### IMA Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Supports version 3.9.0 of the Google IMA SDK for iOS. - -* Adds default values for the `playerType` and `playerVersion` properties of the IMASettings object. - -### SSAI Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Introduces the SSAI Plugin. Refer to the OnceUX or SSAI README for instructions on migrating your apps to the new BrightcoveSSAI framework. - -* Provides access to the VMAP data retrieved in response to a `-setVideos:` call to the Playback Controller. Refer to the SSAI README for details. - -* Fixes an issue which could cause rewind or jump-back to fail, and which could prevent a preroll ad from playing. - -### OnceUX Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Deprecates the OnceUX Plugin. Support for OnceUX is now provided by the SSAI Plugin for Brightcove Player SDK for iOS. Refer to the README for information on migrating your apps to BrightcoveSSAI. - -* Provides access to the VMAP data retrieved in response to a `-setVideos:` call to the Playback Controller. Refer to the OnceUX README for details. - -* Fixes an issue which could cause rewind or jump-back to fail, and which could prevent a preroll ad from playing. - -## Release 6.4.2 - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Adds support for the Brightcove Playback Authorization Service. - -* Fixes an issue where `player_width` and `player_height` were being reported as 0 in analytics for 360° videos. - -* Fixes an issue where the fullscreen toggle button remained visible after entering VR Goggles mode for 360° videos. - -* Adds constants for common values in property/paramater dictionaries. You can find these near the top of: - - * BCOVAnalytics.h - * BCOVAnalyticsSession.h - * BCOVCuePoint.h - * BCOVPlaybackService.h - * BCOVPlaylist.h - * BCOVSource.h - * BCOVVideo.h - -* BCOVBasicSessionLoadingPolicy has been deprecated. Refer to the `Preloading Videos` section of the README for guidance on using multiple playback controllers to achieve a preloading effect. - -### OnceUX Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Fixes an issue where the `creativeView` ad tracking event could be reported twice for each ad. - -* Adds ability to obtain VMAP data after it has been recieved by observing the `kBCOVOUXVMAPResponseReceivedNotification` (now `kBCOVSSAIVMAPResponseReceivedNotification`) notification. - -## Release 6.4.1 - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Adds support for VoiceOver to the built-in BCOVPlayerUI controls. - -* Removes the `kBCOVOfflineVideoManagerHTTPMaximumConnectionsPerHostKey` option to BCOVOfflineVideoManager initialization. Use the BCOVOfflineVideoManagerDelegate `-didCreateSharedBackgroundSesssionConfiguration:` method instead. - -### FreeWheel Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds support for honoring the video Advertising setting (Free or Ad Supported). - -### IMA Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds support for honoring the video Advertising setting (Free or Ad Supported). - -## Release 6.4.0 - -#### Breaking Changes - -* The minimum iOS Deployment Target for all Brightcove Native Player for iOS frameworks is now iOS 10.0. Details are available [here](https://sdks.support.brightcove.com/support/announcements/native-sdk-ios-eol-support-iostvos-10.html). - -### Brightcove Player SDK for iOS (Core) - -#### Additions and Improvements - -* Adds functionality to select a preferred peak bitrate for AVPlayer. Refer to the `Setting a Preferred Bitrate` section of the README as well as the `preferredBitrateConfig` property on the `BCOVPUIPlayerViewOptions` class. - -* Fixes an issue where the status information of offline video downloads was being deleted. This issue is present only in Release 6.3.11. - -### Google Cast Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds new support for integrating Google Cast with your application. - -### FreeWheel Plugin for Brightcove Player SDK for iOS - -#### Additions and Improvements - -* Adds support for tvOS. - -* Supports version 6.26.0 of the FreeWheel AdManager framework for iOS and tvOS. - ## Release 6.3.11 ### Brightcove Player SDK for iOS (Core) @@ -508,7 +46,7 @@ FOUNDATION_EXPORT const unsigned char BrightcovePlayerSDKVersionString[]; * Fixes an issue where, while looping a video with postroll ads, the lifecycle event kBCOVPlaybackSessionLifecycleEventEnd was sent only the first time the video reached its end. -## Release 6.3.9 +## Release 6.3.9 ### Brightcove Player SDK for iOS (Core) @@ -759,7 +297,7 @@ Previously downloaded videos wll not have this property, but it will be added on #### Breaking Changes -* The minimum iOS Deployment Target for all Brightcove Native Player for iOS frameworks is now iOS 9.0. +* The minimum iOS Deployment Target for all Brightcove Native Player for iOS frameworks is now iOS 9.0. Details are available [here](https://support.brightcove.com/announcement-ios-sdk-deprecating-support-ios-9-and-eol-support-ios-8). ### Brightcove Player SDK for iOS (Core) @@ -787,8 +325,7 @@ A few new items are added to support this feature: #### Breaking Changes -* The `BCOVCatalogService`, also referred to as the Brightcove Media API, has reached end-of-life status and been removed from the Brightcove Native Player SDK. If your app uses the BCOVCatalogService, you must update it to use the [BCOVPlaybackService](https://docs.brightcove.com/ios-sdk/Classes/BCOVPlaybackService.html). - +* The `BCOVCatalogService`, also referred to as the Brightcove Media API, has reached end-of-life status and been removed from the Brightcove Native Player SDK. If your app uses the BCOVCatalogService, you must update it to use the [BCOVPlaybackService](https://brightcovelearning.github.io/Brightcove-API-References/ios-sdk/index.html#PlaybackService). * You can no longer download caption files using Sideband Subtitles in iOS 11. Sideband Subtitles is a workaround for incomplete track download support in iOS 10. As a result, you can no longer pass `kBCOVOfflineVideoManagerSubtitleLanguagesKey` as an option when requesting a video download. iOS 11 supports downloading of both subtitle and audio tracks; see "Addtions and Improvements" below for more details. Caption tracks that were downloaded using Sideband Subtitles will continue to play correctly on iOS 11. #### Additions and Improvements @@ -803,19 +340,19 @@ The `BCOVOfflineVideoDownloadState` enumeration adds the following values: ``` /* iOS 11+ only: Download of extra tracks requested but not yet reporting progress */ BCOVOfflineVideoDownloadStateTracksRequested = 7, - + /* iOS 11+ only: Download of extra tracks is progressing normally */ BCOVOfflineVideoDownloadStateTracksDownloading = 8, - + /* iOS 11+ only: Download of extra tracks was paused */ BCOVOfflineVideoDownloadStateTracksSuspended = 9, - + /* iOS 11+ only: Download of extra tracks completed normally */ BCOVOfflineVideoDownloadStateTracksCancelled = 10, - + /* iOS 11+ only: Download of extra tracks completed normally */ BCOVOfflineVideoDownloadStateTracksCompleted = 11, - + /* iOS 11+ only: Download of extra tracks terminated with an error */ BCOVOfflineVideoDownloadStateTracksError = 12 ``` @@ -881,11 +418,11 @@ You can specify AVMediaCharacteristicAudible or AVMediaCharacteristicLegible to - (NSArray *)downloadedMediaSelectionOptionsForMediaCharacteristic:(NSString *)mediaCharacteristic offlineVideoToken:(BCOVOfflineVideoToken)offlineVideoToken ``` - + The `forceStopAllDownloadTasks` method is implemented as a workaround for a bug on iOS 11.0.x and iOS 11.1.x. On these iOS versions, a track download will resume to completion if it was paused and then cancelled. The only way to stop the download is to force all the downloads in progress to stop wtih an error. - + This method should not be used on other versions of iOS; you can cancel an aggregate download task normally on iOS 11.2 by calling `cancelVideoDownload`. - + ``` - (void)forceStopAllDownloadTasks ``` @@ -973,7 +510,7 @@ For full details about downloading video for offline playback, see the *iOS App #### Additions and Improvements * Fixes an issue where a zero-length file in the framework would cause a build warning. -* Fixes an issue where adding the Brightcove Player SDK using CocoaPods required the manual addition of the MediaAccessibility framework. +* Fixes an issue where adding the Brightcove Player SDK using CocoaPods required the manual addition of the MediaAccessibility framework. ## Release 6.0.4 @@ -1022,10 +559,8 @@ For full details about downloading video for offline playback, see the *iOS App #### Breaking Changes -* This and future releases of Brightcove Native Player for iOS will include all software components, all having the same version number. When building your app with Brightcove Native Player for iOS components, the component version numbers must always match. As an example, when using version 6.0.1 of the FreeWheel Plugin for Brightcove Player SDK for iOS, you must also use version 6.0.1 of the core Brightcove Player SDK for iOS. Each component will continue to be available from individual GitHub repositories. - +* This and future releases of Brightcove Native Player for iOS will include all software components, all having the same version number. When building your app with Brightcove Native Player for iOS components, the component version numbers must always match. As an example, when using version 6.0.1 of the FreeWheel Plugin for Brightcove Player SDK for iOS, you must also use version 6.0.1 of the core Brightcove Player SDK for iOS. Each component will continue to be available from an individual GitHub repositories. * The Brightcove Podspecs repository has moved and the Pods have been renamed. The Podspecs are now available at [https://github.com/brightcove/BrightcoveSpecs](https://github.com/brightcove/BrightcoveSpecs). - * All CocoaPods podfiles that use Brightcove frameworks should include a reference to the Brightcove Podspecs at the top of the podfile: ``` @@ -1035,7 +570,6 @@ source 'https://github.com/brightcove/BrightcoveSpecs.git' * CHANGELOG.md (this file) has been consolidated to include all Brightcove Native Player for iOS software components. ### Brightcove Player SDK for iOS (Core) - #### Breaking Changes * The BrightcoveFairPlay module is now integrated into the core BrightcovePlayerSDK module and framework. No functional code changes are required, but you should make these changes for your build: @@ -1053,7 +587,7 @@ source 'https://github.com/brightcove/BrightcoveSpecs.git' * Supports downloading FairPlay-encrypted HLS videos, and playing them back from storage while online or offline. * New classes and types to support offline playback: `BCOVOfflineVideoManager`, `BCOVOfflineVideoStatus`, `BCOVOfflineVideoToken`, `BCOVOfflineVideoDownloadState`. -* Please see our app developer's guide for full details: "iOS App Developer's Guide to Video Downloading and Offline Playback with FairPlay" in OfflinePlayback.md. +* Please see our app developer's guide for full details: [iOS App Developer's Guide to Video Downloading and Offline Playback with FairPlay](OfflinePlayback.md) * The `BCOVVideo` class has three new properties: * `BOOL canBeDownloaded`: Returns YES if this video object can be downloaded for offline playback * `BOOL offline`: Returns YES if this instance refers to an offline video. diff --git a/FairPlay.md b/FairPlay.md index 43f9932b..0193cc87 100644 --- a/FairPlay.md +++ b/FairPlay.md @@ -1,4 +1,4 @@ -# Using FairPlay With The Brightcove Player SDK for iOS, version 6.7.7.1171 +# Using FairPlay With The Brightcove Player SDK for iOS, version 6.3.12 Quick Start =========== @@ -114,23 +114,6 @@ If you have questions or need help, we have a support forum for Brightcove's nat [bcovsdk]: https://github.com/brightcove/brightcove-player-sdk-ios [forum]: https://groups.google.com/forum/#!forum/brightcove-native-player-sdks -Content Key Preloading -=========== -You may preload content keys for videos by calling the `preloadContentKeysForVideos:` class method on `BCOVFairPlayManager`. Typically a content key for a FairPlay protected video is processed when the video begins playback. By preloading the content key you can improve the playback startup experience for your users. For example: - -``` -static NSString * const kViewControllerVideoID = @"..."; - -[self.playbackService findVideoWithVideoID:kViewControllerVideoID parameters:nil completion:^(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error) { - - if (video) - { - [BCOVFairPlayManager preloadContentKeysForVideos:@[video]]; - } - -}]; -``` - Application Certificates =========== Playabck of FairPlay-protected videos requires an application certificate associated with the content. diff --git a/OfflinePlayback.md b/OfflinePlayback.md index 0649b010..78c4d002 100644 --- a/OfflinePlayback.md +++ b/OfflinePlayback.md @@ -1,11 +1,13 @@ -iOS App Developer's Guide to Video Downloading and Offline Playback with HLS in the Brightcove Player SDK for iOS, version 6.7.7.1171 +iOS App Developer's Guide to Video Downloading and Offline Playback with HLS in the Brightcove Player SDK for iOS, version 6.3.12 -------------- The Brightcove Native Player SDK allows you to download and play back HLS videos, including those protected with FairPlay encryption. Downloaded videos can be played back with or without a network connection. ### Requirements: -- Brightcove Native Player SDK v6.6.2+ +- iOS 10.0+ +- Xcode 9+ +- Brightcove Native Player SDK v6.2.0+ - Brightcove Account with Dynamic Delivery iOS does not allow FairPlay-protected video to display in a simulator, nor does it allow video downloads to a simulator, so it's important to develop on an actual device. @@ -14,7 +16,7 @@ iOS does not allow FairPlay-protected video to display in a simulator, nor does When you request a video download, you will be given a token that is used to keep track of both the active download and the offline video in device storage. The token is of type `BCOVOfflineVideoToken`, and is referred to as a token rather than an object because it can be persisted, and is valid across instances of the app. -Videos are stored in the app's Library directory, in a subdirectory determined by iOS. Apple specifically requires that these videos stay in this location. Be aware that videos can be deleted by iOS under low-storage conditions, and users can delete downloaded videos directly from the iOS Settings app. Also, videos and their associated metadata are not backed up to iCloud. +Videos are stored in the app's Library directory, in a subdirectory determined by iOS. Apple specifically requires that these videos stay in this location. Be aware that videos can be deleted by iOS under low-storage conditions, and starting with iOS 11, users can delete downloaded videos directly from the iOS Settings app. Also, videos and their associated metadata are not backed up to iCloud. A FairPlay license can be requested either when the video download is requested, or preloaded ahead of time with a separate method call. You can specify either a purchase license, or a rental license with an associated rental duration. The license rental duration begins from the moment the request is made with the license server. @@ -49,7 +51,7 @@ If you want to change the `kBCOVOfflineVideoManagerAllowsCellularDownloadKey` va ### Check If A Video Can Be Downloaded -In your user interface, you should indicate if a video is eligible for download. To do this, examine the `BCOVVideo.canBeDownloaded` property. This Boolean property checks the status of the video's `offline_enabled` flag that is settable through the [Brightcove CMS API](https://sdks.support.brightcove.com/features/offline-playback-native-player-sdks.html#Download_management). +In your user interface, you should indicate if a video is eligible for download. To do this, examine the `BCOVVideo.canBeDownloaded` property. This Boolean property checks the status of the video's `offline_enabled` flag that is settable through the [Brightcove CMS API](https://support.brightcove.com/offline-playback-native-player-sdks#Download_management). ### Download A Video @@ -77,23 +79,11 @@ parameters = @{ }; ``` -You can also specify how long a license should remain valid after the video has begun playback. This is known as Dual Expiry or a Rental Profile: - -``` -parameters = @{ - // 30 days in seconds - kBCOVFairPlayLicenseRentalDurationKey: @(60 * 60 * 24 * 30), - // 24 hours in seconds - kBCOVFairPlayLicensePlayDurationKey: @(60 * 60 * 24) -}; -``` -**NOTE: If a license expires during playback of a video the video will not stop, but attempting to reload the video will result in a "license expired" error.** - The completion handler is where you asynchronously receive the offline video token or the error. You can store a reference to this offline video token if the error is nil. You will receive notficiation of progress and completion thorugh delegate methods. ### Preload A FairPLay license -If you plan to download multiple FairPlay-protected videos, it's a good idea to prelaod all the FairPlay licenses beforehand, because FairPlay license exchange cannot happen while the app is in the background. Preload a FairPlay license with a similar call: +If you plan to download multiple FairPlay-protected videos, it's a good idea to prelaod all the FairPlay licenses beforehand, because FairPlay license exchange cannot happen while the app is in the background. In iOS 10.3 and later, preload a FairPlay license with a similar call: ``` [BCOVOfflineVideoManager.sharedManager @@ -110,7 +100,6 @@ An offline video token will be established for the download at this point. After ``` [BCOVOfflineVideoManager.sharedManager requestVideoDownload:video - mediaSelections:nil parameters:nil completion:^(BCOVOfflineVideoToken offlineVideoToken, NSError *error) { @@ -121,18 +110,87 @@ An offline video token will be established for the download at this point. After At this point, the download will continue even if the user sends the app to the background. Keep in mind, however, that a FairPlay license rental duration begins from the time when the license is requested. +In iOS 10.2 and earlier, license prelaoding is not possible. It's important to make sure that a video begins downloading before allowing the user to move the app to the background; this ensures that the FairPlay license has been established. To prevent issues with background license exchange we recommending limiting downloads to one or two videos at a time on iOS 10.2 and earlier. + ### Downloading Secondary Tracks -Subtitle, caption and audio tracks of a language are known collectively as a media selection option. A video can have multiple media selection options, for example, English, French and Spanish. The language settings of the device determine the *preferred* media selection option, for example, English. When downloading a video for offline viewing, the preferred media selection option and any chosen additional media selection options are downloaded together in response to a single download request. Internally, the SDK manages the download using a single AVAggregateAssetDownloadTask. +Subtitle, caption, and audio tracks are collectively known as "secondary tracks", and are downloaded differently on iOS 10.x, and ios 11+. + +#### Downloading Secondary Tracks On iOS 11+ -Downloading involves these basic steps: +iOS 11 introduced a newer, more reliable way of downloading secondary tracks using a new AVFoundation class, AVAggregateAssetDownloadTask. -1. Select the tracks you would like to download. Tracks are selected as AVMediaSelection objects and BCOVOfflineVideoManager provides the utility method `-[BCOVOfflineVideoManager urlAssetForVideo:error:]` to help you choose AVMediaSelections of interest. Refer to the "*Finding Media Selections*" methods of AVAsset. -1. Create an NSArray of your media selections, and pass it to `-[BCOVOfflineVideoManager requestVideoDownload:mediaSelections:parameters:completion:]` or pass `nil` to automatically download the preferred AVMediaSelections. -2. Track download progress using methods in the `BCOVOfflineVideoManagerDelegate` protocol. +Downloading with iOS 11 involves these basic steps: + +1. Make sure the primary video has completed downloading. +1. Select which tracks you would like to download. Tracks are selected as AVMediaSelection objects. You can see all the available AVMediaSelection objects for a downloaded video using the method `-[AVURLAsset allMediaSelections]`. +1. Create an NSArray out of your media selections, and pass it to `-[BCOVOfflineVideoManager requestMediaSelectionsDownload:offlineVideoToken:]`. +2. Track download progress through new methods in the `BCOVOfflineVideoManagerDelegate` protocol. Secondary tracks use the same offline video token as the primary video. Some tracks may have already been downloaded as part of the initial video download. +#### Downloading Secondary Tracks On iOS 10 + +iOS 10.x does not handle downloading of subtitle and caption tracks reliably, so we have created a custom WebVTT downloader and renderer for subtitles in your HLS videos. This support is known as Sideband Subtitles. + +Downloading secondary audio tracks is not available for iOS 10. + +To download subtitles, first check what subtitle languages are available in your video: + +``` +[BCOVOfflineVideoManager.sharedManager + alternativeRenditionAttributesDictionariesForVideo:video + completion:^(NSArray *alternativeRenditionAttributesDictionariesArray, NSError *error) { + + // Check available languages + + // This set collects the language code for each language + NSMutableSet *languagesSet = NSMutableSet.set; + + // Loop through each of the alternative rendition tracks + for (NSDictionary *alternativeRenditionAttributesDictionary in alternativeRenditionAttributesDictionariesArray) + { + NSString *typeString = alternativeRenditionAttributesDictionary[@"TYPE"]; + NSString *languageString = alternativeRenditionAttributesDictionary[@"LANGUAGE"]; + + // If it's a subtitle with a valid language code, add it to the set + if ([typeString isEqualToString:@"SUBTITLES"] && languageString != nil) + { + [languagesSet addObject:languageString]; + } + } + + // Get array of all languages from set and save it + self.languagesArray = languagesSet.allObjects; + +}]; +``` + +"Alternative renditions" is the HLS term for subtitles and audio tracks that provide a different way of presenting the main content. + +The `alternativeRenditionAttributesDictionariesArray` array will contain an array of dictionaries, one for each alternative rendition. Attribute keys are taken directly from the attribute names in the HLS specification. You can check dictionaries whose "TYPE" key is "SUBTITLES", and record the "LANGUAGE" field used by each one. Once you have the languages you want to download, put them in an array and pass them along with your other download parameters to the download request method. + +To download all the languages we found above, you can pass the entire array as the value for `kBCOVOfflineVideoManagerPlaybackSubtitleLanguageKey `. + +``` +parameters = @{ + // Purchase license + kBCOVFairPlayLicensePurchaseKey: @(YES), + + // Languages to download + kBCOVOfflineVideoManagerPlaybackSubtitleLanguageKey: self.languagesArray +}; + +[BCOVOfflineVideoManager.sharedManager + requestVideoDownload:video + parameters:parameters + completion:^(BCOVOfflineVideoToken offlineVideoToken, NSError *error) { + + // store offlineVideoToken or handle error + +}]; +``` + **Displaying Sideband Subtitles** The PlayerUI built-in controls will automatically detect and present your available Sideband Subtitles in the same, familiar closed caption control for you, so don't need to do anything if you are using a standard `BCOVPUIPlayerView`. @@ -389,7 +447,7 @@ You should use these methods rather than operating on the internal `AVAssetDownl ### Renewing a FairPlay License -Starting with version 6.2.2 of the iOS Native Player SDK, you can renew the FairPlay license for a downloaded video without re-downloading the video. The device must be online for license renewal to succeed. +Starting with version 6.2.2 of the iOS Native Player SDK, you can renew the FairPlay license for a downloaded video without re-downloading the video. The device must be online for license renewal to succeed. This functionality is available when running on iOS 10.3 or later. To renew a license, call `-renewFairPlayLicense:video:parameters:completion:` with the offline video token for your previously-downloaded video, and a parameter dictionary specifying the new license terms. The parameter dictionary must not contain bitrate or subtitle language information. @@ -425,22 +483,6 @@ For example, here is how you can renew a FairPlay license with a new 30-day rent ``` -If you are using the Playback Authorization Service you'll need to use the renew FairPlay license method that accepts an authorization token: - -``` - // Request license renewal - [BCOVOfflineVideoManager.sharedManager renewFairPlayLicense:offlineVideoToken - video:video // recent video from Playback API or Playback Service class - authToken: authToken - parameters:parameters - completion:^(BCOVOfflineVideoToken offlineVideoToken, NSError *error) - { - - // handle errors - - }]; -``` - When license renewal is finshed, the completion block will be called with the same offline video token that was passed in, plus an `NSError` indicating any problem that occurred (or `nil` if no error). This block is not called on any specific thread. ### FairPlay Application Certificates @@ -497,7 +539,7 @@ Prior to system version 11.3, iOS did not realiably handle pausing and resuming **Sequential Downloads** -You can preload FairPlay licenses for a set of videos, and then create a queue for downloading videos one at a time until they are all complete. +On iOS 10.3 and later, you can preload FairPlay licenses for a set of videos, and then create a queue for downloading videos one at a time until they are all complete. When doing this it's a good idea to enable the "Background Fetch" mode for the application so that you can be woken up periodically to handle download completions and kick off new downloads. @@ -513,6 +555,8 @@ Doing this has several potentially unexpected side effects: - When you stop playing, the download task may not resume. This will happen if the video's session is still active in the `BCOVPlaybackController`. To clear out the current session, you can play a new video, or delete the playback controller. Be sure you don't store the current session in a strong property. +- In iOS 10.x, when you begin playback of a video that is downloading, the `AVPlayer` may initially seek to the end of the video, requiring the user to manually seek back to the beginning. This is an AVFoundation bug and works normally in the latest versions of iOS 11. + ### AirPlay You cannot stream an offline HLS video to an AirPlay device for playback. This is an AVFoundation limitation. @@ -533,10 +577,10 @@ If this is not possible, and you still need to create another playback controlle ### Specifying the Download Display Name -Users can directly examine and optionally delete downloaded videos using the Settings app. The displayed video name is taken from the "name" property of the `BCOVVideo` object. If the "name" property is not present, the offline video token's value will be used instead. +In iOS 11+, users can directly examine and optionally delete downloaded videos using the Settings app. The displayed video name is taken from the "name" property of the `BCOVVideo` object. If the "name" property is not present, the offline video token's value will be used instead. To provide a more customized experience, you can set a display name for the video asset in the options dictionary passed to `-requestVideoDownload:parameters:completion:` (or when preloading the license). Use the `kBCOVOfflineVideoManagerDisplayNameKey` key to set an `NSString` as the new asset display name. Note that iOS uses the asset name string as part of the downloaded video's file path, so you should avoid characters that would not be valid in a POSIX path, like a "/" character. -You may choose to replace these with more standardized names using the `kBCOVOfflineVideoManagerDisplayNameKey` option. +Also note that iOS 10 does not handle all unicode names properly, so on iOS 10, any unicode strings will instead use the offline video token as the display name. You may choose to replace these with more standardized names using the `kBCOVOfflineVideoManagerDisplayNameKey` option. diff --git a/README.md b/README.md index d3e013bd..05b68f7d 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,10 @@ -# Brightcove Player SDK for iOS, version 6.7.7.1171 +# Brightcove Player SDK for iOS, version 6.3.12 # Table of Contents -1. [Requirements](#Requirements) 1. [Supported Platforms](#SupportedPlatforms) -1. [Noteworthy](#Noteworthy) -1. [FairPlay](#FairPlay) -1. [Sidecar Subtitles](#SidecarSubtitles) -1. [Offline Playback](#OfflinePlayback) +1. [What's New](#New) 1. [Installation](#Installation) 1. [CocoaPods](#CocoaPods) 1. [Manual Installaion](#ManualInstallation) @@ -16,144 +12,126 @@ 1. [Quick Start](#QuickStart) 1. [Built-In PlayerUI Controls for iOS](#PlayerUI) 1. [Built-In TV Player Controls for tvOS](#TVPlayer) -1. [AirPlay](#AirPlay) +1. [FairPlay](#FairPlay) +1. [Sidecar Subtitles](#SidecarSubtitles) 1. [Video 360](#Video360) 1. [Architectural Overview](#ArchitecturalOverview) 1. [Play, Pause, and Seek](#PlayPauseSeek) 1. [Preloading Videos](#PreloadingVideos) 1. [Source Selection (HLS, MP4, HTTP/HTTPS)](#SourceSelection) -1. [Setting a Preferred Bitrate](#PreferredBitrate) -1. [Obtaining Content and Ad Playback Information](#PlaybackInformation) +1. [Obtaining Content And Ad Playback Information](#PlaybackInformation) 1. [Handling Network Interruptions and Slowdowns](#HandlingNetworkInterruptionsAndSlowdowns) 1. [Subclassing](#Subclassing) 1. [Values](#Values) 1. [Retrieving Brightcove Assets Using the Playback Service](#PlaybackService) 1. [View Strategy](#ViewStrategy) -1. [Playing Video In The Background](#BackgroundVideo) -1. [Picture In Picture](#PIP) -1. [Thumbnail Scrubbing](#ThumbnailScrubbing) +1. [Playing Video In The Background and Picture In Picture](#BackgroundPIP) 1. [Tracking Errors](#TrackingErrors) 1. [Combining Plugins](#CombiningPlugins) 1. [Buffer Optimization](#BufferOptimization) 1. [Using an AVPlayerViewController with a BCOVPlaybackController](#AVPlayerViewController) -1. [Playback Authorization Service](#PlaybackAuthorizationService) -1. [VoiceOver Support](#VoiceOver) 1. [Frequently Asked Questions](#FAQ) -Requirements -============ - -- Xcode 11.0+ -- ARC - Supported Platforms =================== -iOS 11.0 and above. - -tvOS 11.0 and above. +iOS 9.0 and above. -Noteworthy -============ +tvOS 9.0 and above. -All SDK components - the core and plugin frameworks - are released with the same version number. When upgrading any single component, upgrade all components to the same version. +ARC is required. -**CocoaPods Podspec names (since release 6.7.7)** +What's New +============ -Release 6.7.7 of the Brightcove Player SDK renames some Podspec files in order to improve CocoaPods compliance. Several Podspec files retain original names. Where there is a choice of dynamic and static frameworks, static framework Podspec files are named with a *-static* suffix. Prior to Release 6.7.7, static Brightcove frameworks were the default and dynamic frameworks were differentiated by a subspec name, for example `Brightcove-Player-Core/dynamic`. Using the Core SDK as an example: +Built-In TV Player Controls for tvOS +----- +Version 6.3 of the Brightcove Native Player SDK includes built-in controls for playback in tvOS on Apple TV. For full details about using the built-in TV Player UI with the Brightcove Native Player SDK, see our [TV Player guide](TVPlayer.md). -* If your Podfile imports `Brightcove-Player-Core/dynamic`, rename it `Brightcove-Player-Core`. -* If your Podfile imports `Brightcove-Player-Core/static`, rename it `Brightcove-Player-Core-static`. -* If your Podfile imports `Brightcove-Player-Core`, rename it `Brightcove-Player-Core-static` or better, leave it unchanged and make the switch to dynamic frameworks. +Migrating From Earlier Versions +------------------------------ +Version 6.0 has a few changes that you should be aware of, particularly if you have been using an earlier version: +- Podspecs are no longer hosted on [CocoaPods][cocoapods]. All podspecs are now hosted [here][podspecs] in a private specs repository. +- All of the SDK components - core library and plugin frameworks - are now released with the same version. When upgrading any single component, you should upgrade them all so that they all have the same version. +- In your project's podfile, be sure to add `source 'https://github.com/brightcove/BrightcoveSpecs.git'`, and remove any reference to `BCOVSpecs.git`. +- If you install frameworks manually, we recommend removing any current Brightcove frameworks, and then adding the new ones. Make sure the framework search paths in your Xcode target settings point to the new frameworks. -Podspec Name | Framework Type | Dependency -------------- | ------------- | ------------- -Brightcove-Player-Core | dynamic | - -Brightcove-Player-Core-static | static | - -Brightcove-Player-FreeWheel | static | Brightcove-Player-Core-static for iOS, Brightcove-Player-Core for tvOS -Brightcove-Player-GoogleCast | static | Brightcove-Player-Core -Brightcove-Player-GoogleCast-static | static | Brightcove-Player-Core-static -Brightcove-Player-IMA | dynamic | Brightcove-Player-Core -Brightcove-Player-Omniture | static | Brightcove-Player-Core-static -Brightcove-Player-Pulse | dynamic | Brightcove-Player-Core -Brightcove-Player-SSAI | dynamic | Brightcove-Player-Core -Brightcove-Player-SSAI-static | static | Brightcove-Player-Core-static +**Updated Podspec Names** -Dynamic frameworks are preferred over static library frameworks and there will be additional moves to dynamic frameworks in future releases. +Podspec names have been updated in the new BrightcoveSpecs repository to avoid confusion with older podspecs. -**CocoaPods Podspec names (since release 6.0.0)** +Be sure to update the included podspecs in your own podfiles. -Framework | Podspec Name +Old Podspec Name | New Podspec Name ------------- | ------------- -Brightcove Player SDK for iOS | Brightcove-Player-Core -FreeWheel ad plugin | Brightcove-Player-FreeWheel -IMA ad plugin | Brightcove-Player-IMA -Omniture analytics plugin | Brightcove-Player-Omniture -Pulse ad plugin | Brightcove-Player-Pulse -SSAI ad plugin | Brightcove-Player-SSAI +Brightcove-Player-SDK | Brightcove-Player-Core +Brightcove-Player-SDK-FW | Brightcove-Player-FreeWheel +Brightcove-Player-SDK-IMA | Brightcove-Player-IMA +Brightcove-Player-SDK-Omniture | Brightcove-Player-Omniture +Brightcove-Player-SDK-OUX | Brightcove-Player-OnceUX +Brightcove-Player-SDK-FairPlay | *Integrated into the core framework* +Brightcove-Player-SDK-Player-UI | *Integrated into the core framework* +Brightcove-Player-SDK-SidecarSubtitles | *Integrated into the core framework* -FairPlay + +FairPlay -------- -Support for playing FairPlay-protected videos is integrated into the core _BrightcovePlayerSDK_ framework. Refer to the [FairPlay guide](FairPlay.md) for full details about using FairPlay with the Brightcove Native Player SDK. +The `BrightcoveFairPlay` plugin framework and module is now integrated into the core `BrightcovePlayerSDK` framework. If you are currently using the Brightcove FairPlay plugin, no functional code changes are required, but you will need to make some changes for your build. See the [FairPlay](#FairPlay) section below for details. -Sidecar Subtitles +For full details about using FairPlay with the Brightcove Native Player SDK, see our [FairPlay guide](FairPlay.md). + +Sidecar Subtitles -------- -Support for Sidecar Subtitles is integrated into the core _BrightcovePlayerSDK_ framework. For full details about using Sidecar Subtitles with the Brightcove Native Player SDK, refer to the [Sidecar Subtitles guide](SidecarSubtitles.md). +The `BrightcoveSidecarSubtitles` plugin framework and module is now integrated into the core `BrightcovePlayerSDK` framework. If you are currently using the Brightcove Sidecar Subtitles plugin, no functional code changes are required, but you will need to make some changes for your build. See the [SidecarSubtitles](#SidecarSubtitles) section below for details. + +Note also that Sidecar Subtitles is generally not needed when working with Video Cloud Dynamic Delivery, as Dynamic Delivery ensures that your captions are added in-manifest before they are delivery to your app. -Video Downloads and Offline Playback +For full details about using Sidecar Subtitles with the Brightcove Native Player SDK, see our [Sidecar Subtitles guide](SidecarSubtitles.md). + +Video Downloads and Offline Playback -------------- -Since release 6.0.0, the Brightcove Native Player SDK allows you to download HLS videos, including those protected with FairPlay encryption, for playback later, whether online or offline. Refer to the app developer's guide for full details: +As of version 6.0.0, the Brightcove Native Player SDK allows you to download HLS videos, including those protected with FairPlay encryption, and play them back while online or offline. Please see our app developer's guide for full details: [iOS App Developer's Guide to Video Downloading and Offline Playback with FairPlay](OfflinePlayback.md) Installation ============ -The Brightcove Player SDK provides two installation packages for iOS, a static library framework and a dynamic framework. Deployment is supported on iOS 11 and above. +The Brightcove Player SDK provides two installation packages for iOS, a static library framework and a dynamic framework. Deployment is supported on iOS 8 and above. -The Brightcove Player SDK provides a dynamic framework to support tvOS 11.0 and above. +The Brightcove Player SDK provides a dynamic framework to support tvOS 9.0 and above. CocoaPods -------------- -You can use [CocoaPods][cocoapods] to add the Brightcove Player SDK to your project. You can find the latest `Brightcove-Player-Core` podspec [here][podspecs]. The podspec supports both iOS and tvOS. CocoaPods 1.0 or newer is required and the latest version is recommended. +You can use [CocoaPods][cocoapods] to add the Brightcove Player SDK to your project. You can find the latest `Brightcove-Player-Core` podspec [here][podspecs]. The podspec supports both iOS and tvOS. CocoaPods 1.0 or newer is required. When using Brightcove CocoaPods in your project, add `source 'https://github.com/brightcove/BrightcoveSpecs.git'` to the start of your Podfile. -Specifying the default pod `Brightcove-Player-Core` will install the dynamic library framework. To install the static framework, append `-static` like this: `pod 'Brightcove-Player-Core-static'`. +Specifying the default pod `Brightcove-Player-Core` will install the static library framework. To install the dynamic framework, declare the pod with the `dynamic` subspec: `Brightcove-Player-Core/dynamic` -Dynamic Framework example: +Static Framework example: ``` -source 'https://github.com/CocoaPods/Specs' source 'https://github.com/brightcove/BrightcoveSpecs.git' -platform :ios, '11.0' -use_frameworks! - -target 'MyVideoPlayer' do - pod 'Brightcove-Player-Core' -end +pod 'Brightcove-Player-Core' ``` - -Static Framework example: + +Dynamic Framework example: ``` -source 'https://github.com/CocoaPods/Specs' source 'https://github.com/brightcove/BrightcoveSpecs.git' -platform :ios, '11.0' -use_frameworks! - -target 'MyVideoPlayer' do - pod 'Brightcove-Player-Core-static' -end +pod 'Brightcove-Player-Core/dynamic' ``` -When updating your installation, it's a good idea to refresh the local copy of your BrightcoveSpecs repository so that you have the latest podspecs locally, just as you would update your CococaPods master repository. Typically if you run `pod update` in Terminal this will happen automatically, or alternatively you can update explicitly with `pod repo update`. +When updating your installation, it's a good idea to refresh the local copy of your BrightcoveSpecs repository so that you have the latest podspecs locally, just like you would update your CococaPods master repository. + +Typically if you use `pod update` in Terminal this will happen automatically, or alternatively you can update explicitly with `pod repo update brightcove`. (Your BrightcoveSpecs repository may have a different name if you explicitly added it to your list of podspecs repos.) Manual Installation -------------- @@ -163,8 +141,17 @@ To add the Brightcove Player SDK to your project manually: 1. Download the latest zipped release from our [release page][release]. 2. Add `BrightcovePlayerSDK.framework` to your project. Be sure to use the version corresponding to your target, iOS or tvOS. 3. On the "Build Settings" tab of your application target, ensure that the "Framework Search Paths" include the path to the framework. This should have been done automatically unless the framework is stored under a different root directory than your project. -4. On the "General" tab of your application target, add the following to the "Frameworks, Libraries, Embedded Content" section: - +4. On the "General" tab of your application target, add the following to the "Linked Frameworks and Libraries" section: + + * `AVFoundation` (mark as *optional* in Xcode if supporting iOS 9) + * `CoreMedia` + * `CoreMotion` (iOS only) + * `GLKit` + * `MediaPlayer` + * `MediaAccessibility` (iOS only) + * `SafariServices` (iOS only) + * `SystemConfiguration` (iOS only) + * `WebKit` (iOS only) * `BrightcovePlayerSDK.framework` 5. (**Dynamic Framework** only) On the "General" tab of your application target, add 'BrightcovePlayerSDK.framework' to the "Embedded Binaries" section. 6. (**Dynamic Framework** only) On the "Build Phases" tab, add a "Run Script" phase with the command `bash ${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/BrightcovePlayerSDK.framework/strip-frameworks.sh`. Check "Run script only when installing". This will remove unneeded architectures from the build, which is important for App Store submission. @@ -179,8 +166,7 @@ Brightcove-Player-Core | Brightcove-Player-IMA | Brightcove-Player-Omniture | -Brightcove-Player-Pulse | -Brightcove-Player-SSAI | +Brightcove-Player-OnceUX | Imports -------------- @@ -229,11 +215,54 @@ Playing video with the Brightcove Player SDK for iOS: You need to keep the controller from being automatically released at the end of the method. A common way to do this is to store a reference to the controller in a strong instance variable. -Built-in PlayerUI Controls +Built-In PlayerUI Controls ========================== -Since version 5.1.0, the Brightcove PlayerUI is fully integrated into the Core SDK framework. PlayerUI provides a fully-featured set of controls for playback and advertising, right out of the box. +As of version 5.1.0, the Brightcove Player SDK has the Brightcove PlayerUI Plugin integrated into its framework, so you can use its fully-featured set of controls for playback and advertising right out of the box. + +The PlayerUI is quick to set up, displays ad controls for Once and FreeWheel, and can be customized by creating your own layouts. + +Converting from Native Controls to PlayerUI Controls +---------------------------------------------------- +If you were previously using the native controls via the `defaultControlsViewStrategy` like this: + + BCOVPlayerSDKManager *manager = [BCOVPlayerSDKManager sharedManager]; + id playbackController = [manager createPlaybackControllerWithViewStrategy:[manager defaultControlsViewStrategy]]; -The PlayerUI is quick to set up, displays ad controls for SSAI, Pulse and FreeWheel, and can be customized by creating your own layouts. +You should now set the view strategy to nil: + + BCOVPlayerSDKManager *manager = [BCOVPlayerSDKManager sharedManager]; + id playbackController = [manager createPlaybackControllerWithViewStrategy:nil]; + +You also no longer need to add the Playback Controller's view to your hierarchy, so you can remove code like this: + + self.playbackController.view.frame = self.videoView.bounds; + self.playbackController.view.autoresizingMask = UIViewAutoresizingFlexibleHeight | UIViewAutoresizingFlexibleWidth; + [self.videoView addSubview:self.playbackController.view] + +Or code like this: + + self.playbackController.view.translatesAutoresizingMaskIntoConstraints = NO; + [self.videoView addSubview:self.playbackController.view]; + [NSLayoutConstraint activateConstraints:@[ + [self.playbackController.view.topAnchor constraintEqualToAnchor:self.videoView.topAnchor], + [self.playbackController.view.rightAnchor constraintEqualToAnchor:self.videoView.rightAnchor], + [self.playbackController.view.leftAnchor constraintEqualToAnchor:self.videoView.leftAnchor], + [self.playbackController.view.bottomAnchor constraintEqualToAnchor:self.videoView.bottomAnchor], + ]]; + +Instead, you will associate the Playback Controller with a new Player View and add that to your view hierarchy, as described in the **Setting up PlayerUI Controls** section of this document. + +Migrating from the Brightcove PlayerUI Plugin +---------------------------- +With version 5.1 of the Brightcove Player SDK, the PlayerUI controls are integrated into the core framework, and so it's no longer necessary to use a separate Brightcove PlayerUI plugin. If you were previously using the Brightcove PlayerUI plugin, and had installed it manually, you may need to make a few modifications to your project: + +* Remove the reference to BrightcovePlayerUI.framework from your project listing +* In your target's Build Settings, remove any reference to the BrightcovePlayerUI.framework from your Framework Search Paths +* In your target's General settings, remove any reference to BrightcovePlayerUI from the Embedded Binaries and Linked Frameworks and Libraries sections + +If you install Brightcove libraries using CocoaPods, you can remove the BrightcovePlayerUI dependency from your Podfile, and then run `pod update` in Terminal. + +In your project code, any specific `#import` of a PlayerUI header file can be converted from `#import ` to `#import `. Alternately, you can import all the headers at once with `@import BrightcovePlayerSDK;`. Setting up PlayerUI Controls ---------------------------- @@ -432,47 +461,45 @@ For more examples of PlayerUI customization, you can look at the sample code in [github]: https://github.com/BrightcoveOS/ios-player-samples -Built-in TV Player Controls for tvOS +Built-In TV Player Controls for tvOS ========== The Brightcove Native Player SDK includes built-in controls for playback in tvOS on Apple TV. For full details about using the built-in TV Player UI with the Brightcove Native Player SDK, see our [TV Player guide](TVPlayer.md). -AirPlay +FairPlay ========== -Enable AirPlay functionality by setting the `setAllowsExternalPlayback` property on your `BCOVPlaybackController` to `true`. The AirPlay button will be displayed in the playback controls if AirPlay devices are found on your network. +The Brightcove Native Player SDK includes support for playing FairPlay-protected videos. For full details about using FairPlay with the Brightcove Native Player SDK, see our [FairPlay guide](FairPlay.md). -Currently, IMA is the only plugin that supports AirPlay and only when using pre-roll and/or post-roll ads. Using AirPlay with the Pulse, SSAI or FreeWheel ad plugins may result in unexpected behavior. +Migrating From the Brightcove FairPlay Plugin +----- -If you also want to support AirPlay 2 and allow for multiple devices to be selected for audio output you will have to do a few additional things. First, you'll need to configure AVAudioSession so that you can set the `routeSharingPolicy`. For example: +If you were using the Brightcove FairPlay Plugin with the Brightcove Native Player SDK prior to verison 6.0, be aware that the `BrightcoveFairPlay` module is now integrated into the core `BrightcovePlayerSDK` framework. No functional code changes are required, but you should make these changes for your build: -``` -[AVAudioSession.sharedInstance setCategory:AVAudioSessionCategoryPlayback mode:AVAudioSessionModeMoviePlayback routeSharingPolicy:AVAudioSessionRouteSharingPolicyLongForm options:0 error:nil]; -``` -You will also need to configure at least one playback command via `MPRemoteCommandCenter`. At the very least you'll want to configure both the `pauseCommand` and `playCommand`. For Example: +* If using CocoaPods, remove all references to `BrightcoveFairPlay` from your Podfiles, and then update. +* For manual installations, remove the BrightcoveFairPlay.framework from your project. +* In your source code, change any #includes from `` to ``. +* Remove any imports that refer to the `BrightcoveFairPlay` module. +* In your target's Build Settings, remove any reference to the BrightcoveFairPlay.framework from your Framework Search Paths. +* In your target's General settings, remove any reference to BrightcoveFairPlay from the Embedded Binaries and Linked Frameworks and Libraries sections -``` -MPRemoteCommandCenter *center = MPRemoteCommandCenter.sharedCommandCenter; +Sidecar Subtitles +========== -[center.pauseCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent * _Nonnull event) { -[self.playbackController pause]; -return MPRemoteCommandHandlerStatusSuccess; -}]; +The Brightcove Native Player SDK includes support for playing external subtitle files, also know as Sidecar Subtitles. For full details about using Sidecar Subtitles with the Brightcove Native Player SDK, see our [Sidecar Subtitles guide](SidecarSubtitles.md). -[center.playCommand addTargetWithHandler:^MPRemoteCommandHandlerStatus(MPRemoteCommandEvent * _Nonnull event) { -[self.playbackController play]; -return MPRemoteCommandHandlerStatusSuccess; -}]; -``` -Devices that are running iOS 11 or later will take advantage of `AVRoutePickerView` which has two delegate methods. These delegate methods are passed through to `BCOVPUIPlayerViewDelegate`. The methods are: +Please note that if you are a Brightcove Video Cloud customer using Dynamic Delivery, **you will most likely not need to use Sidecar Subtitles**. Please read the [Sidecar Subtitles guide](SidecarSubtitles.md) to confirm your specific use case. -``` -- (void)routePickerViewWillBeginPresentingRoutes:(AVRoutePickerView *)routePickerView; -- (void)routePickerViewDidEndPresentingRoutes:(AVRoutePickerView *)routePickerView; -``` +Migrating From the Brightcove Sidecar Subtitles Plugin +----- -For more information on incorporating AirPlay 2 into your app please see the [Getting Airplay 2 into Your App](https://developer.apple.com/documentation/avfoundation/airplay_2/getting_airplay_2_into_your_app) documentation. +If you were using the Brightcove Sidecar Subtitles Plugin with the Brightcove Native Player SDK prior to verison 6.0, be aware that the `BrightcoveSidecarSubtitles` module is now integrated into the core `BrightcovePlayerSDK` framework. No functional code changes are required, but you should make these changes for your build: -**Important Note: AirPlay 2 is only supported on devices running iOS 11.4 or later.** +* If using CocoaPods, remove all references to `BrightcoveSidecarSubtitles` from your Podfiles, and then update. +* For manual installations, remove the BrightcoveSidecarSubtitles.framework from your project. +* In your source code, change any #includes from `` to ``. +* Remove any imports that refer to the `BrightcoveSidecarSubtitles` module. +* In your target's Build Settings, remove any reference to the BrightcoveSidecarSubtitles.framework from your Framework Search Paths. +* In your target's General settings, remove any reference to BrightcoveSidecarSubtitles from the Embedded Binaries and Linked Frameworks and Libraries sections Video 360 ========== @@ -574,20 +601,28 @@ The Brightcove Player SDK for iOS provides play, pause, and seek methods on the Preloading Videos ------------------------------- -If desired you may choose to preload upcoming videos in a playlist. One possible approach is to double-buffer a list of videos using two playback controllers, for example: +**NOTE:** *Preloading videos is no longer recommended, and this functionality may be removed in a future release.* + +The Brightcove Player SDK for iOS provides the ability to preload upcoming videos in a playlist. By default, this functionality is disabled because of the large amount of memory preloading may use. You can turn on preloading to help ensure futures videos load quickly, however you might want to take into account the amount of memory available on the client's device and speed of their connection. If they are not on Wifi, preloading a video may affect the current video's network resources. + +[`BCOVBasicSessionProviderOptions`][options] and [`BCOVBasicSessionLoadingPolicy`][loadingpolicy] provide two factory methods to modify preloading behavior that are described below: + +* `+sessionPreloadingNever` This method returns a session preloading policy that never preloading videos. This is the default setting. +* `+sessionPreloadingWithProgressPercentage:` This method returns a session preloading policy that preloads the next video in a playlist after the provided percentage of the current video has been reached. If a value below 0 or greater than 100 is used, then `sessionPreloadingNever` is used. Some plugins may ignore this setting. + +An example: + + BCOVPlayerSDKManager *manager = [BCOVPlayerSDKManager sharedManager]; + [1] BCOVBasicSessionLoadingPolicy *policy = [BCOVBasicSessionLoadingPolicy sessionPreloadingWithProgressPercentage:50]; + BCOVBasicSessionProviderOptions *options = [[BCOVBasicSessionProviderOptions alloc] init]; + options.sessionPreloadingPolicy = policy; + id provider = [manager createBasicSessionProviderWithOptions:options]; -1. Initialize two playback controllers -1. Set up your player view and assign one of the two playback controllers to the playerView's playbackController property (now your active playback controller) -1. Once your playlist is ready assign the playlist (or just the videos array property) to a property as we'll need to access each video separately -1. Get the first video in the videos array and give it to the active playback controller (`[self.playbackController1 setVideos:@[self.videos.firstObject]]`) -1. Utilizing the `playbackController:didProgressTo:` delegate method of the playback controller determine if the current video has progressed far enough to where you want to begin preloading the next video -1. Once you determine it's time to preload get the next video in the videos array and set it on the alternate playback controller -1. Once the current video has completed set the playbackController on the playerView to the alternate playback controller -1. Rinse and repeat steps 5-7 +1. Create a session preloading policy which starts preloading of an upcoming session when the current session reaches 50% of progress. -For a working example you may download our [VideoPreloading](https://github.com/BrightcoveOS/ios-player-samples/tree/master/Player/VideoPreloading) sample app from our [Player Samples](https://github.com/BrightcoveOS/ios-player-samples) repository. +[options]:https://github.com/brightcove/brightcove-player-sdk-ios/blob/fd5e766693e533854f202f270d3d62e32ceaae04/ios/dynamic/BrightcovePlayerSDK.framework/Headers/BCOVBasicSessionProvider.h#L111-L129 -**Note: You might want to take into account the amount of memory available on the client's device and speed of their connection. If they are not on Wifi, preloading a video may affect the current video's network resources.** +[loadingpolicy]:https://github.com/brightcove/brightcove-player-sdk-ios/blob/fd5e766693e533854f202f270d3d62e32ceaae04/ios/dynamic/BrightcovePlayerSDK.framework/Headers/BCOVBasicSessionProvider.h#L80-L102 Source Selection (HLS, MP4, HTTP/HTTPS) --------------------------------------- @@ -621,33 +656,8 @@ If this default selection policy does not work for you, there are a few alternat Please be aware there are App Store limitations regarding the use of MP4 videos. Check the latest Apple Developer information for details. -Setting a Preferred Bitrate ---------------------------- -The Brightcove Player SDK for iOS provides a way to set the preferred bitrate for a video. You can create a BCOVPreferredBitrateConfig object that contains your desired bitrate options, along with some configuration for the view controller which is created to display the options. -The title for the menu is optional. The bitrate options are an array of NSDictionary's with each dictionary having one key:value pair. The key will be used as the option name, and the value is an NSNumber with the bitrate for that option in bps (bits per second). The bitrates you enter are values that can be mapped to bitrates of the renditions of your video assets. You can learn more about renditions in [Ingest Profiles Best Practices]. - -Here is an example: - - BCOVPUIPlayerViewOptions *options = [[BCOVPUIPlayerViewOptions alloc] init]; - options.preferredBitrateConfig = [BCOVPreferredBitrateConfig configWithMenuTitle:@"Select an Option" andBitrateOptions:@[@{@"Auto":@(0)}, @{@"Setting 1":@(aBitrateValue)}, @{@"Setting 2":@(aBitrateValue)}]]; - -When the end-user selects one of the options, the [preferredPeakBitRate] property of the current AVPlayerItem will be set to the option's value. If the video is in a playlist, the next video played will also have the preferredPeakBitRate value set. - -After setting a non-zero value for [preferredPeakBitRate] you may not notice a difference in quality until AVPlayer has reached the end of its current buffered cache. - -You may additionally use the `configWithMenuTitle:bitrateOptions:andIndexofInitialSelection:` initializer that provides the ability to set the index of your preferred initial value. The index should correlate to the index of the desired option in the `bitrateOptions` array. - -You may additionally use the `setPreferredPeakBitRate:` method on your `BCOVPlaybackController` object to programatically set the preferred bitrate for the current and future sessions. - -NOTE: End-users must be given a way to return to the default value (0) of [preferredPeakBitRate]. You can do this by providing an option with a bitrate value of 0. If you do not provide a bitrate option of 0 an "Automatic" option will be appended to your list of options for the end-user. - -Please see Apple's documentation on [preferredPeakBitRate] for more information. - -[preferredPeakBitRate]:https://developer.apple.com/documentation/avfoundation/avplayeritem/1388541-preferredpeakbitrate -[Ingest Profiles Best Practices]:https://support.brightcove.com/ingest-profiles-best-practices - -Obtaining Content and Ad Playback Information +Obtaining Content And Ad Playback Information -------------------------------------- The Brightcove Player SDK for iOS provides two mechanisms for obtaining playback information. The playback controller provides a delegate property that implements [`BCOVPlaybackControllerDelegate`][delegate]. A delegate can implement these optional methods to get notified of playback metadata like progress, duration changes, and other events. If an ad plugin is installed, it may also use this delegate to provide information about [ad playback][adplayback]. The [lifecycle event][lifecycle] delegate method provides events to signal changes in playback state. For example, when a player goes from the paused state to the playing state, the lifecycle event delegate method will be called with the `kBCOVPlaybackSessionLifecycleEventPlay` event. The default Lifecycle events are declared in [`BCOVPlaybackSession`][lifecycleevents]. Plugins provided by Brightcove add additional lifecycle events which are defined in each plugin. @@ -740,7 +750,7 @@ As you can see in the example, `video1` has not been changed by the `-update` me Retrieving Brightcove Assets Using the Playback Service ------------------------ -The playback service class, `BCOVPlaybackService`, provides functionality for retrieving your Brightcove video assets and playlists via the [Brightcove Playback API][PlaybackAPI] , including rich metadata such as text tracks, previews, and thumbnails. The following example shows how to retrieve a video with a video ID. Methods for retrieving a video or playlist with that video's reference ID are also available. +The playback service class, `BCOVPlaybackService`, provides functionality for retrieving your Brightcove video assets and playlists via the [Brightcove Playback API][PlaybackAPI] , including rich metadata such as text tracks, previews, and thumbnails. The following example shows how to retrieve a video with a video ID. Methods for retrieving a video or playlist with that video's reference ID are also available.. [1] NSString *policyKey = ; NSString *accountId = ; @@ -765,8 +775,6 @@ The playback service class, `BCOVPlaybackService`, provides functionality for re 1. The playback service requests **policy key** for authentication. To learn more about policy key and how to obtain one, please refer to the [policy key documentation][PolicyKey]. -**NOTE: If you are using the Playback Authorization Service please review the [section](#PlaybackAuthorizationService) of this README related to that feature. - **Playlist Paging** For ``BCOVPlaybackService` methods that return a playlist, you can request a partial playlist, or "pages" from the playlist by specifying a limit and offset parameter in the parameters dictionary. The limit specifies the maximum number of videos that will be returned, and the offset specifies the index into the playlist at which videos will be returned. @@ -858,7 +866,7 @@ Again, for most use cases it should suffice to not use a view strategy at all. J There is one caveat to using a view strategy: you must not access the playback controller's `view` property from within the view strategy block. Since the block is being called *because* the playback controller's `view` property was accessed for the first time, accessing the `view` property again *within* the view strategy block will cause your program to crash. -Playing Video In The Background +Playing Video In The Background and Picture In Picture ------------- By default, when an iOS application is sent to the background, or the device is locked, iOS will pause any video that is playing. To change this behavior, set the `allowsBackgroundAudioPlayback` property of the `BCOVPlaybackController` object to `YES`. (The default value is `NO`, indicating playback will pause in the background.) @@ -866,45 +874,11 @@ You should also follow the guidelines set by Apple in [Technical Q&A QA1668][tqa It's important that the `AVPlayerLayer` be detached from the `AVPlayer` before the app is switched to the background (and reattached when the app returns to the foreground). The Brightcove Player SDK will handle this for you when `allowsBackgroundAudioPlayback` is set to `YES`. -Finally, when playing background videos (and particularly when using playlists), you should use the iOS `MPRemoteCommandCenter` API to give the user playback control on the lock screen and in the control center. - -[tqa1668]: https://developer.apple.com/library/ios/qa/qa1668 - -Picture in Picture -------------- -To enable Picture-in-Picture in your application, set the `showPictureInPictureButton` property of the `BCOVPUIPlayerViewOptions` object to `YES` when instantiating your `BCOVPUIPlayerView` object. The Picture-in-Picture button will then be displayed in the controls bar on any device that support it. - -For Picture-in-Picture to work properly you will need to ensure that the `Audio, AirPlay, and Picture in Picture` mode is turned in the `Background Modes` section of the target Capabilities tab of your project. You should also follow the guidelines set by Apple in [Technical Q&A QA1668][tqa1668] to set the proper background modes and audio session category for your app. - -Some `AVPictureInPictureControllerDelegate` methods are passed along via `BCOVPUIPlayerViewDelegate`. These methods are: - -``` -- (void)pictureInPictureControllerDidStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController; -- (void)pictureInPictureControllerDidStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController; -- (void)pictureInPictureControllerWillStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController; -- (void)pictureInPictureControllerWillStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController; -- (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController failedToStartPictureInPictureWithError:(NSError *)error -``` - -To implement your own Picture-in-Picture behavior, keep the `pictureInPictureActive` property of `BCOVPlaybackController` updated with the Picture-in-Picture status. If you are using the `AVPictureInPictureController`, you can use the `pictureInPictureControllerDidStartPictureInPicture:` and `pictureInPictureControllerDidStopPictureInPicture:` delegate methods to update this property. +Finally, when playing background videos (and particularly when using playlists), you should use the iOS `MPRemoteCommandCenter` API to give the user playback control on the lock screen and in the control center. Note that `MPRemoteCommandCenter` is only available in iOS 7.1 and later; if you need to support iOS 7.0, you should use `UIApplication`'s `beginReceivingRemoteControlEvents` and `endReceivingRemoteControlEvents`. -You can read more about implmeneting Picture-in-Picture in Apple's [Adopting Picture in Picture in a Custom Player](https://developer.apple.com/documentation/avkit/adopting_picture_in_picture_in_a_custom_player) documentation. +**Important Picture in Picture Note:** When you want to support background audio and Picture in Picture on the same player, you must update the `pictureInPictureActive` property on `BCOVPlaybackController` with the Picture in Picture status. If you are using the `AVPictureInPictureController`, you can use the `pictureInPictureControllerDidStartPictureInPicture:` and `pictureInPictureControllerDidStopPictureInPicture:` delegate methods to update this property. -**Important: The Brightcove Native Player SDK's Picture-in-Picture functionality does not support videos with ad playback. Trying to use a video with ads with the Picture-in-Picture functionality active will result in unexpected behavior.** - -Thumbnail Scrubbing -------------- -Thumbnail scrubbing allows users to drag the playhead along the timeline and view thumbnails as a preview of the associated content. This gives users the ability to quickly navigate a video file and find the content that they are interested in. - -This feature is also referred to by Apple as Trick Play, and is referenced in their [HLS Authoring Specification](https://developer.apple.com/documentation/http_live_streaming/hls_authoring_specification_for_apple_devices?language=objc). - -This feature is enabled by default. If you wish to disable thumbnail scrubbing you can do so by setting the `thumbnailScrubbingEnabled` property on your `BCOVPlaybackController` to `NO`. - -``` -self.playbackController.thumbnailScrubbingEnabled = NO; -``` - -Thumbnail scrubbing is only available for online videos; downloaded/offline videos do not support this feature. +[tqa1668]: https://developer.apple.com/library/ios/qa/qa1668 Tracking Errors ----- @@ -921,7 +895,7 @@ The session ID is a unique string that does not change during the app life cycle Combining Plugins ----- -If you need to combine Player SDK plugins, for example to add subtitles to a DRM-protected video which plays ads managed by Google IMA, `BCOVSessionProviders` from each plugin are created and chained together and the chain is used to construct the `BCOVPlaybackController`. +If you need to combine Player SDK plugins, for example to add subtitles to a DRM-protected video which plays ads managed by Google IMA. To achieve this, `BCOVSessionProviders` from each plugin are created and chained together, and the chain is used to construct the `BCOVPlaybackController`. ``` BCOVPlayerSDKManager *sdkManager = [BCOVPlayerSDKManager sharedManager]; @@ -965,7 +939,7 @@ Buffer Optimization Overview ----- -Developers have control over the size of the forward playback buffer used by the `AVPlayer`. This is done by setting the `preferredForwardBufferDuration` property in the `AVPlayerItem` class. +With the release of iOS 10, you now have control over the size of the forward playback buffer used by the `AVPlayer`. This is done by setting the `preferredForwardBufferDuration` property in the `AVPlayerItem` class. By default, the Brightcove Native Player SDK sets the `preferredForwardBufferDuration` property in a way that optimizes overall bandwidth without sacrificing playback quality. This behavior can be overridden with your own values. @@ -1001,7 +975,7 @@ These options should be set before calling `-BCOVPlaybackController setVideos:`. - If the values are set too small, playback may stall under erratic network conditions. - If the values are set too large, the `AVPlayer` may buffer data that is never viewed. - Testing based on your expected use cases is important. -- Values are specified in seconds of time, and must be greater than or equal to 1.0. (Zero is a special value in the `AVPlayerItem` that tells the `AVPlayer` to determine its own buffer size. +- Values are specified in seconds of time, and must be greater than or equal to 1.0. (Zero is a special value in the `AVPlayerItem` that tells the `AVPlayer` to determine its own buffer size, as is done with iOS 9 and earlier). Turning Off Buffer Optimization @@ -1017,7 +991,7 @@ If you do not want any buffer optimization active in your current playback sessi // Set new dictionary in your playback controller self.playbackController.options = options; -With the method set to “None”, iOS will maintain full control of the forward buffer size. +With the method set to “None”, iOS will maintain full control of the forward buffer size, as is done on iOS 9 and earlier. Implementing Your Own Buffer Optimization Method ----- @@ -1025,7 +999,7 @@ If you want to set your own buffer size for playback, first turn off buffer opti - (void)playbackController:(id)controller didAdvanceToPlaybackSession:(id)session { - // Make sure the property exists on the current AVPlayerItem. + // Make sure the property exists on the current AVPlayerItem. This will return false for iOS 9 or earlier. if ([session.player.currentItem respondsToSelector:NSSelectorFromString(@"preferredForwardBufferDuration")]) { // Set your preferredForwardBufferDuration value here. @@ -1033,11 +1007,13 @@ If you want to set your own buffer size for playback, first turn off buffer opti } } +**Important:** You must compile against the iOS 10 SDK to use the `preferredForwardBufferDuration` property directly. Do not attempt to access this property on iOS 9 or earlier, or your app will crash. + If you want to change the buffer size dynamically over time, you can set `session.player.currentItem.preferredForwardBufferDuration` in the `BCOVPlaybackController`'s progress delegate method in a similar fashion: - (void)playbackController:(id)controller playbackSession:(id)session didProgressTo:(NSTimeInterval)progress { - // Make sure the property exists on the current AVPlayerItem. + // Make sure the property exists on the current AVPlayerItem. This will return false for iOS 9 or earlier. if ([session.player.currentItem respondsToSelector:NSSelectorFromString(@"preferredForwardBufferDuration")]) { // Set preferredForwardBufferDuration based on your own logic here @@ -1071,97 +1047,19 @@ To use the AVPlayerViewController, you can set a BCOVPlaybackController dictiona The default value of kBCOVAVPlayerViewControllerCompatibilityKey is @NO, which means that a BCOVPlaybackController created without this dictionary property explicitly set will use the BCOVPlaybackSession's AVPlayerLayer by default. -Sample Projects ---------------- -We have sample projects demonstrating the use of AVPlayerViewController with the Brightcove iOS SDK. You can find the [iOS sample project here](https://github.com/BrightcoveOS/ios-player-samples/tree/master/Player/NativeControls) and the [tvOS sample project here](https://github.com/BrightcoveOS/ios-player-samples/tree/master/IMA/NativeControlsIMAPlayer_tvOS). - Limitations to Using the AVPlayerViewController ----------------------------------------------- -**Advertising:** - -The Brightcove IMA and FreeWheel ad plugins are compatible when using AVPlayerViewController. You can use the AVPlayerViewController's `contentOverlayView` for the view in which to display ads. - -You may wish to hide/show the AVPlayerViewController's playback controls before and after ads play: +Advertising: +Using the AVPlayerViewController's AVPlayerLayer will not work with the iOS SDK advertising plugins: +IMA Plugin +FreeWheel Plugin +OnceUX Plugin -``` -- (void)playbackController:(id)controller playbackSession:(id)session didEnterAdSequence:(BCOVAdSequence *)adSequence -{ - self.avpvc.showsPlaybackControls = NO; -} - -- (void)playbackController:(id)controller playbackSession:(id)session didExitAdSequence:(BCOVAdSequence *)adSequence -{ - self.avpvc.showsPlaybackControls = YES; -} -``` -The Brightcove SSAI and Pulse ad plugins are not currently compatible with AVPlayerViewController. - -**Analytics:** +due to the use by those plugins of a separate instance of the AVPlayer. +Analytics: When using the AVPlayerViewController, the video_engagement events sent to the Brightcove Analytics server will report 0 for player_width and player_height. -Playback Authorization Service -================= -If you are using the Playback Authorization Service you will need to use the playback service methods that allow you to pass in an authorization token. - -``` -- (void)findPlaylistWithPlaylistID:(NSString *)playlistID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler; - -- (void)findPlaylistWithReferenceID:(NSString *)referenceID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler; - -- (void)findVideoWithVideoID:(NSString *)videoID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler; - -- (void)findVideoWithReferenceID:(NSString *)referenceID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler; - -``` - -**Note: In the case of playlists, all videos in the playlist must use the same token. In a subsequent release, assigning a different token to each video in a playlist will be possible. You will be responsible for maintaining the mapping between video id and token.** - -VoiceOver Support -================= - -VoiceOver is supported out-of-the-box for the playback controls. By default, if VoiceOver is enabled, the BCOVPlayerUI control view will not auto-hide. Using the double-tap VoiceOver activation gesture on the playback controller's view will toggle the visibility of the control view. There is an associated `accessibilityHint` that is set on the playback controller's view. The `accessibilityLabel` of each BCOVPlayerUI control can be customized within your application. - -To change the `accessibilityLabel` values of any of the buttons in the control view you must set an object to be a `BCOVPUIButtonAccessibilityDelegate` like this: - - [self.playerView.controlsView setButtonsAccessibilityDelegate:self]; - -You must then have that object conform to the `BCOVPUIButtonAccessibilityDelegate` protocol by implmenting the `- (NSString *)accessibilityLabelForButton:(BCOVPUIButton *)button isPrimaryState:(BOOL)isPrimaryState` method similar to this: - - - (NSString *)accessibilityLabelForButton:(BCOVPUIButton *)button isPrimaryState:(BOOL)isPrimaryState - { - switch (button.tag) - { - case BCOVPUIViewTagButtonPlayback: - return isPrimaryState ? NSLocalizedString(@"Start Playback", nil) : NSLocalizedString(@"Stop PLayback", nil); - case BCOVPUIViewTagButtonScreenMode: - return isPrimaryState ? NSLocalizedString(@"Enter Fullscreen", nil) : NSLocalizedString(@"Exit Fullscreen", nil); - case BCOVPUIViewTagButtonJumpBack: - return nil; - case BCOVPUIViewTagButtonClosedCaption: - return nil; - case BCOVPUIViewTagButtonVideo360: - return nil; - case BCOVPUIViewTagButtonPreferredBitrate: - return nil; - default: - return nil; - } - } - -If a `nil` value is returned the default value will be used. - -Setting the `accessibilityHint` on the playback controller can be done like this: - - self.playbackController.view.accessibilityHint = @"Double tap to show or hide controls"; - -Similarly you can set the `accessibilityLabel` on the current time and duration labels, along with the progress slider, like this: - - self.playerView.controlsView.durationLabel.accessibilityLabelPrefix = @"Total Time"; - self.playerView.controlsView.currentTimeLabel.accessibilityLabelPrefix = @"Current Time"; - self.playerView.controlsView.progressSlider.accessibilityLabel = @"Timeline"; - - Frequently Asked Questions ========================== **My content won't load. Is there an easy way to test whether the URL points to a valid video?** diff --git a/SidecarSubtitles.md b/SidecarSubtitles.md index 3c1a475d..eeb22c59 100644 --- a/SidecarSubtitles.md +++ b/SidecarSubtitles.md @@ -1,4 +1,4 @@ -# Using Sidecar Subtitles With The Brightcove Player SDK for iOS, version 6.7.7.1171 +# Using Sidecar Subtitles With The Brightcove Player SDK for iOS, version 6.3.12 Introduction =================== @@ -49,7 +49,7 @@ BCOVSidecarSubtitles adds some category methods to BCOVPlaybackManager. The firs * If you are developing for tvOS, the viewStrategy passed to createSidecarSubtitlesPlaybackControllerWithViewStrategy must be nil. -* Note that `BCOVSSSessionProvider` should come before any session providers in the chain passed to the manager when constructing the playback controller. +* Note that `BCOVSSSessionProvider` should come before any session providers in the chain passed to the manager when constructing the playback controller. This extension is **not compatible** with the Widevine plugin. If you have questions or need help, visit the support forum for Brightcove Native Player SDKs at https://groups.google.com/forum/#!forum/brightcove-native-player-sdks . @@ -194,6 +194,8 @@ Known Issues * Subtitles will not be displayed when viewing 360 degree videos. +* This extension currently does not support integrating with the Widevine Plugin for Brightcove Brightcove Player SDK for iOS. + * When retrieving your videos from the Brightcove Playback API, your renditions must include a master M3U8 playlist. Sidecar Subtitles does not work with single rendition M3U8 playlists. * If you are providing a subtitle playlist to the Sidecar Subtitles, and that subtitle playlist includes links to web vtt files that respond as 404, playback will fail. This is a bug in Apple's AVPlayer. diff --git a/TVPlayer.md b/TVPlayer.md index 892b947d..167ca801 100644 --- a/TVPlayer.md +++ b/TVPlayer.md @@ -1,4 +1,4 @@ -# Using the TV Player UI With The Brightcove Player SDK for tvOS, version 6.7.7.1171 +# Using the TV Player UI With The Brightcove Player SDK for tvOS, version 6.3.12 ## Overview The Brightcove Native Player SDK provides a full set of controls for playback in tvOS on Apple TV known as the TV Player. The TV Player provides playback controls for both regular video content, and video content with Brightcove Server-Side Ad Insertion (SSAI) enabled. @@ -217,6 +217,6 @@ Support ---------------- If you have questions or need help, we have a support forum for Brightcove's native Player SDKs at . -[ssai]: https://sdks.support.brightcove.com/features/implementing-server-side-ads-native-player-sdks.html +[ssai]: https://support.brightcove.com/video-cloud-ssai-native-player-sdks [bcovsdk]: https://github.com/brightcove/brightcove-player-sdk-ios diff --git a/html/Blocks/BCOVBasicSessionProviderSourceSelectionPolicy.html b/html/Blocks/BCOVBasicSessionProviderSourceSelectionPolicy.html index 047879b5..8dfef82f 100644 --- a/html/Blocks/BCOVBasicSessionProviderSourceSelectionPolicy.html +++ b/html/Blocks/BCOVBasicSessionProviderSourceSelectionPolicy.html @@ -80,7 +80,7 @@

BCOVBasicSessionProviderSourceSelectionPolicy Block Reference<