@readium/navigator 2.4.0-beta.4 → 2.4.0-beta.6

package/package.json

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

package/src/audio/AudioNavigator.ts

@@ -66,6 +66,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     private _defaults: AudioDefaults;
     private _settings: AudioSettings;
     private _preferencesEditor: AudioPreferencesEditor | null = null;
+    private _mediaSessionEnabled: boolean = false;
     private pool: AudioPoolManager;
     private readonly _navigatorProtector: AudioNavigatorProtector | null = null;
     private readonly _keyboardPeripheralsManager: KeyboardPeripherals | null = null;
@@ -110,7 +111,6 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 state: {
                     currentTime: initialTime,
                     duration: 0,
-                    volume: this._settings.volume
                 } as PlaybackState,
                 playWhenReady: false,
                 index: trackIndex
@@ -154,10 +154,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         }
 
         this.setupEventListeners();
-
-        if (this._settings.enableMediaSession) {
-            this.setupMediaSession();
-        }
+        this.applyPreferences();
 
         this.pool.setCurrentAudio(trackIndex, "forward");
 
@@ -190,7 +187,6 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     }
 
     private applyPreferences(): void {
-        const oldSettings = this._settings;
         this._settings = new AudioSettings(this._preferences, this._defaults);
 
         if (this._preferencesEditor !== null) {
@@ -200,9 +196,11 @@ 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._settings.enableMediaSession && !oldSettings.enableMediaSession) {
+        if (this._settings.enableMediaSession && !this._mediaSessionEnabled) {
+            this._mediaSessionEnabled = true;
             this.setupMediaSession();
-        } else if (!this._settings.enableMediaSession && oldSettings.enableMediaSession) {
+        } else if (!this._settings.enableMediaSession && this._mediaSessionEnabled) {
+            this._mediaSessionEnabled = false;
             this.destroyMediaSession();
         }
     }
@@ -328,6 +326,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 fragments: [`t=${this.duration}`]
             }));
             this.listeners.trackEnded(this.currentLocator);
+            if (!this.canGoForward) return;
             await this.nextTrack();
             if (this._settings.autoPlay) this.play();
         });

package/src/audio/AudioPoolManager.ts

@@ -1,8 +1,11 @@
 import { Link, Publication } from "@readium/shared";
 import { WebAudioEngine } from "./engine/WebAudioEngine";
 
