@readium/navigator 2.4.0-beta.10 → 2.4.0-beta.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/navigator",
-  "version": "2.4.0-beta.10",
+  "version": "2.4.0-beta.11",
   "type": "module",
   "description": "Next generation SDK for publications in Web Apps",
   "author": "readium",

package/src/audio/AudioNavigator.ts

@@ -16,6 +16,13 @@ import { AudioNavigatorProtector } from "./protection/AudioNavigatorProtector";
 import { NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT } from "../protection/NavigatorProtector";
 import { KeyboardPeripherals, NAVIGATOR_KEYBOARD_PERIPHERAL_EVENT } from "../peripherals/KeyboardPeripherals";
 
+export interface AudioMetadata {
+    duration: number;
+    textTracks: TextTrackList;
+    readyState: number;
+    networkState: number;
+}
+
 export interface AudioNavigatorListeners {
     trackLoaded: (media: HTMLMediaElement) => void;
     positionChanged: (locator: Locator) => void;
@@ -24,13 +31,14 @@ export interface AudioNavigatorListeners {
     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 => ({
@@ -50,10 +58,15 @@ const defaultListeners = (listeners: Partial<AudioNavigatorListeners>): AudioNav
     contextMenu: listeners.contextMenu ?? (() => {}),
 });
 
+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;
 }
 
@@ -76,6 +89,9 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     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;
 
     constructor(publication: Publication, listeners: AudioNavigatorListeners, initialPosition?: Locator, configuration: AudioNavigatorConfiguration = {
         preferences: {},
@@ -121,10 +137,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 || []
@@ -160,17 +177,21 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         this.setupEventListeners();
         this.applyPreferences();
 
+        this._isNavigating = true;
         this.pool.setCurrentAudio(trackIndex, "forward");
 
         // 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._notifyTimelineChange(this.currentLocator);
                 this.listeners.positionChanged(this.currentLocator);
+                this._setupRemotePlayback();
             })
             .catch(() => {
+                this._isNavigating = false;
                 // Error already forwarded via the error event listener.
             });
     }
@@ -349,20 +370,24 @@ 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", () => {
+            if (this._isNavigating) return;
             this.listeners.stalled(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;
@@ -378,14 +403,21 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             }
         });
 
-        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("canplaythrough", () => this.listeners.stalled(false));
-        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.listeners.stalled(true); });
+        this.pool.audioEngine.on("canplaythrough", () => { if (!this._isNavigating) this.listeners.stalled(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);
         });
     }
 
