Merge branch 'master' of https://github.com/bbc/bigscreen-player into…

… plugin-playback-rate

docs/arch/001-native-strategy.md

@@ -2,21 +2,23 @@
 
 Originally Added: February 20th, 2019
 
-# Context
+## Context
 
-* As it stands, `bigscreen-player` requires using the `tal` device object - when in `talstrategy` - to obtain a media player for playback
-* Since the `tal` device media player exists as a singleton, applications using `talstrategy` can only access one active media element.
-* Unlike `msestrategy`, `talstrategy` also requires loading in the extra dependency (`tal` device) - and is therefore limited by the limitations of the `tal` device.
+- As it stands, `bigscreen-player` requires using the `tal` device object - when in `talstrategy` - to obtain a media player for playback
+- Since the `tal` device media player exists as a singleton, applications using `talstrategy` can only access one active media element.
+- Unlike `msestrategy`, `talstrategy` also requires loading in the extra dependency (`tal` device) - and is therefore limited by the limitations of the `tal` device.
 
-# Decision
-* A new strategy type - `nativestrategy` - has been created which pulls the media player out of `tal`
-* This is a refactor of the `tal` device media player code which allows further manipulation and control i.e. multiple video playback
+## Decision
 
+- A new strategy type - `nativestrategy` - has been created which pulls the media player out of `tal`
+- This is a refactor of the `tal` device media player code which allows further manipulation and control i.e. multiple video playback
+
+## Status
 
-# Status
 Approved
 
-# Consequences
-* Multiple active video instances can be controlled  
-  * Preloading of content on different media elements is more achievable
-* The successful migration of all media player code from `tal` will create much greater modularity for `bigscreen-player` - therefore removing any limitations introduced by the current coupling with `tal`
+## Consequences
+
+- Multiple active video instances can be controlled
+  - Preloading of content on different media elements is more achievable
+- The successful migration of all media player code from `tal` will create much greater modularity for `bigscreen-player` - therefore removing any limitations introduced by the current coupling with `tal`

docs/arch/002-sinon.md

@@ -21,9 +21,9 @@ Accepted
 
 ## Consequences
 
-* Using sinon makes it simpler to provide custom responses to network requests.
-* Another third party library is now pulled into bigscreen-player as a dev dependency.
+- Using sinon makes it simpler to provide custom responses to network requests.
+- Another third party library is now pulled into bigscreen-player as a dev dependency.
 
 ## Further Reading
 
-See https://sinonjs.org/ for more information
+See <https://sinonjs.org/> for more information

docs/arch/003-subtitles-polling-frequency.md

@@ -4,7 +4,7 @@ Originally Added: April 7th, 2020
 
 ## Context
 
-Subtitles in Bigscreen Player are updated by checking for the next available subtitle using a set timeout of 750ms. 
+Subtitles in Bigscreen Player are updated by checking for the next available subtitle using a set timeout of 750ms.
 This number of 750ms was originally used with no record of why it was picked, and is also potentially too infrequent to keep the subtitles perfectly in sync with the audio and visual cues.
 There was a piece of work done to increase the polling rate to 250ms, however we found that this caused some slower devices to buffer due to the increased load on the devices memory.
 
@@ -18,5 +18,5 @@ Accepted
 
 ## Consequences
 
-* Synchronisation issues are negligible.
-* It does not cause device performance to suffer.
+- Synchronisation issues are negligible.
+- It does not cause device performance to suffer.

docs/arch/004-time-representation.md

@@ -0,0 +1,36 @@
+# 004 Removing `windowType`; changing time representation
+
+Originally added: 2025-02-03
+
+## Status
+
+| Discussing | Approved | Superceded |
+| ---------- | -------- | ---------- |
+|            | x        |            |
+
+## Context
+
+BigscreenPlayer supports DASH and HLS streaming. Each transfer format (aka streaming protocol) represents time in a stream in a different way. BigscreenPlayer normalised these times in versions prior to v9.0.0. This normalisation made multiple assumptions:
+
+- The timestamp in the media samples are encoded as UTC times (in seconds) for "sliding window" content i.e. streams with time shift.
+- Streams with time shift never use a presentation time offset.
+
+What is more, metadata (i.e. the `windowType`) determined BigscreenPlayer's manifest parsing strategy from v7.1.0 and codified these assumptions.
+
+- How might we overhaul our time representation to support streams that don't comply with these assumptions?
+
+### Considered Options
+
+1. Expose time reported by the `MediaElement` directly. Provide functions to convert the time from the `MediaElement` into availability and media sample time.
+2. Do not apply time correction based on `timeShiftBufferDepth` if `windowType === WindowTypes.GROWING`
+3. Do not apply time correction based on `timeShiftBufferDepth` if SegmentTemplates in the MPD have `presentationTimeOffset`
+
+## Decision
+
+Chosen option: 1
+
+This approach provides a lot of flexibility to consumers of BigscreenPlayer. It also simplifies time-related calculations such as failover, start time, and subtitle synchronisation.
+
+## Consequences
+
+A major version (v9.0.0) to remove window type and overhaul BigscreenPlayer's internals.

