Abort a blocked play()'s downloads; unload fixes (5.0.0-alpha.2) (#32)

* Unload tracks that leave the preload window

Moving a track out of the window now aborts its download, drops a decode
in progress and releases its decoded buffer, instead of only cancelling
an unfinished fetch. Late fetch/decode results from an unloaded load are
ignored.

* Bump to 5.0.0-alpha.1

* Abort a blocked play()'s downloads

When the browser refused HTML5 play() (autoplay policy, NotAllowedError),
gapless reported onPlayBlocked and the queue paused, but the track stayed
in the html5 state with both downloads running: the Web Audio HEAD and
GET started alongside play(), and the element, switched to preload=auto,
kept buffering. Nothing cancelled them; unload() refuses the current
track, and the element is internal. A page whose autoplay was blocked
downloaded the whole first track anyway.

A blocked play() now sends PLAY_BLOCKED to the track before onPlayBlocked
runs. From html5 it returns to idle, as if play() had never been called:
isPlaying cleared, progress loop stopped, the element released (source
dropped and reattached with preload=none, which aborts its fetch without
an error event), and a Web Audio load still in flight aborted, with any
decode that finishes later dropped (the same bookkeeping as unload()).
The seek target is kept, so the next play() resumes where it would have.
The next play() starts both loads fresh.

The queue's existing PAUSE then reaches an idle track, which ignores it,
so the app sees a stopped queue inside its onPlayBlocked callback.

* Bump to 5.0.0-alpha.2

* Report HTML5 again when an unloaded track replays

Nothing set playbackType back to HTML5. Before tracks could be unloaded
that didn't matter: a track that had played on Web Audio kept its
buffer, so it replayed on Web Audio. Now unload() can release that
buffer, and replaying the track goes through HTML5 with playbackType
still WEBAUDIO, which the queue reads in two places:

- _preloadAhead's bandwidth guard (defer preloading while the current
  track is on HTML5 and still loading) didn't apply, so the next track
  downloaded alongside the current track's fresh fetch, delaying its
  crossover;
- _cancelScheduledGapless skipped cancelling the HTML5 gain mute.

The html5 state now sets playbackType to HTML5 on entry: it's HTML5
playback by definition, and both transitions into it get it.

Reported by Codex review on #32.

* Release a finished source node when unloading its track

unload() nulled audioBuffer, but a track that ended naturally on Web
Audio still held its source node: WEBAUDIO_ENDED goes to idle without
stopping it, and DEACTIVATE in idle doesn't either. The node's buffer is
the decoded audio, so in ordinary sequential playback every finished
track kept its decoded audio (hundreds of MB for a long track) after the
queue unloaded it for leaving the preload window.

unload() now also releases the source node through _stopSourceNode()
(onended cleared, disconnected, dropped). unload() never runs on a
playing or scheduled track, so the node it finds is a finished one.

Reported by Codex review on #32.

Author: switz

README.md

@@ -143,9 +143,11 @@ safe at any point:
 - the current entry keeps playing, untouched;
 - if the entry after it changed, the old one's scheduled gapless start is
   cancelled, and the new one is preloaded and scheduled;
-- downloads for entries that left the preload window (the current entry plus
-  the next `preloadNumTracks`) are aborted, so they don't compete with the
-  entries about to play; decoded audio is kept.
+- entries that left the preload window (the current entry plus the next
+  `preloadNumTracks`) are unloaded: downloads are aborted, so they don't
+  compete with the entries about to play, and decoded audio is released,
+  since a decoded track takes hundreds of MB. An entry that comes back into
+  the window loads again.
 
 #### Repeat
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gapless",
-  "version": "5.0.0-alpha.0",
+  "version": "5.0.0-alpha.2",
   "private": false,
   "description": "Gapless audio playback javascript plugin",
   "license": "MIT",

src/Queue.ts

@@ -604,7 +604,7 @@ export class Queue implements TrackQueueRef {
     if (this.isPlaying) {
       this._preloadAhead(this._currentTrack);
     } else {
-      this._cancelPreloadsOutsideWindow(this._currentTrack);
+      this._unloadOutsideWindow(this._currentTrack);
     }
   }
 
@@ -709,9 +709,9 @@ export class Queue implements TrackQueueRef {
       this._preloadAhead(current);
       this._tryScheduleGapless(current);
     } else {
-      // "Next" is unchanged, but a move can still push a downloading track
-      // out of the window.
-      this._cancelPreloadsOutsideWindow(current);
+      // "Next" is unchanged, but a move can still push a loading or loaded
+      // track out of the window.
+      this._unloadOutsideWindow(current);
     }
   }
 
