Expand on seeking by timeline docs

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"

docs/tutorials/Events.md → 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);
-```
+bigscreenPlayer.unregisterForSubtitleChanges(subtitleChangeToken)
+```

docs/tutorials/State Changes.md → 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)
+![State Changes](../static/bsp_state_changes_august_2019.png)

docs/tutorials/seeking.md → 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.
 

docs/tutorials/cdn-failover.md → 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**_
+_**This can be replicated by blocking CDN in the inspect debug tool**_

docs/tutorials/Design.md → docs/tutorials/90-design.md

@@ -3,17 +3,21 @@ 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
 
 ![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.
+
+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.

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)

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)"
   }