Merge branch 'master' into embedded-subtitles

Author: ryanmccartney

.releasinator.json

@@ -0,0 +1,8 @@
+{
+  "publish": "release",
+  "versioning": "semver",
+  "tagPattern": "$.$.$",
+  "displayPattern": "$.$.$",
+  "enforceUserFacingLabel": false,
+  "projectType": "npm-like"
+}

docs/tutorials/00-getting-started.md

@@ -112,6 +112,17 @@ const optionalData = {
       fontFamily: "Arial",
       backgroundColour: "black", // (css colour, hex)
     },
+    audioDescribed: [
+      // 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",
+      },
+    ],
     playerSettings: {
       // See settings documentation for more details
       failoverResetTime: 60000,

docs/tutorials/Audio Description.md

@@ -0,0 +1,49 @@
+BigscreenPlayer provides Audio Description (AD) support for accessible media playback. This document details the two implementations.
+
+## Implementations
+
+BigscreenPlayer uses two distinct methods for handling AD: a source switching approach and an MSE-specific approach.
+
+### 1. Source Switching Audio Description (MediaSources)
+
+The `MediaSources` module manages AD by accepting separate sources for audio description tracks. This method is used when AD is provided as a distinct media resource.
+
+- **Separate Source Management:**
+  - `MediaSources` accepts a separate `media.audioDescribed` source, containing URLs and CDNs, distinct from the main media source.
+  - Failover for AD sources occurs **independently** within this provided source.
+  - Example:
+    If CDN 'A' in the Audio Description source fails, failover occurs only within that AD source, independently of the main video source. If AD is turned off, and CDN 'A' is present for the main source, it will be available.
+- **Manifest Switching:**
+  - Enabling or disabling AD triggers the loading of a new manifest from the appropriate URL within the provided AD source.
+  - This effectively switches between the main and AD audio streams.
+
+### 2. MSE Strategy-Specific Audio Description (MSEStrategy)
+
+The `MSEStrategy` strategy implementation manages AD within the same media stream.
+
+- **Track Selection:**
+  - AD tracks are identified within the DASH manifest by their roles and accessibility schemes.
+  - Currently, a track is identified as AD if it matches the `Broadcast mix AD` descriptor values. These values are:
+    - Role `value` of `alternate`
+    - Accessibility `schemeIdUri` of `urn:tva:metadata:cs:AudioPurposeCS:2007` and `value` of `1`.
+  - These values are defined in [ETSI TS 103 285 V1.1.1 Technical Specification](https://www.etsi.org/deliver/etsi_ts/103200_103299/103285/01.01.01_60/ts_103285v010101p.pdf#%5B%7B%22num%22%3A59%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22FitH%22%7D%2C392%5D)
+
+## Developer API
+
+Audio Described functionality can be interacted with through BigScreenPlayers API, which exposes the following functions:
+
+- **`isAudioDescribedAvailable()`:**
+  - Checks if AD tracks are available.
+  - If the source switching implementation (MediaSources) provides AD, **this takes priority**.
+- **`isAudioDescribedEnabled()`:**
+  - Checks if an AD track/source is currently active.
+- **`setAudioDescribed(enable)`:**
+  - Enables or disables AD.
+  - Example:
+    ```javascript
+    bigScreenPlayer.setAudioDescribed(true)
+    ```
+
+## Priority
+
+If there are separate audioDescribed media sources provided, it will take priority over the MSE specific implementation.

eslint.config.js

@@ -174,6 +174,7 @@ export default tseslint.config(
       "unicorn/prefer-math-trunc": "off",
       "unicorn/prefer-number-properties": "off",
       "unicorn/prefer-optional-catch-binding": "off",
+      "unicorn/prefer-set-has": "off",
       "unicorn/prefer-string-replace-all": "off",
 
       // HAS ISSUES

jsdoc.conf.json

@@ -9,7 +9,7 @@
     "excludePattern": "(node_modules/|docs)"
   },
   "sourceType": "module",
-  "plugins": ["plugins/markdown", "node_modules/better-docs/typescript"],
+  "plugins": ["jsdoc-plugin-typescript", "plugins/markdown", "node_modules/better-docs/typescript"],
   "templates": {
     "cleverLinks": false,
     "monospaceLinks": true,