@yetric/audioplayer 0.0.0-stage → 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1287 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  attachAudioPlayerMediaSession: () => attachAudioPlayerMediaSession,
+  attachAudioPlayerPersistence: () => attachAudioPlayerPersistence,
+  attachAudioPlayerProgressReporter: () => attachAudioPlayerProgressReporter,
+  createAudioPlayer: () => createAudioPlayer,
+  createLocalStoragePersistenceAdapter: () => createLocalStoragePersistenceAdapter
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_PREVIOUS_RESTART_THRESHOLD_SECONDS = 5;
+var DEFAULT_PERSISTENCE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+var DEFAULT_PERSISTENCE_SAVE_INTERVAL_MS = 5e3;
+var DEFAULT_PROGRESS_REPORT_INTERVAL_MS = 5e3;
+var DEFAULT_MEDIA_SESSION_ARTWORK_SIZES = [96, 128, 192, 256, 384, 512];
+var DEFAULT_MEDIA_SESSION_SEEK_OFFSET_SECONDS = 10;
+var createInitialState = (options) => ({
+  status: "idle",
+  currentSource: null,
+  currentSourceId: null,
+  currentTime: 0,
+  duration: 0,
+  buffered: 0,
+  progress: {
+    currentTime: 0,
+    duration: 0,
+    buffered: 0,
+    playedFraction: 0,
+    bufferedFraction: 0
+  },
+  rate: options.initialRate ?? 1,
+  volume: options.initialVolume ?? 1,
+  muted: options.initialMuted ?? false,
+  queue: {
+    items: [],
+    itemIds: [],
+    position: {
+      currentIndex: -1,
+      currentSourceId: null,
+      length: 0,
+      repeatMode: options.initialRepeatMode ?? "off",
+      hasNext: false,
+      hasPrevious: false
+    }
+  },
+  error: null
+});
+var createPlayerError = (code, message, cause) => ({
+  code,
+  message,
+  cause
+});
+var isRuntimePlayerError = (value) => !!value && typeof value === "object" && "code" in value && "message" in value;
+var normalizePlayerError = (fallbackCode, fallbackMessage, cause) => isRuntimePlayerError(cause) ? cause : createPlayerError(fallbackCode, fallbackMessage, cause);
+var assertStableSource = (source) => {
+  if (!source.id || !source.src) {
+    throw createPlayerError(
+      "INVALID_QUEUE_ITEM",
+      "AudioSource requires stable id and src."
+    );
+  }
+};
+var isFiniteNumber = (value) => Number.isFinite(value) && !Number.isNaN(value);
+var safeDuration = (audio, hint) => {
+  const duration = audio?.duration;
+  return duration !== void 0 && isFiniteNumber(duration) ? duration : hint ?? 0;
+};
+var safeBuffered = (audio) => {
+  if (!audio || audio.buffered.length === 0) {
+    return 0;
+  }
+  try {
+    return audio.buffered.end(audio.buffered.length - 1);
+  } catch {
+    return 0;
+  }
+};
+var cloneQueueState = (state) => ({
+  items: [...state.queue.items],
+  itemIds: [...state.queue.itemIds],
+  position: {
+    ...state.queue.position
+  }
+});
+var updateQueueFlags = (state) => {
+  const { items, position } = state.queue;
+  const { currentIndex, repeatMode } = position;
+  const lastIndex = items.length - 1;
+  const hasItems = items.length > 0;
+  const hasNext = !hasItems || currentIndex < 0 ? false : repeatMode === "all" ? items.length > 0 : currentIndex < lastIndex;
+  const hasPrevious = !hasItems || currentIndex < 0 ? false : repeatMode === "all" ? items.length > 0 : currentIndex > 0;
+  return {
+    ...state,
+    queue: {
+      ...state.queue,
+      itemIds: items.map((item) => item.id),
+      position: {
+        ...position,
+        currentSourceId: state.currentSource?.id ?? null,
+        length: items.length,
+        hasNext,
+        hasPrevious
+      }
+    }
+  };
+};
+var createAudioElement = () => {
+  if (typeof Audio === "undefined") {
+    return null;
+  }
+  return new Audio();
+};
+var createUnavailableAudioEngine = () => {
+  const unavailableError = () => createPlayerError(
+    "UNSUPPORTED_ENVIRONMENT",
+    "HTMLAudioElement is not available in this environment."
+  );
+  return {
+    available: false,
+    getSnapshot(durationHint) {
+      return {
+        currentTime: 0,
+        duration: durationHint ?? 0,
+        buffered: 0,
+        rate: 1,
+        volume: 1,
+        muted: false
+      };
+    },
+    getRuntimeError() {
+      return unavailableError();
+    },
+    on() {
+      return () => {
+      };
+    },
+    setSource() {
+      throw unavailableError();
+    },
+    clearSource() {
+      throw unavailableError();
+    },
+    load() {
+      throw unavailableError();
+    },
+    play() {
+      throw unavailableError();
+    },
+    pause() {
+      throw unavailableError();
+    },
+    setCurrentTime() {
+      throw unavailableError();
+    },
+    setPlaybackRate() {
+      throw unavailableError();
+    },
+    setVolume() {
+      throw unavailableError();
+    },
+    setMuted() {
+      throw unavailableError();
+    },
+    destroy() {
+    }
+  };
+};
+var createHtmlAudioEngine = () => {
+  const audio = createAudioElement();
+  if (!audio) {
+    return createUnavailableAudioEngine();
+  }
+  audio.preload = "metadata";
+  const clearSource = () => {
+    const element = audio;
+    if (typeof element.removeAttribute === "function") {
+      element.removeAttribute("src");
+      return;
+    }
+    audio.src = "";
+  };
+  return {
+    available: true,
+    getSnapshot(durationHint) {
+      return {
+        currentTime: audio.currentTime,
+        duration: safeDuration(audio, durationHint),
+        buffered: safeBuffered(audio),
+        rate: audio.playbackRate,
+        volume: audio.volume,
+        muted: audio.muted
+      };
+    },
+    getRuntimeError() {
+      return audio.error;
+    },
+    on(eventName, listener) {
+      audio.addEventListener(eventName, listener);
+      return () => {
+        audio.removeEventListener(eventName, listener);
+      };
+    },
+    setSource(src) {
+      audio.src = src;
+    },
+    clearSource() {
+      clearSource();
+    },
+    load() {
+      audio.load();
+    },
+    play() {
+      return audio.play();
+    },
+    pause() {
+      audio.pause();
+    },
+    setCurrentTime(time) {
+      audio.currentTime = time;
+    },
+    setPlaybackRate(rate) {
+      audio.playbackRate = rate;
+    },
+    setVolume(volume) {
+      audio.volume = volume;
+    },
+    setMuted(muted) {
+      audio.muted = muted;
+    },
+    destroy() {
+      audio.pause();
+      clearSource();
+      audio.load();
+    }
+  };
+};
+var isBrowserStorageAvailable = () => typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+var isPersistedPlayerState = (value) => {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return candidate.version === 1 && typeof candidate.savedAt === "number" && "currentSource" in candidate && typeof candidate.currentTime === "number" && typeof candidate.rate === "number" && typeof candidate.volume === "number" && typeof candidate.muted === "boolean" && !!candidate.queue && Array.isArray(candidate.queue.items) && !!candidate.queue.position;
+};
+var toPersistedPlayerState = (state) => ({
+  version: 1,
+  savedAt: Date.now(),
+  currentSource: state.currentSource,
+  currentSourceId: state.currentSourceId,
+  currentTime: state.currentTime,
+  rate: state.rate,
+  volume: state.volume,
+  muted: state.muted,
+  queue: {
+    items: [...state.queue.items],
+    position: {
+      currentIndex: state.queue.position.currentIndex,
+      currentSourceId: state.queue.position.currentSourceId,
+      repeatMode: state.queue.position.repeatMode
+    }
+  }
+});
+var toProgressSnapshot = (state) => ({
+  source: state.currentSource,
+  sourceId: state.currentSourceId,
+  currentTime: state.currentTime,
+  duration: state.duration,
+  playedFraction: state.progress.playedFraction,
+  status: state.status,
+  queue: {
+    ...state.queue.position
+  }
+});
+var hasMediaSession = () => typeof navigator !== "undefined" && "mediaSession" in navigator;
+var createMediaSessionArtwork = (source, sizes) => {
+  if (!source?.artwork) {
+    return [];
+  }
+  return sizes.map((size) => ({
+    src: source.artwork,
+    sizes: `${size}x${size}`
+  }));
+};
+var createLocalStoragePersistenceAdapter = (key) => ({
+  load() {
+    if (!isBrowserStorageAvailable()) {
+      return null;
+    }
+    try {
+      const raw = window.localStorage.getItem(key);
+      if (!raw) {
+        return null;
+      }
+      const parsed = JSON.parse(raw);
+      return isPersistedPlayerState(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  },
+  save(state) {
+    if (!isBrowserStorageAvailable()) {
+      return;
+    }
+    window.localStorage.setItem(key, JSON.stringify(state));
+  },
+  clear() {
+    if (!isBrowserStorageAvailable()) {
+      return;
+    }
+    window.localStorage.removeItem(key);
+  }
+});
+var createAudioPlayer = (options = {}) => {
+  let state = updateQueueFlags(createInitialState(options));
+  let destroyed = false;
+  let shouldAutoplayAfterLoad = false;
+  let suppressPauseEvent = false;
+  const engine = createHtmlAudioEngine();
+  const subscribers = /* @__PURE__ */ new Set();
+  const eventListeners = {
+    sourcechange: /* @__PURE__ */ new Set(),
+    queuechange: /* @__PURE__ */ new Set(),
+    play: /* @__PURE__ */ new Set(),
+    pause: /* @__PURE__ */ new Set(),
+    seeking: /* @__PURE__ */ new Set(),
+    seeked: /* @__PURE__ */ new Set(),
+    timeupdate: /* @__PURE__ */ new Set(),
+    ratechange: /* @__PURE__ */ new Set(),
+    volumechange: /* @__PURE__ */ new Set(),
+    ended: /* @__PURE__ */ new Set(),
+    error: /* @__PURE__ */ new Set(),
+    destroy: /* @__PURE__ */ new Set()
+  };
+  const getState = () => state;
+  const publishState = () => {
+    for (const subscriber of subscribers) {
+      subscriber(state);
+    }
+  };
+  const emit = (eventName, event) => {
+    for (const listener of eventListeners[eventName]) {
+      listener(event);
+    }
+  };
+  const setState = (updater) => {
+    state = updateQueueFlags(updater(state));
+    publishState();
+    return state;
+  };
+  const setError = (error) => {
+    shouldAutoplayAfterLoad = false;
+    const nextState = setState((currentState) => ({
+      ...currentState,
+      status: "error",
+      error: {
+        code: error.code,
+        message: error.message
+      }
+    }));
+    emit("error", { error, state: nextState });
+  };
+  const clearError = () => {
+    if (!state.error) {
+      return;
+    }
+    setState((currentState) => ({
+      ...currentState,
+      error: null
+    }));
+  };
+  const syncAudioSnapshot = (statusOverride) => {
+    const snapshot = engine.getSnapshot(state.currentSource?.durationHint);
+    const currentTime = snapshot.currentTime;
+    const duration = snapshot.duration;
+    const buffered = snapshot.buffered;
+    const playedFraction = duration > 0 ? Math.min(1, Math.max(0, currentTime / duration)) : 0;
+    const bufferedFraction = duration > 0 ? Math.min(1, Math.max(0, buffered / duration)) : 0;
+    const nextState = setState((currentState) => ({
+      ...currentState,
+      currentSourceId: currentState.currentSource?.id ?? null,
+      currentTime,
+      duration,
+      buffered,
+      progress: {
+        currentTime,
+        duration,
+        buffered,
+        playedFraction,
+        bufferedFraction
+      },
+      rate: snapshot.rate,
+      volume: snapshot.volume,
+      muted: snapshot.muted,
+      status: statusOverride ?? currentState.status,
+      error: statusOverride === "error" ? currentState.error : null
+    }));
+    return nextState;
+  };
+  const findQueueIndexById = (id) => id ? state.queue.items.findIndex((item) => item.id === id) : -1;
+  const resolveNextQueueIndex = (mode) => {
+    const { items, position } = state.queue;
+    const { currentIndex, repeatMode } = position;
+    if (items.length === 0 || currentIndex < 0) {
+      return null;
+    }
+    if (repeatMode === "one") {
+      return currentIndex;
+    }
+    if (currentIndex < items.length - 1) {
+      return currentIndex + 1;
+    }
+    if (repeatMode === "all") {
+      return 0;
+    }
+    return mode === "ended" ? -1 : null;
+  };
+  const resolvePreviousQueueIndex = () => {
+    const { items, position } = state.queue;
+    const { currentIndex, repeatMode } = position;
+    if (items.length === 0 || currentIndex < 0) {
+      return null;
+    }
+    if (currentIndex > 0) {
+      return currentIndex - 1;
+    }
+    if (repeatMode === "all") {
+      return items.length - 1;
+    }
+    return null;
+  };
+  const updateCurrentSource = (source, nextStatus) => {
+    const queueIndex = findQueueIndexById(source?.id);
+    const nextState = setState((currentState) => ({
+      ...currentState,
+      currentSource: source,
+      currentSourceId: source?.id ?? null,
+      currentTime: 0,
+      duration: source?.durationHint ?? 0,
+      buffered: 0,
+      progress: {
+        currentTime: 0,
+        duration: source?.durationHint ?? 0,
+        buffered: 0,
+        playedFraction: 0,
+        bufferedFraction: 0
+      },
+      status: nextStatus,
+      error: null,
+      queue: {
+        ...currentState.queue,
+        position: {
+          ...currentState.queue.position,
+          currentIndex: queueIndex,
+          currentSourceId: source?.id ?? null
+        }
+      }
+    }));
+    emit("sourcechange", { source, state: nextState });
+    return nextState;
+  };
+  const setQueueState = (items, currentIndex) => setState((currentState) => ({
+    ...currentState,
+    queue: {
+      ...currentState.queue,
+      items,
+      position: {
+        ...currentState.queue.position,
+        currentIndex
+      }
+    }
+  }));
+  const emitQueueChange = (nextState) => {
+    emit("queuechange", { queue: cloneQueueState(nextState), state: nextState });
+  };
+  const attachSourceToAudio = (source, autoplayAfterLoad) => {
+    shouldAutoplayAfterLoad = autoplayAfterLoad;
+    suppressPauseEvent = true;
+    try {
+      engine.pause();
+    } finally {
+      suppressPauseEvent = false;
+    }
+    engine.setSource(source.src);
+    engine.setCurrentTime(0);
+    engine.setPlaybackRate(state.rate);
+    engine.setVolume(state.volume);
+    engine.setMuted(state.muted);
+    engine.load();
+  };
+  const loadInternal = async (source, autoplayAfterLoad = false) => {
+    assertStableSource(source);
+    updateCurrentSource(source, "loading");
+    attachSourceToAudio(source, autoplayAfterLoad);
+  };
+  const selectQueueIndex = async (index, autoplayAfterLoad = false) => {
+    const item = state.queue.items[index] ?? null;
+    if (!item) {
+      return null;
+    }
+    await loadInternal(item, autoplayAfterLoad);
+    const nextState = setQueueState(state.queue.items, index);
+    emitQueueChange(nextState);
+    return item;
+  };
+  const playLoadedAudio = async () => {
+    try {
+      await engine.play();
+    } catch (cause) {
+      setError(createPlayerError("PLAY_ERROR", "Failed to start playback.", cause));
+    }
+  };
+  const handlePlaybackEnded = async () => {
+    if (destroyed) {
+      return;
+    }
+    if (state.queue.items.length > 0 && state.queue.position.currentIndex >= 0) {
+      const nextIndex = resolveNextQueueIndex("ended");
+      if (nextIndex === -1 || nextIndex === null) {
+        const endedState2 = syncAudioSnapshot("ended");
+        emit("ended", { source: endedState2.currentSource, state: endedState2 });
+        return;
+      }
+      await selectQueueIndex(nextIndex, true);
+      return;
+    }
+    const endedState = syncAudioSnapshot("ended");
+    emit("ended", { source: endedState.currentSource, state: endedState });
+  };
+  const detachEngineListeners = [
+    engine.on("loadedmetadata", () => {
+      if (destroyed || !state.currentSource) {
+        return;
+      }
+      syncAudioSnapshot("ready");
+      if (shouldAutoplayAfterLoad) {
+        shouldAutoplayAfterLoad = false;
+        void playLoadedAudio();
+      }
+    }),
+    engine.on("timeupdate", () => {
+      if (destroyed) {
+        return;
+      }
+      const nextState = syncAudioSnapshot(
+        state.status === "ended" ? "playing" : void 0
+      );
+      emit("timeupdate", {
+        currentTime: nextState.currentTime,
+        duration: nextState.duration,
+        state: nextState
+      });
+    }),
+    engine.on("progress", () => {
+      if (!destroyed) {
+        syncAudioSnapshot();
+      }
+    }),
+    engine.on("play", () => {
+      if (destroyed) {
+        return;
+      }
+      const nextState = syncAudioSnapshot("playing");
+      emit("play", { source: nextState.currentSource, state: nextState });
+    }),
+    engine.on("pause", () => {
+      if (destroyed || suppressPauseEvent) {
+        return;
+      }
+      const nextStatus = state.status === "ended" ? "ended" : state.currentSource ? "paused" : "idle";
+      const nextState = syncAudioSnapshot(nextStatus);
+      emit("pause", { source: nextState.currentSource, state: nextState });
+    }),
+    engine.on("seeked", () => {
+      if (destroyed) {
+        return;
+      }
+      const nextState = syncAudioSnapshot();
+      emit("seeked", { currentTime: nextState.currentTime, state: nextState });
+      emit("timeupdate", {
+        currentTime: nextState.currentTime,
+        duration: nextState.duration,
+        state: nextState
+      });
+    }),
+    engine.on("ratechange", () => {
+      if (destroyed) {
+        return;
+      }
+      const nextState = syncAudioSnapshot();
+      emit("ratechange", { rate: nextState.rate, state: nextState });
+    }),
+    engine.on("volumechange", () => {
+      if (destroyed) {
+        return;
+      }
+      const nextState = syncAudioSnapshot();
+      emit("volumechange", {
+        volume: nextState.volume,
+        muted: nextState.muted,
+        state: nextState
+      });
+    }),
+    engine.on("ended", () => {
+      void handlePlaybackEnded();
+    }),
+    engine.on("error", () => {
+      if (destroyed) {
+        return;
+      }
+      setError(
+        createPlayerError(
+          "LOAD_ERROR",
+          "Audio element reported a playback error.",
+          engine.getRuntimeError()
+        )
+      );
+    })
+  ];
+  return {
+    getState,
+    subscribe(listener) {
+      subscribers.add(listener);
+      listener(state);
+      return () => {
+        subscribers.delete(listener);
+      };
+    },
+    on(eventName, listener) {
+      eventListeners[eventName].add(
+        listener
+      );
+      return () => {
+        eventListeners[eventName].delete(
+          listener
+        );
+      };
+    },
+    async load(source) {
+      try {
+        await loadInternal(source);
+      } catch (cause) {
+        setError(
+          normalizePlayerError("LOAD_ERROR", "Failed to load source.", cause)
+        );
+      }
+    },
+    async play(source) {
+      try {
+        if (source) {
+          await loadInternal(source, true);
+          return;
+        }
+        if (!state.currentSource) {
+          setError(
+            createPlayerError(
+              "NO_ACTIVE_SOURCE",
+              "Cannot play without an active source."
+            )
+          );
+          return;
+        }
+        if (state.status === "loading") {
+          shouldAutoplayAfterLoad = true;
+          return;
+        }
+        await playLoadedAudio();
+      } catch (cause) {
+        setError(normalizePlayerError("PLAY_ERROR", "Failed to start playback.", cause));
+      }
+    },
+    pause() {
+      if (!engine.available) {
+        return;
+      }
+      shouldAutoplayAfterLoad = false;
+      engine.pause();
+    },
+    async toggle() {
+      if (state.status === "playing") {
+        this.pause();
+        return;
+      }
+      await this.play();
+    },
+    unload() {
+      shouldAutoplayAfterLoad = false;
+      if (engine.available) {
+        suppressPauseEvent = true;
+        try {
+          engine.pause();
+        } finally {
+          suppressPauseEvent = false;
+        }
+        engine.clearSource();
+        engine.load();
+      }
+      const nextState = updateCurrentSource(null, "idle");
+      emitQueueChange(nextState);
+    },
+    seek(time) {
+      if (!state.currentSource) {
+        setError(
+          createPlayerError("SEEK_ERROR", "Cannot seek without an active source.")
+        );
+        return;
+      }
+      const max = engine.getSnapshot(state.currentSource.durationHint).duration;
+      const normalized = Math.max(
+        0,
+        max > 0 ? Math.min(time, max) : isFiniteNumber(time) ? time : 0
+      );
+      emit("seeking", { from: state.currentTime, to: normalized, state });
+      try {
+        engine.setCurrentTime(normalized);
+      } catch (cause) {
+        setError(normalizePlayerError("SEEK_ERROR", "Failed to seek audio.", cause));
+      }
+    },
+    setRate(rate) {
+      if (!engine.available) {
+        setError(
+          createPlayerError("INVALID_RATE", "Audio element is unavailable.")
+        );
+        return;
+      }
+      if (!isFiniteNumber(rate) || rate <= 0) {
+        setError(
+          createPlayerError("INVALID_RATE", "Playback rate must be greater than 0.")
+        );
+        return;
+      }
+      engine.setPlaybackRate(rate);
+      clearError();
+      syncAudioSnapshot();
+    },
+    setVolume(volume) {
+      if (!engine.available) {
+        setError(
+          createPlayerError("INVALID_VOLUME", "Audio element is unavailable.")
+        );
+        return;
+      }
+      if (!isFiniteNumber(volume) || volume < 0 || volume > 1) {
+        setError(
+          createPlayerError("INVALID_VOLUME", "Volume must be between 0 and 1.")
+        );
+        return;
+      }
+      engine.setVolume(volume);
+      clearError();
+      syncAudioSnapshot();
+    },
+    setMuted(muted) {
+      if (!engine.available) {
+        return;
+      }
+      engine.setMuted(muted);
+      clearError();
+      syncAudioSnapshot();
+    },
+    async setQueue(items, queueOptions = {}) {
+      try {
+        for (const item of items) {
+          assertStableSource(item);
+        }
+        const startIndex = queueOptions.startAtId === void 0 ? items.length > 0 ? 0 : -1 : items.findIndex((item) => item.id === queueOptions.startAtId);
+        if (queueOptions.startAtId && startIndex < 0) {
+          throw createPlayerError(
+            "INVALID_QUEUE_ITEM",
+            `Queue start item ${queueOptions.startAtId} was not found.`
+          );
+        }
+        const nextState = setState((currentState) => ({
+          ...currentState,
+          currentSource: startIndex >= 0 ? items[startIndex] ?? null : null,
+          currentSourceId: startIndex >= 0 ? items[startIndex]?.id ?? null : null,
+          currentTime: 0,
+          duration: startIndex >= 0 ? items[startIndex]?.durationHint ?? 0 : 0,
+          buffered: 0,
+          progress: {
+            currentTime: 0,
+            duration: startIndex >= 0 ? items[startIndex]?.durationHint ?? 0 : 0,
+            buffered: 0,
+            playedFraction: 0,
+            bufferedFraction: 0
+          },
+          status: startIndex >= 0 ? "ready" : "idle",
+          error: null,
+          queue: {
+            ...currentState.queue,
+            items: [...items],
+            position: {
+              ...currentState.queue.position,
+              currentIndex: startIndex,
+              currentSourceId: startIndex >= 0 ? items[startIndex]?.id ?? null : null
+            }
+          }
+        }));
+        emitQueueChange(nextState);
+        emit("sourcechange", {
+          source: nextState.currentSource,
+          state: nextState
+        });
+        if (nextState.currentSource) {
+          await loadInternal(nextState.currentSource, queueOptions.autoplay === true);
+          const syncedState = setQueueState(items, startIndex);
+          emitQueueChange(syncedState);
+        } else if (engine.available) {
+          shouldAutoplayAfterLoad = false;
+          suppressPauseEvent = true;
+          engine.pause();
+          suppressPauseEvent = false;
+          engine.clearSource();
+          engine.load();
+        }
+      } catch (cause) {
+        setError(
+          normalizePlayerError(
+            "INVALID_QUEUE_ITEM",
+            "Failed to set queue.",
+            cause
+          )
+        );
+      }
+    },
+    appendToQueue(items) {
+      try {
+        for (const item of items) {
+          assertStableSource(item);
+        }
+        const nextState = setState((currentState) => ({
+          ...currentState,
+          queue: {
+            ...currentState.queue,
+            items: [...currentState.queue.items, ...items]
+          }
+        }));
+        emitQueueChange(nextState);
+      } catch (cause) {
+        setError(
+          normalizePlayerError(
+            "INVALID_QUEUE_ITEM",
+            "Failed to append queue items.",
+            cause
+          )
+        );
+      }
+    },
+    removeFromQueue(id) {
+      const nextItems = state.queue.items.filter((item) => item.id !== id);
+      const nextIndex = nextItems.findIndex(
+        (item) => item.id === state.currentSource?.id
+      );
+      const nextState = setState((currentState) => ({
+        ...currentState,
+        queue: {
+          ...currentState.queue,
+          items: nextItems,
+          position: {
+            ...currentState.queue.position,
+            currentIndex: nextIndex,
+            currentSourceId: nextIndex >= 0 ? nextItems[nextIndex]?.id ?? null : null
+          }
+        }
+      }));
+      emitQueueChange(nextState);
+    },
+    clearQueue() {
+      const nextState = setState((currentState) => ({
+        ...currentState,
+        queue: {
+          ...currentState.queue,
+          items: [],
+          position: {
+            ...currentState.queue.position,
+            currentIndex: -1,
+            currentSourceId: null
+          }
+        }
+      }));
+      emitQueueChange(nextState);
+    },
+    async next() {
+      const nextIndex = resolveNextQueueIndex("manual");
+      if (nextIndex === null) {
+        return;
+      }
+      await selectQueueIndex(nextIndex, true);
+    },
+    async previous(previousOptions = {}) {
+      if (!state.currentSource) {
+        return;
+      }
+      const threshold = previousOptions.restartThresholdSeconds ?? DEFAULT_PREVIOUS_RESTART_THRESHOLD_SECONDS;
+      if (state.currentTime > threshold) {
+        this.seek(0);
+        return;
+      }
+      const previousIndex = resolvePreviousQueueIndex();
+      if (previousIndex === null) {
+        this.seek(0);
+        return;
+      }
+      await selectQueueIndex(previousIndex, true);
+    },
+    setRepeatMode(mode) {
+      const nextState = setState((currentState) => ({
+        ...currentState,
+        queue: {
+          ...currentState.queue,
+          position: {
+            ...currentState.queue.position,
+            repeatMode: mode
+          }
+        }
+      }));
+      emitQueueChange(nextState);
+    },
+    destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      shouldAutoplayAfterLoad = false;
+      for (const detach of detachEngineListeners) {
+        detach();
+      }
+      suppressPauseEvent = true;
+      engine.destroy();
+      suppressPauseEvent = false;
+      const nextState = setState(() => createInitialState(options));
+      emit("destroy", { state: nextState });
+      subscribers.clear();
+      for (const eventName of Object.keys(eventListeners)) {
+        eventListeners[eventName].clear();
+      }
+    }
+  };
+};
+var attachAudioPlayerPersistence = (player, options) => {
+  const maxAgeMs = options.maxAgeMs ?? DEFAULT_PERSISTENCE_MAX_AGE_MS;
+  const saveIntervalMs = options.saveIntervalMs ?? DEFAULT_PERSISTENCE_SAVE_INTERVAL_MS;
+  let destroyed = false;
+  let playIntervalId = null;
+  const save = () => {
+    if (destroyed) {
+      return;
+    }
+    const state = player.getState();
+    if (!state.currentSource) {
+      options.adapter.clear();
+      return;
+    }
+    options.adapter.save(toPersistedPlayerState(state));
+  };
+  const clear = () => {
+    options.adapter.clear();
+  };
+  const stopPlayInterval = () => {
+    if (playIntervalId !== null) {
+      clearInterval(playIntervalId);
+      playIntervalId = null;
+    }
+  };
+  const startPlayInterval = () => {
+    if (playIntervalId !== null) {
+      return;
+    }
+    playIntervalId = setInterval(() => {
+      save();
+    }, saveIntervalMs);
+  };
+  const waitForRestoredSource = (sourceId) => new Promise((resolve) => {
+    let settled = false;
+    let unsubscribe;
+    unsubscribe = player.subscribe((state) => {
+      if (settled || state.currentSourceId !== sourceId) {
+        return;
+      }
+      if (state.status === "loading") {
+        return;
+      }
+      settled = true;
+      unsubscribe?.();
+      resolve();
+    });
+    if (settled) {
+      unsubscribe();
+    }
+  });
+  const restore = async () => {
+    const persisted = options.adapter.load();
+    if (!persisted) {
+      return null;
+    }
+    if (Date.now() - persisted.savedAt > maxAgeMs) {
+      options.adapter.clear();
+      return null;
+    }
+    player.setRepeatMode(persisted.queue.position.repeatMode);
+    player.setVolume(persisted.volume);
+    player.setMuted(persisted.muted);
+    player.setRate(persisted.rate);
+    if (persisted.queue.items.length > 0) {
+      await player.setQueue(persisted.queue.items, {
+        startAtId: persisted.queue.position.currentSourceId ?? void 0
+      });
+    } else if (persisted.currentSource) {
+      await player.load(persisted.currentSource);
+    } else {
+      return persisted;
+    }
+    if (persisted.currentSourceId) {
+      await waitForRestoredSource(persisted.currentSourceId);
+    }
+    if (persisted.currentTime > 0) {
+      player.seek(persisted.currentTime);
+    }
+    return persisted;
+  };
+  const stateUnsubscribe = player.subscribe((state) => {
+    if (state.status === "playing") {
+      startPlayInterval();
+      return;
+    }
+    stopPlayInterval();
+  });
+  const pauseUnsubscribe = player.on("pause", () => {
+    save();
+  });
+  const endedUnsubscribe = player.on("ended", () => {
+    save();
+  });
+  const sourceUnsubscribe = player.on("sourcechange", () => {
+    save();
+  });
+  const queueUnsubscribe = player.on("queuechange", () => {
+    save();
+  });
+  const rateUnsubscribe = player.on("ratechange", () => {
+    save();
+  });
+  const volumeUnsubscribe = player.on("volumechange", () => {
+    save();
+  });
+  const beforeUnloadHandler = () => {
+    save();
+  };
+  const visibilityHandler = () => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    if (document.visibilityState === "hidden") {
+      save();
+    }
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("beforeunload", beforeUnloadHandler);
+  }
+  if (typeof document !== "undefined") {
+    document.addEventListener("visibilitychange", visibilityHandler);
+  }
+  if (options.autoRestore !== false) {
+    void restore();
+  }
+  return {
+    restore,
+    save,
+    clear,
+    destroy() {
+      destroyed = true;
+      stopPlayInterval();
+      stateUnsubscribe();
+      pauseUnsubscribe();
+      endedUnsubscribe();
+      sourceUnsubscribe();
+      queueUnsubscribe();
+      rateUnsubscribe();
+      volumeUnsubscribe();
+      if (typeof window !== "undefined") {
+        window.removeEventListener("beforeunload", beforeUnloadHandler);
+      }
+      if (typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", visibilityHandler);
+      }
+    }
+  };
+};
+var attachAudioPlayerProgressReporter = (player, options) => {
+  const intervalMs = options.intervalMs ?? DEFAULT_PROGRESS_REPORT_INTERVAL_MS;
+  let destroyed = false;
+  let intervalId = null;
+  const report = () => {
+    if (destroyed) {
+      return;
+    }
+    const state = player.getState();
+    if (!state.currentSource) {
+      return;
+    }
+    options.onReport(toProgressSnapshot(state));
+  };
+  const stopInterval = () => {
+    if (intervalId !== null) {
+      clearInterval(intervalId);
+      intervalId = null;
+    }
+  };
+  const startInterval = () => {
+    if (intervalId !== null) {
+      return;
+    }
+    intervalId = setInterval(() => {
+      report();
+    }, intervalMs);
+  };
+  const stateUnsubscribe = player.subscribe((state) => {
+    if (state.status === "playing") {
+      startInterval();
+      return;
+    }
+    stopInterval();
+  });
+  const pauseUnsubscribe = player.on("pause", () => {
+    report();
+  });
+  const endedUnsubscribe = player.on("ended", () => {
+    report();
+  });
+  const seekedUnsubscribe = player.on("seeked", () => {
+    report();
+  });
+  const sourceUnsubscribe = player.on("sourcechange", () => {
+    report();
+  });
+  return {
+    report,
+    destroy() {
+      destroyed = true;
+      stopInterval();
+      stateUnsubscribe();
+      pauseUnsubscribe();
+      endedUnsubscribe();
+      seekedUnsubscribe();
+      sourceUnsubscribe();
+    }
+  };
+};
+var attachAudioPlayerMediaSession = (player, options = {}) => {
+  if (!hasMediaSession()) {
+    return {
+      sync() {
+      },
+      destroy() {
+      }
+    };
+  }
+  const artworkSizes = options.artworkSizes ?? DEFAULT_MEDIA_SESSION_ARTWORK_SIZES;
+  const seekOffsetSeconds = options.seekOffsetSeconds ?? DEFAULT_MEDIA_SESSION_SEEK_OFFSET_SECONDS;
+  let destroyed = false;
+  const sync = () => {
+    if (destroyed || !hasMediaSession()) {
+      return;
+    }
+    const state = player.getState();
+    const source = state.currentSource;
+    navigator.mediaSession.metadata = source ? new MediaMetadata({
+      title: source.title ?? "",
+      artist: source.artist ?? "",
+      album: source.album ?? "",
+      artwork: createMediaSessionArtwork(source, artworkSizes)
+    }) : null;
+    navigator.mediaSession.playbackState = state.status === "playing" ? "playing" : state.currentSource ? "paused" : "none";
+    if (state.currentSource && state.duration > 0) {
+      try {
+        navigator.mediaSession.setPositionState({
+          duration: state.duration,
+          playbackRate: state.rate,
+          position: Math.min(state.currentTime, state.duration)
+        });
+      } catch {
+      }
+    } else {
+      try {
+        navigator.mediaSession.setPositionState();
+      } catch {
+      }
+    }
+  };
+  const setActionHandler = (action, handler) => {
+    try {
+      navigator.mediaSession.setActionHandler(action, handler);
+    } catch {
+    }
+  };
+  setActionHandler("play", () => {
+    void player.play();
+  });
+  setActionHandler("pause", () => {
+    player.pause();
+  });
+  setActionHandler("seekbackward", () => {
+    const state = player.getState();
+    player.seek(Math.max(0, state.currentTime - seekOffsetSeconds));
+  });
+  setActionHandler("seekforward", () => {
+    const state = player.getState();
+    const max = state.duration > 0 ? state.duration : state.currentTime + seekOffsetSeconds;
+    player.seek(Math.min(max, state.currentTime + seekOffsetSeconds));
+  });
+  setActionHandler("previoustrack", () => {
+    void player.previous();
+  });
+  setActionHandler("nexttrack", () => {
+    void player.next();
+  });
+  setActionHandler("seekto", (details) => {
+    if (details.seekTime === void 0) {
+      return;
+    }
+    player.seek(details.seekTime);
+  });
+  setActionHandler("stop", () => {
+    player.pause();
+  });
+  const stateUnsubscribe = player.subscribe(() => {
+    sync();
+  });
+  sync();
+  return {
+    sync,
+    destroy() {
+      destroyed = true;
+      stateUnsubscribe();
+      if (!hasMediaSession()) {
+        return;
+      }
+      const actions = [
+        "play",
+        "pause",
+        "seekbackward",
+        "seekforward",
+        "previoustrack",
+        "nexttrack",
+        "seekto",
+        "stop"
+      ];
+      for (const action of actions) {
+        setActionHandler(action, null);
+      }
+      navigator.mediaSession.metadata = null;
+      navigator.mediaSession.playbackState = "none";
+      try {
+        navigator.mediaSession.setPositionState();
+      } catch {
+      }
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  attachAudioPlayerMediaSession,
+  attachAudioPlayerPersistence,
+  attachAudioPlayerProgressReporter,
+  createAudioPlayer,
+  createLocalStoragePersistenceAdapter
+});
+//# sourceMappingURL=index.cjs.map