/srgletterbox-ios-1

The official SRG SSR media playback experience for iOS

Primary LanguageObjective-CMIT LicenseMIT

Carthage compatible

About

The SRG Letterbox library defines the official SRG SSR media player experience, packed into a single library, providing:

  • A controller to play audios and videos, which supports on-demand, live and DVR streams.
  • A service to manage application-wide playback.
  • A responsive player view with the official SRG SSR look and feel.
  • Support for 360° videos.
  • Support for chapter and segment browsing and selection.
  • Playlist support.
  • Access to all SRG SSR business unit medias.
  • Native AirPlay and picture in picture support.
  • Seamless integration with the SRG SSR analytics SDK when used.
  • ... and a lot more.

To ensure a coherent visual player identity throughout SRG SSR applications, the design is intentionally not intended for customization, and will follow future design evolutions. If you need a completely custom player, you should rather use the SRG Media Player library instead, on top of which Letterbox itself is implemented.

Compatibility

The library is suitable for applications running on iOS 9 and above. The project is meant to be opened with the latest Xcode version (currently Xcode 10).

Contributing

If you want to contribute to the project, have a look at our contributing guide.

Installation

The library can be added to a project using Carthage. For more information about Carthage and its use, refer to its official documentation.

Installation with content protection

The ability to play protected content (e.g. livestreams, foreign TV series) is provided by an internal SRG Content Protection framework. If you have access to it, integrate Letterbox by adding the following dependencies to your Cartfile:

github "SRGSSR/srgletterbox-ios"
github "SRGSSR/srgcontentprotection-ios"

Check the wiki for the recommended version of SRG Content Protection to use.

Installation without content protection

If you have no access to the internal SRG Content Protection framework, integrate Letterbox by adding the following dependencies to your Cartfile:

github "SRGSSR/srgletterbox-ios"
github "SRGSSR/srgcontentprotection-fake-ios"

Check the wiki for the recommended version of SRG Content Protection to use.

With this setup, non-protected content only (e.g. in-house productions or audio content) will be playable.

Dependencies

The library requires the following frameworks to be added to any target requiring it:

  • ComScore: The comScore framework.
  • FXReachability: A reachability framework.
  • libextobjc: A utility framework.
  • MAKVONotificationCenter: A safe KVO framework.
  • Mantle: The framework used to parse the data.
  • Masonry: An autolayout framework.
  • SRGAnalytics: The main analytics framework.
  • SRGAnalytics_MediaPlayer: The media player analytics companion framework.
  • SRGAnalytics_DataProvider: The data provider analytics companion framework.
  • SRGAppearance: The appearance framework.
  • SRGContentProtection: The framework to enable playback of protected medias.
  • SRGDiagnostics: Framework for collecting diagnostic information.
  • SRGLetterbox: The Letterbox library framework.
  • SRGLogger: The framework used for internal logging.
  • SRGMediaPlayer: The media player framework (if not already in your project).
  • SRGNetwork: A networking framework.
  • TCCore: The core TagCommander framework.
  • TCSDK: The main TagCommander SDK framework.
  • YYWebImage: A framework for image retrieval.

Dynamic framework integration

  1. Run carthage update to update the dependencies (which is equivalent to carthage update --configuration Release).
  2. Add the frameworks listed above and generated in the Carthage/Build/iOS folder to your target Embedded binaries.

If your target is building an application, a few more steps are required:

  1. Add a Run script build phase to your target, with /usr/local/bin/carthage copy-frameworks as command.
  2. Add each of the required frameworks above as input file $(SRCROOT)/Carthage/Build/iOS/FrameworkName.framework.

Static framework integration

  1. Run carthage update --configuration Release-static to update the dependencies.
  2. Add the frameworks listed above and generated in the Carthage/Build/iOS/Static folder to the Linked frameworks and libraries list of your target.
  3. Also add any resource bundle .bundle found within the .framework folders to your target directly.
  4. Some non-statically built framework dependencies are built in the Carthage/Build/iOS folder. Add them by following the Dynamic framework integration instructions above.
  5. Add the -all_load flag to your target Other linker flags.

Building the project

A Makefile provides several targets to build and package the library. The available targets can be listed by running the following command from the project root folder:

make help

Alternatively, you can of course open the project with Xcode and use the available schemes.

Private project settings (keys, tokens, etc.) are stored in a private repository, pulled under the Configuration directory when running make setup (or any other target depending on it). The SHA-1 of the configuration commit which is used is explicitly provided in the Makefile. Settings are therefore versioned alongside the project, providing for reproducible builds.

If you need to make changes to the settings:

  1. Perform the required changes in the Configuration directory (and in the project as well if needed).
  2. Switch to the Configuration directory and commit changes there.
  3. Update the Makefile CONFIGURATION_COMMIT_SHA1 variable to point at the configuration commit to use.
  4. Push all commits when you are ready.

Usage

When you want to use classes or functions provided by the library in your code, you must import it from your source files first.

Usage from Objective-C source files

Import the global header file using:

#import <SRGLetterbox/SRGLetterbox.h>

or directly import the module itself:

@import SRGLetterbox;

Usage from Swift source files

Import the module where needed:

import SRGLetterbox

Working with the library

To learn about how the library can be used, have a look at the getting started guide.

Logging

The library internally uses the SRG Logger library for logging, within the ch.srgssr.letterbox subsystem. This logger either automatically integrates with your own logger, or can be easily integrated with it. Refer to the SRG Logger documentation for more information.

Control preview in Interface Builder

Interface Builder can render custom controls dropped onto a storyboard or a xib. If you want to enable this feature for Letterbox controls, and after Carthage has been run, open the Carthage/Checkouts/srgletterbox-ios/Designables directory, copy the SRGLetterboxDesignables.m file it contains to your project and add it to your target.

When dropping a view (e.g. SRGLetterboxView) onto a storyboard or xib, Xcode will now build your project in the background and render the view when it is done.

If rendering does not work properly:

  • Be sure that your project correctly compiles
  • If you still get dlopen errors, this means some frameworks are not available to Xcode when it runs your project for rendering. This usually means that the copy-frameworks build phase described in the Carthage readme has not been setup properly. Be sure that all SRG Media Player dependencies are properly copied (see above framework list).

Demo project

To test what the library is capable of, run the associated demo.

Known issues

Control center and lock screen integrations are not working reliably in the iOS simulator. This is a known simulator-only limitation, everything works fine on a device.

Moreover, standard view controller transitions (e.g. screen edge pan in a navigation controller), more generally those based on UIPercentDrivenInteractiveTransition, will interfere with playback, since they alter layer speeds (and thus AVPlayerLayer speed). For a perfect result you should therefore implement your own transition animator. An example is supplied with the demo.

Standard system behaviors

If playback is paused from the application and the device is locked afterwards, the lock screen will surprisingly not display playback controls. This is standard iOS behavior (Apple Podcasts application works the same). Playback can be restarted from the control center, though.

Moreover, video playback is paused by the system automatically when putting the application in the background, except when picture in picture is used.

License

See the LICENSE file for more information.