docs/arch/005-remove-fake-seeking.md

@@ -0,0 +1,34 @@
+# 005 Remove fake seeking from restartable strategy
+
+Originally added: 2025-02-04
+
+## Status
+
+| Discussing | Approved | Superceded |
+| ---------- | -------- | ---------- |
+|            | x        |            |
+
+## Context
+
+Native media players with the capability to start playback in a livestream from any (available) point in the stream are called "restartable" in BigscreenPlayer's jargon. Unlike "seekable" devices, "restartable" devices don't support in-stream navigation. In other words, seeking is not supported.
+
+BigscreenPlayer exploited this restart capability to implement "fake seeking" prior to v9.0.0. The restartable player effectively polyfilled the native media player's implementation of `MediaElement#currentTime` and `MediaElement#seekable`. This polyfill relied on the `windowType` metadata to make assumptions about the shape of the stream's seekable range. v9.0.0 deprecates `windowType`.
+
+- Should we continue to support fake seeking for native playback?
+- How might we continue to support fake seeking?
+
+### Considered Options
+
+1. Remove fake seeking from restartable strategy
+2. Poll the HLS manifest for time shift
+3. Provide a "magic" time shift buffer depth for HLS streams
+
+## Decision
+
+Chosen option: 1
+
+The effort to contine support for fake seeking on restartable devices is not justified by the small number of people that benefit from the continued support.
+
+## Consequences
+
+Viewers that use devices on the restartable strategy will no longer be able to pause or seek in-stream.

docs/arch/006-detect-autoresume.md

@@ -0,0 +1,36 @@
+# 006 Detect timeshift to enable auto-resume
+
+Originally added: 2025-02-04
+
+## Status
+
+| Discussing | Approved | Superceded |
+| ---------- | -------- | ---------- |
+|            | x        |            |
+
+## Context
+
+BigscreenPlayer's auto-resume feature prevents undefined behaviour when native players resume playback outside the seekable range. Auto-resume consists of two mechanisms:
+
+1. Playback is resumed before current time can drift outside of the seekable range
+2. Pausing isn't possible when current time is close to the start of the seekable range
+
+Auto-resume is only relevant for streams with time shift. The presence of time shift was signalled through the `windowType === WindowTypes.SLIDING` parameter prior to v9.0.0. v9.0.0 deprecates `windowType`.
+
+DASH manifests explicitly encode the time shift of the stream through the `timeShiftBufferDepth`. On the other hand, time shift in HLS manifests is only detectable by refreshing the manifest.
+
+- How might we detect timeshift and enable the auto-resume feature for DASH and HLS streams?
+
+### Considered Options
+
+1. Poll the HLS manifest to check if the first segment changes
+2. Poll the seekable range for changes to the start of the seekable range
+3. Provide a "magic" time shift buffer depth for HLS streams
+
+## Decision
+
+Chosen option: 2
+
+## Consequences
+
+The time it takes the `timeshiftdetector` to detect and signal timeshift depends on it's polling rate. Hence, there is a risk the user navigates outside of the seekable range in the span of time before the `timeshiftdetector` detects a sliding seekable range.

docs/arch/007-estimate-hls-ast.md

@@ -0,0 +1,44 @@
+# 007 Estimate HLS Availability Start Time
+
+Originally added: 2025-02-04
+
+## Status
+
+| Discussing | Approved | Superceded |
+| ---------- | -------- | ---------- |
+|            | x        |            |
+
+## Context
+
+BigscreenPlayer adds functions to convert between three timelines:
+
+1. Presentation time: Output by the MediaElement
+2. Media sample time: Timestamps encoded in the current media
+3. Availablity time: UTC times that denote time available. Only relevant for dynamic streams.
+
+BigscreenPlayer relies on metadata in the manifest to calculate each conversion.
+
+For DASH:
+
+- Presentation time <-> Media sample time relies on `presentationTimeOffset`
+- Presentation time <-> Availability time relies on `availabilityStartTime`
+
+For HLS:
+
+- Presentation time <-> Media sample time relies on `programDateTime`
+- Presentation time <-> Availability time relies on ???
+
+HLS signals availability through the segment list. An HLS media player must refresh the segment list to track availability. Availability start time can be estimated as the difference between the current wallclock time and the duration of the stream so far. This estimate should also correct for any difference between the client and server's UTC wallclock time.
+
+### Considered Options
+
+1. Accept the conversion between availability and presentation time is broken for HLS streams.
+2. Estimate availability start time for HLS streams. This requires clients provide the offset between the client and server's UTC wallclock time in order to synchronise the calculation.
+
+## Decision
+
+Chosen option: 1
+
+## Consequences
+
+The conversion between presentation time and availability start time is erroneous for HLS.

docs/arch/__template.md

@@ -0,0 +1,19 @@
+# 000 Title
+
+Originally added:
+
+## Status
+
+| Discussing | Approved | Superceded |
+| ---------- | -------- | ---------- |
+|            | x        |            |
+
+## Context
+
+### [Considered Options]
+
+Optional
+
+## Decision
+
+## Consequences

