@readium/navigator 2.4.0-beta.8 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/navigator",
-  "version": "2.4.0-beta.8",
+  "version": "2.4.0",
   "type": "module",
   "description": "Next generation SDK for publications in Web Apps",
   "author": "readium",
@@ -50,7 +50,7 @@
     "generate:css-selector": "node scripts/generate-css-selector.js"
   },
   "devDependencies": {
-    "@readium/css": "^2.0.0",
+    "@readium/css": "^2.0.1",
     "@readium/navigator-html-injectables": "workspace:*",
     "@readium/shared": "workspace:*",
     "@types/path-browserify": "^1.0.3",

package/src/audio/AudioNavigator.ts

@@ -1,7 +1,7 @@
-import { Link, Locator, LocatorLocations, Publication } from "@readium/shared";
-import { MediaNavigator, IContentProtectionConfig, IKeyboardPeripheralsConfig } from "../Navigator";
-import { Configurable } from "../preferences";
-import { WebAudioEngine, PlaybackState } from "./engine";
+import { Link, Locator, LocatorLocations, Publication, Timeline, TimelineItem } from "@readium/shared";
+import { MediaNavigator, IContentProtectionConfig, IKeyboardPeripheralsConfig } from "../Navigator.ts";
+import { Configurable } from "../preferences/Configurable.ts";
+import { WebAudioEngine, PlaybackState } from "./engine/index.ts";
 import {
     AudioPreferences,
     AudioDefaults,
@@ -9,33 +9,42 @@ import {
     AudioPreferencesEditor,
     IAudioPreferences,
     IAudioDefaults
-} from "./preferences";
-import { AudioPoolManager } from "./AudioPoolManager";
-import { AudioTimeline } from "./AudioTimeline";
+} from "./preferences/index.ts";
+import { AudioPoolManager } from "./AudioPoolManager.ts";
 import { ContextMenuEvent, KeyboardEventData, SuspiciousActivityEvent } from "@readium/navigator-html-injectables";
-import { AudioNavigatorProtector } from "./protection/AudioNavigatorProtector";
-import { NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT } from "../protection/NavigatorProtector";
-import { KeyboardPeripherals, NAVIGATOR_KEYBOARD_PERIPHERAL_EVENT } from "../peripherals/KeyboardPeripherals";
+import { AudioNavigatorProtector } from "./protection/AudioNavigatorProtector.ts";
+import { NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT } from "../protection/NavigatorProtector.ts";
+import { KeyboardPeripherals, NAVIGATOR_KEYBOARD_PERIPHERAL_EVENT } from "../peripherals/KeyboardPeripherals.ts";
+
+export interface AudioMetadata {
+    duration: number;
+    textTracks: TextTrackList;
+    readyState: number;
+    networkState: number;
+}
 
 export interface AudioNavigatorListeners {
     trackLoaded: (media: HTMLMediaElement) => void;
     positionChanged: (locator: Locator) => void;
+    timelineItemChanged: (item: TimelineItem | undefined) => void;
     error: (error: any, locator: Locator) => void;
     trackEnded: (locator: Locator) => void;
     play: (locator: Locator) => void;
     pause: (locator: Locator) => void;
-    metadataLoaded: (duration: number) => void;
+    metadataLoaded: (metadata: AudioMetadata) => void;
     stalled: (isStalled: boolean) => void;
     seeking: (isSeeking: boolean) => void;
     seekable: (seekable: TimeRanges) => void;
     contentProtection: (type: string, data: SuspiciousActivityEvent) => void;
     peripheral: (data: KeyboardEventData) => void;
     contextMenu: (data: ContextMenuEvent) => void;
+    remotePlaybackStateChanged: (state: RemotePlaybackState) => void;
 }
 
 const defaultListeners = (listeners: Partial<AudioNavigatorListeners>): AudioNavigatorListeners => ({
     trackLoaded: listeners.trackLoaded ?? (() => {}),
     positionChanged: listeners.positionChanged ?? (() => {}),
+    timelineItemChanged: listeners.timelineItemChanged ?? (() => {}),
     error: listeners.error ?? (() => {}),
     trackEnded: listeners.trackEnded ?? (() => {}),
     play: listeners.play ?? (() => {}),
@@ -47,12 +56,18 @@ const defaultListeners = (listeners: Partial<AudioNavigatorListeners>): AudioNav
     contentProtection: listeners.contentProtection ?? (() => {}),
     peripheral: listeners.peripheral ?? (() => {}),
     contextMenu: listeners.contextMenu ?? (() => {}),
+    remotePlaybackStateChanged: listeners.remotePlaybackStateChanged ?? (() => {}),
 });
 
+export interface IAudioContentProtectionConfig extends IContentProtectionConfig {
+    /** Prevents the media element from being cast to remote devices via the Remote Playback API. */
+    disableRemotePlayback?: boolean;
+}
+
 export interface AudioNavigatorConfiguration {
     preferences: IAudioPreferences;
     defaults: IAudioDefaults;
-    contentProtection?: IContentProtectionConfig;
+    contentProtection?: IAudioContentProtectionConfig;
     keyboardPeripherals?: IKeyboardPeripheralsConfig;
 }
 
@@ -71,10 +86,16 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     private _mediaSessionEnabled: boolean = false;
     private pool: AudioPoolManager;
     private readonly _navigatorProtector: AudioNavigatorProtector | null = null;
-    private readonly _timeline: AudioTimeline;
+    private _currentTimelineItem: TimelineItem | undefined;
     private readonly _keyboardPeripheralsManager: KeyboardPeripherals | null = null;
     private readonly _suspiciousActivityListener: ((event: Event) => void) | null = null;
     private readonly _keyboardPeripheralListener: ((event: Event) => void) | null = null;
+    private readonly _contentProtection: IAudioContentProtectionConfig;
+    /** True while a track transition is in progress; suppresses spurious mid-navigation events. */
+    private _isNavigating: boolean = false;
+    private _isStalled: boolean = false;
+    private _stalledWatchdog: ReturnType<typeof setInterval> | null = null;
+    private _stalledCheckTime: number = 0;
 
     constructor(publication: Publication, listeners: AudioNavigatorListeners, initialPosition?: Locator, configuration: AudioNavigatorConfiguration = {
         preferences: {},
@@ -82,13 +103,16 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     }) {
         super();
         this.pub = publication;
-        this._timeline = new AudioTimeline(publication);
         this.listeners = defaultListeners(listeners);
 
         this._preferences = new AudioPreferences(configuration.preferences);
         this._defaults = new AudioDefaults(configuration.defaults);
         this._settings = new AudioSettings(this._preferences, this._defaults);
 
+        if (publication.readingOrder.items.length === 0) {
+            throw new Error("AudioNavigator: publication has an empty reading order");
+        }
+
         if (initialPosition) {
             this.currentLocation = this.ensureLocatorLocations(initialPosition);
         } else {
@@ -98,7 +122,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 type: firstLink.type || "audio/mpeg",
                 title: firstLink.title,
                 locations: new LocatorLocations({
-                    position: 0,
+                    position: 1,
                     progression: 0,
                     totalProgression: 0,
                     fragments: ["t=0"]
@@ -108,6 +132,9 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
 
         const initialHref = this.currentLocation.href.split("#")[0];
         const trackIndex = this.hrefToTrackIndex(initialHref);
+        if (trackIndex === -1) {
+            throw new Error(`AudioNavigator: initial href "${ initialHref }" not found in reading order`);
+        }
         const initialTime = this.currentLocation.locations?.time() || 0;
 
         const audioEngine = new WebAudioEngine({
@@ -121,10 +148,11 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             }
         });
 
-        this.pool = new AudioPoolManager(audioEngine, publication);
+        this.pool = new AudioPoolManager(audioEngine, publication, configuration.contentProtection);
 
         // Initialize content protection
         const contentProtection = configuration.contentProtection || {};
+        this._contentProtection = contentProtection;
         const keyboardPeripherals = this.mergeKeyboardPeripherals(
             contentProtection,
             configuration.keyboardPeripherals || []
@@ -158,19 +186,27 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         }
 
         this.setupEventListeners();
-        this.applyPreferences();
 
+        this._isNavigating = true;
         this.pool.setCurrentAudio(trackIndex, "forward");
 
+        // applyPreferences() must come after setCurrentAudio() so that the src
+        // is already set on the media element when setPlaybackRate() tries to
+        // activate the Web Audio graph for the preservePitch polyfill path.
+        this.applyPreferences();
+
         // Load and seek to initial position, then notify consumer.
         // No cancellation needed here — the constructor runs once.
         this.waitForLoadedAndSeeked(initialTime)
             .then(() => {
+                this._isNavigating = false;
                 this.listeners.trackLoaded(this.pool.audioEngine.getMediaElement());
-                this._timeline.update(this.currentLocator);
+                this._notifyTimelineChange(this.currentLocator);
                 this.listeners.positionChanged(this.currentLocator);
+                this._setupRemotePlayback();
             })
             .catch(() => {
+                this._isNavigating = false;
                 // Error already forwarded via the error event listener.
             });
     }
@@ -201,6 +237,8 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         this.pool.audioEngine.setVolume(this._settings.volume);
         this.pool.audioEngine.setPlaybackRate(this._settings.playbackRate, this._settings.preservePitch);
 
+        if (this.positionPollInterval !== null) this.startPositionPolling();
+
         if (this._settings.enableMediaSession && !this._mediaSessionEnabled) {
             this._mediaSessionEnabled = true;
             this.setupMediaSession();
@@ -214,8 +252,19 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         return this.pub;
     }
 
-    get timeline(): AudioTimeline {
-        return this._timeline;
+    get timeline(): Timeline {
+        return this.pub.timeline;
+    }
+
+    private _notifyTimelineChange(locator: Locator): void {
+        const item = this.pub.timeline.locate(locator);
+        if (item !== this._currentTimelineItem) {
+            this._currentTimelineItem = item;
+            this.listeners.timelineItemChanged(item);
+            if (this._settings.enableMediaSession) {
+                this.updateMediaSessionMetadata();
+            }
+        }
     }
 
     private ensureLocatorLocations(locator: Locator): Locator {
@@ -271,7 +320,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             title: link.title,
             locations: new LocatorLocations({
                 progression: duration > 0 ? timestamp / duration : 0,
-                position: trackIndex,
+                position: trackIndex + 1,
                 fragments: [`t=${timestamp}`]
             })
         });
@@ -330,7 +379,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         this.pool.audioEngine.on("ended", async () => {
             this.stopPositionPolling();
             this.currentLocation = this.currentLocation.copyWithLocations(new LocatorLocations({
-                position: this.currentTrackIndex(),
+                position: this.currentTrackIndex() + 1,
                 progression: 1,
                 fragments: [`t=${this.duration}`]
             }));
@@ -341,45 +390,91 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         });
 
         this.pool.audioEngine.on("play", () => {
+            if (this._isNavigating) return;
             this.startPositionPolling();
             this.listeners.play(this.currentLocator);
         });
 
         this.pool.audioEngine.on("playing", () => {
-            this.listeners.stalled(false);
+            if (this._isNavigating) return;
+            this._setStalled(false);
         });
 
         this.pool.audioEngine.on("pause", () => {
+            if (this._isNavigating) return;
             this.stopPositionPolling();
             this.listeners.pause(this.currentLocator);
         });
 
         this.pool.audioEngine.on("seeked", () => {
+            if (this._isNavigating) return;
             this.listeners.seeking(false);
-            if (!this.isPlaying) {
-                const currentTime = this.currentTime;
-                const duration = this.duration;
-                const progression = duration > 0 ? currentTime / duration : 0;
-                this.currentLocation = this.currentLocation.copyWithLocations(new LocatorLocations({
-                    position: this.currentTrackIndex(),
-                    progression,
-                    fragments: [`t=${currentTime}`]
-                }));
-                this._timeline.update(this.currentLocation);
-                this.listeners.positionChanged(this.currentLocation);
-            }
+            const currentTime = this.currentTime;
+            const duration = this.duration;
+            const progression = duration > 0 ? currentTime / duration : 0;
+            this.currentLocation = this.currentLocation.copyWithLocations(new LocatorLocations({
+                position: this.currentTrackIndex() + 1,
+                progression,
+                fragments: [`t=${currentTime}`]
+            }));
+            // Always notify on seeked — don't defer to polling — so that a skip
+            // crossing a timeline item boundary fires timelineItemChanged immediately
+            // regardless of play state. _notifyTimelineChange deduplicates internally.
+            this._notifyTimelineChange(this.currentLocation);
+            this.listeners.positionChanged(this.currentLocation);
         });
 
-        this.pool.audioEngine.on("seeking", () => this.listeners.seeking(true));
-        this.pool.audioEngine.on("waiting", () => this.listeners.seeking(true));
-        this.pool.audioEngine.on("stalled", () => this.listeners.stalled(true));
-        this.pool.audioEngine.on("progress", (seekable: TimeRanges) => this.listeners.seekable(seekable));
-        
+        this.pool.audioEngine.on("seeking", () => { if (!this._isNavigating) this.listeners.seeking(true); });
+        this.pool.audioEngine.on("waiting", () => { if (!this._isNavigating) this.listeners.seeking(true); });
+        this.pool.audioEngine.on("stalled", () => { if (!this._isNavigating) this._setStalled(true); });
+        this.pool.audioEngine.on("canplaythrough", () => { if (!this._isNavigating) this._setStalled(false); });
+        this.pool.audioEngine.on("progress", (seekable: TimeRanges) => { if (!this._isNavigating) this.listeners.seekable(seekable); });
+
         this.pool.audioEngine.on("loadedmetadata", () => {
-            this.listeners.metadataLoaded(this.pool.audioEngine.duration());
+            const mediaElement = this.pool.audioEngine.getMediaElement();
+            const metadata: AudioMetadata = {
+                duration: this.pool.audioEngine.duration(),
+                textTracks: mediaElement.textTracks,
+                readyState: mediaElement.readyState,
+                networkState: mediaElement.networkState
+            };
+            this.listeners.metadataLoaded(metadata);
         });
     }
 
+    private _setStalled(isStalled: boolean): void {
+        if (this._isStalled === isStalled) return;
+        this._isStalled = isStalled;
+        this.listeners.stalled(isStalled);
+        if (isStalled) {
+            this._stalledCheckTime = this.currentTime;
+            this._startStalledWatchdog();
+        } else {
+            this._stopStalledWatchdog();
+        }
+    }
+
+    private _startStalledWatchdog(): void {
+        this._stalledWatchdog = setInterval(() => {
+            if (!this.isPlaying) {
+                this._setStalled(false);
+                return;
+            }
+            const t = this.currentTime;
+            if (t !== this._stalledCheckTime) {
+                this._setStalled(false);
+            }
+            this._stalledCheckTime = t;
+        }, 500);
+    }
+
+    private _stopStalledWatchdog(): void {
+        if (this._stalledWatchdog !== null) {
+            clearInterval(this._stalledWatchdog);
+            this._stalledWatchdog = null;
+        }
+    }
+
     private setupMediaSession(): void {
         if (!("mediaSession" in navigator)) return;
         navigator.mediaSession.setActionHandler("play", () => this.play());
@@ -402,7 +497,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 ? this.pub.metadata.authors.items.map((a) => a.name.getTranslation()).join(", ")
                 : undefined,
             album: this.pub.metadata.title.getTranslation(),
-            artwork: cover ? [{ src: cover.href, type: cover.type }] : undefined,
+            artwork: cover ? [{ src: cover.toURL(this.pub.baseURL) ?? cover.href, type: cover.type }] : undefined,
         });
     }
 
