@readium/navigator 2.4.0-alpha.8 → 2.4.0-beta.1

package/src/audio/AudioPoolManager.ts

@@ -0,0 +1,120 @@
+import { Publication } from "@readium/shared";
+import { WebAudioEngine } from "./engine/WebAudioEngine";
+
+export class AudioPoolManager {
+    private preloadedElements: Map<string, HTMLAudioElement> = new Map();
+    private _audioEngine: WebAudioEngine;
+
+    constructor(audioEngine: WebAudioEngine) {
+        this._audioEngine = audioEngine;
+    }
+
+    get audioEngine(): WebAudioEngine {
+        return this._audioEngine;
+    }
+
+    /**
+     * 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').
+     */
+    setCurrentAudio(href: string, publication: Publication, currentIndex: number, direction: 'forward' | 'backward'): void {
+        // 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(publication, 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);
+    }
+
+    /**
+     * Retrieves a preloaded audio element by URL.
+     * @param href The URL of the audio resource.
+     * @returns The preloaded HTMLAudioElement, or undefined if not preloaded.
+     */
+    get(href: string): HTMLAudioElement | undefined {
+        return this.preloadedElements.get(href);
+    }
+
+    /**
+     * 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(publication: Publication, currentIndex: number): void {
+        const nextIndex = currentIndex + 1;
+        if (nextIndex < publication.readingOrder.items.length) {
+            const nextLink = publication.readingOrder.items[nextIndex];
+            if (nextLink.href) {
+                this.preload(nextLink.href);
+            }
+        }
+    }
+
+    /**
+     * 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 {
+        const prevIndex = currentIndex - 1;
+        if (prevIndex >= 0) {
+            const prevLink = publication.readingOrder.items[prevIndex];
+            if (prevLink.href) {
+                this.preload(prevLink.href);
+            }
+        }
+    }
+
+    /**
+     * 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' = 'forward'): void {
+        if (direction === 'forward') {
+            this.preloadNext(publication, currentIndex);
+            this.preloadPrevious(publication, currentIndex);
+        } else {
+            this.preloadPrevious(publication, currentIndex);
+            this.preloadNext(publication, currentIndex);
+        }
+    }
+
+    /**
+     * Destroys the pool by stopping the engine and clearing all preloaded elements.
+     */
+    destroy(): void {
+        this.audioEngine.stop();
+        this.preloadedElements.clear();
+    }
+}

package/src/audio/engine/AudioEngine.ts

@@ -1,6 +1,3 @@
-import { Locator } from '@readium/shared';
-import { Publication } from '@readium/shared';
-
 /**
  * Initial state of the audio engine playback.
  */
