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

package/src/audio/engine/WebAudioEngine.ts

@@ -1,286 +1,585 @@
 /* Implements the AudioEngine interface using the Web Audio API. */
 
 import {
-    AudioEngine,
-    Playback,
-  } from "./AudioEngine";
-  
-  import { Publication } from "@readium/shared";
-  import { Locator } from "@readium/shared";
-  
-  type EventCallback = (data: any) => void;
-  
-  export class WebAudioEngine implements AudioEngine {
-    /* Defines the current playback state. */
-    public readonly playback: Playback;
-    private audioContext: AudioContext;
-    private mediaElement: HTMLAudioElement;
-    private sourceNode: MediaElementAudioSourceNode | null = null;
-    private gainNode: GainNode;
-    private listeners: { [event: string]: EventCallback[] } = {};
-    private isMutedValue: boolean = false;
-    private isPlayingValue: boolean = false;
-    private isPausedValue: boolean = false;
-    private isLoadingValue: boolean = false;
-    private isLoadedValue: boolean = false;
-    private isEndedValue: boolean = false;
-  
-    constructor(values: { playback: Playback; audioContext: AudioContext }) {
-      this.playback = values.playback;
-      this.audioContext = values.audioContext;
-      this.gainNode = this.audioContext?.createGain();
-      this.setVolume(this.playback.state.volume); // Default initial volume
-  
-      // Create an HTML audio element
-      this.mediaElement = document.createElement("audio");
-      this.mediaElement.crossOrigin = "use-credentials"; // Optional: Handle cross-origin audio files
-  
-      // Event listeners (to report the client app about some async events)
-      this.mediaElement.addEventListener(
-        "canplaythrough",
-        this.onCanPlayThrough.bind(this)
-      );
-      this.mediaElement.addEventListener(
-        "timeupdate",
-        this.onTimeUpdate.bind(this)
-      );
-      this.mediaElement.addEventListener("error", this.onError.bind(this));
-      this.mediaElement.addEventListener("ended", this.onEnded.bind(this));
-  
-      //Set the start time
-      this.mediaElement.currentTime = this.playback.state.currentTime;
-    }
-  
-    /**
-     * Adds an event listener to the audio engine.
-     * @param event - event name to be listened.
-     * @param callback - callback function to be called when the event is triggered.
-     */
-    public on(event: string, callback: EventCallback) {
-      if (!this.listeners[event]) {
-        this.listeners[event] = [];
-      }
-      this.listeners[event].push(callback);
-    }
-  
-    /**
-     * Removes an event listener from the audio engine.
-     * @param event - event name to be removed from the listeners.
-     * @param callback - callback function to be removed.
-     */
-    public off(event: string, callback: EventCallback) {
-      if (!this.listeners[event]) return;
-      this.listeners[event] = this.listeners[event].filter(
-        (cb) => cb !== callback
-      );
+  AudioEngine,
+  Playback,
+} from "./AudioEngine";
+import { PreservePitchWorklet } from "./PreservePitchWorklet";
+
+type EventCallback = (data: any) => void;
+
+export class WebAudioEngine implements AudioEngine {
+  /* Defines the current playback state. */
+  public readonly playback: Playback;
+  private audioContext: AudioContext | null = null;
+  private mediaElement: HTMLAudioElement;
+  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;
+  private isLoadingValue: boolean = false;
+  private isLoadedValue: boolean = false;
+  private isEndedValue: boolean = false;
+  private isStoppedValue: boolean = false;
+  private worklet: PreservePitchWorklet | null = null;
+  private webAudioActive: boolean = false;
+
+  private readonly boundOnCanPlayThrough = this.onCanPlayThrough.bind(this);
+  private readonly boundOnTimeUpdate = this.onTimeUpdate.bind(this);
+  private readonly boundOnError = this.onError.bind(this);
+  private readonly boundOnEnded = this.onEnded.bind(this);
+  private readonly boundOnStalled = this.onStalled.bind(this);
+  private readonly boundOnEmptied = this.onEmptied.bind(this);
+  private readonly boundOnSuspend = this.onSuspend.bind(this);
+  private readonly boundOnWaiting = this.onWaiting.bind(this);
+  private readonly boundOnLoadedMetadata = this.onLoadedMetadata.bind(this);
+  private readonly boundOnSeeking = this.onSeeking.bind(this);
+  private readonly boundOnSeeked = this.onSeeked.bind(this);
+  private readonly boundOnPlay = this.onPlay.bind(this);
+  private readonly boundOnPlaying = this.onPlaying.bind(this);
+  private readonly boundOnPause = this.onPause.bind(this);
+  private readonly boundOnProgress = this.onProgress.bind(this);
+
+  constructor(values: { playback: Playback }) {
+    this.playback = values.playback;
+
+    // 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);
+    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);
+
+    //Set the start time
+    this.mediaElement.currentTime = this.playback.state.currentTime;
+  }
+
+  /**
+   * Adds an event listener to the audio engine.
+   * @param event - event name to be listened.
+   * @param callback - callback function to be called when the event is triggered.
+   */
+  public on(event: string, callback: EventCallback) {
+    if (!this.listeners[event]) {
+      this.listeners[event] = [];
     }
-  
-    /**
-     * 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.listeners[event].push(callback);
+  }
+
+  /**
+   * Removes an event listener from the audio engine.
+   * @param event - event name to be removed from the listeners.
+   * @param callback - callback function to be removed.
+   */
+  public off(event: string, callback: EventCallback) {
+    if (!this.listeners[event]) return;
+    this.listeners[event] = this.listeners[event].filter(
+      (cb) => cb !== callback
+    );
+  }
+
+  /**
+   * 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();
-  
-      // Create a new source node only if it doesn't exist
-      if (!this.sourceNode) {
-        this.sourceNode = new MediaElementAudioSourceNode(this.audioContext, {
-          mediaElement: this.mediaElement,
-        });
-        this.sourceNode.connect(this.gainNode);
-        this.gainNode.connect(this.audioContext.destination);
-      }
     }
-  
-    // Ensure AudioContext is running
-    private async ensureAudioContextRunning() {
-      if (this.audioContext.state === "suspended") {
-        await this.audioContext.resume();
-      }
+  }
+
+  private deactivateWebAudio(): void {
+    if (this.worklet) {
+      this.worklet.destroy();
+      this.worklet = null;
     }
-  
-    // Event handler for timeupdate
-    private onTimeUpdate() {
-      // Continuously track the current time of the media element
-      // You can update UI elements or perform other tasks here
-      this.emit("timeupdate", this.mediaElement.currentTime);
+    if (this.sourceNode) {
+      this.sourceNode.disconnect();
+      this.sourceNode = null;
     }
-  
-    // Event handler for canplaythrough
-    private onCanPlayThrough() {
-      this.isLoadingValue = false;
-      this.isLoadedValue = true;
-      this.emit("canplaythrough", 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;
     }
-  
-    // Event handler for error
-    private onError() {
-      console.error("Error loading media element");
-      this.emit("error", this.mediaElement.error);
+
+    // 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'));
     }
-  
-    // Event handle for ended
-    private onEnded() {
-      this.isPlayingValue = false;
-      this.isPausedValue = false;
-      this.isEndedValue = true;
-      this.emit("ended", null);
+
+    // 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();
     }
-  
-    // Used to emit some events like timeupdate or ended
-    private emit(event: string, data: any) {
-      if (!this.listeners[event]) return;
-      this.listeners[event].forEach((callback) => callback(data));
+
+    // 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;
     }
-  
-    /**
-     * Plays the audio resource at the given locator.
-     */
-    public async playLocator(
-      _publication: Publication,
-      _locator: Locator
-    ): Promise<void> {
-      // Implementation details.
+  }
+
+  // Ensure AudioContext is running
+  private async ensureAudioContextRunning() {
+    if (!this.audioContext) {
+      this.audioContext = new AudioContext();
     }
-  
-    /**
-     * Plays the current audio resource.
-     */
-    public async play(): Promise<void> {
-      await this.ensureAudioContextRunning();
-  
-      if (this.isPlayingValue) {
-        this.stop();
-        console.error("Audio is already playing");
-        return;
-      }
-  
-      try {
-        await this.mediaElement.play();
-        this.isPlayingValue = true;
-        this.isPausedValue = false;
-      } catch (err) {
-        console.error("error trying to play media element", err);
-      }
+    if (this.audioContext.state === "suspended") {
+      await this.audioContext.resume();
     }
-  
-    /**
-     * Pauses the currently playing audio resource.
-     */
-    public pause(): void {
-      this.mediaElement.pause();
-      this.isPlayingValue = false;
-      this.isPausedValue = true;
+  }
+
+  private getOrCreateAudioContext(): AudioContext {
+    if (!this.audioContext) {
+      this.audioContext = new AudioContext();
     }
-  
-    /**
-     * Stops the currently playing audio resource.
-     */
-    public stop(): void {
-      // Stop the audio and reset the current time
-      this.mediaElement.pause();
-      this.mediaElement.currentTime = 0;
-      this.isPlayingValue = false;
+    return this.audioContext;
+  }
+
+  // Event handler for timeupdate
+  private onTimeUpdate() {
+    // Continuously track the current time of the media element
+    // You can update UI elements or perform other tasks here
+    this.emit("timeupdate", this.mediaElement.currentTime);
+  }
+
+  // Event handler for canplaythrough
+  private onCanPlayThrough() {
+    this.isLoadingValue = false;
+    this.isLoadedValue = true;
+    this.emit("canplaythrough", null);
+  }
+
+  // Event handler for error
+  private onError() {
+    console.error("Error loading media element");
+    this.emit("error", this.mediaElement.error);
+  }
+
+  // Event handle for ended
+  private onEnded() {
+    this.isPlayingValue = false;
+    this.isPausedValue = false;
+    this.isEndedValue = true;
+    this.emit("ended", null);
+  }
+
+  private onStalled(event: Event) {
+    this.emit("stalled", event);
+  }
+
+  private onEmptied(event: Event) {
+    this.emit("emptied", event);
+  }
+
+  private onSuspend(event: Event) {
+    this.emit("suspend", event);
+  }
+
+  private onWaiting(event: Event) {
+    this.emit("waiting", event);
+  }
+
+  private onLoadedMetadata(event: Event) {
+    this.emit("loadedmetadata", event);
+  }
+
+  private onSeeking(event: Event) {
+    this.emit("seeking", event);
+  }
+
+  private onSeeked(event: Event) {
+    this.emit("seeked", event);
+  }
+
+  private onPlay() {
+    this.emit("play", null);
+  }
+
+  private onPlaying() {
+    this.emit("playing", null);
+  }
+
+  private onPause() {
+    this.emit("pause", null);
+  }
+
+  private onProgress() {
+    this.emit("progress", this.mediaElement.seekable);
+  }
+
+  // Used to emit some events like timeupdate or ended
+  private emit(event: string, data: any) {
+    if (!this.listeners[event]) return;
+    this.listeners[event].forEach((callback) => callback(data));
+  }
+
+  /**
+   * Plays the current audio resource.
+   */
+  public async play(): Promise<void> {
+    if (this.isPlayingValue) {
+      return;
+    }
+
+    try {
+      await this.mediaElement.play();
+      this.isPlayingValue = true;
       this.isPausedValue = false;
+      this.isStoppedValue = false;
+    } catch (err: any) {
+      // AbortError is expected when load() interrupts a pending play() during navigation
+      if (err?.name === "AbortError") return;
+      console.error("error trying to play media element", err);
+      this.emit("error", err);
     }
-  
-    /**
-     * Adjusts the [volume] of the audio resource.
-     * @volume The volume to set, in the range [0, 1].
-     */
-    public setVolume(volume: number): void {
-      if (volume < 0) {
+  }
+
+  /**
+   * Pauses the currently playing audio resource.
+   */
+  public pause(): void {
+    this.mediaElement.pause();
+    this.isPlayingValue = false;
+    this.isPausedValue = true;
+  }
+
+  /**
+   * Stops the currently playing audio resource.
+   */
+  public stop(): void {
+    // Stop the audio and reset the current time
+    this.mediaElement.pause();
+    this.mediaElement.currentTime = 0;
+    this.isPlayingValue = false;
+    this.isPausedValue = false;
+    this.isStoppedValue = true;
+  }
+
+  /**
+   * Adjusts the [volume] of the audio resource.
+   * @volume The volume to set, in the range [0, 1].
+   */
+  public setVolume(volume: number): void {
+    if (volume < 0) {
+      this.mediaElement.volume = 0;
+      if (this.gainNode) {
         this.gainNode.gain.value = 0;
-        this.isMutedValue = true;
-        return;
       }
-      if (volume > 1) {
-        this.setVolume(volume / 100);
-        return;
-      }
-      this.gainNode.gain.value = volume;
-    }
-  
-    /**
-     * Skips [seconds] either forward or backward if [seconds] is negative.
-     */
-    public skip(seconds: number): void {
-      if (!this.mediaElement) {
-        console.error("Audio not loaded");
-        return;
-      }
-  
-      const newTime = this.mediaElement.currentTime + seconds;
-      if (newTime < 0) this.mediaElement.currentTime = 0;
-      else if (newTime > this.mediaElement.duration)
-        this.mediaElement.currentTime = this.mediaElement.duration;
-      else this.mediaElement.currentTime = newTime;
-    }
-  
-    /**
-     * Returns de current time in the audio resource.
-     */
-    public currentTime(): number {
-      return this.mediaElement.currentTime;
+      this.isMutedValue = true;
+      this.playback.state.volume = 0;
+      return;
     }
-  
-    /**
-     * Returns the duration in seconds of the current media element resource.
-     */
-    public duration(): number {
-      // Implementation details.
-      return this.mediaElement.duration;
+    if (volume > 1) {
+      this.setVolume(volume / 100);
+      return;
     }
-  
-    /**
-     * Returns whether the audio resource is currently playing.
-     */
-    public isPlaying(): boolean {
-      return this.isPlayingValue;
-    }
-  
-    /**
-     * Returns whether the audio resource is currently paused.
-     */
-    public isPaused(): boolean {
-      return this.isPausedValue;
-    }
-  
-    /**
-     * Returns whether the audio resource is currently stopped.
-     */
-    public isStopped(): boolean {
-      return false;
-    }
-  
-    /**
-     * Returns whether the audio resource is currently loading.
-     */
-    public isLoading(): boolean {
-      return this.isLoadingValue;
+    this.mediaElement.volume = volume;
+    if (this.gainNode) {
+      this.gainNode.gain.value = volume;
     }
-  
-    /**
-     * Returns whether the audio resource is currently loaded.
-     */
-    public isLoaded(): boolean {
-      return this.isLoadedValue;
+    this.playback.state.volume = volume;
+  }
+
+  /**
+   * Skips [seconds] either forward or backward if [seconds] is negative.
+   */
+  public skip(seconds: number): void {
+    const duration = this.mediaElement.duration;
+    if (!isFinite(duration)) return;
+
+    const newTime = this.mediaElement.currentTime + seconds;
+    if (newTime < 0) this.mediaElement.currentTime = 0;
+    else if (newTime > duration) this.mediaElement.currentTime = duration;
+    else this.mediaElement.currentTime = newTime;
+  }
+
+  /**
+   * Returns de current time in the audio resource.
+   */
+  public currentTime(): number {
+    return this.mediaElement.currentTime;
+  }
+
+  /**
+   * Returns the duration in seconds of the current media element resource.
+   */
+  public duration(): number {
+    // Implementation details.
+    return this.mediaElement.duration;
+  }
+
+  /**
+   * Returns whether the audio resource is currently playing.
+   */
+  public isPlaying(): boolean {
+    return this.isPlayingValue;
+  }
+
+  /**
+   * Returns whether the audio resource is currently paused.
+   */
+  public isPaused(): boolean {
+    return this.isPausedValue;
+  }
+
+  /**
+   * Returns whether the audio resource is currently stopped.
+   */
+  public isStopped(): boolean {
+    return this.isStoppedValue;
+  }
+
+  /**
+   * Returns whether the audio resource is currently loading.
+   */
+  public isLoading(): boolean {
+    return this.isLoadingValue;
+  }
+
+  /**
+   * Returns whether the audio resource is currently loaded.
+   */
+  public isLoaded(): boolean {
+    return this.isLoadedValue;
+  }
+
+  /**
+   * Returns whether the audio resource is currently ended.
+   */
+  public isEnded(): boolean {
+    return this.isEndedValue;
+  }
+
+  /**
+   * Returns whether the audio resource is currently muted.
+   */
+  public isMuted(): boolean {
+    return this.isMutedValue;
+  }
+
+  /**
+   * 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) {
+        (this.mediaElement as any).preservesPitch = true;
+      } else {
+        // Activate Web Audio graph first, then attach the worklet
+        this.activateWebAudio().then(() => {
+          if (!this.worklet) {
+            if (this.sourceNode) {
+              this.sourceNode.disconnect();
+              this.sourceNode = null;
+            }
+            PreservePitchWorklet.createWorklet({
+              ctx: this.getOrCreateAudioContext(),
+              mediaElement: this.mediaElement,
+              pitchFactor: 1.0
+            }).then(worklet => {
+              this.worklet = worklet;
+              this.worklet.workletNode!.connect(this.gainNode!);
+              this.worklet.updatePitchFactor(1 / rate);
+            }).catch(err => {
+              console.warn("Failed to create preserve pitch worklet", err);
+            });
+          } else {
+            this.worklet.updatePitchFactor(1 / rate);
+          }
+        }).catch(err => {
+          console.warn("Web Audio unavailable, playing without pitch correction:", err);
+        });
+      }
+    } else {
+      if (this.worklet) {
+        this.worklet.destroy();
+        this.worklet = null;
+        // Worklet is gone; restore the direct source → gain path
+        if (this.webAudioActive) {
+          this.sourceNode = new MediaElementAudioSourceNode(this.getOrCreateAudioContext(), { mediaElement: this.mediaElement });
+          this.sourceNode.connect(this.gainNode!);
+        }
+      }
     }
-  
-    /**
-     * Returns whether the audio resource is currently ended.
-     */
-    public isEnded(): boolean {
-      return this.isEndedValue;
+  }
+
+  /**
+   * Activates the Web Audio graph for the current media element.
+   * Sets crossOrigin = "anonymous" and reloads so MediaElementAudioSourceNode can be used.
+   * No-ops if Web Audio is already active.
+   */
+  private async activateWebAudio(): Promise<void> {
+    if (this.webAudioActive) return;
+
+    const src = this.mediaElement.src;
+    if (!src) return;
+
+    const currentTime = this.mediaElement.currentTime;
+    const wasPlaying = this.isPlayingValue;
+
+    if (wasPlaying) {
+      this.mediaElement.pause();
+      this.isPlayingValue = false;
     }
-  
-    /**
-     * Returns whether the audio resource is currently muted.
-     */
-    public isMuted(): boolean {
-      return this.isMutedValue;
+
+    this.mediaElement.crossOrigin = "anonymous";
+    this.mediaElement.src = src;
+    this.mediaElement.load();
+
+    await new Promise<void>((resolve, reject) => {
+      const onReady = () => {
+        this.mediaElement.removeEventListener("canplaythrough", onReady);
+        this.mediaElement.removeEventListener("error", onFail);
+        resolve();
+      };
+      const onFail = () => {
+        this.mediaElement.removeEventListener("canplaythrough", onReady);
+        this.mediaElement.removeEventListener("error", onFail);
+        reject(new Error("Audio reload with CORS failed — server may not send Access-Control-Allow-Origin"));
+      };
+      this.mediaElement.addEventListener("canplaythrough", onReady);
+      this.mediaElement.addEventListener("error", onFail);
+    });
+
+    this.mediaElement.currentTime = currentTime;
+
+    this.sourceNode = new MediaElementAudioSourceNode(this.getOrCreateAudioContext(), { mediaElement: this.mediaElement });
+    
+    // Create gainNode lazily when Web Audio is activated
+    const audioContext = this.getOrCreateAudioContext();
+    this.gainNode = audioContext.createGain();
+    this.sourceNode.connect(this.gainNode);
+    this.gainNode.connect(audioContext.destination);
+
+    this.webAudioActive = true;
+
+    if (wasPlaying) {
+      await this.ensureAudioContextRunning();
+      await this.mediaElement.play();
+      this.isPlayingValue = true;
+      this.isPausedValue = false;
     }
   }
-  
+
+  public get isWebAudioActive(): boolean {
+    return this.webAudioActive;
+  }
+
+  /**
+   * Returns the HTML media element used for playback.
+   */
+  public getMediaElement(): HTMLMediaElement {
+    return this.mediaElement;
+  }
+}