@@ -413,11 +508,11 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             const duration = this.duration;
             const progression = duration > 0 ? currentTime / duration : 0;
             this.currentLocation = this.currentLocation.copyWithLocations(new LocatorLocations({
-                position: this.currentTrackIndex(),
+                position: this.currentTrackIndex() + 1,
                 progression,
                 fragments: [`t=${currentTime}`]
             }));
-            this._timeline.update(this.currentLocation);
+            this._notifyTimelineChange(this.currentLocation);
             this.listeners.positionChanged(this.currentLocation);
         }, this._settings.pollInterval);
     }
@@ -442,23 +537,28 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             }
 
             const id = ++this.navigationId;
-            const direction: "forward" | "backward" = trackIndex >= this.currentTrackIndex() ? "forward" : "backward";
-            // Use _playIntent rather than isPlaying — setMediaElement resets the
-            // engine's playing flag, so a rapid second go() would see false and
-            // never resume playback.
+            const previousTrackIndex = this.currentTrackIndex();
+            const direction: "forward" | "backward" = trackIndex >= previousTrackIndex ? "forward" : "backward";
             const wasPlaying = this.isPlaying || this._playIntent;
             this._playIntent = wasPlaying;
 
+            this._isNavigating = true;
             this.stopPositionPolling();
             this.pool.setCurrentAudio(trackIndex, direction);
             this.currentLocation = locator.copyWithLocations(locator.locations);
 
             await this.waitForLoadedAndSeeked(time, id);