@@ -49,10 +46,11 @@ export interface AudioEngine {
     playback: Playback;
 
     /**
-     * Plays the audio resource at the given locator.
+     * Loads the audio resource at the given URL.
+     * @param url The URL of the audio resource.
      */
-    playLocator(publication: Publication, locator: Locator): Promise<void>;
-
+    loadAudio(url: string): void;
+    
     /**
      * Adds an event listener to the audio engine.
      * @param event The event name to listen.
@@ -66,12 +64,12 @@ export interface AudioEngine {
      * @param callback Callback function to be removed.
      */
     off(event: string, callback: (data: any) => void): void;
-
+    
     /**
-     * Loads the audio resource at the given URL.
-     * @param url The URL of the audio resource.
+     * Sets the media element for playback, enabling use of preloaded elements from the pool.
+     * @param element The HTML audio element to use for playback.
      */
-    loadAudio(url: string): void;
+    setMediaElement(element: HTMLAudioElement): void;
     
     /**
      * Plays the current audio resource.
@@ -97,6 +95,19 @@ export interface AudioEngine {
      * Returns the duration of the audio resource.
      */
     duration(): number;
+
+    /**
+     * Sets the volume of the audio resource.
+     * @param volume The volume to set, in the range [0, 1].
+     */
+    setVolume(volume: number): void;
+
+    /**
+     * Sets the playback rate of the audio resource.
+     * @param rate The playback rate to set.
+     * @param preservePitch Whether to preserve pitch when changing playback rate.
+     */
+    setPlaybackRate(rate: number, preservePitch: boolean): void;
     
     /**
      * Returns whether the audio resource is currently playing.
@@ -108,6 +119,11 @@ export interface AudioEngine {
      */
     isPaused(): boolean;
     
+    /**
+     * Returns the HTML media element used for playback.
+     */
+    getMediaElement(): HTMLMediaElement;
+    
     /**
      * Returns whether the audio resource is currently stopped.
      */

package/src/audio/engine/PreservePitchProcessor.js

@@ -0,0 +1,149 @@
+// PreservePitchProcessor.js
+// AudioWorklet processor for pitch preservation via pitch shifting
+
+class PreservePitchProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.bufferSize = 1024;
+    this.hopSize = 256;
+    this.overlap = this.bufferSize - this.hopSize;
+    this.inputBuffer = new Float32Array(this.bufferSize);
+    this.outputBuffer = new Float32Array(this.bufferSize);
+    this.window = new Float32Array(this.bufferSize);
+    this.bufferIndex = 0;
+    this.pitchFactor = 1.0;
+
+    // Hann window
+    for (let i = 0; i < this.bufferSize; i++) {
+      this.window[i] = 0.5 * (1 - Math.cos(2 * Math.PI * i / this.bufferSize));
+    }
+
+    this.port.onmessage = (event) => {
+      if (event.data.type === 'setPitchFactor') {
+        this.pitchFactor = event.data.factor;
+      }
+    };
+  }
+
+  process(inputs, outputs) {
+    const input = inputs[0];
+    const output = outputs[0];
+
+    if (!input || !output) return true;
+
+    const inputChannel = input[0];
+    const outputChannel = output[0];
+
+    // Accumulate input
+    for (let i = 0; i < inputChannel.length; i++) {
+      this.inputBuffer[this.bufferIndex] = inputChannel[i];
+      this.bufferIndex++;
+
+      if (this.bufferIndex >= this.bufferSize) {
+        // Process buffer
+        this.processBuffer();
+        // Output hopSize samples
+        for (let j = 0; j < this.hopSize; j++) {
+          outputChannel[j] = this.outputBuffer[j];
+        }
+        // Shift buffer
+        for (let j = 0; j < this.overlap; j++) {
+          this.inputBuffer[j] = this.inputBuffer[j + this.hopSize];
+        }
+        this.bufferIndex = this.overlap;
+        // Clear output buffer for next
+        this.outputBuffer.fill(0);
+      }
+    }
+
+    return true;
+  }
+
+  processBuffer() {
+    // Apply window
+    let windowed = new Float32Array(this.bufferSize);
+    for (let i = 0; i < this.bufferSize; i++) {
+      windowed[i] = this.inputBuffer[i] * this.window[i];
+    }
+
+    // FFT
+    let fftResult = this.fft(windowed);
+
+    // Pitch shift
+    let shifted = this.pitchShift(fftResult, this.pitchFactor);
+
+    // IFFT
+    let ifftResult = this.ifft(shifted);
+
+    // Overlap-add
+    for (let i = 0; i < this.bufferSize; i++) {
+      this.outputBuffer[i] += ifftResult[i] * this.window[i];
+    }
+  }
+
+  pitchShift(fft, factor) {
+    let N = fft.length;
+    let result = new Array(N).fill(null).map(() => ({ real: 0, imag: 0 }));
+    for (let k = 0; k < N / 2; k++) {
+      let newK = Math.round(k * factor);
+      if (newK < N / 2) {
+        result[newK] = fft[k];
+        result[N - newK] = fft[N - k]; // symmetric for real input
+      }
+    }
+    return result;
+  }
+
+  fft(input) {
+    let N = input.length;
+    if (N <= 1) return [{ real: input[0] || 0, imag: 0 }];
+    if ((N & (N - 1)) !== 0) throw new Error('N must be power of 2');
+
+    let even = this.fft(input.filter((_, i) => i % 2 === 0));
+    let odd = this.fft(input.filter((_, i) => i % 2 === 1));
+
+    let result = new Array(N);
+    for (let k = 0; k < N / 2; k++) {
+      let t = odd[k];
+      let angle = -2 * Math.PI * k / N;
+      let twiddle = { real: Math.cos(angle), imag: Math.sin(angle) };
+      let twiddled = {
+        real: t.real * twiddle.real - t.imag * twiddle.imag,
+        imag: t.real * twiddle.imag + t.imag * twiddle.real
+      };
+      result[k] = {
+        real: even[k].real + twiddled.real,
+        imag: even[k].imag + twiddled.imag
+      };
+      result[k + N / 2] = {
+        real: even[k].real - twiddled.real,
+        imag: even[k].imag - twiddled.imag
+      };
+    }
+    return result;
+  }
+
+  ifft(input) {
+    let N = input.length;
+    // Conjugate
+    let conj = input.map(c => ({ real: c.real, imag: -c.imag }));
+    // FFT
+    let fftConj = this.fft(conj.map(c => c.real)); // wait, fft expects real array
+    // FFT on complex is needed, but simplify
+    // For simplicity, implement IFFT similarly
+    let result = new Float32Array(N);
+    for (let n = 0; n < N; n++) {
+      let sumReal = 0, sumImag = 0;
+      for (let k = 0; k < N; k++) {
+        let angle = 2 * Math.PI * k * n / N;
+        let c = input[k];
+        sumReal += c.real * Math.cos(angle) - c.imag * Math.sin(angle);
+        sumImag += c.real * Math.sin(angle) + c.imag * Math.cos(angle);
+      }
+      result[n] = sumReal / N;
+    }
+    return result;
+  }
+}
+
+registerProcessor('preserve-pitch-processor', PreservePitchProcessor);

