From 5ab9097537d34cc83b1d2ebefb1e266a7137383c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eirik=20Jo=20Bj=C3=B6rnerstedt?= Date: Mon, 17 Nov 2025 17:53:27 +0000 Subject: [PATCH] docs: expand on seeking by timeline --- docs/tutorials/01-playback-strategies.md | 2 +- ...rrides.md => 01-settings-and-overrides.md} | 0 .../{Debugging.md => 02-debugging.md} | 0 docs/tutorials/{Events.md => 02-events.md} | 29 +++++++------- ...e Changes.md => 02-media-state-changes.md} | 2 +- docs/tutorials/{Plugins.md => 02-plugins.md} | 0 ...live-streaming.md => 10-live-streaming.md} | 0 docs/tutorials/{seeking.md => 10-seeking.md} | 12 +++++- ...Description.md => 20-audio-description.md} | 0 .../{Subtitles.md => 20-timed-text.md} | 0 .../{cdn-failover.md => 30-cdn-failover.md} | 26 ++++++++----- docs/tutorials/{Design.md => 90-design.md} | 8 +++- docs/tutorials/90-testing.md | 39 +++++++++++++++++++ docs/tutorials/Testing.md | 32 --------------- docs/tutorials/tutorials.json | 37 ++++++++++++++---- 15 files changed, 118 insertions(+), 69 deletions(-) rename docs/tutorials/{02-settings-and-overrides.md => 01-settings-and-overrides.md} (100%) rename docs/tutorials/{Debugging.md => 02-debugging.md} (100%) rename docs/tutorials/{Events.md => 02-events.md} (82%) rename docs/tutorials/{State Changes.md => 02-media-state-changes.md} (83%) rename docs/tutorials/{Plugins.md => 02-plugins.md} (100%) rename docs/tutorials/{live-streaming.md => 10-live-streaming.md} (100%) rename docs/tutorials/{seeking.md => 10-seeking.md} (87%) rename docs/tutorials/{Audio Description.md => 20-audio-description.md} (100%) rename docs/tutorials/{Subtitles.md => 20-timed-text.md} (100%) rename docs/tutorials/{cdn-failover.md => 30-cdn-failover.md} (76%) rename docs/tutorials/{Design.md => 90-design.md} (84%) create mode 100644 docs/tutorials/90-testing.md delete mode 100644 docs/tutorials/Testing.md diff --git a/docs/tutorials/01-playback-strategies.md b/docs/tutorials/01-playback-strategies.md index fce65f392..19f7b9a07 100644 --- a/docs/tutorials/01-playback-strategies.md +++ b/docs/tutorials/01-playback-strategies.md @@ -34,7 +34,7 @@ This requires additional config to select which media player implementation to u window.bigscreenPlayer.mediaPlayer: 'html5' ``` -You must also indicate the device's live playback capability. There's more info in [the documentation on live-streaming](https://bbc.github.io/bigscreen-player/api/tutorial-live-streaming.html) +You must also indicate the device's live playback capability. There's more info in [the documentation on live-streaming](https://bbc.github.io/bigscreen-player/api/tutorial-10-live-streaming.html) ```javascript window.bigscreenPlayer.liveSupport = "seekable" diff --git a/docs/tutorials/02-settings-and-overrides.md b/docs/tutorials/01-settings-and-overrides.md similarity index 100% rename from docs/tutorials/02-settings-and-overrides.md rename to docs/tutorials/01-settings-and-overrides.md diff --git a/docs/tutorials/Debugging.md b/docs/tutorials/02-debugging.md similarity index 100% rename from docs/tutorials/Debugging.md rename to docs/tutorials/02-debugging.md diff --git a/docs/tutorials/Events.md b/docs/tutorials/02-events.md similarity index 82% rename from docs/tutorials/Events.md rename to docs/tutorials/02-events.md index 3544c818b..fd3d2ac42 100644 --- a/docs/tutorials/Events.md +++ b/docs/tutorials/02-events.md @@ -3,6 +3,7 @@ Bigscreen Player uses a variety of events to signal its current state. ## 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` @@ -13,17 +14,17 @@ State changes which are emitted from the player can be acted upon to by register State changes may be registered for before initialisation and will automatically be cleared upon `tearDown()` of the player. ```javascript -var bigscreenPlayer = BigscreenPlayer(); +var bigscreenPlayer = BigscreenPlayer() // The token is only required in the case where the function is anonymous, a reference to the function can be stored and used to unregister otherwise. var stateChangeToken = bigscreenPlayer.registerForStateChanges(function (event) { - if(event.state == MediaState.PLAYING) { - console.log('Playing'); + if (event.state == MediaState.PLAYING) { + console.log("Playing") // handle playing event } -}); +}) -bigscreenPlayer.unRegisterForStateChanges(stateChangeToken); +bigscreenPlayer.unRegisterForStateChanges(stateChangeToken) ``` ## Reacting to time updates @@ -33,14 +34,14 @@ Time updates are emitted multiple times a second. Your application can register Time updates may be registered for before initialisation and will automatically be cleared upon `tearDown()` of the player. ```javascript -var bigscreenPlayer = BigscreenPlayer(); +var bigscreenPlayer = BigscreenPlayer() // The token is only required in the case where the function is anonymous, a reference to the function can be stored and used to unregister otherwise. var timeUpdateToken = bigscreenPlayer.registerForTimeUpdates(function (event) { - console.log('Current Time: ' + event.currentTime); -}); + console.log("Current Time: " + event.currentTime) +}) -bigscreenPlayer.unRegisterForTimeUpdates(timeUpdateToken); +bigscreenPlayer.unRegisterForTimeUpdates(timeUpdateToken) ``` ## Reacting to subtitles being turned on/off @@ -50,12 +51,12 @@ This is emitted on every `setSubtitlesEnabled` call. The emitted object contains This may be registered for before initialisation and will automatically be cleared upon `tearDown()` of the player. ```javascript -var bigscreenPlayer = BigscreenPlayer(); +var bigscreenPlayer = BigscreenPlayer() // The token is only required in the case where the function is anonymous, a reference to the function can be stored and used to unregister otherwise. var subtitleChangeToken = bigscreenPlayer.registerForSubtitleChanges(function (event) { - console.log('Subttiles enabled: ' + event.enabled); -}); + console.log("Subttiles enabled: " + event.enabled) +}) -bigscreenPlayer.unregisterForSubtitleChanges(subtitleChangeToken); -``` \ No newline at end of file +bigscreenPlayer.unregisterForSubtitleChanges(subtitleChangeToken) +``` diff --git a/docs/tutorials/State Changes.md b/docs/tutorials/02-media-state-changes.md similarity index 83% rename from docs/tutorials/State Changes.md rename to docs/tutorials/02-media-state-changes.md index 1ebd7911c..6485289d6 100644 --- a/docs/tutorials/State Changes.md +++ b/docs/tutorials/02-media-state-changes.md @@ -2,4 +2,4 @@ During playback, `bigscreen-player` may change state (e.g enter buffering, pause The following diagram describes the flow of these events. -![State Changes](../static/bsp_state_changes_august_2019.png) \ No newline at end of file +![State Changes](../static/bsp_state_changes_august_2019.png) diff --git a/docs/tutorials/Plugins.md b/docs/tutorials/02-plugins.md similarity index 100% rename from docs/tutorials/Plugins.md rename to docs/tutorials/02-plugins.md diff --git a/docs/tutorials/live-streaming.md b/docs/tutorials/10-live-streaming.md similarity index 100% rename from docs/tutorials/live-streaming.md rename to docs/tutorials/10-live-streaming.md diff --git a/docs/tutorials/seeking.md b/docs/tutorials/10-seeking.md similarity index 87% rename from docs/tutorials/seeking.md rename to docs/tutorials/10-seeking.md index e3c812067..e93964c41 100644 --- a/docs/tutorials/seeking.md +++ b/docs/tutorials/10-seeking.md @@ -1,4 +1,14 @@ -A seek is initiated by `BigscreenPlayer#setCurrentTime()`. It can take a number or a number and a timeline. Each timeline is defined in the `Timeline` enum. +A seek is initiated by `BigscreenPlayer#setCurrentTime()`. + +```js +bigscreenPlayer.setCurrentTime(30) // seeks in seconds +``` + +You can also specify [a timeline (read more in section: Timelines)](#timelines) to anchor your seek: + +```js +bigscreenPlayer.setCurrentTime(Date.now() / 1000 - 60, Timeline.AVAILABILITY_TIME) +``` BigscreenPlayer will signal a seek is in progress through the `isSeeking` property on the `WAITING` state change. diff --git a/docs/tutorials/Audio Description.md b/docs/tutorials/20-audio-description.md similarity index 100% rename from docs/tutorials/Audio Description.md rename to docs/tutorials/20-audio-description.md diff --git a/docs/tutorials/Subtitles.md b/docs/tutorials/20-timed-text.md similarity index 100% rename from docs/tutorials/Subtitles.md rename to docs/tutorials/20-timed-text.md diff --git a/docs/tutorials/cdn-failover.md b/docs/tutorials/30-cdn-failover.md similarity index 76% rename from docs/tutorials/cdn-failover.md rename to docs/tutorials/30-cdn-failover.md index 98b33ce16..a8c50a4c4 100644 --- a/docs/tutorials/cdn-failover.md +++ b/docs/tutorials/30-cdn-failover.md @@ -1,27 +1,31 @@ When a user is playing video/audio and an error occurs we want playback to recover using different CDN. ### When is it triggered? + Few reasons why errors can happen when playback is attempted: -- Loss of network/low network -- Loss of connection to a particular CDN + +- Loss of network/low network +- Loss of connection to a particular CDN - Missing segments in manifest -- Device specific fatal errors +- Device specific fatal errors _Note: CDN Failover is not attempted if the error occurs in last 60 secs of static (on demand) content_ -## Standard Failover - On all devices/playback strategies +## Standard Failover - On all devices/playback strategies ### Buffering timeout Errors + Some potential causes: + - Loss of Network - Internal error not reported by device browser -#### Errors at the start of the playback +#### Errors at the start of the playback 1. Bigscreen Player has been initialised and is in WAITING state -1. CDN failover is attempted after 30 secs +1. CDN failover is attempted after 30 secs -#### Errors during playback +#### Errors during playback 1. Playback strategy reports waiting event 1. Bigscreen Player is in WAITING state @@ -30,19 +34,21 @@ Some potential causes: _**This can be replicated by network throttling. We usually use very low setting of 12 kb/s to trigger buffering.**_ ### FATAL Errors + Some potential causes: + - Loss of CDN, unavailable CDN - Corrupted stream - Issue with the device browser 1. Playback strategy reports error event 1. Bigscreen Player is in WAITING state -1. CDN failover is attempted after 5 secs +1. CDN failover is attempted after 5 secs _**This can be replicated by blocking CDN in the inspect debug tool.**_ -## Seamless Failover - Only on MSE Strategy Devices +## Seamless Failover - Only on MSE Strategy Devices We provide dash.js with all the `urls` provided. dash.js will switch CDN 'seamlessly' if it detects an issue, which may not always result in a WAITING event being throw. -_**This can be replicated by blocking CDN in the inspect debug tool**_ \ No newline at end of file +_**This can be replicated by blocking CDN in the inspect debug tool**_ diff --git a/docs/tutorials/Design.md b/docs/tutorials/90-design.md similarity index 84% rename from docs/tutorials/Design.md rename to docs/tutorials/90-design.md index 46f2571e3..0573e1181 100644 --- a/docs/tutorials/Design.md +++ b/docs/tutorials/90-design.md @@ -3,12 +3,15 @@ This document covers the basics of the `bigscreen-player` high level architectur Further setup code and specific examples can be found in the repo itself. A good place to start is the [README](https://github.com/bbc/bigscreen-player/blob/master/README.md). ## Dependencies + As it stands, the player relies on two dependencies: #### [Dash.js](https://github.com/bbc/dash.js) -Our custom fork of the reference implementation of the ***dynamic adaptive streaming over http*** protocol. Used for MSE (Media Source Extension) capable devices. This is required in specifically by `bigscreen-player`, when the mse-strategy is used. + +Our custom fork of the reference implementation of the **_dynamic adaptive streaming over http_** protocol. Used for MSE (Media Source Extension) capable devices. This is required in specifically by `bigscreen-player`, when the mse-strategy is used. #### [imscJS](https://github.com/bbc/imscJS) + Our custom fork for rendering subtitles. ## Architecture @@ -16,4 +19,5 @@ Our custom fork for rendering subtitles. ![Bigscreen Player Image](../static/bsp_arch.svg) ### Player Component -This stage provides a wrapper for the interaction with all of the individual strategies and is what `bigscreen-player` uses to interact with the video element, at its core. \ No newline at end of file + +This stage provides a wrapper for the interaction with all of the individual strategies and is what `bigscreen-player` uses to interact with the video element, at its core. diff --git a/docs/tutorials/90-testing.md b/docs/tutorials/90-testing.md new file mode 100644 index 000000000..60f98d753 --- /dev/null +++ b/docs/tutorials/90-testing.md @@ -0,0 +1,39 @@ +**This page lists the areas that are to be considered for testing Bigscreen Player changes** + +Different Streaming types should be considered - MP4, HLS, DASH - Audio and Video + +- Subtitles (currently on demand only) +- CDN Failover +- Tearing down playback and immediately starting something new (e.g 'autoplay' features) +- Soak testing (i.e. play for a long period of time) +- End of playback +- Seeking and related UI (e.g. scrub bar, thumbnails) +- Buffering UI +- Adaptive Bit Rate (ABR) +- Any other application behaviour driven by Bigscreen Player events (e.g. stats) + +## Live Playback specific areas + +Different types of live playback capability should be considered - **Playable, Restartable, Seekable** + +### Sliding Windows + +1. Live Restart Curtain +2. Manifest Parsing + +- Watch form Live +- Start from a given point in the window (a.k.a Live restart) +- Watch from the start of the window +- Auto resume at the start of the window +- Seeking + +### Growing Windows + +1. Live Restart Curtain +2. Manifest Parsing + +- Watch from Live +- Live restart +- Seeking + +3. End of stream (Ended Event) diff --git a/docs/tutorials/Testing.md b/docs/tutorials/Testing.md deleted file mode 100644 index 0ae86b355..000000000 --- a/docs/tutorials/Testing.md +++ /dev/null @@ -1,32 +0,0 @@ -**This page lists the areas that are to be considered for testing Bigscreen Player changes** - -Different Streaming types should be considered - MP4, HLS, DASH - Audio and Video -* Subtitles (currently on demand only) -* CDN Failover -* Tearing down playback and immediately starting something new (e.g 'autoplay' features) -* Soak testing (i.e. play for a long period of time) -* End of playback -* Seeking and related UI (e.g. scrub bar, thumbnails) -* Buffering UI -* Adaptive Bit Rate (ABR) -* Any other application behaviour driven by Bigscreen Player events (e.g. stats) - -## Live Playback specific areas -Different types of live playback capability should be considered - **Playable, Restartable, Seekable** - -### Sliding Windows -1. Live Restart Curtain -2. Manifest Parsing -* Watch form Live -* Start from a given point in the window (a.k.a Live restart) -* Watch from the start of the window -* Auto resume at the start of the window -* Seeking - -### Growing Windows -1. Live Restart Curtain -2. Manifest Parsing -* Watch from Live -* Live restart -* Seeking -3. End of stream (Ended Event) diff --git a/docs/tutorials/tutorials.json b/docs/tutorials/tutorials.json index 9499d0f36..bb1f4dbce 100644 --- a/docs/tutorials/tutorials.json +++ b/docs/tutorials/tutorials.json @@ -5,21 +5,42 @@ "01-playback-strategies": { "title": "Playback Strategies" }, - "02-settings-and-overrides": { + "01-settings-and-overrides": { "title": "Settings And Overrides" }, - "cdn-failover": { - "title": "CDN Failover" - }, - "debugging": { + "02-debugging": { "title": "Debugging" }, - "live-streaming": { - "title": "Live" + "02-events": { + "title": "Events" + }, + "02-media-state-changes": { + "title": "Media State Changes" }, - "seeking": { + "02-plugins": { + "title": "Plugins" + }, + "10-live-streaming": { + "title": "Playing Livestreams" + }, + "10-seeking": { "title": "Seeking" }, + "20-audio-description": { + "title": "Audio Description" + }, + "20-timed-text": { + "title": "Subtitles and Timed Text" + }, + "30-cdn-failover": { + "title": "CDN Failover" + }, + "90-design": { + "title": "Design" + }, + "90-testing": { + "title": "Testing" + }, "XX-mocking": { "title": "Mocking Playback (deprecated)" }