+            this._isNavigating = false;
 
-            if (id !== this.navigationId) return;
+            if (id !== this.navigationId) {
+                cb(false);
+                return;
+            }
 
-            this.listeners.trackLoaded(this.pool.audioEngine.getMediaElement());
-            this._timeline.update(this.currentLocator);
+            if (trackIndex !== previousTrackIndex) {
+                this.listeners.trackLoaded(this.pool.audioEngine.getMediaElement());
+            }
+            this._notifyTimelineChange(this.currentLocator);
             this.listeners.positionChanged(this.currentLocator);
 
             if (this._settings.enableMediaSession) {
@@ -466,12 +566,14 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             }
 
             if (wasPlaying) this.play();
-            this._playIntent = false;
 
             cb(true);
         } catch (error) {
+            this._isNavigating = false;
             console.error("Failed to go to locator:", error);
             cb(false);
+        } finally {
+            this._playIntent = false;
         }
     }
 
@@ -561,6 +663,29 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         return this.currentTrackIndex() < this.pub.readingOrder.items.length - 1;
     }
 
+    /**
+     * The RemotePlayback object for the primary media element.
+     * Because the element is never swapped, this reference is stable for the
+     * lifetime of the navigator — host apps can store it and call `.prompt()`,
+     * `.watchAvailability()`, etc. directly.
+     */
+    get remotePlayback(): RemotePlayback | undefined {
+        const el = this.pool.audioEngine.getMediaElement();
+        return "remote" in el ? el.remote : undefined;
+    }
+
+    /** Wires up the optional remotePlaybackStateChanged listener. Called once after initial load. */
+    private _setupRemotePlayback(): void {
+        if (this._contentProtection.disableRemotePlayback) {
+            return;
+        }
+        const remote = this.remotePlayback;
+        if (!remote) return;
+        remote.onconnecting = () => this.listeners.remotePlaybackStateChanged("connecting");
+        remote.onconnect    = () => this.listeners.remotePlaybackStateChanged("connected");
+        remote.ondisconnect = () => this.listeners.remotePlaybackStateChanged("disconnected");
+    }
+
     private destroyMediaSession(): void {
         if (!("mediaSession" in navigator)) return;
         navigator.mediaSession.metadata = null;
@@ -574,6 +699,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
 
     destroy(): void {
         this.stopPositionPolling();
+        this._stopStalledWatchdog();
         this.destroyMediaSession();
         if (this._suspiciousActivityListener) {
             window.removeEventListener(NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT, this._suspiciousActivityListener);

package/src/audio/AudioPoolManager.ts

@@ -1,5 +1,6 @@
 import { Link, Publication } from "@readium/shared";
-import { WebAudioEngine } from "./engine/WebAudioEngine";
+import { WebAudioEngine } from "./engine/WebAudioEngine.ts";
+import type { IAudioContentProtectionConfig } from "./AudioNavigator.ts";
 
 const UPPER_BOUNDARY = 1;
 const LOWER_BOUNDARY = 1;
@@ -10,10 +11,14 @@ export class AudioPoolManager {
     private readonly _publication: Publication;
     private readonly _supportedAudioTypes: Map<string, "probably" | "maybe">;
 
-    constructor(audioEngine: WebAudioEngine, publication: Publication) {
+    constructor(audioEngine: WebAudioEngine, publication: Publication, contentProtection: IAudioContentProtectionConfig = {}) {
         this._audioEngine = audioEngine;
         this._publication = publication;
         this._supportedAudioTypes = this.detectSupportedAudioTypes();
+
+        if (contentProtection.disableRemotePlayback) {
+            this._audioEngine.getMediaElement().disableRemotePlayback = true;
+        }
     }
 
     private detectSupportedAudioTypes(): Map<string, "probably" | "maybe"> {
@@ -34,16 +39,18 @@ export class AudioPoolManager {
     }
 
     private pickPlayableHref(link: Link): string {
+        const base = this._publication.baseURL;
         const candidates = [link, ...(link.alternates?.items ?? [])];
         let best: { href: string; confidence: "probably" | "maybe" } | undefined;
         for (const candidate of candidates) {
             if (!candidate.type) continue;
             const confidence = this._supportedAudioTypes.get(candidate.type);
             if (!confidence) continue;
-            if (confidence === "probably") return candidate.href;
-            if (!best) best = { href: candidate.href, confidence };
+            const href = candidate.toURL(base) ?? candidate.href;
+            if (confidence === "probably") return href;
+            if (!best) best = { href, confidence };
         }
-        return best?.href ?? link.href;
+        return best?.href ?? (link.toURL(base) ?? link.href);
     }
 
     get audioEngine(): WebAudioEngine {
@@ -59,8 +66,8 @@ export class AudioPoolManager {
         if (!element) {
             element = document.createElement("audio");
             element.preload = "auto";
-            // When Web Audio is active CORS already succeeded, so preload
-            // with crossOrigin to avoid a destructive reload at swap time.
+            // Match the primary element's CORS mode so cached responses
+            // are reusable when changeSrc() loads this href on it.
             if (this._audioEngine.isWebAudioActive) {
                 element.crossOrigin = "anonymous";
             }
@@ -74,12 +81,14 @@ export class AudioPoolManager {
     /**
      * Updates the pool around the given index: ensures elements exist within
      * the LOWER_BOUNDARY and disposes those beyond the UPPER_BOUNDARY.
+     * The current track is excluded — the primary engine element represents it.
      */
     private update(currentIndex: number): void {
         const items = this._publication.readingOrder.items;
         const keep = new Set<string>();
 
         for (let j = 0; j < items.length; j++) {
+            if (j === currentIndex) continue; // primary element handles the current track
             const href = this.pickPlayableHref(items[j]);
             if (j >= currentIndex - LOWER_BOUNDARY && j <= currentIndex + LOWER_BOUNDARY) {
                 this.ensure(href);
@@ -103,17 +112,21 @@ export class AudioPoolManager {
     }
 
     /**
-     * Sets the current audio for playback at the given track index.
-     * The element is always sourced from the pool — never loaded ad-hoc on the engine.
+     * Sets the current audio for playback at the given track index by changing
+     * the src on the persistent primary element. This preserves the RemotePlayback
+     * session and any Web Audio graph connections across track changes.
      */
     setCurrentAudio(currentIndex: number, _direction: 'forward' | 'backward'): void {
         const href = this.pickPlayableHref(this._publication.readingOrder.items[currentIndex]);
-        const element = this.ensure(href);
+        this.audioEngine.changeSrc(href);
 
-        this.audioEngine.setMediaElement(element);
-
-        // Remove from pool so the engine fully owns it and we don't dispose it
-        this.pool.delete(href);
+        // Discard any pool entry for this href — the primary element owns it now
+        if (this.pool.has(href)) {
+            const existing = this.pool.get(href)!;
+            existing.removeAttribute("src");
+            existing.load();
+            this.pool.delete(href);
+        }
 
         // Manage the pool around the new position
         this.update(currentIndex);

package/src/audio/engine/AudioEngine.ts

@@ -55,10 +55,11 @@ export interface AudioEngine {
     off(event: string, callback: (data: any) => void): void;
     
     /**
-     * Sets the media element for playback, enabling use of preloaded elements from the pool.
-     * @param element The HTML audio element to use for playback.
+     * Changes the src of the primary media element without swapping it,
+     * preserving the RemotePlayback session and all attached event listeners.
+     * @param href The URL of the new audio resource.
      */
-    setMediaElement(element: HTMLAudioElement): void;
+    changeSrc(href: string): void;
     
     /**
      * Plays the current audio resource.