@@ -452,17 +484,16 @@ 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 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) {
                 cb(false);
@@ -481,6 +512,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
 
             cb(true);
         } catch (error) {
+            this._isNavigating = false;
             console.error("Failed to go to locator:", error);
             cb(false);
         } finally {
@@ -574,6 +606,28 @@ 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 {
+        return this.pool.audioEngine.getMediaElement().remote;
+    }
+
+    /** 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;

package/src/audio/AudioPoolManager.ts

@@ -1,5 +1,6 @@
 import { Link, Publication } from "@readium/shared";
 import { WebAudioEngine } from "./engine/WebAudioEngine";
+import type { IAudioContentProtectionConfig } from "./AudioNavigator";
 
 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"> {
@@ -59,8 +64,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 +79,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 +110,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.

package/src/audio/engine/WebAudioEngine.ts

@@ -16,8 +16,6 @@ export class WebAudioEngine implements AudioEngine {
   private sourceNode: MediaElementAudioSourceNode | null = null;
   private gainNode: GainNode | null = null;
   private listeners: { [event: string]: EventCallback[] } = {};
-  private currentVolume: number = 1;
-  private currentPlaybackRate: number = 1;
   private isMutedValue: boolean = false;
   private isPlayingValue: boolean = false;
   private isPausedValue: boolean = false;
@@ -95,120 +93,6 @@ export class WebAudioEngine implements AudioEngine {
     );
   }
 
-  private deactivateWebAudio(): void {
-    if (this.worklet) {
-      this.worklet.destroy();
-      this.worklet = null;
-    }
-    if (this.sourceNode) {
-      this.sourceNode.disconnect();
-      this.sourceNode = null;
-    }
-    if (this.gainNode) {
-      this.gainNode.disconnect();
-      this.gainNode = null;
-    }
-    this.webAudioActive = false;
-  }
-
-  /**
-   * Sets the media element for playback.
-   * @param element The HTML audio element to use.
-   */
-  public setMediaElement(element: HTMLAudioElement): void {
-    // Remove listeners BEFORE pausing so the pause doesn't leak through
-    this.mediaElement.removeEventListener("canplaythrough", this.boundOnCanPlayThrough);
-    this.mediaElement.removeEventListener("timeupdate", this.boundOnTimeUpdate);
-    this.mediaElement.removeEventListener("error", this.boundOnError);
-    this.mediaElement.removeEventListener("ended", this.boundOnEnded);
-    this.mediaElement.removeEventListener("stalled", this.boundOnStalled);
-    this.mediaElement.removeEventListener("emptied", this.boundOnEmptied);
-    this.mediaElement.removeEventListener("suspend", this.boundOnSuspend);
-    this.mediaElement.removeEventListener("waiting", this.boundOnWaiting);
-    this.mediaElement.removeEventListener("loadedmetadata", this.boundOnLoadedMetadata);
-    this.mediaElement.removeEventListener("seeking", this.boundOnSeeking);
-    this.mediaElement.removeEventListener("seeked", this.boundOnSeeked);
-    this.mediaElement.removeEventListener("play", this.boundOnPlay);
-    this.mediaElement.removeEventListener("playing", this.boundOnPlaying);
-    this.mediaElement.removeEventListener("pause", this.boundOnPause);
-    this.mediaElement.removeEventListener("progress", this.boundOnProgress);
-
-    // Now safe to pause the outgoing element
-    this.mediaElement.pause();
-    this.isPlayingValue = false;
-    this.isPausedValue = false;
-
-    // Disconnect old source node if it exists
-    if (this.sourceNode) {
-      this.sourceNode.disconnect();
-      this.sourceNode = null;
-    }
-
-    // Set new media element
-    this.mediaElement = element;
-
-    // Add event listeners to new element
-    this.mediaElement.addEventListener("canplaythrough", this.boundOnCanPlayThrough);
-    this.mediaElement.addEventListener("timeupdate", this.boundOnTimeUpdate);
-    this.mediaElement.addEventListener("error", this.boundOnError);
-    this.mediaElement.addEventListener("ended", this.boundOnEnded);
-    this.mediaElement.addEventListener("stalled", this.boundOnStalled);
-    this.mediaElement.addEventListener("emptied", this.boundOnEmptied);
-    this.mediaElement.addEventListener("suspend", this.boundOnSuspend);
-    this.mediaElement.addEventListener("waiting", this.boundOnWaiting);
-    this.mediaElement.addEventListener("loadedmetadata", this.boundOnLoadedMetadata);
-    this.mediaElement.addEventListener("seeking", this.boundOnSeeking);
-    this.mediaElement.addEventListener("seeked", this.boundOnSeeked);
-    this.mediaElement.addEventListener("play", this.boundOnPlay);
-    this.mediaElement.addEventListener("playing", this.boundOnPlaying);
-    this.mediaElement.addEventListener("pause", this.boundOnPause);
-    this.mediaElement.addEventListener("progress", this.boundOnProgress);
-
-    // Re-apply current volume and playback rate to the new element
-    this.mediaElement.volume = this.isMutedValue ? 0 : this.currentVolume;
-    this.mediaElement.playbackRate = this.currentPlaybackRate;
-
-    // Reconnect the Web Audio graph to the new element
-    if (this.webAudioActive) {
-      try {
-        const ctx = this.getOrCreateAudioContext();
-        this.sourceNode = new MediaElementAudioSourceNode(ctx, { mediaElement: this.mediaElement });
-        if (!this.gainNode) {
-          this.gainNode = ctx.createGain();
-          this.gainNode.connect(ctx.destination);
-        }
-        if (this.worklet?.workletNode) {
-          this.sourceNode.connect(this.worklet.workletNode);
-        } else {
-          this.sourceNode.connect(this.gainNode);
-        }
-      } catch {
-        // CORS failed on this element — deactivate Web Audio gracefully
-        this.deactivateWebAudio();
-      }
-    }
-
-    // Check if metadata is already loaded (common with preloaded elements)
-    if (this.mediaElement.readyState >= 1) {
-      this.onLoadedMetadata(new Event('loadedmetadata'));
-    }
-
-    // Preloaded elements may have already buffered data before being swapped in,
-    // so progress events would have fired before we were listening. Emit now if
-    // seekable ranges are already available.
-    if (this.mediaElement.seekable.length > 0) {
-      this.onProgress();
-    }
-
-    // Check if the element is already loaded and trigger appropriate events
-    if (this.mediaElement.readyState >= 4) {
-      this.onCanPlayThrough();
-    } else {
-      this.isLoadingValue = true;
-      this.isLoadedValue = false;
-    }
-  }
-
   // Ensure AudioContext is running
   private async ensureAudioContextRunning() {
     if (!this.audioContext) {
@@ -352,7 +236,6 @@ export class WebAudioEngine implements AudioEngine {
    */
   public setVolume(volume: number): void {
     if (volume < 0) {
-      this.currentVolume = 0;
       this.mediaElement.volume = 0;
       if (this.gainNode) {
         this.gainNode.gain.value = 0;
@@ -364,7 +247,6 @@ export class WebAudioEngine implements AudioEngine {
       this.setVolume(volume / 100);
       return;
     }
-    this.currentVolume = volume;
     this.mediaElement.volume = volume;
     if (this.gainNode) {
       this.gainNode.gain.value = volume;
@@ -452,7 +334,6 @@ export class WebAudioEngine implements AudioEngine {
    * Sets the playback rate of the audio resource with pitch preservation.
    */
   public setPlaybackRate(rate: number, preservePitch: boolean): void {
-    this.currentPlaybackRate = rate;
     this.mediaElement.playbackRate = rate;
     if (preservePitch) {
       if ('preservesPitch' in this.mediaElement) {
@@ -558,6 +439,27 @@ export class WebAudioEngine implements AudioEngine {
     return this.webAudioActive;
   }
 
+  /**
+   * Changes the src of the primary media element without swapping the element.
+   * Preserves the RemotePlayback session and all attached event listeners.
+   */
+  public changeSrc(href: string): void {
+    if (this.mediaElement.src === href) {
+      return;
+    }
+    this.mediaElement.pause();
+    this.isPlayingValue = false;
+    this.isPausedValue = false;
+    this.isLoadedValue = false;
+    this.isLoadingValue = true;
+    this.isEndedValue = false;
+    if (this.webAudioActive) {
+      this.mediaElement.crossOrigin = "anonymous";
+    }
+    this.mediaElement.src = href;
+    this.mediaElement.load();
+  }
+
   /**
    * Returns the HTML media element used for playback.
    */

package/types/src/audio/AudioNavigator.d.ts

@@ -3,6 +3,12 @@ import { MediaNavigator, IContentProtectionConfig, IKeyboardPeripheralsConfig }
 import { Configurable } from "../preferences";
 import { AudioPreferences, AudioSettings, AudioPreferencesEditor, IAudioPreferences, IAudioDefaults } from "./preferences";
 import { ContextMenuEvent, KeyboardEventData, SuspiciousActivityEvent } from "@readium/navigator-html-injectables";
+export interface AudioMetadata {
+    duration: number;
+    textTracks: TextTrackList;
+    readyState: number;
+    networkState: number;
+}
 export interface AudioNavigatorListeners {
     trackLoaded: (media: HTMLMediaElement) => void;
     positionChanged: (locator: Locator) => void;
@@ -11,18 +17,23 @@ export interface AudioNavigatorListeners {
     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;
+}
+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;
 }
 export declare class AudioNavigator extends MediaNavigator implements Configurable<AudioSettings, AudioPreferences> {
@@ -43,6 +54,9 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     private readonly _keyboardPeripheralsManager;
     private readonly _suspiciousActivityListener;
     private readonly _keyboardPeripheralListener;
+    private readonly _contentProtection;
+    /** True while a track transition is in progress; suppresses spurious mid-navigation events. */
+    private _isNavigating;
     constructor(publication: Publication, listeners: AudioNavigatorListeners, initialPosition?: Locator, configuration?: AudioNavigatorConfiguration);
     get settings(): AudioSettings;
     get preferencesEditor(): AudioPreferencesEditor;
@@ -90,6 +104,15 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     get isTrackEnd(): boolean;
     get canGoBackward(): boolean;
     get canGoForward(): boolean;
+    /**
+     * 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;
+    /** Wires up the optional remotePlaybackStateChanged listener. Called once after initial load. */
+    private _setupRemotePlayback;
     private destroyMediaSession;
     destroy(): void;
 }

package/types/src/audio/AudioPoolManager.d.ts

@@ -1,11 +1,12 @@
 import { Publication } from "@readium/shared";
 import { WebAudioEngine } from "./engine/WebAudioEngine";
+import type { IAudioContentProtectionConfig } from "./AudioNavigator";
 export declare class AudioPoolManager {
     private readonly pool;
     private _audioEngine;
     private readonly _publication;
     private readonly _supportedAudioTypes;
-    constructor(audioEngine: WebAudioEngine, publication: Publication);
+    constructor(audioEngine: WebAudioEngine, publication: Publication, contentProtection?: IAudioContentProtectionConfig);
     private detectSupportedAudioTypes;
     private pickPlayableHref;
     get audioEngine(): WebAudioEngine;
@@ -17,11 +18,13 @@ export declare 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;
     /**
-     * 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;
     destroy(): void;

package/types/src/audio/engine/AudioEngine.d.ts

@@ -49,10 +49,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.
      */

package/types/src/audio/engine/WebAudioEngine.d.ts

@@ -7,8 +7,6 @@ export declare class WebAudioEngine implements AudioEngine {
     private sourceNode;
     private gainNode;
     private listeners;
-    private currentVolume;
-    private currentPlaybackRate;
     private isMutedValue;
     private isPlayingValue;
     private isPausedValue;
@@ -48,12 +46,6 @@ export declare class WebAudioEngine implements AudioEngine {
      * @param callback - callback function to be removed.
      */
     off(event: string, callback: EventCallback): void;
-    private deactivateWebAudio;
-    /**
-     * Sets the media element for playback.
-     * @param element The HTML audio element to use.
-     */
-    setMediaElement(element: HTMLAudioElement): void;
     private ensureAudioContextRunning;
     private getOrCreateAudioContext;
     private onTimeUpdate;
@@ -140,6 +132,11 @@ export declare class WebAudioEngine implements AudioEngine {
      */
     private activateWebAudio;
     get isWebAudioActive(): boolean;
+    /**
+     * Changes the src of the primary media element without swapping the element.
+     * Preserves the RemotePlayback session and all attached event listeners.
+     */
+    changeSrc(href: string): void;
     /**
      * Returns the HTML media element used for playback.
      */