shaka-player

# Shaka Player v2 Offline Design last update: 2016-05-24 by: [joeyparrish@google.com](mailto:joeyparrish@google.com) ## Overview Offline storage in Shaka Player v2 will be represented by an instance of `shaka.offline.Storage`. The API for offline storage will not be on `shaka.Player` so that offline capabilities can be trivially omitted from the build. Internal classes used to implement offline storage/playback will live in the `shaka.offline` namespace. Everything in the `shaka.offline` namespace will be listed in `build/types/offline` for quick exclusion of the feature. `Storage` will store streams for offline playback, allow selection of which tracks to store, provide progress information while storing streams, allow the listing of stored content, and allow the removal of stored content. To reduce the number of parameters in the `store()` method, we will offer a `configure()` interface to set callbacks. We will also provide a default track-selection callback to make it easier to get started. Backward compatibility with stored content from v1 is an explicit non-goal. If it turns out that there is a need in the community to migrate stored content from v1 to v2, a simple migration utility can be written later. #### `Storage` API sketch ```js new shaka.offline.Storage(player) shaka.offline.Storage.support => boolean // NOTE: Not connected to player.configure(). shaka.offline.Storage.prototype.configure({ trackSelectionCallback: function(allTracks) { // The default callback selects: // 1. highest bandwidth video track with height <= 480, // 2. middle bandwidth audio track with best audio pref language match, // 3. all text tracks with any text pref language match. // Return an array of selected Tracks. }, progressCallback: function(storedContent, percentComplete) {} }); // Store content and metadata. shaka.offline.Storage.prototype.store(manifestUri, appMetadata, manifestParser) => Promise.<StoredContent> // Remove stored content and metadata. shaka.offline.Storage.prototype.remove(storedContent) => Promise // List stored content. shaka.offline.Storage.prototype.list() => Promise.<Array.<StoredContent>> StoredContent: offlineUri: string // at which the stored content can be accessed originalManifestUri: string // the original manifest URI of the content we stored duration: number // length of the stored content in seconds size: number // size of the stored content in bytes tracks: !Array.<shaka.extern.Track> // the tracks we stored appMetadata: object // arbitrary format, provided by the application to store() ``` #### Implementation Like v1, v2 will use IndexedDB for storage. In v1, applications were required to persist the list of stored content and any app metadata in window.localStorage. In v2, we will provide an API to list stored content and we will store app metadata along-side the content. In v1, progress was inaccurate. It was calculated in terms of segments, even though segment sizes are very different between audio and video. In v2, progress can be calculated in terms of bytes, which will provide a more accurate percentage. If the index does not have byte ranges for segments, presumed segment sizes can be calculated based on average bitrate and duration. This will be accurate enough on average to provide a smooth progress bar. (Smooth relative to v1.) Actual bytes transferred will be tracked in the `StoredContent` structure. In v1, segments were combined into larger chunks to reduce the overhead of reading from the disk. This was premature optimization, as we had no data to suggest this was necessary. In v2, all segments will be stored in their original form. `store()` will transfer segment types (audio, video) in parallel, since some CDNs limit download rate based on the bandwidth requirements of the stream. `Storage` will have to load a manifest using the correct parser, filter the tracks as `Player` does, and invoke a callback to select streams. This should involve a factoring of the load and filtering logic of `Player`, perhaps into `ManifestParser` or `PlayerUtil`. These methods will not be exported. A `Player` instance is required to instantiate a `Storage`, and `Storage` will get manifest configuration from that instance. `Storage` will also need to use `DrmEngine` directly to persist licenses and get the session IDs. The session IDs will be stored in the database as part of the content. Removing a piece of content should result in any associated persistent sessions being released. A scheme plugin will register itself with `NetworkingEngine` to implement the `offline` scheme. Manifest URIs will be of the form `offline:123`, where `123` is an automatically-assigned ID representing the stored content. Segment URIs will be of the form `offline:123/7/99`, where `7` is an auto-ID for the track and `99` is an auto-ID for the segment. The scheme handler will handle `HEAD` requests and return a `Content-Type` header with the value `application/x-offline-manifest`. This type will be registered with `ManifestParser` in order to "parse the manifest" (load it from the database). To include offline support info in `Player.probeSupport()` but still make it possible to exclude offline from the build, `Player.probeSupport()` will now have a plugin interface. `Storage` will register its `support()` method with `Player` under the key `offline`. Overall library support is not contingent on the `basic` support of any of the plugins, including offline. Support plugins are synchronous, for simplicity. It's okay if the app selects multiple streams of a type. For text, this may be necessary, for example, to store subtitles for all languages. For audio it may be necessary as well, for similar reasons. For video it makes little sense, but we won't restrict it. Apps can make whatever decision they want about tracks to store, but we should document best practice. We could also issue a warning if multiple tracks of same type, kind, and language are selected, since offline adaptation is currently an uncommon scenario and may indicate a mistake on the part of the app developer. For example, this would trigger on two video with different bitrate or size, or two audio of same language but different bitrate, or two text of same language and kind. `Storage` will need good unit and integration tests. Integration tests should store a stream created by `StreamGenerator` and verify that the `StoredContent` structure is correct. A test should also load the stored data and verify that it matches the generated segments. #### Error conditions Errors during `store()`: - No IndexedDB support - No persistent license support - Out of storage space - Can't store a live stream - Any error that could occur during player.load() Errors while loading content: - Content not found - Persistent license cannot be loaded (may have been cleared by browser) - Any error that could occur during player.load()