@freqhole/playlistz 0.0.1

package/src/services/audioService.ts

@@ -0,0 +1,1395 @@
+// audio service with a functional approach
+// uses solidjs-style signals for reactive state management
+
+import { createSignal } from "solid-js";
+import type { Song, Playlist, AudioState } from "../types/playlist.js";
+import { loadAllPlaybackPositions, savePlaybackPosition, deletePlaybackPosition, saveLastPlayed, loadLastPlayed } from "./indexedDBService.js";
+import { getBlobObjectURL } from "@freqhole/api-client/storage";
+import { fetchSongBlob, prefetchUpcoming } from "./blobTransferService.js";
+import { getSongsForPlaylist } from "./playlistDocService.js";
+import { enrichSongsWithStandalonePaths } from "./standaloneService.js";
+import {
+  streamAudioWithCaching,
+  downloadSongIfNeeded,
+  isSongDownloading,
+} from "./streamingAudioService.js";
+
+// audio state signals
+const [currentSong, setCurrentSong] = createSignal<Song | null>(null);
+const [currentPlaylist, setCurrentPlaylist] = createSignal<Playlist | null>(
+  null
+);
+const [playlistQueue, setPlaylistQueue] = createSignal<Song[]>([]);
+const [isPlaying, setIsPlaying] = createSignal(false);
+const [currentTime, setCurrentTime] = createSignal(0);
+const [duration, setDuration] = createSignal(0);
+const [currentIndex, setCurrentIndex] = createSignal(-1);
+const [volume, setVolume] = createSignal(1.0);
+const [isLoading, setIsLoading] = createSignal(false);
+const [loadingSongIds, setLoadingSongIds] = createSignal<Set<string>>(
+  new Set()
+);
+const [selectedSongId, setSelectedSongId] = createSignal<string | null>(null);
+const [preloadingSongId, setPreloadingSongId] = createSignal<string | null>(
+  null
+);
+let hasTriggeredPreload = false;
+const [repeatMode, setRepeatMode] = createSignal<"none" | "one" | "all">(
+  "none"
+);
+const [isShuffled, setIsShuffled] = createSignal(false);
+
+// download progress tracking
+const [downloadProgress, setDownloadProgress] = createSignal<
+  Map<string, number>
+>(new Map());
+const [cachingSongIds, setCachingSongIds] = createSignal<Set<string>>(
+  new Set()
+);
+
+// per-song saved playback positions (songId -> seconds), persists across pause/track switch
+const [songPlaybackPositions, setSongPlaybackPositions] = createSignal<Map<string, number>>(new Map());
+
+// pending seek time to apply after loadedmetadata fires for the new song
+let pendingSeekTime = 0;
+
+// whether the current audio.src was created from an in-memory File object
+// (vs a blob store url). only file-based urls should be explicitly revoked;
+// blob store urls are backed by persistent opfs data and may be cached by
+// getBlobObjectURL - revoking them causes the cached handle to become stale,
+// resulting in WebKitBlobResource errors on replay.
+let currentAudioNeedsRevoke = false;
+
+// load all persisted positions from indexeddb into the in-memory signal
+let positionsLoaded = false;
+async function ensurePositionsLoaded(): Promise<void> {
+  if (positionsLoaded) return;
+  positionsLoaded = true;
+  const saved = await loadAllPlaybackPositions();
+  if (saved.size > 0) {
+    setSongPlaybackPositions(saved);
+  }
+}
+
+// load positions eagerly so song rows can show progress fills before playback starts
+ensurePositionsLoaded().catch(() => {});
+
+// persist current song position to indexeddb (fire-and-forget)
+function flushCurrentPosition(): void {
+  const song = currentSong();
+  const pos = audioElement?.currentTime ?? 0;
+  if (song && pos > 1) {
+    savePlaybackPosition(song.id, pos).catch(() => {});
+  }
+}
+
+// single audio element for the entire app
+let audioElement: HTMLAudioElement | null = null;
+
+// Initialize audio element
+function initializeAudio(): HTMLAudioElement {
+  if (audioElement) return audioElement;
+
+  audioElement = new Audio();
+  audioElement.volume = volume();
+  audioElement.preload = "metadata";
+
+  // load persisted positions from indexeddb on first use
+  ensurePositionsLoaded().catch(() => {});
+
+  // save current position when page is closed / refreshed
+  window.addEventListener("beforeunload", flushCurrentPosition);
+
+  // audio event listenerz
+  audioElement.addEventListener("loadstart", () => {
+    setIsLoading(true);
+  });
+  audioElement.addEventListener("canplay", () => {
+    setIsLoading(false);
+    // note: don't clear loadingSongIds here as it's handled in playSong
+  });
+  audioElement.addEventListener("loadedmetadata", () => {
+    const newDuration = audioElement?.duration || 0;
+    setDuration(newDuration);
+    setIsLoading(false);
+    // apply resume position if set
+    if (pendingSeekTime > 0 && audioElement) {
+      audioElement.currentTime = pendingSeekTime;
+      setCurrentTime(pendingSeekTime);
+      pendingSeekTime = 0;
+    }
+    // update media session now that we have proper metadata
+    updateMediaSession();
+  });
+
+  audioElement.addEventListener("timeupdate", () => {
+    const newCurrentTime = audioElement?.currentTime || 0;
+    setCurrentTime(newCurrentTime);
+
+    // save position for current song so it can be resumed later
+    const song = currentSong();
+    if (song && newCurrentTime > 0) {
+      setSongPlaybackPositions((prev) => {
+        const next = new Map(prev);
+        next.set(song.id, newCurrentTime);
+        return next;
+      });
+    }
+
+    // try to preload next song at halfway point
+    const duration = audioElement?.duration || 0;
+    if (
+      duration > 0 &&
+      newCurrentTime / duration >= 0.5 &&
+      !hasTriggeredPreload
+    ) {
+      hasTriggeredPreload = true;
+      preloadNextSong();
+    }
+  });
+
+  audioElement.addEventListener("play", () => {
+    setIsPlaying(true);
+    hasTriggeredPreload = false; // reset preload flag for new song
+    // only update media session if not in a loading state
+    if (!isLoading()) {
+      updateMediaSession();
+    }
+  });
+  audioElement.addEventListener("pause", () => {
+    setIsPlaying(false);
+    // persist position when pausing so it survives page reload
+    flushCurrentPosition();
+    updateMediaSession();
+  });
+  audioElement.addEventListener("ended", () => {
+    setIsPlaying(false);
+    // mark a complete listen by saving the full duration - the row keeps a
+    // full progress fill, and next play restarts from the beginning since
+    // positions >=95% are treated as complete
+    const song = currentSong();
+    const dur = audioElement?.duration ?? 0;
+    if (song && dur > 0) {
+      setSongPlaybackPositions((prev) => {
+        const next = new Map(prev);
+        next.set(song.id, dur);
+        return next;
+      });
+      savePlaybackPosition(song.id, dur).catch(() => {});
+    }
+    handleSongEnded();
+  });
+
+  audioElement.addEventListener("error", (e) => {
+    console.error("onoz! audio error:", e);
+    setIsPlaying(false);
+    setIsLoading(false);
+    // clear all loading songz on audio error
+    setLoadingSongIds(new Set<string>());
+    updatePageTitle();
+  });
+
+  audioElement.addEventListener("seeked", () => {
+    const playingPl = currentPlaylist();
+    const song = currentSong();
+    if (!playingPl || !song || !isPlaying()) return;
+    const elapsed = audioElement?.currentTime ?? 0;
+    const dur = audioElement?.duration ?? song.duration ?? 0;
+    const remaining = Math.max(0, dur - elapsed);
+    prefetchUpcoming(playingPl, song.id, remaining);
+  });
+
+  return audioElement;
+}
+
+function createAudioURL(file: File): string {
+  return URL.createObjectURL(file);
+}
+
+// trash old blob URL
+function releaseAudioURL(url: string): void {
+  URL.revokeObjectURL(url);
+}
+
+// update page title with currently playing song
+function updatePageTitle(): void {
+  const song = currentSong();
+
+  if (song) {
+    document.title = `${song.title} - ${song.artist || "unknown artist"} | P L A Y L I S T Z`;
+  } else {
+    document.title = "P L A Y L I S T Z";
+  }
+}
+
+// Media Session API stuff
+async function updateMediaSession(): Promise<void> {
+  if (!("mediaSession" in navigator)) return;
+
+  const song = currentSong();
+  const playlist = currentPlaylist();
+  const loading = isLoading();
+
+  if (song) {
+    const artwork = await getMediaSessionArtwork(song, playlist || undefined);
+
+    // clear metadata first, then set it; cuz iOS Safari
+    navigator.mediaSession.metadata = null;
+
+    navigator.mediaSession.metadata = new MediaMetadata({
+      title: loading ? `loading... ${song.title}` : song.title,
+      artist: song.artist || "unknown artist",
+      album: song.album || playlist?.title || "unknown album",
+      artwork,
+    });
+
+    // set playback state - show paused during loading to prevent timing issuez
+    // #TODO: is there a loading state to set here?!
+    navigator.mediaSession.playbackState = loading
+      ? "paused"
+      : isPlaying()
+        ? "playing"
+        : "paused";
+
+    // setup player control action handlerz
+    navigator.mediaSession.setActionHandler("play", () => {
+      togglePlayback();
+    });
+
+    navigator.mediaSession.setActionHandler("pause", () => {
+      togglePlayback();
+    });
+
+    navigator.mediaSession.setActionHandler("previoustrack", () => {
+      playPrevious();
+    });
+
+    navigator.mediaSession.setActionHandler("nexttrack", () => {
+      playNext();
+    });
+
+    navigator.mediaSession.setActionHandler("seekto", (details) => {
+      if (details.seekTime !== undefined && !loading) {
+        seek(details.seekTime);
+      }
+    });
+
+    // set position state only if we have valid duration and are not loading
+    const duration = audioState.duration();
+    const currentTime = audioState.currentTime();
+    if (duration > 0 && !loading) {
+      navigator.mediaSession.setPositionState({
+        duration,
+        playbackRate: 1,
+        position: currentTime,
+      });
+    } else if (loading) {
+      // clear position state during loading
+      try {
+        navigator.mediaSession.setPositionState({
+          duration: 0,
+          playbackRate: 1,
+          position: 0,
+        });
+      } catch {
+        // some browsers don't support clearing position state, ignore error
+      }
+    }
+  } else {
+    navigator.mediaSession.metadata = null;
+    navigator.mediaSession.playbackState = "none";
+  }
+
+  updatePageTitle();
+}
+
+// resize image if it's too large for ios safari mediasession
+async function resizeImageForMediaSession(
+  imageData: ArrayBuffer,
+  mimeType: string
+): Promise<ArrayBuffer> {
+  // if image is smaller than 500kb, use as-is
+  if (imageData.byteLength < 500000) {
+    return imageData;
+  }
+
+  return new Promise((resolve) => {
+    const blob = new Blob([imageData], { type: mimeType });
+    const img = new Image();
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+
+    img.onload = () => {
+      // resize to max 300x300 to keep file size reasonable
+      const maxSize = 300;
+      let { width, height } = img;
+
+      if (width > maxSize || height > maxSize) {
+        const ratio = Math.min(maxSize / width, maxSize / height);
+        width *= ratio;
+        height *= ratio;
+      }
+
+      canvas.width = width;
+      canvas.height = height;
+
+      if (ctx) {
+        ctx.drawImage(img, 0, 0, width, height);
+
+        canvas.toBlob(
+          (resizedBlob) => {
+            if (resizedBlob) {
+              resizedBlob.arrayBuffer().then(resolve);
+            } else {
+              resolve(imageData); // fallback to original
+            }
+          },
+          mimeType,
+          0.8
+        );
+      } else {
+        resolve(imageData); // fallback to original
+      }
+    };
+
+    img.onerror = () => {
+      resolve(imageData); // fallback to original
+    };
+
+    img.src = URL.createObjectURL(blob);
+  });
+}
+
+// get artwork for Media Session
+async function getMediaSessionArtwork(
+  song: Song,
+  playlist?: Playlist
+): Promise<MediaImage[]> {
+  const artwork: MediaImage[] = [];
+
+  // try song image first (prefer thumbnail for MediaSession)
+  const songImageData = song.thumbnailData || song.imageData;
+  if (songImageData && song.imageType) {
+    const resizedImageData = await resizeImageForMediaSession(
+      songImageData,
+      song.imageType
+    );
+    const blob = new Blob([resizedImageData], { type: song.imageType });
+    const url = URL.createObjectURL(blob);
+    // add multiple sizes for ios safari compatibility
+    artwork.push({
+      src: url,
+      sizes: "512x512",
+      type: song.imageType,
+    });
+    artwork.push({
+      src: url,
+      sizes: "256x256",
+      type: song.imageType,
+    });
+    artwork.push({
+      src: url,
+      sizes: "96x96",
+      type: song.imageType,
+    });
+  }
+  // fallback to playlist image (prefer thumbnail for mediasession)
+  else {
+    const playlistImageData = playlist?.thumbnailData || playlist?.imageData;
+    if (playlistImageData && playlist?.imageType) {
+      const resizedImageData = await resizeImageForMediaSession(
+        playlistImageData,
+        playlist.imageType
+      );
+      const blob = new Blob([resizedImageData], { type: playlist.imageType });
+      const url = URL.createObjectURL(blob);
+      // add multiple sizes for ios safari compatibility
+      artwork.push({
+        src: url,
+        sizes: "512x512",
+        type: playlist.imageType,
+      });
+      artwork.push({
+        src: url,
+        sizes: "256x256",
+        type: playlist.imageType,
+      });
+      artwork.push({
+        src: url,
+        sizes: "96x96",
+        type: playlist.imageType,
+      });
+    } else {
+      // oops, no artwork available!
+    }
+  }
+
+  return artwork;
+}
+
+// load playlist songz into queue
+async function loadPlaylistQueue(playlist: Playlist): Promise<void> {
+  try {
+    // songs come from the automerge doc; playlist.id is the docId
+    const playlistSongs = await getSongsForPlaylist(playlist.id);
+    setPlaylistQueue(enrichSongsWithStandalonePaths(playlistSongs));
+    setCurrentPlaylist(playlist);
+  } catch (error) {
+    console.error("error loading playlist queue:", error);
+    throw error;
+  }
+}
+
+// refresh playlist queue while maintaining current song position
+export async function refreshPlaylistQueue(playlist: Playlist): Promise<void> {
+  try {
+    const currentSong = audioState.currentSong();
+    await loadPlaylistQueue(playlist);
+
+    // update current index to match new position of currently playing song
+    if (currentSong) {
+      const queue = playlistQueue();
+      const newIndex = queue.findIndex((song) => song.id === currentSong.id);
+      setCurrentIndex(newIndex >= 0 ? newIndex : -1);
+    }
+  } catch (error) {
+    console.error("Error refreshing playlist queue:", error);
+    throw error;
+  }
+}
+
+// get the next song in queue
+function getNextSong(): Song | null {
+  const queue = playlistQueue();
+  const currentIdx = currentIndex();
+
+  if (queue.length === 0) return null;
+
+  // note: repeat mode is mostly unused
+  const repeat = repeatMode();
+
+  if (repeat === "one") {
+    // repeat current song
+    return currentIdx >= 0 ? queue[currentIdx] || null : null;
+  }
+
+  const nextIdx = currentIdx + 1;
+
+  if (nextIdx < queue.length) {
+    return queue[nextIdx] || null;
+  }
+
+  if (repeat === "all") {
+    // loop back to first song
+    return queue[0] || null;
+  }
+
+  // no repeat, end of queue
+  return null;
+}
+
+// bet the previous song in queue
+function getPreviousSong(): Song | null {
+  const queue = playlistQueue();
+  const currentIdx = currentIndex();
+
+  if (queue.length === 0 || currentIdx <= 0) return null;
+
+  return queue[currentIdx - 1] || null;
+}
+
+// skip to next playable song when current next song fails
+async function skipToNextPlayableSong(): Promise<void> {
+  const queue = playlistQueue();
+  const currentIdx = currentIndex();
+  const repeat = repeatMode();
+
+  // try each subsequent song until we find one that plays or reach the end
+  let testIndex = currentIdx + 1;
+  const maxAttempts = queue.length; // prevent infinite loops
+  let attempts = 0;
+
+  while (attempts < maxAttempts) {
+    // handle wrap-around for repeat all mode
+    if (testIndex >= queue.length) {
+      if (repeat === "all") {
+        testIndex = 0;
+      } else {
+        // end of queue, no repeat
+        setIsPlaying(false);
+        updateMediaSession();
+        return;
+      }
+    }
+
+    // don't retry the same song we just failed on
+    if (testIndex === currentIdx) {
+      setIsPlaying(false);
+      updateMediaSession();
+      return;
+    }
+
+    const testSong = queue[testIndex];
+    if (!testSong) {
+      testIndex++;
+      attempts++;
+      continue;
+    }
+
+    try {
+      setCurrentIndex(testIndex);
+      setSelectedSongId(testSong.id);
+      await playSong(testSong);
+      return; // success!
+    } catch (error) {
+      console.error(`onoz! failed to play song "${testSong.title}":`, error);
+      testIndex++;
+      attempts++;
+    }
+  }
+
+  // if we get here, all songs failed to load
+  console.error("oopz! all remaining songs failed to load, stopping playback");
+  setIsPlaying(false);
+  updateMediaSession();
+}
+
+// handle song ended - auto-advance logic
+async function handleSongEnded(): Promise<void> {
+  const nextSong = getNextSong();
+  if (nextSong) {
+    try {
+      await playNext();
+    } catch (error) {
+      console.error("error during auto-advance:", error);
+      // if playNext fails, try to skip to the song after that
+      await skipToNextPlayableSong();
+    }
+  } else {
+    // stay on last song but stop playing
+    setIsPlaying(false);
+    updateMediaSession();
+  }
+}
+
+// play a specific song
+export async function playSong(song: Song, skipResume = false): Promise<void> {
+  const audio = initializeAudio();
+
+  try {
+    // ensure persisted positions are loaded before checking resume state
+    await ensurePositionsLoaded();
+
+    // save the outgoing song's position before switching tracks
+    flushCurrentPosition();
+
+    // set this as the selected song immediately
+    setSelectedSongId(song.id);
+
+    // add this song to loading set
+    setLoadingSongIds((prev) => new Set(Array.from(prev).concat([song.id])));
+
+    // clear preloading state if this song was being preloaded
+    if (preloadingSongId() === song.id) {
+      setPreloadingSongId(null);
+    }
+
+    // only revoke file-backed blob urls (created from File objects). blob
+    // store urls (getBlobObjectURL) are backed by persistent opfs data and
+    // may be cached internally - revoking them causes the cache to return
+    // the same now-invalid url on replay (WebKitBlobResource error 1).
+    if (currentAudioNeedsRevoke && audio.src && audio.src.startsWith("blob:")) {
+      releaseAudioURL(audio.src);
+    }
+
+    // reset time/duration immediately to prevent stale values
+    setCurrentTime(0);
+    setDuration(0);
+    audio.currentTime = 0;
+
+    // check for a saved position to resume from.
+    // if the saved position is <95% of the song's known duration, resume from there.
+    // otherwise (near end or unknown duration) start from the beginning.
+    // skipResume=true when auto-advancing (song ended naturally) - always start fresh.
+    const savedPos = skipResume ? 0 : (songPlaybackPositions().get(song.id) ?? 0);
+    const knownDuration = song.duration ?? 0;
+    if (savedPos > 0 && (knownDuration === 0 || savedPos < knownDuration * 0.95)) {
+      pendingSeekTime = savedPos;
+    } else {
+      pendingSeekTime = 0;
+      // if near the end, clear the stale saved position so it restarts cleanly
+      if (savedPos > 0) {
+        setSongPlaybackPositions((prev) => {
+          const next = new Map(prev);
+          next.delete(song.id);
+          return next;
+        });
+      }
+    }
+
+    setIsLoading(true);
+    setCurrentSong(song);
+
+    // update media session immediately with new song info (fixes iOS lock screen image issue)
+    await updateMediaSession();
+
+    // clear media session position state during loading to prevent timing issues
+    if ("mediaSession" in navigator) {
+      navigator.mediaSession.playbackState = "paused";
+      // clear position state to stop time updates from old song
+      try {
+        navigator.mediaSession.setPositionState({
+          duration: 0,
+          playbackRate: 1,
+          position: 0,
+        });
+      } catch {
+        // some browsers don't support clearing position state, ignore error
+      }
+    }
+
+    // check playlist context and load queue if needed
+    const queue = playlistQueue();
+
+    // try to find song in current queue first
+    const queueIndex = queue.findIndex((queueSong) => queueSong.id === song.id);
+    if (queueIndex >= 0) {
+      // song is in current queue, use it
+      setCurrentIndex(queueIndex);
+      // save last played for this playlist so we can resume on reload
+      const pl = currentPlaylist();
+      if (pl) {
+        saveLastPlayed(pl.id, song.id);
+      }
+    } else {
+      // song not in current queue, clear playlist context for single song play
+      setCurrentPlaylist(null);
+      setPlaylistQueue([]);
+      setCurrentIndex(-1);
+    }
+
+    // try to get audio url in order of preference:
+    // 1. existing bloburl from song
+    // 2. create from file if available
+    // 3. load from indexeddb on-demand
+    let audioURL = song.blobUrl;
+    // track whether the resolved url was created from an in-memory File
+    // (needs explicit revocation) vs from the blob store (should not be revoked)
+    let audioUrlIsFileBacked = false;
+    if (!audioURL && song.file) {
+      audioURL = createAudioURL(song.file);
+      audioUrlIsFileBacked = true;
+    }
+
+    if (!audioURL) {
+      // check for standalone file path when using file:// protocol
+      if (window.location.protocol === "file:" && song.standaloneFilePath) {
+        const filePath = song.standaloneFilePath;
+        audioURL = new URL(filePath, window.location.href).href;
+
+        // test if the file is accessible
+        const testAudio = document.createElement("audio");
+        testAudio.src = audioURL;
+        testAudio.addEventListener("error", (e) => {
+          console.error("audio file test failed:", e);
+          console.error("audio error:", testAudio.error);
+        });
+        testAudio.load();
+      } else {
+        // try to load audio from the blob store (sha256-keyed opfs)
+        let cachedURL: string | null = null;
+        const sha = song.sha ?? song.sha256;
+        if (sha) {
+          cachedURL = await getBlobObjectURL(sha);
+        }
+        if (!cachedURL && sha && song.playlistId && !song.standaloneFilePath) {
+          // blob not local - try fetching from the playlist's p2p peers
+          setCachingSongIds(
+            (prev) => new Set(Array.from(prev).concat([song.id]))
+          );
+          try {
+            const fetched = await fetchSongBlob(song, (p) => {
+              setDownloadProgress((prev) => {
+                const newMap = new Map(prev);
+                newMap.set(song.id, Math.round(p.fraction * 100));
+                return newMap;
+              });
+            });
+            if (fetched) {
+              cachedURL = await getBlobObjectURL(sha);
+            }
+          } catch (err) {
+            console.warn("p2p audio fetch failed:", err);
+          } finally {
+            setDownloadProgress((prev) => {
+              const newMap = new Map(prev);
+              newMap.delete(song.id);
+              return newMap;
+            });
+            setCachingSongIds((prev) => {
+              const newSet = new Set(prev);
+              newSet.delete(song.id);
+              return newSet;
+            });
+          }
+        }
+        if (cachedURL) {
+          audioURL = cachedURL;
+        } else if (song.standaloneFilePath) {
+          const filePath = song.standaloneFilePath;
+
+          // for file:// protocol, use direct path (no caching needed - it's local)
+          if (window.location.protocol === "file:") {
+            audioURL = new URL(filePath, window.location.href).href;
+          } else {
+            // for http/https, use streaming approach for immediate playback
+            try {
+              const { blobUrl, downloadPromise } = await streamAudioWithCaching(
+                song,
+                filePath,
+                (progress) => {
+                  // update progress tracking
+                  setDownloadProgress((prev) => {
+                    const newMap = new Map(prev);
+                    newMap.set(song.id, progress.percentage);
+                    return newMap;
+                  });
+                }
+              );
+
+              // track that this song is being cached
+              setCachingSongIds(
+                (prev) => new Set(Array.from(prev).concat([song.id]))
+              );
+
+              audioURL = blobUrl;
+              audioUrlIsFileBacked = true; // blobUrl from streamAudioWithCaching is a temp object url
+
+              // handle caching completion in background
+              downloadPromise
+                .then((success) => {
+                  if (success) {
+                    console.debug(`successfully cached ${song.title}`);
+                  } else {
+                    console.warn(`failed to cache ${song.title}`);
+                  }
+                })
+                .catch((error) => {
+                  console.error(`error caching ${song.title}:`, error);
+                })
+                .finally(() => {
+                  // clean up progress tracking
+                  setDownloadProgress((prev) => {
+                    const newMap = new Map(prev);
+                    newMap.delete(song.id);
+                    return newMap;
+                  });
+                  setCachingSongIds((prev) => {
+                    const newSet = new Set(prev);
+                    newSet.delete(song.id);
+                    return newSet;
+                  });
+                });
+            } catch (streamError) {
+              console.error(
+                "streaming approach failed, using direct url:",
+                streamError
+              );
+              // for http/https, fall back to direct url streaming
+              audioURL = filePath;
+
+              // start background caching separately
+              setCachingSongIds(
+                (prev) => new Set(Array.from(prev).concat([song.id]))
+              );
+              downloadSongIfNeeded(song, filePath, (progress) => {
+                setDownloadProgress((prev) => {
+                  const newMap = new Map(prev);
+                  newMap.set(song.id, progress.percentage);
+                  return newMap;
+                });
+              }).finally(() => {
+                // clean up progress tracking
+                setDownloadProgress((prev) => {
+                  const newMap = new Map(prev);
+                  newMap.delete(song.id);
+                  return newMap;
+                });
+                setCachingSongIds((prev) => {
+                  const newSet = new Set(prev);
+                  newSet.delete(song.id);
+                  return newSet;
+                });
+              });
+            }
+          }
+        }
+      }
+    }
+
+    if (!audioURL) {
+      throw new Error(
+        `no audio source available for song: ${song.title}. check that audio files are accessible.`
+      );
+    }
+
+    // only continue if this song is still the selected one
+    if (selectedSongId() !== song.id) {
+      // song is loaded but user has moved on to a different song
+      setLoadingSongIds((prev) => {
+        const newSet = new Set(prev);
+        newSet.delete(song.id);
+        return newSet;
+      });
+      return;
+    }
+
+    // update the revoke flag before switching src
+    currentAudioNeedsRevoke = audioUrlIsFileBacked;
+    audio.src = audioURL;
+
+    // add error event listener to catch loading issues
+    audio.addEventListener(
+      "error",
+      (e) => {
+        console.error("audio loading error:", e);
+        console.error("audio error details:", audio.error);
+      },
+      { once: true }
+    );
+
+    await audio.play();
+
+    // remove song from loading set since it's now playing
+    setLoadingSongIds((prev) => {
+      const newSet = new Set(prev);
+      newSet.delete(song.id);
+      return newSet;
+    });
+
+    // prefetch upcoming songs from p2p peers (~30 min rolling window from now)
+    const playingPl = currentPlaylist();
+    if (playingPl) {
+      const elapsed = audioElement?.currentTime ?? 0;
+      const dur = audioElement?.duration ?? song.duration ?? 0;
+      const remaining = Math.max(0, dur - elapsed);
+      prefetchUpcoming(playingPl, song.id, remaining);
+    }
+
+    // media session will be updated by loadedmetadata event
+  } catch (error) {
+    console.error("error playing song:", error);
+    setIsLoading(false);
+    setLoadingSongIds((prev) => {
+      const newSet = new Set(prev);
+      newSet.delete(song.id);
+      return newSet;
+    });
+    updatePageTitle();
+    throw error;
+  }
+}
+
+// play a song with playlist context (loads queue if needed)
+export async function playSongFromPlaylist(
+  song: Song,
+  playlist: Playlist
+): Promise<void> {
+  // only reload queue if it's a different playlist or queue is empty
+  const currentPl = currentPlaylist();
+  if (
+    !currentPl ||
+    currentPl.id !== playlist.id ||
+    playlistQueue().length === 0
+  ) {
+    await loadPlaylistQueue(playlist);
+  }
+
+  // find song in queue and play it
+  const queue = playlistQueue();
+  const index = queue.findIndex((queueSong) => queueSong.id === song.id);
+  if (index >= 0) {
+    setCurrentIndex(index);
+  }
+
+  await playSong(song);
+}
+
+// play entire playlist starting from specific index
+export async function playPlaylist(
+  playlist: Playlist,
+  startIndex = 0
+): Promise<void> {
+  await loadPlaylistQueue(playlist);
+
+  const queue = playlistQueue();
+  if (!queue.length) return;
+
+  // ensure persisted positions are loaded before checking resume state
+  await ensurePositionsLoaded();
+
+  // check if there's a last-played song to resume from
+  const lastSongId = await loadLastPlayed(playlist.id);
+  if (lastSongId) {
+    const lastIdx = queue.findIndex((s) => s.id === lastSongId);
+    if (lastIdx >= 0) {
+      const lastSong = queue[lastIdx]!;
+      const savedPos = songPlaybackPositions().get(lastSongId) ?? 0;
+      const knownDuration = lastSong.duration ?? 0;
+      const nearEnd = knownDuration > 0 && savedPos >= knownDuration * 0.95;
+
+      if (!nearEnd) {
+        // resume this song at its saved position (pendingSeekTime handles the seek)
+        await tryPlaySongFromIndex(lastIdx);
+        return;
+      } else {
+        // song was near end - advance to next, or wrap to start if last song
+        const nextIdx = lastIdx + 1 < queue.length ? lastIdx + 1 : 0;
+        await tryPlaySongFromIndex(nextIdx);
+        return;
+      }
+    }
+  }
+
+  // no last-played data - start from requested index
+  if (startIndex >= queue.length || startIndex < 0) return;
+  await tryPlaySongFromIndex(startIndex);
+}
+
+// try to play song at index, falling back to skipToNextPlayableSong if it fails
+async function tryPlaySongFromIndex(startIndex: number): Promise<void> {
+  const queue = playlistQueue();
+  const song = queue[startIndex];
+  if (!song) return;
+
+  try {
+    setCurrentIndex(startIndex);
+    setSelectedSongId(song.id);
+    await playSong(song);
+  } catch (error) {
+    console.error(`failed to play song "${song.title}":`, error);
+    // use existing skip logic
+    await skipToNextPlayableSong();
+  }
+}
+
+// play next song in playlist
+export async function playNext(): Promise<void> {
+  const queue = playlistQueue();
+  const currentIdx = currentIndex();
+
+  if (queue.length === 0) {
+    return;
+  }
+
+  const repeat = repeatMode();
+  let nextIndex: number;
+
+  if (repeat === "one") {
+    // repeat current song
+    nextIndex = currentIdx;
+  } else if (currentIdx + 1 < queue.length) {
+    // normal next song
+    nextIndex = currentIdx + 1;
+  } else if (repeat === "all") {
+    // loop back to first song
+    nextIndex = 0;
+  } else {
+    // end of queue, no repeat
+    return;
+  }
+
+  const nextSong = queue[nextIndex];
+  if (nextSong) {
+    setCurrentIndex(nextIndex);
+    setSelectedSongId(nextSong.id);
+    try {
+      // auto-advance always starts from beginning, never resumes saved position
+      await playSong(nextSong, true);
+    } catch (error) {
+      console.error("error playing next song:", error);
+      throw error; // re-throw for handleSongEnded to catch
+    }
+  }
+}
+
+// play previous song in playlist
+export async function playPrevious(): Promise<void> {
+  const queue = playlistQueue();
+  const currentIdx = currentIndex();
+
+  if (queue.length === 0 || currentIdx <= 0) {
+    return;
+  }
+
+  const prevIndex = currentIdx - 1;
+  const prevSong = queue[prevIndex];
+
+  if (prevSong) {
+    setCurrentIndex(prevIndex);
+    setSelectedSongId(prevSong.id);
+    await playSong(prevSong);
+  }
+}
+
+// toggle play/pause
+export async function togglePlayback(): Promise<void> {
+  const audio = audioElement;
+  if (!audio) {
+    return;
+  }
+
+  try {
+    const currentlyPlaying = isPlaying();
+
+    if (currentlyPlaying) {
+      audio.pause();
+    } else {
+      await audio.play();
+    }
+  } catch (error) {
+    console.error("onoz! error toggling playback:", error);
+  }
+}
+
+// pause playback
+export function pause(): void {
+  const audio = audioElement;
+  if (audio && !audio.paused) {
+    audio.pause();
+  }
+}
+
+// stop playback and reset
+export function stop(): void {
+  const audio = audioElement;
+  if (audio) {
+    audio.pause();
+    audio.currentTime = 0;
+    if (audio.src && audio.src.startsWith("blob:")) {
+      releaseAudioURL(audio.src);
+    }
+    audio.src = "";
+  }
+
+  setCurrentSong(null);
+  setCurrentPlaylist(null);
+  setIsPlaying(false);
+  setCurrentTime(0);
+  setDuration(0);
+  setCurrentIndex(0);
+  updatePageTitle();
+}
+
+// seek and destroy!
+export function seek(time: number): void {
+  const audio = audioElement;
+  if (audio && !isNaN(audio.duration)) {
+    const clamped = Math.max(0, Math.min(time, audio.duration));
+    audio.currentTime = clamped;
+    // keep saved position in sync with manual seek
+    const song = currentSong();
+    if (song) {
+      setSongPlaybackPositions((prev) => {
+        const next = new Map(prev);
+        if (clamped < 1) {
+          next.delete(song.id); // seeking to start clears saved position
+          deletePlaybackPosition(song.id).catch(() => {});
+        } else {
+          next.set(song.id, clamped);
+          savePlaybackPosition(song.id, clamped).catch(() => {});
+        }
+        return next;
+      });
+    }
+  }
+}
+
+// set volume (0 to 1)
+export function setAudioVolume(newVolume: number): void {
+  const clampedVolume = Math.max(0, Math.min(1, newVolume));
+  setVolume(clampedVolume);
+
+  const audio = audioElement;
+  if (audio) {
+    audio.volume = clampedVolume;
+  }
+}
+
+// set repeat mode
+export function setRepeatModeValue(mode: "none" | "one" | "all"): void {
+  setRepeatMode(mode);
+}
+
+// toggle repeat mode
+export function toggleRepeatMode(): "none" | "one" | "all" {
+  const current = repeatMode();
+  const modes: ("none" | "one" | "all")[] = ["none", "one", "all"];
+  const nextIndex = (modes.indexOf(current) + 1) % modes.length;
+  const nextMode = modes[nextIndex] as "none" | "one" | "all";
+  setRepeatModeValue(nextMode);
+  return nextMode;
+}
+
+// get queue info
+export function getQueueInfo() {
+  const queue = playlistQueue();
+  const currentIdx = currentIndex();
+
+  return {
+    length: queue.length,
+    currentIndex: currentIdx,
+    hasNext: getNextSong() !== null,
+    hasPrevious: getPreviousSong() !== null,
+    currentSong: currentIdx >= 0 ? queue[currentIdx] : null,
+    nextSong: getNextSong(),
+    previousSong: getPreviousSong(),
+  };
+}
+
+// jump to specific song in queue
+// #TODO: deal with duplicate fns :/
+export async function playQueueIndex(index: number): Promise<void> {
+  const queue = playlistQueue();
+
+  if (index < 0 || index >= queue.length) {
+    return;
+  }
+
+  const song = queue[index];
+  if (song) {
+    setCurrentIndex(index);
+    await playSong(song);
+  }
+}
+
+// get current audio state
+export function getAudioState(): AudioState {
+  return {
+    currentSong: currentSong(),
+    currentPlaylist: currentPlaylist(),
+    isPlaying: isPlaying(),
+    currentTime: currentTime(),
+    duration: duration(),
+    volume: volume(),
+    currentIndex: currentIndex(),
+    queue: playlistQueue(),
+    repeatMode: repeatMode(),
+    isShuffled: isShuffled(),
+    isLoading: isLoading(),
+  };
+}
+
+// format time for display
+export function formatTime(seconds: number): string {
+  if (isNaN(seconds) || seconds < 0 || !isFinite(seconds)) return "0:00";
+
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, "0")}`;
+}
+
+// export state getters for components to use
+export const audioState = {
+  currentSong,
+  currentPlaylist,
+  playlistQueue,
+  isPlaying,
+  currentTime,
+  duration,
+  currentIndex,
+  volume,
+  isLoading,
+  loadingSongIds,
+  selectedSongId,
+  preloadingSongId,
+  repeatMode,
+  isShuffled,
+  downloadProgress,
+  cachingSongIds,
+  songPlaybackPositions,
+};
+
+// cleanup function
+export function cleanup(): void {
+  stop();
+
+  const audio = audioElement;
+  if (audio) {
+    // remove all event listeners
+    audio.removeEventListener("loadstart", () => {});
+    audio.removeEventListener("canplay", () => {});
+    audio.removeEventListener("loadedmetadata", () => {});
+    audio.removeEventListener("timeupdate", () => {});
+    audio.removeEventListener("play", () => {});
+    audio.removeEventListener("pause", () => {});
+    audio.removeEventListener("ended", () => {});
+    audio.removeEventListener("error", () => {});
+  }
+
+  audioElement = null;
+
+  // clear queue state
+  setPlaylistQueue([]);
+  setCurrentIndex(-1);
+  setRepeatMode("none");
+  setIsShuffled(false);
+}
+
+// helper to preload next song in background
+async function preloadNextSong(): Promise<void> {
+  const queue = playlistQueue();
+  const currentIdx = currentIndex();
+
+  if (queue.length === 0 || currentIdx < 0) return;
+
+  const nextIndex = currentIdx + 1;
+  if (nextIndex >= queue.length) return; // no next song
+
+  const nextSong = queue[nextIndex];
+  if (!nextSong) return;
+
+  // don't preload if already loading or preloaded
+  if (loadingSongIds().has(nextSong.id) || preloadingSongId() === nextSong.id) {
+    return;
+  }
+
+  setPreloadingSongId(nextSong.id);
+  setLoadingSongIds((prev) => new Set(Array.from(prev).concat([nextSong.id])));
+
+  try {
+    // check if song already has audio cached in the blob store
+    const blobUrl = (nextSong.sha ?? nextSong.sha256)
+      ? await getBlobObjectURL((nextSong.sha ?? nextSong.sha256)!)
+      : null;
+    if (blobUrl) {
+      setLoadingSongIds((prev) => {
+        const newSet = new Set(prev);
+        newSet.delete(nextSong.id);
+        return newSet;
+      });
+      setPreloadingSongId(null);
+      return;
+    }
+
+    // check if song is already being downloaded
+    if (isSongDownloading(nextSong.id)) {
+      setLoadingSongIds((prev) => {
+        const newSet = new Set(prev);
+        newSet.delete(nextSong.id);
+        return newSet;
+      });
+      setPreloadingSongId(null);
+      return;
+    }
+
+    if (nextSong.standaloneFilePath) {
+      // track that this song is being cached for preloading
+      setCachingSongIds(
+        (prev) => new Set(Array.from(prev).concat([nextSong.id]))
+      );
+
+      // start preload download
+      downloadSongIfNeeded(
+        nextSong,
+        nextSong.standaloneFilePath,
+        (progress) => {
+          // update preload progress tracking
+          setDownloadProgress((prev) => {
+            const newMap = new Map(prev);
+            newMap.set(nextSong.id, progress.percentage);
+            return newMap;
+          });
+        }
+      )
+        .then((success) => {
+          if (success) {
+            console.debug(`successfully preloaded ${nextSong.title}`);
+          } else {
+            console.warn(`failed to preload ${nextSong.title}`);
+          }
+        })
+        .catch((error) => {
+          console.error(`error preloading ${nextSong.title}:`, error);
+        })
+        .finally(() => {
+          // clean up preload progress tracking
+          setDownloadProgress((prev) => {
+            const newMap = new Map(prev);
+            newMap.delete(nextSong.id);
+            return newMap;
+          });
+          setCachingSongIds((prev) => {
+            const newSet = new Set(prev);
+            newSet.delete(nextSong.id);
+            return newSet;
+          });
+        });
+    }
+  } catch {
+    // ignore errors when clearing cache
+  } finally {
+    // always clean up loading state for preloading
+    setLoadingSongIds((prev) => {
+      const newSet = new Set(prev);
+      newSet.delete(nextSong.id);
+      return newSet;
+    });
+    setPreloadingSongId(null);
+  }
+}
+
+// helper to select a song to play (sets immediate ui feedback)
+export function selectSong(songId: string): void {
+  // pause current audio immediately
+  const audio = audioElement;
+  if (audio) {
+    audio.pause();
+    setIsPlaying(false);
+  }
+
+  // set this as the selected song
+  setSelectedSongId(songId);
+}
+
+// clear the selected song
+export function clearSelectedSong(): void {
+  setSelectedSongId(null);
+}
+
+// helper functions for streaming downloadz
+export function getSongDownloadProgress(songId: string): number {
+  return downloadProgress().get(songId) || 0;
+}
+
+export function isSongCaching(songId: string): boolean {
+  return cachingSongIds().has(songId);
+}
+
+// --- dev hook points (implementations registered in src/dev-hooks.ts) ---
+
+// seek the current audio element to a specific time in seconds.
+export function _devSeekTo(seconds: number): void {
+  if (audioElement) audioElement.currentTime = seconds;
+}
+
+// fire the "ended" event on the audio element as if the track finished.
+export function _devTriggerTrackEnd(): void {
+  audioElement?.dispatchEvent(new Event("ended"));
+}
+
+// fire an "error" event on the audio element. code defaults to
+// MEDIA_ERR_SRC_NOT_SUPPORTED (4).
+export function _devTriggerAudioError(code = 4): void {
+  if (!audioElement) return;
+  const err = { code, message: "test-injected error" };
+  Object.defineProperty(audioElement, "error", {
+    get: () => err,
+    configurable: true,
+  });
+  audioElement.dispatchEvent(new Event("error"));
+  Object.defineProperty(audioElement, "error", {
+    get: undefined,
+    configurable: true,
+  });
+}