@readium/navigator 2.4.0-beta.5 → 2.4.0-beta.7

package/package.json

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

package/src/audio/AudioNavigator.ts

@@ -59,6 +59,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     private readonly pub: Publication;
     private positionPollInterval: ReturnType<typeof setInterval> | null = null;
     private navigationId: number = 0;
+    private _playIntent: boolean = false;
     private listeners: AudioNavigatorListeners;
     private currentLocation!: Locator;
 
@@ -326,6 +327,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();
         });
@@ -431,7 +433,11 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
 
             const id = ++this.navigationId;
             const direction: "forward" | "backward" = trackIndex >= this.currentTrackIndex() ? "forward" : "backward";
-            const wasPlaying = this.isPlaying;
+            // 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.stopPositionPolling();
             this.pool.setCurrentAudio(trackIndex, direction);
@@ -449,6 +455,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             }
 
             if (wasPlaying) this.play();
+            this._playIntent = false;
 
             cb(true);
         } catch (error) {

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,80 @@ 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);
-        }
-        this.preloadAdjacent(currentIndex, direction);
-    }
-    preload(href: string): void {
-        if (this.preloadedElements.has(href)) {
-            return; // Already preloaded
+    private ensure(href: string): HTMLAudioElement {
+        let element = this.pool.get(href);
+        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.
+            if (this._audioEngine.isWebAudioActive) {
+                element.crossOrigin = "anonymous";
+            }
+            element.src = href;
+            element.load();
+            this.pool.set(href, element);
         }
-
-        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);
-        } else {
-            this.preloadPrevious(currentIndex);
-            this.preloadNext(currentIndex);
-        }
+    setCurrentAudio(currentIndex: number, _direction: 'forward' | 'backward'): void {
+        const href = this.pickPlayableHref(this._publication.readingOrder.items[currentIndex]);
+        const element = this.ensure(href);
+
+        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

@@ -40,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.

package/src/audio/engine/WebAudioEngine.ts

@@ -95,47 +95,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();
-      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
-      // 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();
-        this.mediaElement.playbackRate = this.currentPlaybackRate;
-      };
-      const onCORSSuccess = () => cleanup();
-      this.mediaElement.addEventListener("error", onCORSError);
-      this.mediaElement.addEventListener("canplaythrough", onCORSSuccess);
-    } else {
-      this.mediaElement.src = url;
-      this.mediaElement.load();
-      this.mediaElement.playbackRate = this.currentPlaybackRate;
-    }
-  }
-
   private deactivateWebAudio(): void {
     if (this.worklet) {
       this.worklet.destroy();
@@ -157,18 +116,7 @@ export class WebAudioEngine implements AudioEngine {
    * @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
+    // 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);
@@ -185,6 +133,17 @@ export class WebAudioEngine implements AudioEngine {
     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;
 
@@ -209,6 +168,26 @@ export class WebAudioEngine implements AudioEngine {
     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'));

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

@@ -28,6 +28,7 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     private readonly pub;
     private positionPollInterval;
     private navigationId;
+    private _playIntent;
     private listeners;
     private currentLocation;
     private _preferences;

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

@@ -36,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.

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

@@ -48,11 +48,6 @@ export declare class WebAudioEngine implements AudioEngine {
      * @param callback - callback function to be removed.
      */
     off(event: string, callback: EventCallback): void;
-    /**
-     * Load the audio resource at the given URL.
-     * @param url The URL of the audio resource.
-     * */
-    loadAudio(url: string): void;
     private deactivateWebAudio;
     /**
      * Sets the media element for playback.