@brightspace-ui/labs 2.63.0 → 2.63.1

package/demo/components/media-player/static/sample-vtt-en-descriptions.vtt

@@ -0,0 +1,7 @@
+WEBVTT
+
+00:00:03.000 --> 00:00:04.000
+A person enters the scene.
+
+00:00:07.500 --> 00:00:08.500
+The camera pans across the nearby landscape.

package/demo/components/media-player/static/sample-vtt-fr-descriptions.vtt

@@ -0,0 +1,7 @@
+WEBVTT
+
+00:00:03.000 --> 00:00:04.000
+Une personne entre dans la scène.
+
+00:00:07.500 --> 00:00:08.500
+La caméra balaie le paysage environnant.

package/package.json

@@ -112,5 +112,5 @@
     "parse-srt": "^1.0.0-alpha",
     "webvtt-parser": "^2"
   },
-  "version": "2.63.0"
+  "version": "2.63.1"
 }

package/src/components/media-player/README.md

@@ -216,9 +216,33 @@ The media player supports captions and subtitles, provided as `.srt` or `.vtt` f
 | default | Boolean | false | The track to be selected by default. If D2L.MediaPlayer.Preferences.Track is defined in local storage, then it will take precedence over this attribute.
 | default-ignore-preferences | Boolean | false | Same as default, but if D2L.MediaPlayer.Preferences.Track is defined, it will be ignored and this track will be selected instead.
 