+const UPPER_BOUNDARY = 1;
+const LOWER_BOUNDARY = 1;
+
 export class AudioPoolManager {
-    private preloadedElements: Map<string, HTMLAudioElement> = new Map();
+    private readonly pool: Map<string, HTMLAudioElement> = new Map();
     private _audioEngine: WebAudioEngine;
     private readonly _publication: Publication;
     private readonly _supportedAudioTypes: Map<string, "probably" | "maybe">;
@@ -48,102 +51,84 @@ export class AudioPoolManager {
     }
 
     /**
-     * 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(currentIndex: number, direction: 'forward' | 'backward'): void {
-        const href = this.pickPlayableHref(this._publication.readingOrder.items[currentIndex]);
-        // When Web Audio is active, preloaded elements lack crossOrigin="anonymous"
-        // and cannot be connected to MediaElementAudioSourceNode, so bypass the pool.
-        const preloadedElement = !this.audioEngine.isWebAudioActive ? this.get(href) : undefined;
-        if (preloadedElement) {
-            this.audioEngine.setMediaElement(preloadedElement);
-            this.clear(href);
-        } else {
-            this.clear(href);
-            this.audioEngine.loadAudio(href);
+    private ensure(href: string): HTMLAudioElement {
+        let element = this.pool.get(href);
+        if (!element) {
+            element = document.createElement("audio");
+            element.preload = "auto";
+            element.src = href;
+            element.load();
+            this.pool.set(href, element);
         }
-        this.preloadAdjacent(currentIndex, direction);
-    }
-    preload(href: string): void {
-        if (this.preloadedElements.has(href)) {
-            return; // Already preloaded
-        }
-
-        const audioElement = document.createElement("audio");
-        audioElement.preload = "auto";
-        audioElement.src = href;
-        audioElement.load(); // Start buffering
-
-        this.preloadedElements.set(href, audioElement);
+        return element;
     }
 
     /**
-     * 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.
      */
-    get(href: string): HTMLAudioElement | undefined {
-        return this.preloadedElements.get(href);
-    }
+    private update(currentIndex: number): void {
+        const items = this._publication.readingOrder.items;
+        const keep = new Set<string>();
 
-    /**
-     * Removes a preloaded element from the pool.
-     * @param href The URL of the audio resource.
-     */
-    clear(href: string): void {
-        this.preloadedElements.delete(href);
-    }
-
-    /**
-     * Preloads the next track in the reading order.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     */
-    preloadNext(currentIndex: number): void {
-        const nextIndex = currentIndex + 1;
-        if (nextIndex < this._publication.readingOrder.items.length) {
-            const nextLink = this._publication.readingOrder.items[nextIndex];
-            this.preload(this.pickPlayableHref(nextLink));
+        for (let j = 0; j < items.length; j++) {
+            const href = this.pickPlayableHref(items[j]);
+            if (j >= currentIndex - LOWER_BOUNDARY && j <= currentIndex + LOWER_BOUNDARY) {
+                this.ensure(href);
+                keep.add(href);
+            } else if (j >= currentIndex - UPPER_BOUNDARY && j <= currentIndex + UPPER_BOUNDARY) {
+                // Between lower and upper: keep if already loaded, don't create
+                if (this.pool.has(href)) {
+                    keep.add(href);
+                }
+            }
         }
-    }
 
-    /**
-     * Preloads the previous track in the reading order.
-     * @param currentIndex The current track index.
-     */
-    preloadPrevious(currentIndex: number): void {
-        const prevIndex = currentIndex - 1;
-        if (prevIndex >= 0) {
-            const prevLink = this._publication.readingOrder.items[prevIndex];
-            this.preload(this.pickPlayableHref(prevLink));
+        // Dispose elements beyond the upper boundary
+        for (const [href, element] of this.pool) {
+            if (!keep.has(href)) {
+                element.removeAttribute("src");
+                element.load(); // release network resources
+                this.pool.delete(href);
+            }
         }
     }
 
     /**
-     * Preloads adjacent tracks (previous and next) for smoother navigation.
-     * @param currentIndex The current track index.
-     * @param direction The navigation direction ('forward' or 'backward').
+     * 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.
      */
-    preloadAdjacent(currentIndex: number, direction: 'forward' | 'backward' = 'forward'): void {
-        if (direction === 'forward') {
-            this.preloadNext(currentIndex);
-            this.preloadPrevious(currentIndex);
+    setCurrentAudio(currentIndex: number, _direction: 'forward' | 'backward'): void {
+        const href = this.pickPlayableHref(this._publication.readingOrder.items[currentIndex]);
+        const element = this.ensure(href);
+
+        // Hand the element to the engine. When Web Audio is active, the pooled
+        // element doesn't have crossOrigin set (it would break non-CORS servers
+        // during preload), so we swap in the fresh element and let loadAudio
+        // handle CORS setup + fallback on the engine's own mediaElement.
+        if (this.audioEngine.isWebAudioActive) {
+            this.audioEngine.setMediaElement(element);
+            this.audioEngine.loadAudio(href);
         } else {
-            this.preloadPrevious(currentIndex);
-            this.preloadNext(currentIndex);
+            this.audioEngine.setMediaElement(element);
         }
+
+        // Remove from pool so the engine fully owns it and we don't dispose it
+        this.pool.delete(href);
+
+        // Manage the pool around the new position
+        this.update(currentIndex);
     }
 
-    /**
-     * Destroys the pool by stopping the engine and clearing all preloaded elements.
-     */
     destroy(): void {
         this.audioEngine.stop();
-        this.preloadedElements.clear();
+        for (const [, element] of this.pool) {
+            element.removeAttribute("src");
+            element.load();
+        }
+        this.pool.clear();
     }
 }

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;
 }
 
 /**

package/src/audio/engine/WebAudioEngine.ts

@@ -16,6 +16,7 @@ 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;
@@ -48,7 +49,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);
@@ -100,6 +100,11 @@ export class WebAudioEngine implements AudioEngine {
    * @param url The URL of the audio resource.
    * */
   public loadAudio(url: string): void {
+    // Abort any in-progress load before starting a new one.
+    this.mediaElement.pause();
+    this.mediaElement.removeAttribute("src");
+    this.mediaElement.load();
+
     this.isLoadingValue = true;
     this.isLoadedValue = false;
     this.isPlayingValue = false;
@@ -109,6 +114,7 @@ export class WebAudioEngine implements AudioEngine {
       this.mediaElement.crossOrigin = "anonymous";
       this.mediaElement.src = url;
       this.mediaElement.load();
+      this.mediaElement.playbackRate = this.currentPlaybackRate;
 
       // 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
@@ -123,6 +129,7 @@ export class WebAudioEngine implements AudioEngine {
         this.mediaElement.removeAttribute("crossOrigin");
         this.mediaElement.src = url;
         this.mediaElement.load();
+        this.mediaElement.playbackRate = this.currentPlaybackRate;
       };
       const onCORSSuccess = () => cleanup();
       this.mediaElement.addEventListener("error", onCORSError);
@@ -130,6 +137,7 @@ export class WebAudioEngine implements AudioEngine {
     } else {
       this.mediaElement.src = url;
       this.mediaElement.load();
+      this.mediaElement.playbackRate = this.currentPlaybackRate;
     }
   }
 
@@ -203,7 +211,7 @@ export class WebAudioEngine implements AudioEngine {
     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.volume = this.isMutedValue ? 0 : this.currentVolume;
     this.mediaElement.playbackRate = this.currentPlaybackRate;
 
     // Check if metadata is already loaded (common with preloaded elements)
@@ -370,23 +378,23 @@ 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;
       }
       this.isMutedValue = true;
-      this.playback.state.volume = 0;
       return;
     }
     if (volume > 1) {
       this.setVolume(volume / 100);
       return;
     }
+    this.currentVolume = volume;
     this.mediaElement.volume = volume;
     if (this.gainNode) {
       this.gainNode.gain.value = volume;
     }
-    this.playback.state.volume = volume;
   }
 
   /**

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

@@ -34,6 +34,7 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     private _defaults;
     private _settings;
     private _preferencesEditor;
+    private _mediaSessionEnabled;
     private pool;
     private readonly _navigatorProtector;
     private readonly _keyboardPeripheralsManager;

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

@@ -1,7 +1,7 @@
 import { Publication } from "@readium/shared";
 import { WebAudioEngine } from "./engine/WebAudioEngine";
 export declare class AudioPoolManager {
-    private preloadedElements;
+    private readonly pool;
     private _audioEngine;
     private readonly _publication;
     private readonly _supportedAudioTypes;
@@ -10,45 +10,19 @@ export declare class AudioPoolManager {
     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(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.
      */
-    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(currentIndex: number): void;
-    /**
-     * Preloads the previous track in the reading order.
-     * @param currentIndex The current track index.
-     */
-    preloadPrevious(currentIndex: number): void;
-    /**
-     * Preloads adjacent tracks (previous and next) for smoother navigation.
-     * @param currentIndex The current track index.
-     * @param direction The navigation direction ('forward' or 'backward').
-     */
-    preloadAdjacent(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.
+     * The element is always sourced from the pool — never loaded ad-hoc on the engine.
      */
+    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

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

@@ -7,6 +7,7 @@ export declare class WebAudioEngine implements AudioEngine {
     private sourceNode;
     private gainNode;
     private listeners;
+    private currentVolume;
     private currentPlaybackRate;
     private isMutedValue;
     private isPlayingValue;