package/src/audio/engine/PreservePitchWorklet.ts

@@ -0,0 +1,79 @@
+interface PreservePitchWorkletOptions {
+  ctx: AudioContext;
+  mediaElement?: HTMLMediaElement;
+  pitchFactor?: number;
+  modulePath?: string;
+}
+
+import processorCode from './PreservePitchProcessor.js?raw';
+
+export class PreservePitchWorklet {
+  mediaElement: HTMLMediaElement | null = null;
+  source: MediaElementAudioSourceNode | null = null;
+  ctx: AudioContext;
+  workletNode: AudioWorkletNode | null = null;
+  url: string | null = null;
+
+  static async createWorklet(options: PreservePitchWorkletOptions): Promise<PreservePitchWorklet> {
+    const { ctx, mediaElement, pitchFactor, modulePath } = options;
+    const worklet = new PreservePitchWorklet(ctx);
+
+    try {
+      if (modulePath) {
+        await ctx.audioWorklet.addModule(modulePath);
+      } else {
+        const blob = new Blob([processorCode], { type: 'text/javascript' });
+        worklet.url = URL.createObjectURL(blob);
+        await ctx.audioWorklet.addModule(worklet.url);
+      }
+    } catch (err) {
+      worklet.destroy();
+      throw new Error(`Error adding module: ${err}`);
+    }
+
+    try {
+      worklet.workletNode = new AudioWorkletNode(ctx, 'preserve-pitch-processor');
+
+      if (pitchFactor) {
+        worklet.updatePitchFactor(pitchFactor);
+      }
+
+      if (mediaElement) {
+        const source = ctx.createMediaElementSource(mediaElement);
+        source.connect(worklet.workletNode);
+        worklet.mediaElement = mediaElement;
+        worklet.source = source;
+      }
+    } catch (err) {
+      worklet.destroy();
+      throw new Error(`Error creating worklet node: ${err}`);
+    }
+
+    return worklet;
+  }
+
+  constructor(ctx: AudioContext) {
+    this.ctx = ctx;
+  }
+
+  updatePitchFactor(factor: number): void {
+    if (this.workletNode) {
+      this.workletNode.port.postMessage({ type: 'setPitchFactor', factor });
+    }
+  }
+
+  destroy(): void {
+    if (this.workletNode) {
+      this.workletNode.disconnect();
+      this.workletNode = null;
+    }
+    if (this.source) {
+      this.source.disconnect();
+      this.source = null;
+    }
+    if (this.url) {
+      URL.revokeObjectURL(this.url);
+      this.url = null;
+    }
+  }
+}