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

package/src/audio/engine/AudioEngine.ts

@@ -11,11 +11,6 @@ export interface PlaybackState {
      * The duration of the audio resource.
      */
     duration: number;
-
-    /**
-     * The volume of the audio resource.
-     */
-    volume: number;
 }
 
 /**
@@ -45,12 +40,6 @@ export interface AudioEngine {
      */
     playback: Playback;
 
-    /**
-     * Loads the audio resource at the given URL.
-     * @param url The URL of the audio resource.
-     */
-    loadAudio(url: string): void;
-    
     /**
      * Adds an event listener to the audio engine.
      * @param event The event name to listen.
@@ -66,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,7 +16,6 @@ export class WebAudioEngine implements AudioEngine {
   private sourceNode: MediaElementAudioSourceNode | null = null;
   private gainNode: GainNode | null = null;
   private listeners: { [event: string]: EventCallback[] } = {};
-  private currentPlaybackRate: number = 1;
   private isMutedValue: boolean = false;
   private isPlayingValue: boolean = false;
   private isPausedValue: boolean = false;
@@ -48,7 +47,6 @@ export class WebAudioEngine implements AudioEngine {
 
     // crossOrigin is set lazily in activateWebAudio() only when the worklet is needed
     this.mediaElement = document.createElement("audio");
-    this.setVolume(this.playback.state.volume);
 
     // Event listeners (to report the client app about some async events)
     this.mediaElement.addEventListener("canplaythrough", this.boundOnCanPlayThrough);
@@ -95,138 +93,6 @@ export class WebAudioEngine implements AudioEngine {
     );
   }
 
-  /**
-   * Load the audio resource at the given URL.
-   * @param url The URL of the audio resource.
-   * */
-  public loadAudio(url: string): void {
-    this.isLoadingValue = true;
-    this.isLoadedValue = false;
-    this.isPlayingValue = false;
-    this.isPausedValue = false;
-
-    if (this.webAudioActive) {
-      this.mediaElement.crossOrigin = "anonymous";
-      this.mediaElement.src = url;
-      this.mediaElement.load();
-
-      // If the server doesn't honour the CORS preflight, fall back to a
-      // non-CORS load and tear down the Web Audio graph so the element
-      // is never passed to MediaElementAudioSourceNode in a tainted state.
-      const cleanup = () => {
-        this.mediaElement.removeEventListener("error", onCORSError);
-        this.mediaElement.removeEventListener("canplaythrough", onCORSSuccess);
-      };
-      const onCORSError = () => {
-        cleanup();
-        this.deactivateWebAudio();
-        this.mediaElement.removeAttribute("crossOrigin");
-        this.mediaElement.src = url;
-        this.mediaElement.load();
-      };
-      const onCORSSuccess = () => cleanup();
-      this.mediaElement.addEventListener("error", onCORSError);
-      this.mediaElement.addEventListener("canplaythrough", onCORSSuccess);
-    } else {
-      this.mediaElement.src = url;
-      this.mediaElement.load();
-    }
-  }
-
-  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 {
-    // Pause the outgoing element before replacing it
-    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;
-    }
-
-    // Remove old event listeners from current mediaElement
-    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);
-
-    // 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.playback.state.volume;
-    this.mediaElement.playbackRate = this.currentPlaybackRate;
-
-    // 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) {
@@ -375,7 +241,6 @@ export class WebAudioEngine implements AudioEngine {
         this.gainNode.gain.value = 0;
       }
       this.isMutedValue = true;
