You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/arch/001-native-strategy.md
+14-12Lines changed: 14 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,21 +2,23 @@
2
2
3
3
Originally Added: February 20th, 2019
4
4
5
-
# Context
5
+
##Context
6
6
7
-
* As it stands, `bigscreen-player` requires using the `tal` device object - when in `talstrategy` - to obtain a media player for playback
8
-
* Since the `tal` device media player exists as a singleton, applications using `talstrategy` can only access one active media element.
9
-
* Unlike `msestrategy`, `talstrategy` also requires loading in the extra dependency (`tal` device) - and is therefore limited by the limitations of the `tal` device.
7
+
- As it stands, `bigscreen-player` requires using the `tal` device object - when in `talstrategy` - to obtain a media player for playback
8
+
- Since the `tal` device media player exists as a singleton, applications using `talstrategy` can only access one active media element.
9
+
- Unlike `msestrategy`, `talstrategy` also requires loading in the extra dependency (`tal` device) - and is therefore limited by the limitations of the `tal` device.
10
10
11
-
# Decision
12
-
* A new strategy type - `nativestrategy` - has been created which pulls the media player out of `tal`
13
-
* This is a refactor of the `tal` device media player code which allows further manipulation and control i.e. multiple video playback
11
+
## Decision
14
12
13
+
- A new strategy type - `nativestrategy` - has been created which pulls the media player out of `tal`
14
+
- This is a refactor of the `tal` device media player code which allows further manipulation and control i.e. multiple video playback
15
+
16
+
## Status
15
17
16
-
# Status
17
18
Approved
18
19
19
-
# Consequences
20
-
* Multiple active video instances can be controlled
21
-
* Preloading of content on different media elements is more achievable
22
-
* 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`
20
+
## Consequences
21
+
22
+
- Multiple active video instances can be controlled
23
+
- Preloading of content on different media elements is more achievable
24
+
- 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`
Copy file name to clipboardExpand all lines: docs/arch/003-subtitles-polling-frequency.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ Originally Added: April 7th, 2020
4
4
5
5
## Context
6
6
7
-
Subtitles in Bigscreen Player are updated by checking for the next available subtitle using a set timeout of 750ms.
7
+
Subtitles in Bigscreen Player are updated by checking for the next available subtitle using a set timeout of 750ms.
8
8
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.
9
9
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.
# 004 Removing `windowType`; changing time representation
2
+
3
+
Originally added: 2025-02-03
4
+
5
+
## Status
6
+
7
+
| Discussing | Approved | Superceded |
8
+
| ---------- | -------- | ---------- |
9
+
|| x ||
10
+
11
+
## Context
12
+
13
+
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:
14
+
15
+
- The timestamp in the media samples are encoded as UTC times (in seconds) for "sliding window" content i.e. streams with time shift.
16
+
- Streams with time shift never use a presentation time offset.
17
+
18
+
What is more, metadata (i.e. the `windowType`) determined BigscreenPlayer's manifest parsing strategy from v7.1.0 and codified these assumptions.
19
+
20
+
- How might we overhaul our time representation to support streams that don't comply with these assumptions?
21
+
22
+
### Considered Options
23
+
24
+
1. Expose time reported by the `MediaElement` directly. Provide functions to convert the time from the `MediaElement` into availability and media sample time.
25
+
2. Do not apply time correction based on `timeShiftBufferDepth` if `windowType === WindowTypes.GROWING`
26
+
3. Do not apply time correction based on `timeShiftBufferDepth` if SegmentTemplates in the MPD have `presentationTimeOffset`
27
+
28
+
## Decision
29
+
30
+
Chosen option: 1
31
+
32
+
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.
33
+
34
+
## Consequences
35
+
36
+
A major version (v9.0.0) to remove window type and overhaul BigscreenPlayer's internals.
# 005 Remove fake seeking from restartable strategy
2
+
3
+
Originally added: 2025-02-04
4
+
5
+
## Status
6
+
7
+
| Discussing | Approved | Superceded |
8
+
| ---------- | -------- | ---------- |
9
+
|| x ||
10
+
11
+
## Context
12
+
13
+
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.
14
+
15
+
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`.
16
+
17
+
- Should we continue to support fake seeking for native playback?
18
+
- How might we continue to support fake seeking?
19
+
20
+
### Considered Options
21
+
22
+
1. Remove fake seeking from restartable strategy
23
+
2. Poll the HLS manifest for time shift
24
+
3. Provide a "magic" time shift buffer depth for HLS streams
25
+
26
+
## Decision
27
+
28
+
Chosen option: 1
29
+
30
+
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.
31
+
32
+
## Consequences
33
+
34
+
Viewers that use devices on the restartable strategy will no longer be able to pause or seek in-stream.
BigscreenPlayer's auto-resume feature prevents undefined behaviour when native players resume playback outside the seekable range. Auto-resume consists of two mechanisms:
14
+
15
+
1. Playback is resumed before current time can drift outside of the seekable range
16
+
2. Pausing isn't possible when current time is close to the start of the seekable range
17
+
18
+
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`.
19
+
20
+
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.
21
+
22
+
- How might we detect timeshift and enable the auto-resume feature for DASH and HLS streams?
23
+
24
+
### Considered Options
25
+
26
+
1. Poll the HLS manifest to check if the first segment changes
27
+
2. Poll the seekable range for changes to the start of the seekable range
28
+
3. Provide a "magic" time shift buffer depth for HLS streams
29
+
30
+
## Decision
31
+
32
+
Chosen option: 2
33
+
34
+
## Consequences
35
+
36
+
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.
BigscreenPlayer adds functions to convert between three timelines:
14
+
15
+
1. Presentation time: Output by the MediaElement
16
+
2. Media sample time: Timestamps encoded in the current media
17
+
3. Availablity time: UTC times that denote time available. Only relevant for dynamic streams.
18
+
19
+
BigscreenPlayer relies on metadata in the manifest to calculate each conversion.
20
+
21
+
For DASH:
22
+
23
+
- Presentation time <-> Media sample time relies on `presentationTimeOffset`
24
+
- Presentation time <-> Availability time relies on `availabilityStartTime`
25
+
26
+
For HLS:
27
+
28
+
- Presentation time <-> Media sample time relies on `programDateTime`
29
+
- Presentation time <-> Availability time relies on ???
30
+
31
+
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.
32
+
33
+
### Considered Options
34
+
35
+
1. Accept the conversion between availability and presentation time is broken for HLS streams.
36
+
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.
37
+
38
+
## Decision
39
+
40
+
Chosen option: 1
41
+
42
+
## Consequences
43
+
44
+
The conversion between presentation time and availability start time is erroneous for HLS.
Copy file name to clipboardExpand all lines: docs/tutorials/00-getting-started.md
+38-35Lines changed: 38 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,13 +22,13 @@ Configuration for bigscreen-player can be set using an object on the window:
22
22
window.bigscreenPlayer
23
23
```
24
24
25
-
You must provide a *playback strategy* to use BigscreenPlayer:
25
+
You must provide a _playback strategy_ to use BigscreenPlayer:
26
26
27
27
```javascript
28
-
window.bigscreenPlayer.playbackStrategy='msestrategy'// OR 'nativestrategy' OR 'basicstrategy'
28
+
window.bigscreenPlayer.playbackStrategy="msestrategy"// OR 'nativestrategy' OR 'basicstrategy'
29
29
```
30
30
31
-
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)
31
+
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)
32
32
33
33
### Minimal Data
34
34
@@ -37,9 +37,9 @@ You must provide a manifest and its MIME type.
0 commit comments