diff --git a/docs/tutorials/index.json b/docs/tutorials/index.json index 5eae98dd83..ba85fa1cdd 100644 --- a/docs/tutorials/index.json +++ b/docs/tutorials/index.json @@ -16,7 +16,8 @@ "title": "Upgrade Guide", "children": { "upgrade-v1": { "title": "Upgrade Guide, v1 => v2.1" }, - "upgrade-v2-0": { "title": "Upgrade Guide, v2.0 => v2.1" } + "upgrade-v2-0": { "title": "Upgrade Guide, v2.0 => v2.1" }, + "upgrade-v2-1": { "title": "Upgrade Guide, v2.1 => v2.2" } } } } ] diff --git a/docs/tutorials/plugins.md b/docs/tutorials/plugins.md index 2c5962f8a8..d946ac9f40 100644 --- a/docs/tutorials/plugins.md +++ b/docs/tutorials/plugins.md @@ -39,6 +39,13 @@ __Subtitle/caption parsers__ - TTML: {@linksource shaka.media.TtmlTextParser} and {@linksource shaka.media.Mp4TtmlParser} +__Subtitle/caption displayers__ + - Configured at runtime on a Player instance + - Use {@link player.configure} and set the `textDisplayFactory` field + - Must implement the {@link shakaExtern.TextDisplayer} interface + - Default TextDisplayer implementation: + {@linksource shaka.text.SimpleTextDisplayer} + __Networking plugins__ - Selected by URI scheme (http, https, etc.) - Register with {@link shaka.net.NetworkingEngine.registerScheme} @@ -48,7 +55,7 @@ __Networking plugins__ __ABR plugins__ - Configured at runtime on a Player instance - - Use {@link player.configure} and set the `abr.manager` field + - Use {@link player.configure} and set the `abrFactory` field - Must implement the {@link shakaExtern.AbrManager} interface - Default AbrManager implementation: {@linksource shaka.abr.SimpleAbrManager} diff --git a/docs/tutorials/upgrade-v1.md b/docs/tutorials/upgrade-v1.md index cb35456f45..39e68d2cb4 100644 --- a/docs/tutorials/upgrade-v1.md +++ b/docs/tutorials/upgrade-v1.md @@ -23,6 +23,16 @@ Shaka v2 has several improvements over v1, including: - New plugin and build system to extend Shaka - Cache-friendly networking - Simpler, mobile-friendly demo app + - Basic HLS support + - DASH trick mode support + - Support for jumping gaps in the timeline + - Additional stats and events from Player + - Indication of critical errors vs recoverable errors + - Allowing applications to render their own text tracks + - Making the default ABR manager more configurable + - Adding channel count and bandwidth info to variant tracks + - Xlink support in DASH + - New option for offline protected content without persistent licensing #### Shaka Plugins @@ -347,11 +357,8 @@ and custom AbrManagers are now provided via `player.configure()`: ```js // v2: var player = new shaka.Player(video); -var customAbrManager = new MyCustomAbrManager(); player.configure({ - abr: { - manager: customAbrManager - } + abrFactory: MyCustomAbrManager }); player.load(manifestUri); ``` @@ -536,9 +543,10 @@ player.getStats() bufferingTime: number // seconds, same as v1 switchHistory: Array of Objects // replaces v1's streamHistory timestamp: number // seconds, when the stream was selected - id: number // stream ID + id: number // track ID type: string // 'variant' or 'text' fromAdaptation: boolean // distinguishes between ABR and manual choices + bandwidth: ?number // track's bandwidth (null for text tracks) stateChange: Array of Objects timestamp: number // seconds, when the state changed state: string // 'buffering', 'playing', 'paused', or 'ended' diff --git a/docs/tutorials/upgrade-v2-0.md b/docs/tutorials/upgrade-v2-0.md index bc4c087410..606a6f786d 100644 --- a/docs/tutorials/upgrade-v2-0.md +++ b/docs/tutorials/upgrade-v2-0.md @@ -1,11 +1,11 @@ -# Shaka Upgrade Guide, v2.0 => v2.1 +# Shaka Upgrade Guide, v2.0 => v2.2 -This is a detailed guide for upgrading from Shaka Player v2.0 to v2.1. +This is a detailed guide for upgrading from Shaka Player v2.0 to v2.2. Feel free to skim or to search for the class and method names you are using in your application. -#### What's New in v2.1? +#### What's New in v2.1 and v2.2? Shaka v2.1 introduces several improvements over v2.0, including: - Basic HLS support @@ -14,6 +14,12 @@ Shaka v2.1 introduces several improvements over v2.0, including: - Asynchronous network filters - Additional stats and events from Player - Indication of critical errors vs recoverable errors + - Allowing applications to render their own text tracks + - Making the default ABR manager more configurable + - Adding channel count and bandwidth info to variant tracks + - Xlink support in DASH + - Stricter runtime type-checking of EME cert configuration + - New option for offline protected content without persistent licensing #### Selecting tracks @@ -30,7 +36,7 @@ var i = /* choose an index somehow */; player.selectTrack(videoTracks[i]); ``` -In Shaka v2.1, audio and video tracks are combined into a variant track. It is +In Shaka v2.2, audio and video tracks are combined into a variant track. It is not possible to select individual audio/video streams, you can only select a specific variant as specified by the manifest. This was necessary for us to support HLS. Text tracks are independent of variant tracks. @@ -40,22 +46,53 @@ You can get the currently available tracks using `getVariantTracks()` and `selectTextTrack()`. ```js -// v2.1: +// v2.2: var variantTracks = player.getVariantTracks(); var i = /* choose an index somehow */; player.selectVariantTrack(variantTracks[i]); ``` -The v2.0 methods `getTracks()` and `selectTrack()` are still present in v2.1, -but they are deprecated and will be removed in v2.2. However, they are not -completely backward compatible because of the `type` field. If you are looking -for `'video'` or `'audio'` in the `type` field, your application will need to -be updated to handle `'variant'` instead. - See also the {@link shakaExtern.Track} structure which is used for all track types (variant and text). +#### Setting and configuring ABR manager + +In Shaka v2.0 a custom abr manager could be set through +```js +player.configure({ + abr.manager: customAbrManager +}); +``` + +In v2.2 it's done through +```js +player.configure({ + abrFactory: customAbrManager +}); +``` + +The API for abr manager also changed. +In v2.0 default bandwidth estimate and restrictions were set through +`setDefaultEstimate()` and `setRestrictions()` methods. +In 2.2 they are set through `configure()` method which accepts a +{@link shakaExtern.AbrConfiguration} structure. The new method is more general, +and allows for the configuration of bandwidth upgrade and downgrade targets +as well. + +```js +// v2.0: +abrManager.setDefaultEstimate(defaultBandwidthEstimate); +abrManager.setRestrictions(restrictions); + +// v2.2: +abrManager.configure(abrConfigurations); +``` + +In v2.2, the v2.0 interfaces for setting and configuring abr manager are +still supported, but are deprecated. Support will be removed in v2.3. + + #### Selecting tracks and adaptation settings In v2.0, selecting a new video or audio track would implicitly disable @@ -69,10 +106,10 @@ player.selectTrack(videoTracks[i]); player.configure({abr: {enabled: true}}); ``` -In v2.1, any change in ABR state must be made explicitly if desired. +In v2.2, any change in ABR state must be made explicitly if desired. ```js -// v2.1 +// v2.2 player.selectVariantTrack(variantTracks[i]); // Adaptation state has not changed! // To explicitly disable: @@ -93,7 +130,7 @@ player.load(manifestUri); // Canadian French preferred for initial playback player.configure({ preferredAudioLanguage: 'el' }); // switch to Greek ``` -In Shaka v2.1, language selection during playback is explicit and separate from +In Shaka v2.2, language selection during playback is explicit and separate from the configuration. Configuration only affects the next call to `load()`, and will not change languages during playback. @@ -102,7 +139,7 @@ To list available languages, we provide the `getAudioLanguages()` and `selectAudioLanguage()` and `selectTextLanguage()`. ```js -// v2.1: +// v2.2: player.configure({ preferredAudioLanguage: 'fr-CA' }); player.load(manifestUri); // Canadian French preferred for initial playback @@ -138,8 +175,7 @@ For more information, see discussions here: If you have taken advantage of Shaka v2's plugin APIs, you may need to update your plugins to the new interfaces. -In v2.1, the v2.0 interfaces for text and manifest parsers are still supported, -but are deprecated. Support will be removed in v2.2. +The v2.0 interfaces for text and manifest are no longer supported. #### Text parser plugin changes @@ -167,19 +203,21 @@ function MyTextParser(data, periodOffset, segmentStartTime, segmentEndTime) { var cues = []; var parserState = new MyInternalParser(data); while (parserState.more()) { - cues.push(parserState.nextCueOrThrow(periodOffset)); + cues.push(new VTTCue(...)); } return cues; } ``` -In Shaka v2.1, the text parser interface is now a constructor. The interface +In Shaka v2.2, the text parser interface is now a constructor. The interface now has explicit methods for init segments and media segments, and parameters related to time offsets have been grouped together into one `TimeContext` parameter. +Also text parser plugins now return shaka.text.Cue objects instead of VTTCue or +TextTrackCue objects. ```js -// v2.1 +// v2.2 /** @constructor */ function MyTextParser() {} @@ -188,23 +226,49 @@ MyTextParser.prototype.parseInit = function(data) { checkInitSegmentOrThrow(data); }; + /** * @param {!ArrayBuffer} data * @param {shakaExtern.TextParser.TimeContext} timeContext - * @return {!Array.} + * @return {!Array.} */ MyTextParser.prototype.parseMedia = function(data, timeContext) { var cues = []; var parserState = new MyInternalParser(data); while (parserState.more()) { - cues.push(parserState.nextCueOrThrow(timeContext.periodStart)); + cues.push(new shaka.text.Cue(...)); } return cues; }; ``` -For more information, see the {@link shakaExtern.TextParser.TimeContext} and -{@link shakaExtern.TextParser} definitions in the API docs. +All application-specific text-parsing plugins MUST to be updated, +v2.2 does not have backward compatibility on this! +The `Shaka.text.Cue` class contains the same information about a text cue as +the VTTCue class, plus extra information about text style. + +For more information, see the {@link shakaExtern.TextParser.TimeContext}, +{@link shaka.text.Cue} and {@link shakaExtern.TextParser} definitions in +the API docs. + + +#### Customizing subtitle display + +Shaka v2 gave applications an opportunity to have a custom text parser, but +all the displaying was handled by the browser. Shaka v2.2 adds the +possibility to have custom logic for displaying text. By default the +rendering will still be done by the {@linksource shaka.text.SimpleTextDisplayer} +class. + +A custom text display factory can be specified by calling player.configure(). + +```js +player.configure({ + textDisplayFactory: customTextDisplayerClass +}); +``` + +See {@linksource shakaExtern.TextDisplayer} for details. #### Manifest parser plugin changes @@ -281,7 +345,7 @@ MyManifestParser.prototype.start = function(uri, playerInterface) { }; ``` -Shaka v2.1 also adds two new methods to the manifest parser interface: +Shaka v2.2 also adds two new methods to the manifest parser interface: `update()` and `onExpirationUpdated()`. The `update()` method allows `StreamingEngine` to ask for an explicit manifest @@ -289,7 +353,7 @@ update. This is used, for example, to support `emsg` boxes in MP4 content, which can be used by the stream to indicate that a manifest update is needed. ```js -// v2.1 +// v2.2 MyManifestParser.prototype.update = function() { // Trigger an update now! this.updateManifest_(); @@ -302,7 +366,7 @@ changed. We use this internally in our offline support, so that we can keep track of expiring licenses for stored content. ```js -// v2.1 +// v2.2 MyManifestParser.prototype.onExpirationUpdated = function(sessionId, expiration) { var oldExpiration = this.database_.getExpiration(this.contentId_); diff --git a/docs/tutorials/upgrade-v2-1.md b/docs/tutorials/upgrade-v2-1.md new file mode 100644 index 0000000000..a0b4790d3d --- /dev/null +++ b/docs/tutorials/upgrade-v2-1.md @@ -0,0 +1,154 @@ +# Shaka Upgrade Guide, v2.1 => v2.2 + +This is a detailed guide for upgrading from Shaka Player v2.1 to v2.2. +Feel free to skim or to search for the class and method names you are using in +your application. + + +#### What's New in v2.2? + +Shaka v2.2 introduces several improvements over v2.1, including: + - Allowing applications to render their own text tracks + - Making the default ABR manager more configurable + - Adding channel count and bandwidth info to variant tracks + - Xlink support in DASH + - Stricter runtime type-checking of EME cert configuration + - New option for offline protected content without persistent licensing + + +#### Customizing subtitle display + +Shaka v2 gave applications an opportunity to have a custom text parser, but +all the displaying was handled by the browser. Shaka v2.2 adds the +possibility to have custom logic for displaying text. By default the +rendering will still be done by the {@linksource shaka.text.SimpleTextDisplayer} +class. + +A custom text display factory can be specified by calling player.configure(). + +```js +player.configure({ + textDisplayFactory: customTextDisplayerClass +}); +``` + +See {@linksource shakaExtern.TextDisplayer} for details. + + +#### Text parser API changes + +The text-parsing plugin API has changed. Plugins now return `shaka.text.Cue` +objects instead of VTTCue or TextTrackCue objects like in v2.1. + +```js +// v2.1 +/** + * @param {!ArrayBuffer} data + * @param {shakaExtern.TextParser.TimeContext} timeContext + * @return {!Array.} + */ +MyTextParser.prototype.parseMedia = function(data, timeContext) { + var cues = []; + var parserState = new MyInternalParser(data); + while (parserState.more()) { + cues.push(new VTTCue(...)); + } + return cues; +}; + +// v2.2 +/** + * @param {!ArrayBuffer} data + * @param {shakaExtern.TextParser.TimeContext} timeContext + * @return {!Array.} + */ +MyTextParser.prototype.parseMedia = function(data, timeContext) { + var cues = []; + var parserState = new MyInternalParser(data); + while (parserState.more()) { + cues.push(new shaka.text.Cue(...)); + } + return cues; +}; +``` + +All application-specific text-parsing plugins MUST to be updated, +v2.2 does not have backward compatibility on this! +Shaka.text.Cue class contains the same information about a text cue as +VTTCue class plus extra information about text style. + +See {@link shaka.text.Cue} for details. + + +#### Setting and configuring ABR manager + +In Shaka v2.1 a custom abr manager could be set through +```js +player.configure({ + abr.manager: customAbrManager +}); +``` + +In v2.2 it's done through +```js +player.configure({ + abrFactory: customAbrManager +}); +``` + +The API for abr manager also changed. +In v2.1 default bandwidth estimate and restrictions were set through +`setDefaultEstimate()` and `setRestrictions()` methods. +In 2.2 they are set through `configure()` method which accepts a +{@link shakaExtern.AbrConfiguration} structure. The new method is more general, +and allows for the configuration of bandwidth upgrade and downgrade targets +as well. + +```js +// v2.1: +abrManager.setDefaultEstimate(defaultBandwidthEstimate); +abrManager.setRestrictions(restrictions); + +// v2.2: +abrManager.configure(abrConfigurations); +``` + +In v2.2, the v2.1 interfaces for setting and configuring abr manager are +still supported, but are deprecated. Support will be removed in v2.3. + + +#### Switch history changes +In v2.1 `shakaExtern.Stats` had a member `shakaExtern.StreamChoice` structure +named switchHistory that had a type field containing the changed stream's +type ('audio', 'video' or 'text'). + +In 2.2 shakaExtern.StreamChoice was renamed shakaExtern.TrackChoice to +reflect that it contains information about the changed track rather than +stream. The type field now represents the changed track's type: +'variant' or 'text'. It also now contains track's bandwidth. Similarly, the +id field is now a track id instead of stream id. + +```js +// v2.1: +/* + * @typedef {{ + * timestamp: number, + * id: number, // stream id + * type: string, // 'audio'/'video'/'text' + * fromAdaptation: boolean + * }} + */ +shakaExtern.StreamChoice; + +// v2.2: +/* + * @typedef {{ + * timestamp: number, + * id: number, // track id + * type: string, // 'variant'/'text' + * fromAdaptation: boolean, + * bandwidth: ?number + * }} + */ +shakaExtern.TrackChoice; +```