@outbook/webcomponents-player 1.4.6 → 1.5.0

package/_lib/is-valid-track-index.js

@@ -0,0 +1,18 @@
+export function isValidTrackIndex({ index, playlist }) {
+  if (
+    !Number.isInteger(index) ||
+    !Array.isArray(playlist) ||
+    index < 0 ||
+    index >= playlist.length
+  ) {
+    return false;
+  }
+
+  const track = playlist[index];
+  return (
+    track &&
+    typeof track === 'object' &&
+    typeof track.file === 'string' &&
+    track.file.trim().length > 0
+  );
+}

package/_lib/is-valid-track-index.test.js

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { isValidTrackIndex } from './is-valid-track-index.js';
+
+const playlist = [{ file: '/audio/valid.mp3' }, { file: '/audio/other.mp3' }];
+
+describe('isValidTrackIndex', () => {
+  it('accepts an in-range integer for a track with an audio file', () => {
+    expect(isValidTrackIndex({ index: 1, playlist })).toBe(true);
+  });
+
+  it.each([-1, 2, 0.5, '0', NaN])('rejects an invalid index: %s', index => {
+    expect(isValidTrackIndex({ index, playlist })).toBe(false);
+  });
+
+  it.each([undefined, null, '', '   ', 42])(
+    'rejects a track without a valid audio file: %s',
+    file => {
+      expect(isValidTrackIndex({ index: 0, playlist: [{ file }] })).toBe(false);
+    }
+  );
+});

package/_lib/playlist/modules/item-duration.js

