Implement audio crossfade and playlist functionality in UI. Enhanced the audio management system by introducing two audio elements for crossfading, updating the track loading mechanism, and adding playlist support. Refactored related functions for improved clarity and performance, ensuring a seamless user experience during audio transitions.

frontend/ui.js

@@ -42,7 +42,20 @@ export function initUI({
   const deckCassette = $("deck-cassette");
   const deckDownload = $("deck-download");
 
-  audio.loop = true; // a cassette of endless chill
+  // Two audio elements so tapes can crossfade — one element can't overlap
+  // itself. The UI always reflects `active`; the other fades underneath it.
+  const audioA = audio; // the #tape-audio element
+  const audioB = new Audio();
+  audioB.preload = "auto";
+  audioB.id = "tape-audio-b";
+  document.body.appendChild(audioB); // no controls => invisible; in DOM for consistency
+  let active = audioA;
+  let fadeTimer = null;
+  let playlist = []; // collection songs, when playing as a playlist
+  let playlistIndex = -1; // active track's index in `playlist`, or -1 = single loop
+  const CROSSFADE = 2.5; // s — overlap as one tape rolls into the next
+  const PICK_FADE = 0.9; // s — quick blend when you pick or skip a tape by hand
+
   let busy = false;
   let collectionOpen = false;
   let gameboyOpen = false;
@@ -62,7 +75,7 @@ export function initUI({
 
   function currentStage() {
     if (busy) return "generating";
-    return audio.src ? "cassette" : "prompt";
+    return active.src ? "cassette" : "prompt";
   }
 
   function showError(message) {
@@ -104,7 +117,7 @@ export function initUI({
     }
   }
 
-  function loadCassette(song, shell) {
+  function setNowPlaying(song, shell) {
     currentSong = song;
     cassetteTitle.textContent = song.title;
     pillTitle.textContent = song.title;
@@ -112,13 +125,90 @@ export function initUI({
     deckDownload.href = song.url;
     deckDownload.setAttribute("download", `${song.title}.wav`);
     deckDownload.classList.remove("disabled");
-    deckCassette.style.setProperty("--shell1", (shell ?? SHELL_COLORS[0])[0]);
-    deckCassette.style.setProperty("--shell2", (shell ?? SHELL_COLORS[0])[1]);
-    audio.src = song.url;
-    audio.play().catch(() => {});
+    const s = shell ?? SHELL_COLORS[0];
+    deckCassette.style.setProperty("--shell1", s[0]);
+    deckCassette.style.setProperty("--shell2", s[1]);
+  }
+
+  function cancelFade() {
+    if (fadeTimer) {
+      clearInterval(fadeTimer);
+      fadeTimer = null;
+    }
+  }
+
+  // Equal-power crossfade: raise `incoming` while lowering `outgoing` so total
+  // loudness holds steady (a plain linear fade dips in the middle). Driven by a
+  // timer rather than rAF so it still completes when the tab is backgrounded.
+  function rampTo(incoming, outgoing, durSec, onDone) {
+    cancelFade();
+    const t0 = performance.now();
+    fadeTimer = setInterval(() => {
+      const t = Math.min((performance.now() - t0) / (durSec * 1000), 1);
+      incoming.volume = Math.sin((t * Math.PI) / 2);
+      if (outgoing) outgoing.volume = Math.cos((t * Math.PI) / 2);
+      if (t >= 1) {
+        cancelFade();
+        incoming.volume = 1;
+        if (outgoing) {
+          outgoing.pause();
+          outgoing.volume = 1;
+        }
+        onDone && onDone();
+      }
+    }, 33);
+  }
+
+  // Start `url` on the idle element and crossfade the active one into it.
+  function startTrack(url, { loop, fadeSec }) {
+    const incoming = active === audioA ? audioB : audioA;
+    const outgoing = active;
+    const overlap = !!outgoing.src && !outgoing.paused;
+    incoming.src = url;
+    incoming.loop = loop;
+    incoming.currentTime = 0;
+    incoming.volume = overlap ? 0 : 1;
+    active = incoming; // the UI follows the incoming element from here on
+    incoming.play().catch(() => {});
+    if (overlap) rampTo(incoming, outgoing, fadeSec);
+    else cancelFade();
+    syncPlayState();
+  }
+
+  // A freshly vended tape plays on its own and loops (not part of a playlist).
+  function loadCassette(song, shell) {
+    playlist = [];
+    playlistIndex = -1;
+    setNowPlaying(song, shell);
+    startTrack(song.url, { loop: true, fadeSec: PICK_FADE });
     syncCards();
   }
 
+  // Play the collection as a playlist from `index`; tracks crossfade into one
+  // another and wrap back to the start.
+  function playCollection(index, fadeSec = PICK_FADE) {
+    if (!songsList.length) return;
+    const n = songsList.length;
+    playlist = songsList;
+    playlistIndex = ((index % n) + n) % n;
+    centerIndex = playlistIndex;
+    setNowPlaying(
+      songsList[playlistIndex],
+      SHELL_COLORS[playlistIndex % SHELL_COLORS.length],
+    );
+    startTrack(songsList[playlistIndex].url, { loop: false, fadeSec });
+    layoutCarousel();
+  }
+
+  // Near the end of a playlist track, roll into the next one.
+  function maybeAdvance() {
+    if (playlistIndex < 0 || fadeTimer || !active.duration) return;
+    if (active.currentTime < 1) return; // ignore the very start of a track
+    if (active.duration - active.currentTime <= CROSSFADE) {
+      playCollection(playlistIndex + 1, CROSSFADE);
+    }
+  }
+
   // --- cassette collection: carousel + tape deck ------------------------------
 
   // shell gradients, cycled per card like the tape pile on the bench
@@ -155,7 +245,7 @@ export function initUI({
   const CF_FADE = [1, 0.9, 0.46, 0]; // opacity
 
   function layoutCarousel() {
-    const playing = !audio.paused;
+    const playing = !active.paused;
     cards.forEach((card, i) => {
       const offset = i - centerIndex;
       const d = Math.min(Math.abs(offset), 3);
@@ -184,9 +274,9 @@ export function initUI({
     centerIndex = Math.max(0, Math.min(cards.length - 1, index));
     const song = songsList[centerIndex];
     if (load && song && tapeKey(song.url) !== tapeKey(currentSong?.url)) {
-      loadCassette(song, SHELL_COLORS[centerIndex % SHELL_COLORS.length]);
+      playCollection(centerIndex); // start the playlist at this tape
     } else {
-      if (load && audio.paused) audio.play().catch(() => {});
+      if (load && active.paused) active.play().catch(() => {});
       layoutCarousel();
     }
   }
@@ -218,7 +308,7 @@ export function initUI({
       card.addEventListener("click", () => {
         if (i !== centerIndex) centerOn(i, { load: true });
         else if (tapeKey(currentSong?.url) === tapeKey(song.url)) togglePlay();
-        else loadCassette(song, shell);
+        else playCollection(i);
       });
       carousel.appendChild(card);
       return card;
@@ -268,7 +358,7 @@ export function initUI({
     `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
 
   function syncPlayState() {
-    const playing = !audio.paused;
+    const playing = !active.paused;
     playBtn.textContent = playing ? "❚❚" : "▶";
     pillToggle.textContent = playing ? "❚❚" : "▶";
     deckPlay.textContent = playing ? "❚❚" : "▶";
@@ -277,29 +367,46 @@ export function initUI({
     syncCards();
   }
 
-  audio.addEventListener("play", syncPlayState);
-  audio.addEventListener("pause", syncPlayState);
-  audio.addEventListener("timeupdate", () => {
-    if (audio.duration) {
-      const pct = `${(audio.currentTime / audio.duration) * 100}%`;
+  function updateProgress() {
+    if (active.duration) {
+      const pct = `${(active.currentTime / active.duration) * 100}%`;
       progressFill.style.width = pct;
       deckFill.style.width = pct;
     }
-    timeEl.textContent = fmt(audio.currentTime);
-    deckTime.textContent = fmt(audio.currentTime);
-  });
+    timeEl.textContent = fmt(active.currentTime);
+    deckTime.textContent = fmt(active.currentTime);
+  }
 
-  const togglePlay = () => (audio.paused ? audio.play() : audio.pause());
+  // both elements fire events; only react to the one the UI is tracking
+  for (const el of [audioA, audioB]) {
+    el.addEventListener("play", (e) => e.target === active && syncPlayState());
+    el.addEventListener("pause", (e) => e.target === active && syncPlayState());
+    el.addEventListener("timeupdate", (e) => {
+      if (e.target !== active) return;
+      updateProgress();
+      maybeAdvance();
+    });
+  }
+
+  function togglePlay() {
+    if (active.paused) {
+      active.play().catch(() => {});
+    } else {
+      cancelFade(); // a manual pause stops any in-flight crossfade too
+      audioA.pause();
+      audioB.pause();
+    }
+  }
   playBtn.addEventListener("click", togglePlay);
   pillToggle.addEventListener("click", togglePlay);
   deckPlay.addEventListener("click", () => {
-    if (audio.src) togglePlay();
+    if (active.src) togglePlay();
   });
 
   const seek = (bar) => (e) => {
-    if (!audio.duration) return;
+    if (!active.duration) return;
     const rect = bar.getBoundingClientRect();
-    audio.currentTime = ((e.clientX - rect.left) / rect.width) * audio.duration;
+    active.currentTime = ((e.clientX - rect.left) / rect.width) * active.duration;
   };
   progress.addEventListener("click", seek(progress));
   deckProgress.addEventListener("click", seek(deckProgress));
@@ -347,7 +454,7 @@ export function initUI({
     const modalHidden = modal.classList.contains("hidden");
     pill.classList.toggle(
       "hidden",
-      !(audio.src && modalHidden && !collectionOpen && !gameboyOpen),
+      !(active.src && modalHidden && !collectionOpen && !gameboyOpen),
     );
   }
 
@@ -362,7 +469,7 @@ export function initUI({
       modal.classList.add("opening");
       setStage(currentStage());
       syncPill();
-      if (!audio.src && !busy) setTimeout(() => input.focus(), 600);
+      if (!active.src && !busy) setTimeout(() => input.focus(), 600);
     },
     closeModal() {
       if (modal.classList.contains("hidden")) return;