@readium/navigator 2.10.3 → 2.11.0

package/src/audio/AudioPoolManager.ts

@@ -38,19 +38,20 @@ export class AudioPoolManager {
         return supported;
     }
 
-    private pickPlayableHref(link: Link): string {
+    private pickPlayableHref(link: Link): { href: string, type?: string } {
         const base = this._publication.baseURL;
         const candidates = [link, ...(link.alternates?.items ?? [])];
-        let best: { href: string; confidence: "probably" | "maybe" } | undefined;
+        let best: { href: string; type?: string; confidence: "probably" | "maybe" } | undefined;
         for (const candidate of candidates) {
             if (!candidate.type) continue;
             const confidence = this._supportedAudioTypes.get(candidate.type);
             if (!confidence) continue;
             const href = candidate.toURL(base) ?? candidate.href;
-            if (confidence === "probably") return href;
-            if (!best) best = { href, confidence };
+            if (confidence === "probably") return { href, type: candidate.type };
+            if (!best) best = { href, type: candidate.type, confidence };
         }
-        return best?.href ?? (link.toURL(base) ?? link.href);
+        if (best) return { href: best.href, type: best.type };
+        return { href: link.toURL(base) ?? link.href, type: link.type };
     }
 
     get audioEngine(): WebAudioEngine {
@@ -84,12 +85,16 @@ export class AudioPoolManager {
      * The current track is excluded — the primary engine element represents it.
      */
     private update(currentIndex: number): void {
+        // Progressive preload elements would feed encrypted media through the
+        // broken src= demuxer path — the MSE loader owns fetching instead
+        if (this._audioEngine.usesMse) return;
+
         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]);
+            const { href } = this.pickPlayableHref(items[j]);
             if (j >= currentIndex - LOWER_BOUNDARY && j <= currentIndex + LOWER_BOUNDARY) {
                 this.ensure(href);
                 keep.add(href);
@@ -117,8 +122,8 @@ export class AudioPoolManager {
      * 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]);
-        this.audioEngine.changeSrc(href);
+        const { href, type } = this.pickPlayableHref(this._publication.readingOrder.items[currentIndex]);
+        this.audioEngine.changeSrc(href, type);
 
         // Discard any pool entry for this href — the primary element owns it now
         if (this.pool.has(href)) {
@@ -134,6 +139,7 @@ export class AudioPoolManager {
 
     destroy(): void {
         this.audioEngine.stop();
+        this.audioEngine.destroy();
         for (const [, element] of this.pool) {
             element.removeAttribute("src");
             element.load();

package/src/audio/engine/AudioEngine.ts

@@ -30,6 +30,37 @@ export interface Playback {
     buffered?: number;
 }
 
+/**
+ * A consumer-supplied loader that feeds one resource to the playback element
+ * through Media Source Extensions. The engine constructs one per track via
+ * the [AudioMseLoaderFactory] and calls [start] immediately; the loader owns
+ * the element's `src` (a MediaSource object URL), all fetching, buffering and
+ * seek servicing until [destroy] is called. Container specifics (WebM, fMP4,
+ * byte ranges vs. segments…) are entirely up to the implementation.
+ */
+export interface AudioMseLoader {
+    /** Attaches to the element and begins streaming. Called exactly once. */
+    start(): void;
+
+    /**
+     * Cancels in-flight fetches, detaches element listeners and releases the
+     * MediaSource object URL. The element itself must be left intact — the
+     * engine reuses it for the next track.
+     */
+    destroy(): void;
+}
+
+/**
+ * Creates the [AudioMseLoader] for a resource. [mimeType] is the resource's
+ * media type from the manifest, when known — needed to configure the
+ * SourceBuffer.
+ */
+export type AudioMseLoaderFactory = (
+    element: HTMLMediaElement,
+    href: string,
+    mimeType?: string,
+) => AudioMseLoader;
+
 /**
  * An audio engine that plays audio resources from a publication.
  * @playback - The current [Playback] state.
@@ -58,8 +89,10 @@ export interface AudioEngine {
      * 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.
+     * @param mimeType The media type of the resource, when known. Required for
+     * MSE-based loading to configure the SourceBuffer.
      */
-    changeSrc(href: string): void;
+    changeSrc(href: string, mimeType?: string): void;
     
     /**
      * Plays the current audio resource.

package/src/audio/engine/WebAudioEngine.ts

@@ -2,6 +2,8 @@
 
 import {
   AudioEngine,
+  AudioMseLoader,
+  AudioMseLoaderFactory,
   Playback,
 } from "./AudioEngine.ts";
 import { PreservePitchWorklet } from "./PreservePitchWorklet.ts";
@@ -25,6 +27,10 @@ export class WebAudioEngine implements AudioEngine {
   private isStoppedValue: boolean = false;
   private worklet: PreservePitchWorklet | null = null;
   private webAudioActive: boolean = false;
+  private readonly mseLoaderFactory: AudioMseLoaderFactory | null;
+  private mseLoader: AudioMseLoader | null = null;
+  /** The resource href currently loaded (element src is a blob: URL in MSE mode). */
+  private currentHref: string = "";
 
   private readonly boundOnCanPlayThrough = this.onCanPlayThrough.bind(this);
   private readonly boundOnTimeUpdate = this.onTimeUpdate.bind(this);
@@ -42,8 +48,9 @@ export class WebAudioEngine implements AudioEngine {
   private readonly boundOnPause = this.onPause.bind(this);
   private readonly boundOnProgress = this.onProgress.bind(this);
 
-  constructor(values: { playback: Playback }) {
+  constructor(values: { playback: Playback, mseLoaderFactory?: AudioMseLoaderFactory }) {
     this.playback = values.playback;
+    this.mseLoaderFactory = values.mseLoaderFactory ?? null;
 
     // crossOrigin is set lazily in activateWebAudio() only when the worklet is needed
     this.mediaElement = document.createElement("audio");
@@ -386,6 +393,19 @@ export class WebAudioEngine implements AudioEngine {
   private async activateWebAudio(): Promise<void> {
     if (this.webAudioActive) return;
 
+    if (this.usesMse) {
+      // blob: MediaSource URLs are same-origin — no CORS reload required
+      this.sourceNode = new MediaElementAudioSourceNode(this.getOrCreateAudioContext(), { mediaElement: this.mediaElement });
+      const audioContext = this.getOrCreateAudioContext();
+      this.gainNode = audioContext.createGain();
+      this.gainNode.gain.value = this.mediaElement.volume;
+      this.mediaElement.volume = 1;
+      this.sourceNode.connect(this.gainNode);
+      this.gainNode.connect(audioContext.destination);
+      this.webAudioActive = true;
+      return;
+    }
+
     const src = this.mediaElement.src;
     if (!src) return;
 
@@ -469,6 +489,11 @@ export class WebAudioEngine implements AudioEngine {
     return this.webAudioActive;
   }
 
+  /** True when this engine streams media through Media Source Extensions. */
+  public get usesMse(): boolean {
+    return this.mseLoaderFactory !== null;
+  }
+
   /**
    * Tears down the Web Audio graph and restores the media element to standalone
    * playback. Safe to call even if Web Audio was never activated.
@@ -499,10 +524,11 @@ export class WebAudioEngine implements AudioEngine {
    * the required headers), the graph is torn down and the src is reloaded
    * without CORS so playback continues — just without pitch correction.
    */
-  public changeSrc(href: string): void {
-    if (this.mediaElement.src === href) {
+  public changeSrc(href: string, mimeType?: string): void {
+    if (this.currentHref === href || this.mediaElement.src === href) {
       return;
     }
+    this.currentHref = href;
     this.mediaElement.pause();
     this.isPlayingValue = false;
     this.isPausedValue = false;
@@ -510,6 +536,16 @@ export class WebAudioEngine implements AudioEngine {
     this.isLoadingValue = true;
     this.isEndedValue = false;
 
+    if (this.mseLoaderFactory) {
+      // MSE path: swap loaders on the persistent element. The blob: object
+      // URL is same-origin, so none of the crossOrigin reload handling below
+      // applies here — the Web Audio graph (if active) keeps working.
+      this.mseLoader?.destroy();
+      this.mseLoader = this.mseLoaderFactory(this.mediaElement, href, mimeType);
+      this.mseLoader.start();
+      return;
+    }
+
     if (this.webAudioActive) {
       this.mediaElement.crossOrigin = "anonymous";
       this.mediaElement.src = href;
@@ -542,4 +578,13 @@ export class WebAudioEngine implements AudioEngine {
   public getMediaElement(): HTMLMediaElement {
     return this.mediaElement;
   }
+
+  /**
+   * Releases loader resources (in-flight fetches, MediaSource object URL).
+   * The media element itself is left intact.
+   */
+  public destroy(): void {
+    this.mseLoader?.destroy();
+    this.mseLoader = null;
+  }
 }