+## Audio Descriptions Using `<track>`
+
+The media player supports audio descriptions, provided as `.vtt` files, one per language. Audio descriptions are not displayed as burned-in text; instead, when the video's current time crosses a cue's start timestamp (the cue's end timestamp is ignored), the cue text is spoken using the browser's SpeechSynthesis API. If any valid audio description tracks are present, an "Audio descriptions" menu item will be presented in the settings menu with an item for each track.
+
+```html
+<script type="module">
+    import '@brightspace-ui/labs/components/media-player.js';
+</script>
+<d2l-labs-media-player src="/video.webm">
+	<track src="/english-descriptions.vtt" srclang="en" label="English" kind="descriptions">
+	<track src="/french-descriptions.vtt" srclang="fr" label="French" kind="descriptions" pause-video>
+</d2l-labs-media-player>
+```
+
+**Attributes**
+
+| Attribute | Type | Default | Description |
+|--|--|--|--|
+| kind | "descriptions", required | | Identifies the track as an audio description track. |
+| label | String, required | | The label for the track, displayed to the user for selection. |
+| src | String, required | | The URL of the `.vtt` source file. |
+| srclang | String, required | | The language's code. Used as the SpeechSynthesis voice/language and stored as the selection preference. |
+| pause-video | Boolean | false | If set, playback is paused for the duration of each spoken description and resumes automatically once the description finishes, and replay/skip controls are shown. If not set, descriptions play inline with the video and the replay/skip controls are hidden. |
+
 ## Local Storage
 
-The media player uses local storage to persist the user's playback speed, track selections, and volume.
+The media player uses local storage to persist the user's playback speed, track selections, audio description selection, and volume.
 
 **Items**
 
@@ -226,6 +250,7 @@ The media player uses local storage to persist the user's playback speed, track
 | -- | -- |
 | D2L.MediaPlayer.Preferences.Speed | Playback speed that was last selected.
 | D2L.MediaPlayer.Preferences.Track | Identifier for the kind and language of the track that was last selected.
+| D2L.MediaPlayer.Preferences.AudioDescriptionLanguage | Language of the audio description track that was last selected.
 | D2L.MediaPlayer.Preferences.Volume | Volume that was last selected.
 
 ## Accessibility

package/src/components/media-player/media-player-audio-bars.js

@@ -64,7 +64,7 @@ class MediaPlayerAudioBars extends LitElement {
 
 	static properties = {
 		playing: { type: Boolean },
-		_visibleAudioBars: { type: Array, attribute: false },
+		_visibleAudioBars: { state: true },
 	};
 
 	static styles = css`
@@ -72,7 +72,7 @@ class MediaPlayerAudioBars extends LitElement {
 			width: 100%;
 		}
 
-		#d2l-labs-media-player-audio-bars-row {
+		#audio-bars-row {
 			align-items: center;
 			display: flex;
 			flex-direction: row;
@@ -80,13 +80,13 @@ class MediaPlayerAudioBars extends LitElement {
 			justify-content: center;
 		}
 
-		#d2l-labs-media-player-audio-bar-container {
+		#audio-bar-container {
 			display: flex;
 			flex-direction: column;
 			height: 100%;
 		}
 
-		.d2l-labs-media-player-audio-bar {
+		.audio-bar {
 			border-top-left-radius: 0.075rem;
 			border-top-right-radius: 0.075rem;
 			margin: 0 ${AUDIO_BAR_HORIZONTAL_MARGIN_REM}rem;
@@ -143,16 +143,16 @@ class MediaPlayerAudioBars extends LitElement {
 
 				this._startChangingAudioBars();
 			}
-		}).observe(this.shadowRoot.getElementById('d2l-labs-media-player-audio-bars-row'));
+		}).observe(this.shadowRoot.getElementById('audio-bars-row'));
 	}
 
 	render() {
 		return html`
-			<div id="d2l-labs-media-player-audio-bars-row">
+			<div id="audio-bars-row">
 				${this._visibleAudioBars.map(audioBar => html`
-					<div id="d2l-labs-media-player-audio-bar-container">
+					<div id="audio-bar-container">
 						<div style="flex: auto;"></div>
-						<div class="d2l-labs-media-player-audio-bar" style=${styleMap({ backgroundColor: `rgba(${audioBar.red}, ${audioBar.green}, ${audioBar.blue}, 1)`, height: `${audioBar.height}%` })}></div>
+						<div class="audio-bar" style=${styleMap({ backgroundColor: `rgba(${audioBar.red}, ${audioBar.green}, ${audioBar.blue}, 1)`, height: `${audioBar.height}%` })}></div>
 					</div>
 				`)}
 			</div>

package/src/components/media-player/media-player-audio-descriptions.js

@@ -0,0 +1,350 @@
+import '@brightspace-ui/core/components/button/button-icon.js';
+import '@brightspace-ui/core/components/dropdown/dropdown.js';
+import '@brightspace-ui/core/components/dropdown/dropdown-content.js';
+import '@brightspace-ui/core/components/icons/icon-custom.js';
+import '@brightspace-ui/core/components/menu/menu.js';
+import '@brightspace-ui/core/components/menu/menu-item-radio.js';
+import '@brightspace-ui/core/components/menu/menu-item.js';
+import '@brightspace-ui/core/components/menu/menu-item-separator.js';
+import { css, html } from 'lit';
+import { bodySmallStyles } from '@brightspace-ui/core/components/typography/styles.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+
+export const AUDIO_DESCRIPTION_REPLAY_KEY = 'r';
+export const AUDIO_DESCRIPTION_SKIP_KEY = 's';
+export const AUDIO_DESCRIPTION_TRACK_KIND = 'descriptions';
+const PREFERENCES_AUDIO_DESCRIPTION_LANGUAGE_KEY = 'D2L.MediaPlayer.Preferences.AudioDescriptionLanguage';
+const VOICES_LOAD_TIMEOUT_MS = 1000;
+const AUDIO_DESCRIPTION_CONTROLS_IN_MENU_MAX_WIDTH_PX = 768;
+
+export const MediaPlayerAudioDescriptionsMixin = superclass => class extends superclass {
+
+	static properties = {
+		_audioDescriptionControlsInMenu: { state: true },
+		_audioDescriptionPlaying: { state: true },
+		_audioDescriptionTracks: { state: true },
+		_canReplayAudioDescription: { state: true },
+		_selectedAudioDescriptionLanguage: { state: true },
+	};
+
+	static styles = [bodySmallStyles, css`
+		#audio-description-skip-button {
+			margin-inline-end: 12px;
+		}
+		#audio-description-button {
+			margin-inline-end: 15px;
+		}
+		#audio-description-button[data-enabled] {
+			position: relative;
+		}
+		#audio-description-button d2l-icon-custom {
+			display: block;
+			height: calc(1rem - 7px);
+			margin: 0 auto;
+			width: calc(2rem - 9px);
+		}
+		.audio-description-header {
+			background-color: var(--d2l-color-tungsten);
+			border-bottom: 1px solid var(--d2l-color-mica);
+			border-start-end-radius: var(--d2l-popover-border-radius, var(--d2l-popover-default-border-radius));
+			border-start-start-radius: var(--d2l-popover-border-radius, var(--d2l-popover-default-border-radius));
+			color: white;
+			padding: 1rem;
+		}
+		#audio-description-button[data-enabled]::after {
+			border: 2px solid var(--d2l-color-sylvite);
+			border-radius: var(--d2l-button-icon-border-radius, 0.3rem);
+			box-sizing: border-box;
+			content: "";
+			inset: 0;
+			pointer-events: none;
+			position: absolute;
+		}
+	`];
+
+	constructor() {
+		super();
+
+		this._audioDescriptionTracks = [];
+		this._audioDescriptionIndex = 0;
+		this._audioDescriptionPreviousTime = -0.001;
+		this._audioDescriptionPausedVideo = false;
+		this._audioDescriptionPlaying = false;
+		this._audioDescriptionControlsInMenu = false;
+		this._canReplayAudioDescription = false;
+	}
+
+	connectedCallback() {
+		super.connectedCallback();
+		this.#audioDescriptionResizeObserver.observe(this);
+	}
+
+	disconnectedCallback() {
+		this.#audioDescriptionResizeObserver.disconnect();
+		this._cancelAudioDescription();
+		super.disconnectedCallback();
+	}
+
+	#audioDescriptionResizeObserver = new ResizeObserver(entries => {
+		for (const entry of entries) {
+			this._audioDescriptionControlsInMenu = entry.contentRect.width < AUDIO_DESCRIPTION_CONTROLS_IN_MENU_MAX_WIDTH_PX;
+		}
+	});
+
+	_cancelAudioDescription() {
+		if (this._audioDescriptionUtterance && window.speechSynthesis) {
+			window.speechSynthesis.cancel();
+		}
+		this._audioDescriptionUtterance = null;
+		this._audioDescriptionPausedVideo = false;
+		this._audioDescriptionPlaying = false;
+	}
+
+	_getAudioDescriptionsButtonView() {
+		if (!this._audioDescriptionTracks?.length) return null;
+
+		const tooltip = this.localize('components:mediaPlayer:audioDescription');
+		const replayTooltip = this.localize('components:mediaPlayer:replayAudioDescription');
+		const skipTooltip = this.localize('components:mediaPlayer:skipAudioDescription');
+		const showControls = !!this.#getSelectedAudioDescriptionTrack()?.pauseVideo;
+
+		return html`
+			${showControls && !this._audioDescriptionControlsInMenu ? html`
+				<d2l-button-icon
+					icon="tier1:undo"
+					id="audio-description-replay-button"
+					theme="${ifDefined(this._getTheme())}"
+					disabled-tooltip="${replayTooltip}"
+					?disabled="${!this._audioDescriptionPlaying}"
+					@click="${this._replayAudioDescription}"
+				></d2l-button-icon>
+				<d2l-button-icon
+					icon="tier1:redo"
+					id="audio-description-skip-button"
+					theme="${ifDefined(this._getTheme())}"
+					disabled-tooltip="${skipTooltip}"	
+					?disabled="${!this._audioDescriptionPlaying}"
+					@click="${this._skipAudioDescription}"
+				></d2l-button-icon>
+			` : null}
+			<d2l-dropdown>
+				<d2l-button-icon
+					aria-label="${tooltip}"
+					class="d2l-dropdown-opener"
+					id="audio-description-button"
+					title="${tooltip}"
+					theme="${ifDefined(this._getTheme())}"
+					?data-enabled="${!!this._selectedAudioDescriptionLanguage}"
+				><d2l-icon-custom slot="icon"><svg width="28" height="14" viewBox="0 0 28 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M8.89199 8.55L7.21999 3.9805C7.13766 3.77783 7.05216 3.53717 6.96349 3.2585C6.87483 2.97983 6.78616 2.679 6.69749 2.356C6.61516 2.679 6.52966 2.983 6.44099 3.268C6.35233 3.54667 6.26683 3.7905 6.18449 3.9995L4.52199 8.55H8.89199ZM13.4045 13.737H11.4285C11.2068 13.737 11.0263 13.6832 10.887 13.5755C10.7477 13.4615 10.6432 13.3222 10.5735 13.1575L9.54749 10.355H3.85699L2.83099 13.1575C2.78033 13.3032 2.68216 13.4362 2.53649 13.5565C2.39083 13.6768 2.21033 13.737 1.99499 13.737H-7.82078e-06L5.40549 -1.43051e-06H8.00849L13.4045 13.737ZM27.2244 6.8685C27.2244 7.8755 27.0565 8.80017 26.7209 9.6425C26.3852 10.4848 25.9134 11.21 25.3054 11.818C24.6974 12.426 23.9659 12.8978 23.1109 13.2335C22.2559 13.5692 21.3059 13.737 20.2609 13.737H15.0264V-1.43051e-06H20.2609C21.3059 -1.43051e-06 22.2559 0.170999 23.1109 0.512999C23.9659 0.848665 24.6974 1.3205 25.3054 1.9285C25.9134 2.53017 26.3852 3.25217 26.7209 4.0945C27.0565 4.93683 27.2244 5.8615 27.2244 6.8685ZM24.6024 6.8685C24.6024 6.11483 24.501 5.44033 24.2984 4.845C24.102 4.24333 23.8139 3.73667 23.4339 3.325C23.0602 2.907 22.6042 2.58717 22.0659 2.3655C21.5339 2.14383 20.9322 2.033 20.2609 2.033H17.5914V11.704H20.2609C20.9322 11.704 21.5339 11.5932 22.0659 11.3715C22.6042 11.1498 23.0602 10.8332 23.4339 10.4215C23.8139 10.0035 24.102 9.49683 24.2984 8.9015C24.501 8.29983 24.6024 7.62217 24.6024 6.8685Z" fill="white"/>
+</svg></d2l-icon-custom></d2l-button-icon>
+				<d2l-dropdown-content id="audio-description-dropdown-content" class="vdiff-target" no-padding no-padding-header no-pointer theme="${ifDefined(this._getTheme())}">
+					${showControls ? html`<div class="d2l-body-small audio-description-header" slot="header">${this.localize('components:mediaPlayer:extendedAudioDescription')}</div>` : null}
+                    <d2l-menu label="${tooltip}" @d2l-menu-item-change=${this.#onAudioDescriptionMenuItemChange} theme="${ifDefined(this._getTheme())}">
+						${showControls && this._audioDescriptionControlsInMenu ? html`
+							<d2l-menu-item
+								text="${this.localize('components:mediaPlayer:replay')}"
+								?disabled="${!this._audioDescriptionPlaying}"
+								@d2l-menu-item-select="${this._replayAudioDescription}"
+							></d2l-menu-item>
+							<d2l-menu-item
+								text="${this.localize('components:mediaPlayer:skip')}"
+								?disabled="${!this._audioDescriptionPlaying}"
+								@d2l-menu-item-select="${this._skipAudioDescription}"
+							></d2l-menu-item>
+							<d2l-menu-item-separator></d2l-menu-item-separator>
+						` : null}
+                        <d2l-menu-item-radio
+                            ?selected="${!this._selectedAudioDescriptionLanguage}"
+                            text="${this.localize('components:mediaPlayer:off')}"
+                        ></d2l-menu-item-radio>
+                        ${this._audioDescriptionTracks.map(track => html`
+                            <d2l-menu-item-radio
+                                ?selected="${track.srclang === this._selectedAudioDescriptionLanguage}"
+                                text="${track.label}"
+                                value="${track.srclang}"
+                            ></d2l-menu-item-radio>
+                        `)}
+                    </d2l-menu>
+				</d2l-dropdown-content>
+			</d2l-dropdown>
+		`;
+	}
+
+	async _loadAudioDescriptionTrack(node) {
+		for (const attr of ['label', 'src', 'srclang']) {
+			if (!node[attr]) {
+				console.warn(`d2l-labs-media-player component requires '${attr}' text on track`);
+				return;
+			}
+		}
+
+		const res = await fetch(node.src);
+		if (res.status !== 200) {
+			console.warn(`d2l-labs-media-player component could not load track from '${node.src}'`);
+			this.dispatchEvent(new CustomEvent('trackloadfailed'));
+			return;
+		}
+
+		const text = await res.text();
+
+		// Audio descriptions are spoken via SpeechSynthesis rather than displayed, so only each cue's start time and text are needed
+		const { cues } = this._webVTTParser.parse(text, 'metadata');
+		const descriptions = cues
+			.map(cue => ({ text: cue.text, time: cue.startTime }))
+			.filter(description => Number.isFinite(description.time) && description.text)
+			.sort((a, b) => a.time - b.time);
+
+		if (descriptions.length === 0) return;
+
+		// Some browsers (e.g. Chrome) load voices asynchronously on the first getVoices() call
+		window.speechSynthesis?.getVoices?.();
+
+		this._audioDescriptionTracks.push({
+			descriptions,
+			label: node.label,
+			pauseVideo: node.hasAttribute('pause-video'),
+			srclang: node.srclang,
+		});
+		this.dispatchEvent(new CustomEvent('trackloaded'));
+	}
+
+	_onAudioDescriptionTimeUpdate(currentTime) {
+		const track = this._audioDescriptionTracks?.find(track => track.srclang === this._selectedAudioDescriptionLanguage);
+		if (!track) return;
+
+		if (currentTime < this._audioDescriptionPreviousTime) {
+			this._audioDescriptionIndex = track.descriptions.findIndex(description => description.time >= currentTime);
+			if (this._audioDescriptionIndex < 0) this._audioDescriptionIndex = track.descriptions.length;
+			this._cancelAudioDescription();
+		}
+
+		const next = track.descriptions[this._audioDescriptionIndex];
+		if (next && this._audioDescriptionPreviousTime < next.time && currentTime >= next.time) {
+			this._audioDescriptionIndex += 1;
+			this.#speakAudioDescription(next, track);
+		}
+		this._audioDescriptionPreviousTime = currentTime;
+	}
+
+	_replayAudioDescription() {
+		if (!this._audioDescriptionPlaying) return;
+		const track = this.#getSelectedAudioDescriptionTrack();
+		if (!track?.pauseVideo) return;
+		const description = track?.descriptions.findLast(description => description.time <= this.currentTime);
+		if (!description) return;
+
+		// Preserve the pause from the original playback so the video still resumes after the replay
+		const pausedVideo = this._audioDescriptionPausedVideo;
+		this.#speakAudioDescription(description, track);
+		if (pausedVideo) this._audioDescriptionPausedVideo = true;
+	}
+
+	_resetAudioDescriptionCursor(time) {
+		this._cancelAudioDescription();
+		const track = this._audioDescriptionTracks?.find(track => track.srclang === this._selectedAudioDescriptionLanguage);
+		this._audioDescriptionIndex = track
+			? track.descriptions.findIndex(description => description.time >= time)
+			: 0;
+		if (this._audioDescriptionIndex < 0) this._audioDescriptionIndex = track?.descriptions.length || 0;
+		this._audioDescriptionPreviousTime = time - 0.001;
+	}
+
+	_restoreAudioDescriptionPreference() {
+		const audioDescriptionPreference = this._getPreference(PREFERENCES_AUDIO_DESCRIPTION_LANGUAGE_KEY);
+		this._selectedAudioDescriptionLanguage = this._audioDescriptionTracks.some(track => track.srclang === audioDescriptionPreference)
+			? audioDescriptionPreference
+			: null;
+		this._resetAudioDescriptionCursor(this.currentTime);
+	}
+
+	_skipAudioDescription() {
+		if (!this._audioDescriptionPlaying || !this.#getSelectedAudioDescriptionTrack()?.pauseVideo) return;
+		const pausedVideo = this._audioDescriptionPausedVideo;
+		this._cancelAudioDescription();
+		if (pausedVideo) this._play();
+	}
+
+	#getAudioDescriptionVoice(language) {
+		const normalizedLanguage = (language || '').toLowerCase();
+		if (!normalizedLanguage || !window.speechSynthesis?.getVoices) return null;
+
+		const voices = window.speechSynthesis.getVoices();
+		if (!voices.length) return null;
+
+		const bestMatch = voices.find(voice => (voice.lang || '').toLowerCase() === normalizedLanguage)
+			|| voices.find(voice => (voice.lang || '').toLowerCase().startsWith(`${normalizedLanguage.split('-')[0]}-`))
+			|| voices.find(voice => (voice.lang || '').toLowerCase().startsWith(`${normalizedLanguage.split('-')[0]}_`))
+			|| voices.find(voice => (voice.lang || '').toLowerCase().startsWith(normalizedLanguage.split('-')[0]))
+			|| voices.find(voice => (voice.lang || '').toLowerCase().includes(normalizedLanguage.split('-')[0]))
+			|| voices[0];
+		return bestMatch || null;
+	}
+
+	#getSelectedAudioDescriptionTrack() {
+		return this._audioDescriptionTracks?.find(track => track.srclang === this._selectedAudioDescriptionLanguage);
+	}
+
+	#onAudioDescriptionMenuItemChange(e) {
+		this._cancelAudioDescription();
+		this._selectedAudioDescriptionLanguage = e.target.value || null;
+		this._resetAudioDescriptionCursor(this.currentTime);
+		if (this._selectedAudioDescriptionLanguage) {
+			this._setPreference(PREFERENCES_AUDIO_DESCRIPTION_LANGUAGE_KEY, this._selectedAudioDescriptionLanguage);
+		} else {
+			this._clearPreference(PREFERENCES_AUDIO_DESCRIPTION_LANGUAGE_KEY);
+		}
+
+		this.shadowRoot?.querySelector('#audio-description-dropdown-content')?.close();
+	}
+
+	#speakAudioDescription(description, track) {
+		if (!window.speechSynthesis || !window.SpeechSynthesisUtterance) return;
+
+		this._cancelAudioDescription();
+		const utterance = new window.SpeechSynthesisUtterance(description.text);
+		utterance.lang = track.srclang;
+		this._audioDescriptionUtterance = utterance;
+		this._audioDescriptionPlaying = true;
+
+		if (track.pauseVideo && this._media && !this._media.paused) {
+			this._audioDescriptionPausedVideo = true;
+			this._media.pause();
+		}
+
+		const finish = () => {
+			if (this._audioDescriptionUtterance !== utterance) return;
+			this._audioDescriptionUtterance = null;
+			this._audioDescriptionPlaying = false;
+			if (this._audioDescriptionPausedVideo) {
+				this._audioDescriptionPausedVideo = false;
+				this._play();
+			}
+		};
+		utterance.onend = finish;
+		utterance.onerror = finish;
+
+		const speak = () => {
+			if (this._audioDescriptionUtterance !== utterance) return;
+			const voice = this.#getAudioDescriptionVoice(track.srclang);
+			if (voice) utterance.voice = voice;
+			utterance.volume = this.volume;
+			window.speechSynthesis.speak(utterance);
+		};
+
+		if (window.speechSynthesis.getVoices().length) {
+			speak();
+			return;
+		}
+
+		// Speaking before voices have loaded is silently dropped in some browsers
+		const controller = new AbortController();
+		const onVoicesChanged = () => {
+			controller.abort();
+			speak();
+		};
+		window.speechSynthesis.addEventListener('voiceschanged', onVoicesChanged, { signal: controller.signal });
+		const timeout = setTimeout(onVoicesChanged, VOICES_LOAD_TIMEOUT_MS);
+		controller.signal.addEventListener('abort', () => clearTimeout(timeout));
+	}
+};