Bigscreen Player
![Build Status](https://travis-ci.com/bbc/bigscreen-player.svg?branch=master)
Simplified media playback for bigscreen devices.
Introduction
The Bigscreen Player is an open source project developed by the BBC to simplify video and audio playback on a wide range of 'bigscreen' devices (TVs, set-top boxes, games consoles, and streaming devices).
This project should be considered Work in Progress. A full roadmap will be released soon.
Getting Started
$ npm install
Example Usage
We have a working example app - see docs/example-app.
Initialisation
Bigscreen Player uses requirejs for managing dependencies. Once you have required the player, a playback session can be initalised by simply calling the init()
function with some initial data.
The player will render itself into a supplied parent element, and playback will begin as soon as enough data has buffered.
require(
[
'bigscreenplayer/bigscreenplayer',
'bigscreenplayer/windowtypes',
'bigscreenplayer/mediakinds'
],
function (BigscreenPlayer, WindowType, LiveSupport, MediaKind) {
window.bigscreenPlayer.playbackStrategy = 'msestrategy';
var bigscreenPlayer = BigscreenPlayer();
var playbackElement = document.createElement('div');
playbackElement.id = 'BigscreenPlayback';
var body = document.getElementByTagName('body')[0];
body.appendChild(playbackElement);
var minimalData = {
media: {
mimeType: 'video/mp4',
urls: [
{
url: 'https://www.cdn1url.com/reallygoodvideo'
}
]
}
}
var optionalData = {
initialPlaybackTime: 0,
media: {
mimeType: 'video/mp4',
bitrate: 8940,
captionsUrl: 'https://www.somelovelycaptionsurl.com/captions',
codec: 'h264',
kind: MediaKind.VIDEO,
urls: [
{
url: 'https://www.cdn1url.com/reallygoodvideo',
cdn: 'cdn1'
}, {
url: 'https://www.cdn2url.com/reallygoodvideo',
cdn: 'cdn2'
}
]
}
}
var windowType = WindowType.STATIC;
var liveSupport = 'seekable';
var enableSubtitles = false;
bigscreenPlayer.init(playbackElement, optionalData, windowType, enableSubtitles, liveSupport);
}
)
Configuration
The Bigscreen Player has some global configuration that is needed before initialisation. A playback strategy must be configured:
window.bigscreenPlayer.playbackStrategy = 'msestrategy'
See the configuration wiki page for further details on these strategies.
Reacting to state changes
State changes which are emitted from the player can be acted upon to by registering a callback. The callback will receive all of the following state changes as the state
property of the event:
- MediaState.STOPPED
- MediaState.PAUSED
- MediaState.PLAYING
- MediaState.WAITING
- MediaState.ENDED
- MediaState.FATAL_ERROR
State changes may be registered for before initialisation and will automatically be cleared upon tearDown()
of the player.
var bigscreenPlayer = BigscreenPlayer();
var stateChangeToken = bigscreenPlayer.registerForStateChanges(function (event) {
if(event.state == MediaState.PLAYING) {
console.log('Playing');
}
});
bigscreenPlayer.unRegisterForStateChanges(stateChangeToken);
Reacting to time updates
Time updates are emitted multiple times a second. Your application can register to receive these updates. The emitted object contains the currentTime
and endOfStream
properties.
Time updates may be registered for before initialisation and will automatically be cleared upon tearDown()
of the player.
var bigscreenPlayer = BigscreenPlayer();
var timeUpdateToken = bigscreenPlayer.registerForTimeUpdates(function (event) {
console.log('Current Time: ' + event.currentTime);
});
bigscreenPlayer.unRegisterForTimeUpdates(timeUpdateToken);
Creating a plugin
Plugins can be created to extend the functionality of the Bigscreen Player by adhering to an interface which propogates non state change events from the player. For example, when an error is raised or cleared.
The full interface is as follows:
- onError
- onFatalError
- onErrorCleared
- onErrorHandled
- onBuffering
- onBufferingCleared
- onScreenCapabilityDetermined
An example plugin may look like:
function ExamplePlugin (appName) {
var name = appName;
function onFatalError (evt) {
console.log('A fatal error has occured in the app: ' + name);
}
function onErrorHandled (evt) {
console.log('The ' + name + ' app is handling a playback error');
}
return {
onFatalError: onFatalError,
onErrorHandled: onErrorHandled
};
}
var bigscreenPlayer = BigscreenPlayer();
var examplePlugin = ExamplePlugin('myApp');
bigscreenPlayer.registerPlugin(examplePlugin);
bigscreenPlayer.unregisterPlugin(examplePlugin);
Testing
The project is fully unit tested using the Jasmine framework. To run the tests:
$ npm run spec
This project currently has unit test coverage but no integration test suite. This is on our Roadmap to address. Quality is ensured via extensive manual testing however.
Mocking media playback
When writing tests for your application it may be useful to use the mocking functions provided. This creates a fake player with mocking hook functions to simulate real world scenarios.
See here for example usage.
API Reference
The full api is documented here.
Contributing
Whilst it is the intention of the BBC to fully Open Source this project, it is currently work in progress, and as such, there is no contribution model, support model or roadmap. Each of these will be made available in due course.
License
The Bigscreen Player is available to everyone under the terms of the Apache 2.0 open source licence. Take a look at the LICENSE file in the code for more information.