@@ -746,7 +746,7 @@ export class Queue implements TrackQueueRef {
       this._preloadAhead(cur);
       this._tryScheduleGapless(cur);
     } else {
-      this._cancelPreloadsOutsideWindow(cur);
+      this._unloadOutsideWindow(cur);
     }
   }
 
@@ -860,17 +860,18 @@ export class Queue implements TrackQueueRef {
   }
 
   /**
-   * Abort downloads for tracks that are no longer in the preload window (the
-   * current track plus the next preloadNumTracks in play order), so they don't
-   * compete with the tracks that are about to play. Decoded buffers are kept.
+   * Unload tracks that are no longer in the preload window (the current track
+   * plus the next preloadNumTracks in play order): abort their downloads, so
+   * they don't compete with the tracks about to play, and release their
+   * decoded audio, which is large. They load again if they come back.
    */
-  private _cancelPreloadsOutsideWindow(from: Track | null | undefined): void {
+  private _unloadOutsideWindow(from: Track | null | undefined): void {
     const window = new Set(from ? this._preloadWindow(from) : []);
-    for (const t of this._tracks) if (!window.has(t)) t.cancelPreload();
+    for (const t of this._tracks) if (!window.has(t)) t.unload();
   }
 
   private _preloadAhead(from: Track | null | undefined): void {
-    this._cancelPreloadsOutsideWindow(from);
+    this._unloadOutsideWindow(from);
     if (!from) return;
     const cur = from;
 

src/Track.ts

@@ -60,6 +60,8 @@ export class Track {
   readonly skipHEAD: boolean;
   /** Temporary holder between fetch and decode steps (unserializable — stays on Track class). */
   private _pendingArrayBuffer: ArrayBuffer | null = null;
+  /** Bumped by unload(): a fetch or decode that finishes after it is dropped. */
+  private _loadGeneration = 0;
 
   // ---- HTML5 Audio ---------------------------------------------------------
   readonly audio: HTMLAudioElement;
@@ -236,15 +238,21 @@ export class Track {
             }),
             fetchAudio: fromPromise(async ({ input, signal }) => {
               const { resolvedUrl } = input as { resolvedUrl: string };
+              const generation = this._loadGeneration;
               const res = await fetch(resolvedUrl, { signal });
               if (!res.ok) throw new Error(`HTTP ${res.status} for ${resolvedUrl}`);
-              this._pendingArrayBuffer = await res.arrayBuffer();
+              const bytes = await res.arrayBuffer();
+              if (generation === this._loadGeneration) this._pendingArrayBuffer = bytes;
             }),
             decodeAudio: fromPromise(async () => {
               const buf = this._pendingArrayBuffer;
               this._pendingArrayBuffer = null;
               if (!buf || !this.ctx) throw new Error('No ArrayBuffer or AudioContext');
-              this.audioBuffer = await this.ctx.decodeAudioData(buf);
+              const generation = this._loadGeneration;
+              const decoded = await this.ctx.decodeAudioData(buf);
+              // Unloaded mid-decode (which can't be aborted): drop the result.
+              if (generation !== this._loadGeneration) return;
+              this.audioBuffer = decoded;
               this._maybeComputeBufferAlignment();
             }),
           },
@@ -309,6 +317,8 @@ export class Track {
           this._seekAbort = new AbortController();
           this.audio.currentTime = 0;
         },
+        releaseHtml5Element: () => this._releaseHtml5Element(),
+        dropPendingDecode: () => this._dropPendingDecode(),
         resetTiming: () => {
           this._waRefCtxTime = 0;
           this._waRefTrackTime = 0;
@@ -407,21 +417,26 @@ export class Track {
   }
 
   /**
-   * Abort an in-flight Web Audio download, so the track can be preloaded again
-   * later from scratch. Only while the URL is being resolved or the file
-   * fetched: once decoding starts the bytes are already here, and the decode
-   * (which assigns audioBuffer itself) can't be aborted. Returns whether a
-   * download was cancelled.
+   * Let go of this track's Web Audio data, so a track out of the preload
+   * window doesn't hold memory (a decoded hour of audio is hundreds of MB):
+   * abort its download, drop a decode in progress when it finishes (decoding
+   * can't be aborted), or release its decoded buffer. It loads again from
+   * scratch if it comes back into the window. Never while it's playing,
+   * scheduled to play, or waiting for its buffer to play. Returns whether
+   * anything was let go.
    */
-  cancelPreload(): boolean {
-    const snap = this._actor.getSnapshot();
-    if (snap.context.webAudioLoadingState !== 'LOADING' || snap.context.isPlaying) return false;
-    const child = snap.children.fetchDecode as { getSnapshot(): { value: unknown } } | undefined;
-    const stage = child?.getSnapshot().value;
-    if (stage !== 'resolvingUrl' && stage !== 'fetching') return false;
-    this.queueRef.onDebug(`cancelPreload() track=${this.key} stage=${String(stage)}`);
-    this._pendingArrayBuffer = null;
-    this._actor.send({ type: 'CANCEL_PRELOAD' });
+  unload(): boolean {
+    const { context } = this._actor.getSnapshot();
+    const state = context.webAudioLoadingState;
+    if (state !== 'LOADING' && state !== 'LOADED') return false;
+    if (context.isPlaying || context.pendingPlay) return false;
+    this.queueRef.onDebug(`unload() track=${this.key} state=${state}`);
+    this._dropPendingDecode();
+    this.audioBuffer = null;
+    // A track that ended on Web Audio keeps its finished source node, whose
+    // buffer is the decoded audio: let it go too, or the memory stays held.
+    this._stopSourceNode();
+    this._actor.send({ type: 'UNLOAD' });
     return true;
   }
 
@@ -609,6 +624,8 @@ export class Track {
     if (promise) {
       promise.catch((err: unknown) => {
         if (err instanceof Error && err.name === 'NotAllowedError') {
+          // First, so the queue (and the app's callback) see a stopped track.
+          this._actor.send({ type: 'PLAY_BLOCKED' });
           this.queueRef.onPlayBlocked();
         } else if (err instanceof Error && err.name === 'AbortError') {
           // Browser aborted — element will recover on next play()
@@ -619,6 +636,27 @@ export class Track {
     }
   }
 
+  /** A fetch or decode that finishes from now on is dropped (see unload()). */
+  private _dropPendingDecode(): void {
+    this._loadGeneration++;
+    this._pendingArrayBuffer = null;
+  }
+
+  /**
+   * Stop the element's download without an error event: drop its source
+   * (which aborts the fetch) and put it back unloaded, so the next play()
+   * starts it fresh.
+   */
+  private _releaseHtml5Element(): void {
+    this.audio.pause();
+    this._seekAbort.abort();
+    this._seekAbort = new AbortController();
+    this.audio.preload = 'none';
+    this.audio.removeAttribute('src');
+    this.audio.load();
+    this.audio.src = this._trackUrl;
+  }
+
   private _seekHtml5(target: number): void {
     if (!isFinite(target)) return;
     if (this.audio.preload !== 'auto') this.audio.preload = 'auto';

src/machines/track.machine.ts

@@ -59,6 +59,9 @@ export type TrackEvent =
   | { type: 'PRELOAD' }
   | { type: 'BUFFER_LOADING' }
   | { type: 'PLAY' }
+  // The browser refused HTML5 play() (autoplay policy): nothing will play, so
+  // nothing should keep downloading.
+  | { type: 'PLAY_BLOCKED' }
   | { type: 'PLAY_WEBAUDIO' }
   | { type: 'PAUSE' }
   | { type: 'SEEK'; time: number }
@@ -69,8 +72,8 @@ export type TrackEvent =
   | { type: 'WEBAUDIO_ENDED' }
   | { type: 'URL_RESOLVED'; url: string }
   | { type: 'START_FETCH' }
-  // Abort an in-flight fetch (sent by Track only before decoding starts).
-  | { type: 'CANCEL_PRELOAD' }
+  // Let go of Web Audio data: abort a fetch, drop a decode, release a buffer.
+  | { type: 'UNLOAD' }
   | { type: 'SCHEDULE_GAPLESS'; when: number }
   | { type: 'CANCEL_GAPLESS' }
   | { type: 'LOOKAHEAD_REACHED' };
@@ -87,8 +90,10 @@ export function createTrackMachine(initialContext: TrackContext) {
       fetchDecode: fetchDecodeMachine,
     },
     guards: {
-      canCancelPreload: ({ context }) =>
-        context.webAudioLoadingState === 'LOADING' && !context.isPlaying,
+      canUnload: ({ context }) =>
+        (context.webAudioLoadingState === 'LOADING' || context.webAudioLoadingState === 'LOADED') &&
+        !context.isPlaying &&
+        !context.pendingPlay,
       canPlayWebAudio: () => false,
       isWebAudioOnly: () => false,
       canStartFetch: ({ context }) =>
@@ -110,6 +115,8 @@ export function createTrackMachine(initialContext: TrackContext) {
       seekHtml5: () => {},
       seekWebAudio: () => {},
       resetHtml5Element: () => {},
+      releaseHtml5Element: () => {},
+      dropPendingDecode: () => {},
       resetTiming: () => {},
       notifyTrackEnded: () => {},
       triggerFetchForPendingPlay: () => {},
@@ -157,6 +164,9 @@ export function createTrackMachine(initialContext: TrackContext) {
       setPlaybackTypeWebAudio: assign({
         playbackType: () => 'WEBAUDIO' as PlaybackType,
       }),
+      setPlaybackTypeHtml5: assign({
+        playbackType: () => 'HTML5' as PlaybackType,
+      }),
       clearNotifiedLookahead: assign({
         notifiedLookahead: () => false,
       }),
@@ -189,10 +199,11 @@ export function createTrackMachine(initialContext: TrackContext) {
           }),
         ],
       },
-      // Stopping the child aborts its fetch. Never for a playing track: its
-      // decode is what lets it cross over to Web Audio.
-      CANCEL_PRELOAD: {
-        guard: 'canCancelPreload',
+      // Stopping the child aborts its fetch (Track drops a decode in flight and
+      // the buffer itself). Never for a playing, scheduled or waiting track:
+      // its decode is what lets it cross over to Web Audio.
+      UNLOAD: {
+        guard: 'canUnload',
         actions: ['stopFetch', 'resetLoadingState'],
       },
     },
@@ -290,6 +301,9 @@ export function createTrackMachine(initialContext: TrackContext) {
       // html5: HTML5 Audio is playing; WebAudio decode may be in progress
       // -----------------------------------------------------------------
       html5: {
+        // HTML5 is the output here, whatever played before: a track that ran
+        // on Web Audio, was unloaded and plays again starts over on HTML5.
+        entry: 'setPlaybackTypeHtml5',
         on: {
           PAUSE: {
             actions: [
@@ -303,6 +317,35 @@ export function createTrackMachine(initialContext: TrackContext) {
           PLAY: {
             actions: ['setIsPlaying', 'playHtml5', 'startProgressLoop'],
           },
+          // Blocked before a sound was made: back to idle, as if play() had
+          // never been called. The element stops buffering, and a Web Audio
+          // download still in flight is aborted (a decoded buffer is kept: it
+          // costs nothing more). The position is kept for the next play().
+          PLAY_BLOCKED: [
+            {
+              guard: ({ context }: { context: TrackContext }) =>
+                context.webAudioLoadingState === 'LOADING',
+              target: 'idle',
+              actions: [
+                'clearIsPlaying',
+                'stopProgressLoop',
+                'releaseHtml5Element',
+                'stopFetch',
+                'resetLoadingState',
+                'dropPendingDecode',
+                'reportProgress',
+              ],
+            },
+            {
+              target: 'idle',
+              actions: [
+                'clearIsPlaying',
+                'stopProgressLoop',
+                'releaseHtml5Element',
+                'reportProgress',
+              ],
+            },
+          ],
           BUFFER_LOADING: {
             actions: 'setLoadingState',
           },
@@ -367,8 +410,8 @@ export function createTrackMachine(initialContext: TrackContext) {
       // -----------------------------------------------------------------
       loading: {
         on: {
-          CANCEL_PRELOAD: {
-            guard: 'canCancelPreload',
+          UNLOAD: {
+            guard: 'canUnload',
             target: 'idle',
             actions: ['stopFetch', 'resetLoadingState'],
           },

tests/setup.ts

@@ -171,6 +171,10 @@ export class MockAudioElement {
 
   load: Mock = vi.fn();
 
+  removeAttribute = vi.fn((name: string) => {
+    if (name === 'src') this.src = '';
+  });
+
   addEventListener = vi.fn(
     (type: string, cb: EventListenerOrEventListenerObject, opts?: AddEventListenerOptions) => {
       if (!this._listeners[type]) this._listeners[type] = [];