@@ -2,7 +2,7 @@ import { html } from 'lit';
 import {
   readable as formatTime,
   iso as formatTimeDuration
-} from 'mystic-format-time';
+} from '@outbook/format-time';
 
 export function ItemDuration({ duration }) {
   return html`

package/_lib/setup-media-session.js

@@ -1,9 +1,51 @@
 import { getCover } from './get-cover.js';
+import { isValidTrackIndex } from './is-valid-track-index.js';
 
-export function setupMediaSession({ index, playlist, handleAudio }) {
+const MEDIA_SESSION_ACTIONS = [
+  'play',
+  'pause',
+  'stop',
+  'nexttrack',
+  'previoustrack'
+];
+let mediaSessionOwner = null;
+
+function getMediaSession() {
+  return navigator.mediaSession || null;
+}
+
+export function isMediaSessionOwner({ owner }) {
+  return owner !== null && owner !== undefined && mediaSessionOwner === owner;
+}
+
+export function clearMediaSession({ owner }) {
+  const mediaSession = getMediaSession();
+  if (!mediaSession || !isMediaSessionOwner({ owner })) {
+    return false;
+  }
+
+  mediaSession.metadata = null;
+  MEDIA_SESSION_ACTIONS.forEach(action => {
+    mediaSession.setActionHandler(action, null);
+  });
+  mediaSessionOwner = null;
+  return true;
+}
+
+export function setupMediaSession({ owner, index, playlist, handleAudio }) {
+  const mediaSession = getMediaSession();
+  if (!mediaSession || owner === null || owner === undefined) {
+    return false;
+  }
+
+  if (!isValidTrackIndex({ index, playlist })) {
+    return false;
+  }
+
+  mediaSessionOwner = owner;
   const metadata = playlist[index];
   const type = 'image/jpeg';
-  navigator.mediaSession.metadata = new MediaMetadata({
+  mediaSession.metadata = new MediaMetadata({
     title: metadata.title,
     artist: metadata.artist,
     album: metadata.album,
@@ -15,15 +57,32 @@ export function setupMediaSession({ index, playlist, handleAudio }) {
       };
     })
   });
-  navigator.mediaSession.setActionHandler(
+  mediaSession.setActionHandler(
     'nexttrack',
     index < playlist.length - 1 ? handleAudio.next : null
   );
-  navigator.mediaSession.setActionHandler(
+  mediaSession.setActionHandler(
     'previoustrack',
     index > 0 ? handleAudio.previous : null
   );
-  navigator.mediaSession.setActionHandler('play', handleAudio.play);
-  navigator.mediaSession.setActionHandler('pause', handleAudio.pause);
-  navigator.mediaSession.setActionHandler('stop', handleAudio.stop);
+  mediaSession.setActionHandler('play', handleAudio.play);
+  mediaSession.setActionHandler('pause', handleAudio.pause);
+  mediaSession.setActionHandler('stop', handleAudio.stop);
+  return true;
+}
+
+export function syncMediaSession({ owner, index, playlist, handleAudio }) {
+  if (!getMediaSession()) {
+    return () => {};
+  }
+
+  if (index !== null) {
+    setupMediaSession({ owner, index, playlist, handleAudio });
+  } else {
+    clearMediaSession({ owner });
+  }
+
+  return () => {
+    clearMediaSession({ owner });
+  };
 }

package/_lib/setup-media-session.test.js

@@ -0,0 +1,176 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  clearMediaSession,
+  setupMediaSession,
+  syncMediaSession
+} from './setup-media-session.js';
+
+const originalMediaSession = navigator.mediaSession;
+const originalMediaMetadata = globalThis.MediaMetadata;
+const MEDIA_SESSION_ACTIONS = [
+  'play',
+  'pause',
+  'stop',
+  'nexttrack',
+  'previoustrack'
+];
+
+function createMediaSessionSpy() {
+  const actionHandlers = new Map();
+  return {
+    actionHandlers,
+    mediaSession: {
+      setActionHandler: vi.fn((action, handler) => {
+        actionHandlers.set(action, handler);
+      })
+    }
+  };
+}
+
+afterEach(() => {
+  Object.defineProperty(navigator, 'mediaSession', {
+    configurable: true,
+    value: originalMediaSession
+  });
+  globalThis.MediaMetadata = originalMediaMetadata;
+});
+
+describe('setupMediaSession', () => {
+  it('does not change Media Session for an invalid track selection', () => {
+    const { mediaSession } = createMediaSessionSpy();
+    Object.defineProperty(navigator, 'mediaSession', {
+      configurable: true,
+      value: mediaSession
+    });
+
+    expect(
+      setupMediaSession({
+        owner: Symbol('player-owner'),
+        index: 0,
+        playlist: [{ file: '' }],
+        handleAudio: {}
+      })
+    ).toBe(false);
+    expect(mediaSession.setActionHandler).not.toHaveBeenCalled();
+    expect(mediaSession.metadata).toBeUndefined();
+  });
+
+  it('configures Media Session for a valid track selection', () => {
+    const { mediaSession } = createMediaSessionSpy();
+    Object.defineProperty(navigator, 'mediaSession', {
+      configurable: true,
+      value: mediaSession
+    });
+    globalThis.MediaMetadata = class MediaMetadata {
+      constructor(metadata) {
+        Object.assign(this, metadata);
+      }
+    };
+
+    expect(
+      setupMediaSession({
+        owner: Symbol('player-owner'),
+        index: 0,
+        playlist: [{ file: '/audio/valid.mp3', title: 'Valid track' }],
+        handleAudio: {
+          next: vi.fn(),
+          previous: vi.fn(),
+          play: vi.fn(),
+          pause: vi.fn(),
+          stop: vi.fn()
+        }
+      })
+    ).toBe(true);
+    expect(mediaSession.metadata.title).toBe('Valid track');
+    expect(mediaSession.setActionHandler).toHaveBeenCalledTimes(5);
+  });
+
+  it('only lets the owning player clear Media Session handlers', () => {
+    const { actionHandlers, mediaSession } = createMediaSessionSpy();
+    const firstOwner = Symbol('first-player');
+    const secondOwner = Symbol('second-player');
+    const firstHandleAudio = {
+      next: vi.fn(),
+      previous: vi.fn(),
+      play: vi.fn(),
+      pause: vi.fn(),
+      stop: vi.fn()
+    };
+    const secondHandleAudio = {
+      next: vi.fn(),
+      previous: vi.fn(),
+      play: vi.fn(),
+      pause: vi.fn(),
+      stop: vi.fn()
+    };
+    Object.defineProperty(navigator, 'mediaSession', {
+      configurable: true,
+      value: mediaSession
+    });
+    globalThis.MediaMetadata = class MediaMetadata {
+      constructor(metadata) {
+        Object.assign(this, metadata);
+      }
+    };
+
+    setupMediaSession({
+      owner: firstOwner,
+      index: 0,
+      playlist: [{ file: '/audio/first.mp3', title: 'First track' }],
+      handleAudio: firstHandleAudio
+    });
+    setupMediaSession({
+      owner: secondOwner,
+      index: 0,
+      playlist: [{ file: '/audio/second.mp3', title: 'Second track' }],
+      handleAudio: secondHandleAudio
+    });
+
+    expect(clearMediaSession({ owner: firstOwner })).toBe(false);
+    expect(mediaSession.metadata.title).toBe('Second track');
+    expect(actionHandlers.get('play')).toBe(secondHandleAudio.play);
+
+    expect(clearMediaSession({ owner: secondOwner })).toBe(true);
+    expect(mediaSession.metadata).toBeNull();
+    MEDIA_SESSION_ACTIONS.forEach(action => {
+      expect(actionHandlers.get(action)).toBeNull();
+    });
+  });
+
+  it('returns unmount cleanup that clears the owning player session', () => {
+    const { actionHandlers, mediaSession } = createMediaSessionSpy();
+    const owner = Symbol('player-owner');
+    Object.defineProperty(navigator, 'mediaSession', {
+      configurable: true,
+      value: mediaSession
+    });
+    globalThis.MediaMetadata = class MediaMetadata {
+      constructor(metadata) {
+        Object.assign(this, metadata);
+      }
+    };
+
+    const cleanup = syncMediaSession({
+      owner,
+      index: 0,
+      playlist: [{ file: '/audio/track.mp3', title: 'Track to clean up' }],
+      handleAudio: {
+        next: vi.fn(),
+        previous: vi.fn(),
+        play: vi.fn(),
+        pause: vi.fn(),
+        stop: vi.fn()
+      }
+    });
+
+    expect(mediaSession.metadata.title).toBe('Track to clean up');
+
+    cleanup();
+
+    expect(clearMediaSession({ owner })).toBe(false);
+    expect(mediaSession.metadata).toBeNull();
+    MEDIA_SESSION_ACTIONS.forEach(action => {
+      expect(actionHandlers.get(action)).toBeNull();
+    });
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outbook/webcomponents-player",
-  "version": "1.4.6",
+  "version": "1.5.0",
   "main": "player.js",
   "type": "module",
   "private": false,
@@ -31,19 +31,18 @@
     "@outbook/a11y": ">=1.2.1",
     "color.js": "1.2.0",
     "custom-event-conjurer": "1.0.0",
-    "mystic-format-time": "1.0.2",
+    "@outbook/format-time": "1.0.5",
     "@outbook/webcomponents-scrollable": ">=1.0.2",
     "@outbook/webcomponents-type-icon": ">=1.1.4",
     "@outbook/webcomponents-badge-file-extension": ">=1.2.2",
-    "@outbook/webcomponents-player-artwork": ">=1.1.2",
-    "@outbook/webcomponents-player-timeline": ">=1.0.2",
-    "@outbook/icons": ">=1.3.1"
+    "@outbook/webcomponents-player-artwork": ">=1.1.3",
+    "@outbook/webcomponents-player-timeline": ">=1.0.6",
+    "@outbook/icons": ">=1.3.1",
+    "@outbook/webcomponents-player-audio-decoy": ">=1.0.0"
   },
   "devDependencies": {
     "@outbook/colorful": ">=1.1.4",
-    "@outbook/design-decisions": ">=1.1.7",
-    "@outbook/webcomponents-player-artwork": ">=1.0.0",
-    "@outbook/webcomponents-player-timeline": ">=1.0.4"
+    "@outbook/design-decisions": ">=1.1.9"
   },
   "peerDependencies": {
     "lit": "^3.0.0",

package/player.js

@@ -1,9 +1,14 @@
 import { adoptStyles, html, nothing } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
-import { component, useEffect, useState } from 'haunted';
+import { component, useEffect, useRef, useState } from 'haunted';
 import { customEventConjurer } from 'custom-event-conjurer';
 import styleComponent from './_style/player.style.js';
-import { setupMediaSession } from './_lib/setup-media-session.js';
+import {
+  clearMediaSession,
+  isMediaSessionOwner,
+  syncMediaSession
+} from './_lib/setup-media-session.js';
+import { isValidTrackIndex } from './_lib/is-valid-track-index.js';
 import { emptyBackground, getBackgroundColor } from './_lib/background.js';
 import { getCover } from './_lib/get-cover.js';
 import { classMap } from 'lit/directives/class-map.js';
@@ -16,6 +21,7 @@ import { loadLiterals } from './_i18n/i18n.js';
 import _literals from './_i18n/en.json';
 import { useLangObserver } from '@outbook/hooks';
 import { toBoolean } from './_lib/to-boolean.js';
+import { PlayerAudioDecoy } from '@outbook/webcomponents-player-audio-decoy';
 
 function ComponentPlayer(element) {
   const {
@@ -57,6 +63,57 @@ function ComponentPlayer(element) {
   const [prominentColors, setProminentColors] = useState('');
   const [hasProminentColors, setHasProminentColors] = useState(false);
   const [coverUrl, setCoverUrl] = useState(null);
+  const [playbackRequestId, setPlaybackRequestId] = useState(0);
+  const playbackRequestRef = useRef({
+    id: 0,
+    started: true,
+    removeListeners: null
+  });
+  const selectedTrackRef = useRef(null);
+  const mediaSessionOwner = useRef(Symbol('outbook-player-media-session'));
+  const playlistMediaSessionSignature = playlist
+    .map(track =>
+      [
+        track?.file,
+        track?.title,
+        track?.artist,
+        track?.album,
+        track?.cover?.path,
+        track?.cover?.name,
+        track?.cover?.extension
+      ].join('\u0000')
+    )
+    .join('\u0001');
+
+  function setMediaSessionPlaybackState(playbackState) {
+    if (
+      navigator.mediaSession &&
+      isMediaSessionOwner({ owner: mediaSessionOwner.current })
+    ) {
+      navigator.mediaSession.playbackState = playbackState;
+    }
+  }
+
+  function cancelPendingInitialPlayback() {
+    const request = playbackRequestRef.current;
+    request.removeListeners?.();
+    playbackRequestRef.current = {
+      id: request.id + 1,
+      started: true,
+      removeListeners: null
+    };
+    return playbackRequestRef.current.id;
+  }
+
+  function requestInitialPlayback() {
+    const requestId = cancelPendingInitialPlayback();
+    playbackRequestRef.current = {
+      id: requestId,
+      started: false,
+      removeListeners: null
+    };
+    setPlaybackRequestId(requestId);
+  }
 
   useEffect(() => {
     let isActive = true;
@@ -93,22 +150,101 @@ function ComponentPlayer(element) {
   }, []);
 
   useEffect(() => {
-    if (navigator.mediaSession && indexSelected !== null) {
-      setupMediaSession({
-        index: indexSelected,
-        playlist,
-        handleAudio: {
-          stop: handleAudio.stop,
-          play: handleAudio.play,
-          pause: handleSessionPause,
-          next: handleSessionNext,
-          previous: handleSessionPrevious
-        }
-      });
-    } else if (navigator.mediaSession) {
-      navigator.mediaSession.metadata = null;
+    if (!Number.isInteger(indexSelected)) {
+      return undefined;
     }
-  }, [indexSelected]);
+
+    const request = playbackRequestRef.current;
+    if (request.id !== playbackRequestId || request.started) {
+      return undefined;
+    }
+
+    const mediaElement = getMediaElement();
+    if (!mediaElement) {
+      return undefined;
+    }
+
+    const playInitial = () => {
+      if (playbackRequestRef.current !== request || request.started) {
+        return;
+      }
+
+      request.started = true;
+      request.removeListeners?.();
+      request.removeListeners = null;
+      mediaElement.currentTime = 0;
+      setCurrentTime(0);
+      playAudio(mediaElement);
+    };
+
+    if (mediaElement.readyState > 0) {
+      playInitial();
+      return undefined;
+    }
+
+    const removeListeners = () => {
+      mediaElement.removeEventListener('loadedmetadata', playInitial);
+      mediaElement.removeEventListener('canplay', playInitial);
+    };
+    request.removeListeners = removeListeners;
+    mediaElement.addEventListener('loadedmetadata', playInitial, {
+      once: true
+    });
+    mediaElement.addEventListener('canplay', playInitial, { once: true });
+
+    return () => {
+      if (playbackRequestRef.current === request) {
+        removeListeners();
+        request.removeListeners = null;
+      }
+    };
+  }, [indexSelected, playbackRequestId]);
+
+  useEffect(() => () => cancelPendingInitialPlayback(), []);
+
+  useEffect(() => {
+    if (!Number.isInteger(indexSelected)) {
+      selectedTrackRef.current = null;
+      return;
+    }
+
+    const selectedTrack = playlist[indexSelected];
+    if (
+      !isValidTrackIndex({ index: indexSelected, playlist }) ||
+      selectedTrackRef.current?.file !== selectedTrack.file
+    ) {
+      handleSessionStop();
+      return;
+    }
+
+    selectedTrackRef.current = selectedTrack;
+    setCoverUrl(
+      selectedTrack.cover?.name ? getCover(selectedTrack.cover) : null
+    );
+  }, [indexSelected, playlist, playlistMediaSessionSignature]);
+
+  useEffect(() => {
+    if (
+      indexSelected !== null &&
+      (!isValidTrackIndex({ index: indexSelected, playlist }) ||
+        selectedTrackRef.current?.file !== playlist[indexSelected].file)
+    ) {
+      return undefined;
+    }
+
+    return syncMediaSession({
+      owner: mediaSessionOwner.current,
+      index: indexSelected,
+      playlist,
+      handleAudio: {
+        stop: handleAudio.stop,
+        play: handleAudio.play,
+        pause: handleSessionPause,
+        next: handleSessionNext,
+        previous: handleSessionPrevious
+      }
+    });
+  }, [indexSelected, playlist, playlistMediaSessionSignature]);
 
   useEffect(() => {
     let isMounted = true;
@@ -133,25 +269,54 @@ function ComponentPlayer(element) {
   }
 
   function handleSessionPause() {
-    getMediaElement().pause();
-    if (navigator.mediaSession) {
-      navigator.mediaSession.playbackState = 'paused';
+    cancelPendingInitialPlayback();
+    const media = getMediaElement();
+    if (!media) {
+      return;
     }
+    media.pause();
     setIsPlaying(false);
+    setMediaSessionPlaybackState('paused');
   }
 
-  function handleSessionPlay() {
-    getMediaElement().play();
-    setIsPlaying(true);
-    if (navigator.mediaSession) {
-      navigator.mediaSession.playbackState = 'playing';
+  async function playAudio(mediaElement) {
+    try {
+      await mediaElement.play();
+    } catch (err) {
+      console.error('Playback failed:', err);
+      setIsPlaying(false);
+      setMediaSessionPlaybackState('paused');
     }
   }
 
-  function handleSessionStop() {
-    if (navigator.mediaSession) {
-      navigator.mediaSession.playbackState = 'none';
+  async function handleSessionPlay() {
+    const media = getMediaElement();
+    if (!media) {
+      return;
     }
+    await playAudio(media);
+  }
+
+  function handleAudioNativePlay() {
+    setIsPlaying(true);
+    setMediaSessionPlaybackState('playing');
+  }
+
+  function handleAudioNativePause() {
+    setIsPlaying(false);
+    setMediaSessionPlaybackState('paused');
+  }
+
+  function handleAudioNativeError(ev) {
+    cancelPendingInitialPlayback();
+    console.error('Audio error:', ev.currentTarget?.error);
+    setIsPlaying(false);
+    setMediaSessionPlaybackState('paused');
+  }
+
+  function handleSessionStop() {
+    cancelPendingInitialPlayback();
+    setMediaSessionPlaybackState('none');
 
     const media = getMediaElement();
 
@@ -163,12 +328,11 @@ function ComponentPlayer(element) {
     setTotalTime(0);
     setCurrentTime(0); // Set zero on stop
     setHasProminentColors(false);
-
-    if (navigator.mediaSession) {
-      navigator.mediaSession.metadata = null;
-    }
+    setIsPlaying(false);
+    clearMediaSession({ owner: mediaSessionOwner.current });
 
     setIndexSelected(null);
+    selectedTrackRef.current = null;
     setCoverUrl(null);
   }
 
@@ -188,43 +352,31 @@ function ComponentPlayer(element) {
     next: handleSessionNext,
     previous: handleSessionPrevious,
     setTrack({ index, fromControls = false }) {
+      if (!isValidTrackIndex({ index, playlist })) {
+        return false;
+      }
+
+      const media = getMediaElement();
+      if (media) {
+        media.pause();
+        media.currentTime = 0;
+      }
+      setTotalTime(0);
+      setCurrentTime(0);
       setIndexSelected(index);
+      selectedTrackRef.current = playlist[index];
       if (fromControls) {
         handleScroll({ index });
       }
 
-      if (playlist[index]?.cover?.name) {
-        setCoverUrl(getCover(playlist[index]?.cover));
-      } else {
-        setCoverUrl(null);
-      }
-      setTimeout(() => {
-        this.playInitial();
-      }, 100);
+      setCoverUrl(
+        playlist[index].cover?.name ? getCover(playlist[index].cover) : null
+      );
+      requestInitialPlayback();
+      return true;
     },
     stop: handleSessionStop,
     play: handleSessionPlay,
-    playInitial() {
-      const mediaElement = getMediaElement();
-      if (!mediaElement) {
-        console.warn('Audio element not ready yet, retrying...');
-        setTimeout(() => this.playInitial(), 50);
-        return;
-      }
-      mediaElement.currentTime = 0;
-      setCurrentTime(0); // Set zero initial time
-
-      mediaElement
-        .play()
-        .then(function () {
-          setTotalTime(mediaElement.duration);
-          if (navigator.mediaSession) {
-            navigator.mediaSession.playbackState = 'playing';
-          }
-          setIsPlaying(true);
-        })
-        .catch(err => console.error('Autoplay blocked:', err));
-    },
     pause: handleSessionPause
   };
 
@@ -241,13 +393,25 @@ function ComponentPlayer(element) {
     setCurrentTime(media.currentTime);
   }
 
+  function handleDurationChange(ev) {
+    const duration = ev.currentTarget.duration;
+    setTotalTime(Number.isFinite(duration) && duration > 0 ? duration : 0);
+  }
+
   function handleReposition(ev) {
     const newTime = ev.detail.currentTime;
     const media = getMediaElement();
-    if (media) {
-      media.currentTime = newTime;
+    if (
+      !media ||
+      !Number.isFinite(totalTime) ||
+      totalTime <= 0 ||
+      !Number.isFinite(newTime)
+    ) {
+      return;
     }
-    setCurrentTime(newTime);
+    const safeTime = Math.max(0, Math.min(newTime, totalTime));
+    media.currentTime = safeTime;
+    setCurrentTime(safeTime);
   }
 
   const mainClasses = classMap({
@@ -301,6 +465,7 @@ function ComponentPlayer(element) {
             </div>
           </div>
         </div>
+        ${isPlaying ? html`${PlayerAudioDecoy({ mode: 'auto' })}` : nothing}
         ${Number.isInteger(indexSelected)
           ? html`
               <audio
@@ -308,6 +473,11 @@ function ComponentPlayer(element) {
                 id="${mediaId}"
                 @ended="${handleAudioEnd}"
                 @timeupdate="${handleTimeUpdate}"
+                @loadedmetadata="${handleDurationChange}"
+                @durationchange="${handleDurationChange}"
+                @play="${handleAudioNativePlay}"
+                @pause="${handleAudioNativePause}"
+                @error="${handleAudioNativeError}"
               ></audio>
             `
           : nothing}