docs/tutorials/00-getting-started.md

@@ -22,13 +22,13 @@ Configuration for bigscreen-player can be set using an object on the window:
 window.bigscreenPlayer
 ```
 
-You must provide a *playback strategy* to use BigscreenPlayer:
+You must provide a _playback strategy_ to use BigscreenPlayer:
 
 ```javascript
-window.bigscreenPlayer.playbackStrategy = 'msestrategy' // OR 'nativestrategy' OR 'basicstrategy'
+window.bigscreenPlayer.playbackStrategy = "msestrategy" // OR 'nativestrategy' OR 'basicstrategy'
 ```
 
-The MSEStrategy uses DASH. It is most likely what you want. More detail in the [documentation on playback strategies](<https://bbc.github.io/bigscreen-player/api/tutorial-01-playback-strategies.html>). You should also have a peek at the [documentation on settings and overrides](https://bbc.github.io/bigscreen-player/api/tutorial-02-settings-and-overrides.html)
+The `msestrategy` uses Dash.js under the hood. It is likely to be what you want. You should read [the documentation on playback strategies](https://bbc.github.io/bigscreen-player/api/tutorial-01-playback-strategies.html) if you want to use a native media player from your browser. You should also have a peek at the [documentation on settings and overrides](https://bbc.github.io/bigscreen-player/api/tutorial-02-settings-and-overrides.html)
 
 ### Minimal Data
 
@@ -37,9 +37,9 @@ You must provide a manifest and its MIME type.
 ```javascript
 const minimalData = {
   media: {
-    type: 'application/dash+xml',
-    urls: [{ url: 'https://example.com/video.mpd' }]
-  }
+    type: "application/dash+xml",
+    urls: [{ url: "https://example.com/video.mpd" }],
+  },
 }
 ```
 
@@ -67,9 +67,7 @@ playbackElement.id = 'BigscreenPlayback'
 
 body.appendChild(playbackElement)
 
-const enableSubtitles = false
-
-bigscreenPlayer.init(playbackElement, optionalData, WindowTypes.STATIC, enableSubtitles)
+bigscreenPlayer.init(playbackElement, minimalData)
 ```
 
 ## All Options
@@ -79,45 +77,50 @@ The full set of options for BigscreenPlayer is:
 ```javascript
 const optionalData = {
   initialPlaybackTime: 0, // Time (in seconds) to begin playback from
+  enableSubtitles: false,
   media: {
-    type: 'application/dash+xml',
+    type: "application/dash+xml",
     kind: MediaKinds.VIDEO, // Can be VIDEO, or AUDIO
     urls: [
       // Multiple urls offer the ability to fail-over to another CDN if required
       {
-        url: 'https://example.com/video.mpd',
-        cdn: 'origin' // For Debug Tool reference
-      }, {
-        url: 'https://failover.example.com/video.mpd',
-        cdn: 'failover'
-      }
+        url: "https://example.com/video.mpd",
+        cdn: "origin", // For Debug Tool reference
+      },
+      {
+        url: "https://failover.example.com/video.mpd",
+        cdn: "failover",
+      },
     ],
-    captions: [{
-      url: 'https://example.com/captions/$segment$', // $segment$ required for replacement for live subtitle segments
-      segmentLength: 3.84, // Required to calculate live subtitle segment to fetch & live subtitle URL.
-      cdn: 'origin' // Displayed by Debug Tool
-    }, {
-      url: 'https://failover.example.com/captions/$segment$',
-      segmentLength: 3.84,
-      cdn: 'failover'
-    }
+    captions: [
+      {
+        url: "https://example.com/captions/$segment$", // $segment$ required for replacement for live subtitle segments
+        segmentLength: 3.84, // Required to calculate live subtitle segment to fetch & live subtitle URL.
+        cdn: "origin", // Displayed by Debug Tool
+      },
+      {
+        url: "https://failover.example.com/captions/$segment$",
+        segmentLength: 3.84,
+        cdn: "failover",
+      },
     ],
-    captionsUrl: 'https://example.com/imsc-doc.xml', // NB This parameter is being deprecated in favour of the captions array shown above.
+    captionsUrl: "https://example.com/imsc-doc.xml", // NB This parameter is being deprecated in favour of the captions array shown above.
     subtitlesRequestTimeout: 5000, // Optional override for the XHR timeout on sidecar loaded subtitles
     subtitleCustomisation: {
       size: 0.75,
-      lineHeight: 1.10,
-      fontFamily: 'Arial',
-      backgroundColour: 'black' // (css colour, hex)
+      lineHeight: 1.1,
+      fontFamily: "Arial",
+      backgroundColour: "black", // (css colour, hex)
     },
-    playerSettings: { // See settings documentation for more details
+    playerSettings: {
+      // See settings documentation for more details
       failoverResetTime: 60000,
       streaming: {
         buffer: {
-          bufferToKeep: 8
-        }
-      }
-    }
-  }
+          bufferToKeep: 8,
+        },
+      },
+    },
+  },
 }
 ```