-      this.playback.state.volume = 0;
       return;
     }
     if (volume > 1) {
@@ -386,7 +251,6 @@ export class WebAudioEngine implements AudioEngine {
     if (this.gainNode) {
       this.gainNode.gain.value = volume;
     }
-    this.playback.state.volume = volume;
   }
 
   /**
@@ -470,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) {
@@ -576,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/src/audio/protection/AudioNavigatorProtector.ts

@@ -0,0 +1,38 @@
+import { NavigatorProtector } from "../../protection/NavigatorProtector";
+import { DragAndDropProtector } from "../../protection/DragAndDropProtector";
+import { CopyProtector } from "../../protection/CopyProtector";
+import { IContentProtectionConfig } from "../../Navigator";
+
+export class AudioNavigatorProtector extends NavigatorProtector {
+    private dragAndDropProtector?: DragAndDropProtector;
+    private copyProtector?: CopyProtector;
+
+    constructor(config: IContentProtectionConfig = {}) {
+        super(config);
+
+        if (config.disableDragAndDrop) {
+            this.dragAndDropProtector = new DragAndDropProtector({
+                onDragDetected: (dataTransferTypes) => {
+                    this.dispatchSuspiciousActivity("drag_detected", { dataTransferTypes, targetFrameSrc: "" });
+                },
+                onDropDetected: (dataTransferTypes, fileCount) => {
+                    this.dispatchSuspiciousActivity("drop_detected", { dataTransferTypes, fileCount, targetFrameSrc: "" });
+                }
+            });
+        }
+
+        if (config.protectCopy) {
+            this.copyProtector = new CopyProtector({
+                onCopyBlocked: () => {
+                    this.dispatchSuspiciousActivity("bulk_copy", { targetFrameSrc: "" });
+                }
+            });
+        }
+    }
+
+    public override destroy() {
+        super.destroy();
+        this.dragAndDropProtector?.destroy();
+        this.copyProtector?.destroy();
+    }
+}

package/src/epub/frame/FrameManager.ts

@@ -85,7 +85,7 @@ export class FrameManager {
         }
 
         // Apply print protection if configured
-        if (this.contentProtectionConfig.protectPrinting) {
+        if (this.contentProtectionConfig.protectPrinting?.disable) {
             this.comms!.send("print_protection", this.contentProtectionConfig.protectPrinting);
         }
     }

package/src/epub/fxl/FXLFrameManager.ts

@@ -219,7 +219,7 @@ export class FXLFrameManager {
         }
 
         // Apply print protection if configured
-        if (this.contentProtectionConfig.protectPrinting) {
+        if (this.contentProtectionConfig.protectPrinting?.disable) {
             this.comms!.send("print_protection", this.contentProtectionConfig.protectPrinting);
         }
     }

package/src/preferences/Types.ts

@@ -81,8 +81,8 @@ export const volumeRangeConfig: RangeConfig = {
 }
 
 export const playbackRateRangeConfig: RangeConfig = {
-  range: [0.5, 2],
-  step: 0.25
+  range: [0.5, 4],
+  step: 0.1
 }
 
 export const skipIntervalRangeConfig: RangeConfig = {

package/src/protection/CopyProtector.ts

@@ -0,0 +1,22 @@
+export interface CopyProtectionOptions {
+    onCopyBlocked?: () => void;
+}
+
+export class CopyProtector {
+    private copyHandler: (event: ClipboardEvent) => void;
+
+    constructor(options: CopyProtectionOptions = {}) {
+        this.copyHandler = (event: ClipboardEvent) => {
+            event.preventDefault();
+            event.stopPropagation();
+            options.onCopyBlocked?.();
+        };
+
+        document.addEventListener("copy", this.copyHandler, true);
+        window.addEventListener("unload", () => this.destroy());
+    }
+
+    public destroy() {
+        document.removeEventListener("copy", this.copyHandler, true);
+    }
+}

package/src/protection/DevToolsDetector.ts

@@ -282,6 +282,7 @@ export class DevToolsDetector {
         // Cleanup Web Worker
         if (this.workerConsole) {
             this.workerConsole.destroy();
+            this.workerConsole = undefined;
         }
         
         this.isOpen = false;

package/src/protection/DragAndDropProtector.ts

@@ -0,0 +1,34 @@
+export interface DragAndDropProtectionOptions {
+    onDragDetected?: (dataTransferTypes: readonly string[]) => void;
+    onDropDetected?: (dataTransferTypes: readonly string[], fileCount: number) => void;
+}
+
+export class DragAndDropProtector {
+    private dragstartHandler: (event: DragEvent) => void;
+    private dropHandler: (event: DragEvent) => void;
+
+    constructor(options: DragAndDropProtectionOptions = {}) {
+        this.dragstartHandler = (event: DragEvent) => {
+            event.preventDefault();
+            event.stopPropagation();
+            options.onDragDetected?.(Array.from(event.dataTransfer?.types ?? []));
+        };
+
+        this.dropHandler = (event: DragEvent) => {
+            event.preventDefault();
+            event.stopPropagation();
+            const types = Array.from(event.dataTransfer?.types ?? []);
+            const fileCount = event.dataTransfer?.files.length ?? 0;
+            options.onDropDetected?.(types, fileCount);
+        };
+
+        document.addEventListener("dragstart", this.dragstartHandler, true);
+        document.addEventListener("drop", this.dropHandler, true);
+        window.addEventListener("unload", () => this.destroy());
+    }
+
+    public destroy() {
+        document.removeEventListener("dragstart", this.dragstartHandler, true);
+        document.removeEventListener("drop", this.dropHandler, true);
+    }
+}

package/src/protection/NavigatorProtector.ts

@@ -15,7 +15,7 @@ export class NavigatorProtector {
     private printProtector?: PrintProtector;
     private contextMenuProtector?: ContextMenuProtector;
 
-    private dispatchSuspiciousActivity(type: string, detail: Record<string, unknown>) {
+    protected dispatchSuspiciousActivity(type: string, detail: Record<string, unknown>) {
         const event = new CustomEvent(NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT, {
             detail: {
                 type,
@@ -55,7 +55,7 @@ export class NavigatorProtector {
                 }
             });
         }
-        
+
         // Enable iframe embedding detection if explicitly enabled in config
         if (config.checkIFrameEmbedding) {
             this.iframeEmbeddingDetector = new IframeEmbeddingDetector({
@@ -74,7 +74,7 @@ export class NavigatorProtector {
                 }
             });
         }
-        
+
         // Enable context menu protection if configured
         if (config.disableContextMenu) {
             this.contextMenuProtector = new ContextMenuProtector({

package/src/webpub/WebPubFrameManager.ts

@@ -83,7 +83,7 @@ export class WebPubFrameManager {
         }
 
         // Apply print protection if configured
-        if (this.contentProtectionConfig.protectPrinting) {
+        if (this.contentProtectionConfig.protectPrinting?.disable) {
             this.comms!.send("print_protection", this.contentProtectionConfig.protectPrinting);
         }
     }

package/src/webpub/WebPubNavigator.ts

@@ -128,8 +128,12 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
             
             // Listen for custom events from NavigatorProtector
             this._suspiciousActivityListener = (event: Event) => {
-                const customEvent = event as CustomEvent;
-                this.listeners.contentProtection(customEvent.detail.type, customEvent.detail);
+                const { type, ...activity } = (event as CustomEvent).detail;
+                if (type === "context_menu") {
+                    this.listeners.contextMenu(activity as ContextMenuEvent);
+                } else {
+                    this.listeners.contentProtection(type, activity);
+                }
             };
             window.addEventListener(NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT, this._suspiciousActivityListener);
         }

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

@@ -1,40 +1,70 @@
-import { Link, Locator, Publication } from "@readium/shared";
-import { MediaNavigator } from "../Navigator";
+import { Link, Locator, Publication, Timeline, TimelineItem } from "@readium/shared";
+import { MediaNavigator, IContentProtectionConfig, IKeyboardPeripheralsConfig } from "../Navigator";
 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;
+    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;
+}
+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?: IAudioContentProtectionConfig;
+    keyboardPeripherals?: IKeyboardPeripheralsConfig;
 }
 export declare class AudioNavigator extends MediaNavigator implements Configurable<AudioSettings, AudioPreferences> {
     private readonly pub;
     private positionPollInterval;
     private navigationId;
+    private _playIntent;
     private listeners;
     private currentLocation;
     private _preferences;
     private _defaults;
     private _settings;
     private _preferencesEditor;
+    private _mediaSessionEnabled;
     private pool;
+    private readonly _navigatorProtector;
+    private _currentTimelineItem;
+    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;
     submitPreferences(preferences: AudioPreferences): Promise<void>;
     private applyPreferences;
     get publication(): Publication;
+    get timeline(): Timeline;
+    private _notifyTimelineChange;
     private ensureLocatorLocations;
     /** Resolves a bare href (no fragment) to its index in the reading order. Returns -1 if not found. */
     private hrefToTrackIndex;
@@ -74,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,52 +1,31 @@
 import { Publication } from "@readium/shared";
 import { WebAudioEngine } from "./engine/WebAudioEngine";
+import type { IAudioContentProtectionConfig } from "./AudioNavigator";
 export declare class AudioPoolManager {
-    private preloadedElements;
+    private readonly pool;
     private _audioEngine;
-    constructor(audioEngine: WebAudioEngine);
+    private readonly _publication;
+    private readonly _supportedAudioTypes;
+    constructor(audioEngine: WebAudioEngine, publication: Publication, contentProtection?: IAudioContentProtectionConfig);
+    private detectSupportedAudioTypes;
+    private pickPlayableHref;
     get audioEngine(): WebAudioEngine;
     /**
-     * Sets the current audio by href, using preloaded element if available or loading otherwise,
-     * and preloads adjacent tracks.
-     * @param href The URL of the audio resource.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     * @param direction The navigation direction ('forward' or 'backward').
+     * Ensures an audio element exists in the pool for the given href.
+     * If one already exists, it is left untouched (preserving its buffered data).
      */
-    setCurrentAudio(href: string, publication: Publication, currentIndex: number, direction: 'forward' | 'backward'): void;
-    preload(href: string): void;
+    private ensure;
     /**
-     * Retrieves a preloaded audio element by URL.
-     * @param href The URL of the audio resource.
-     * @returns The preloaded HTMLAudioElement, or undefined if not preloaded.
+     * 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.
      */
-    get(href: string): HTMLAudioElement | undefined;
+    private update;
     /**
-     * Removes a preloaded element from the pool.
-     * @param href The URL of the audio resource.
-     */
-    clear(href: string): void;
-    /**
-     * Preloads the next track in the reading order.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     */
-    preloadNext(publication: Publication, currentIndex: number): void;
-    /**
-     * Preloads the previous track in the reading order.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     */
-    preloadPrevious(publication: Publication, currentIndex: number): void;
-    /**
-     * Preloads adjacent tracks (previous and next) for smoother navigation.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     * @param direction The navigation direction ('forward' or 'backward').
-     */
-    preloadAdjacent(publication: Publication, currentIndex: number, direction?: 'forward' | 'backward'): void;
-    /**
-     * Destroys the pool by stopping the engine and clearing all preloaded elements.
+     * 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

@@ -10,10 +10,6 @@ export interface PlaybackState {
      * The duration of the audio resource.
      */
     duration: number;
-    /**
-     * The volume of the audio resource.
-     */
-    volume: number;
 }
 /**
  * Playback interface for an audio engine state
@@ -40,11 +36,6 @@ export interface AudioEngine {
      * The current playback state.
      */
     playback: Playback;
-    /**
-     * Loads the audio resource at the given URL.
-     * @param url The URL of the audio resource.
-     */
-    loadAudio(url: string): void;
     /**
      * Adds an event listener to the audio engine.
      * @param event The event name to listen.
@@ -58,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.
      */