gapless 4.4.0 → 4.4.2

package/dist/machines/fetchDecode.machine.d.ts

@@ -0,0 +1,42 @@
+export interface FetchDecodeContext {
+    trackUrl: string;
+    resolvedUrl: string;
+    skipHEAD: boolean;
+}
+export declare const fetchDecodeMachine: import("xstate").StateMachine<FetchDecodeContext, import("xstate").AnyEventObject, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, void, import("xstate").EventObject> | import("xstate").PromiseActorLogic<void, {
+        resolvedUrl: string;
+    }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<string | null, {
+        trackUrl: string;
+    }, import("xstate").EventObject>> | undefined;
+}, {
+    src: "decodeAudio";
+    logic: import("xstate").PromiseActorLogic<void, void, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "fetchAudio";
+    logic: import("xstate").PromiseActorLogic<void, {
+        resolvedUrl: string;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "resolveUrl";
+    logic: import("xstate").PromiseActorLogic<string | null, {
+        trackUrl: string;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
+}, never, {
+    type: "shouldSkipHEAD";
+    params: unknown;
+}, never, "decoding" | "done" | "error" | "fetching" | "resolvingUrl", string, FetchDecodeContext, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "fetchDecode";
+    states: {
+        readonly resolvingUrl: {};
+        readonly fetching: {};
+        readonly decoding: {};
+        readonly done: {};
+        readonly error: {};
+    };
+}, import("xstate").MetaObject>;
+export type FetchDecodeMachine = typeof fetchDecodeMachine;
+//# sourceMappingURL=fetchDecode.machine.d.ts.map

package/dist/machines/fetchDecode.machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchDecode.machine.d.ts","sourceRoot":"","sources":["../../src/machines/fetchDecode.machine.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID,eAAO,MAAM,kBAAkB;;qBAOkB,MAAM;;kBADA,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAmG3D,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC"}

package/dist/machines/queue.machine.d.ts

@@ -0,0 +1,165 @@
+export interface QueueContext {
+    currentTrackIndex: number;
+    trackCount: number;
+}
+export type QueueEvent = {
+    type: 'PLAY';
+} | {
+    type: 'PAUSE';
+} | {
+    type: 'TOGGLE';
+} | {
+    type: 'NEXT';
+} | {
+    type: 'PREVIOUS';
+} | {
+    type: 'GOTO';
+    index: number;
+    playImmediately?: boolean;
+    startTime?: number;
+} | {
+    type: 'SEEK';
+    time: number;
+} | {
+    type: 'SET_VOLUME';
+    volume: number;
+} | {
+    type: 'ADD_TRACK';
+} | {
+    type: 'REMOVE_TRACK';
+    index: number;
+} | {
+    type: 'TRACK_ENDED';
+} | {
+    type: 'TRACK_LOADED';
+    index: number;
+};
+export declare function createQueueMachine(initialContext: QueueContext): import("xstate").StateMachine<QueueContext, {
+    type: 'PLAY';
+} | {
+    type: 'PAUSE';
+} | {
+    type: 'TOGGLE';
+} | {
+    type: 'NEXT';
+} | {
+    type: 'PREVIOUS';
+} | {
+    type: 'GOTO';
+    index: number;
+    playImmediately?: boolean;
+    startTime?: number;
+} | {
+    type: 'SEEK';
+    time: number;
+} | {
+    type: 'SET_VOLUME';
+    volume: number;
+} | {
+    type: 'ADD_TRACK';
+} | {
+    type: 'REMOVE_TRACK';
+    index: number;
+} | {
+    type: 'TRACK_ENDED';
+} | {
+    type: 'TRACK_LOADED';
+    index: number;
+}, {}, never, {
+    type: "activateAndPlayCurrent";
+    params: unknown;
+} | {
+    type: "advanceOnTrackEnd";
+    params: unknown;
+} | {
+    type: "advanceToNextTrack";
+    params: unknown;
+} | {
+    type: "cancelAllGapless";
+    params: unknown;
+} | {
+    type: "cancelAndRescheduleGapless";
+    params: unknown;
+} | {
+    type: "cancelScheduledGapless";
+    params: unknown;
+} | {
+    type: "deactivateCurrent";
+    params: unknown;
+} | {
+    type: "deactivateEndedTrack";
+    params: unknown;
+} | {
+    type: "decrementTrackCount";
+    params: unknown;
+} | {
+    type: "goToPreviousTrack";
+    params: unknown;
+} | {
+    type: "gotoTrackIndex";
+    params: unknown;
+} | {
+    type: "incrementTrackCount";
+    params: unknown;
+} | {
+    type: "notifyEnded";
+    params: unknown;
+} | {
+    type: "notifyPlayNextTrack";
+    params: unknown;
+} | {
+    type: "notifyPlayPreviousTrack";
+    params: unknown;
+} | {
+    type: "notifyStartNewTrack";
+    params: unknown;
+} | {
+    type: "pauseCurrent";
+    params: unknown;
+} | {
+    type: "playCurrent";
+    params: unknown;
+} | {
+    type: "playOrContinueGapless";
+    params: unknown;
+} | {
+    type: "preloadAhead";
+    params: unknown;
+} | {
+    type: "resetToFirstTrack";
+    params: unknown;
+} | {
+    type: "scheduleGapless";
+    params: unknown;
+} | {
+    type: "seekCurrent";
+    params: unknown;
+} | {
+    type: "seekCurrentToStartTime";
+    params: unknown;
+} | {
+    type: "updateMediaSessionMetadata";
+    params: unknown;
+}, {
+    type: "hasNextTrack";
+    params: unknown;
+} | {
+    type: "isRemovingCurrent";
+    params: unknown;
+} | {
+    type: "playImmediately";
+    params: unknown;
+} | {
+    type: "willBeEmpty";
+    params: unknown;
+}, never, "ended" | "idle" | "paused" | "playing", string, import("xstate").NonReducibleUnknown, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "queue";
+    states: {
+        readonly idle: {};
+        readonly playing: {};
+        readonly paused: {};
+        readonly ended: {};
+    };
+}, import("xstate").MetaObject>;
+export type QueueMachine = ReturnType<typeof createQueueMachine>;
+//# sourceMappingURL=queue.machine.d.ts.map

package/dist/machines/queue.machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.machine.d.ts","sourceRoot":"","sources":["../../src/machines/queue.machine.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAI5C,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,YAAY;UAfnD,MAAM;;UACN,OAAO;;UACP,QAAQ;;UACR,MAAM;;UACN,UAAU;;UACV,MAAM;WAAS,MAAM;sBAAoB,OAAO;gBAAc,MAAM;;UACpE,MAAM;UAAQ,MAAM;;UACpB,YAAY;YAAU,MAAM;;UAC5B,WAAW;;UACX,cAAc;WAAS,MAAM;;UAC7B,aAAa;;UACb,cAAc;WAAS,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAuZxC;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/machines/track.machine.d.ts

@@ -0,0 +1,291 @@
+import type { WebAudioLoadingState, PlaybackType } from '../types';
+export interface TrackContext {
+    trackUrl: string;
+    resolvedUrl: string;
+    skipHEAD: boolean;
+    playbackType: PlaybackType;
+    webAudioLoadingState: WebAudioLoadingState;
+    isPlaying: boolean;
+    scheduledStartContextTime: number | null;
+    notifiedLookahead: boolean;
+    fetchStarted: boolean;
+    /** True when PLAY was received in webAudioOnly mode before buffer is ready. */
+    pendingPlay: boolean;
+}
+export type TrackEvent = {
+    type: 'ACTIVATE';
+} | {
+    type: 'DEACTIVATE';
+} | {
+    type: 'PRELOAD';
+} | {
+    type: 'BUFFER_LOADING';
+} | {
+    type: 'PLAY';
+} | {
+    type: 'PLAY_WEBAUDIO';
+} | {
+    type: 'PAUSE';
+} | {
+    type: 'SEEK';
+    time: number;
+} | {
+    type: 'SET_VOLUME';
+    volume: number;
+} | {
+    type: 'BUFFER_READY';
+} | {
+    type: 'BUFFER_ERROR';
+} | {
+    type: 'HTML5_ENDED';
+} | {
+    type: 'WEBAUDIO_ENDED';
+} | {
+    type: 'URL_RESOLVED';
+    url: string;
+} | {
+    type: 'START_FETCH';
+} | {
+    type: 'SCHEDULE_GAPLESS';
+    when: number;
+} | {
+    type: 'CANCEL_GAPLESS';
+} | {
+    type: 'LOOKAHEAD_REACHED';
+};
+export declare function createTrackMachine(initialContext: TrackContext): import("xstate").StateMachine<TrackContext, {
+    type: 'ACTIVATE';
+} | {
+    type: 'DEACTIVATE';
+} | {
+    type: 'PRELOAD';
+} | {
+    type: 'BUFFER_LOADING';
+} | {
+    type: 'PLAY';
+} | {
+    type: 'PLAY_WEBAUDIO';
+} | {
+    type: 'PAUSE';
+} | {
+    type: 'SEEK';
+    time: number;
+} | {
+    type: 'SET_VOLUME';
+    volume: number;
+} | {
+    type: 'BUFFER_READY';
+} | {
+    type: 'BUFFER_ERROR';
+} | {
+    type: 'HTML5_ENDED';
+} | {
+    type: 'WEBAUDIO_ENDED';
+} | {
+    type: 'URL_RESOLVED';
+    url: string;
+} | {
+    type: 'START_FETCH';
+} | {
+    type: 'SCHEDULE_GAPLESS';
+    when: number;
+} | {
+    type: 'CANCEL_GAPLESS';
+} | {
+    type: 'LOOKAHEAD_REACHED';
+}, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").StateMachine<import("./fetchDecode.machine").FetchDecodeContext, import("xstate").AnyEventObject, {
+        [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, void, import("xstate").EventObject> | import("xstate").PromiseActorLogic<void, {
+            resolvedUrl: string;
+        }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<string | null, {
+            trackUrl: string;
+        }, import("xstate").EventObject>> | undefined;
+    }, {
+        src: "decodeAudio";
+        logic: import("xstate").PromiseActorLogic<void, void, import("xstate").EventObject>;
+        id: string | undefined;
+    } | {
+        src: "fetchAudio";
+        logic: import("xstate").PromiseActorLogic<void, {
+            resolvedUrl: string;
+        }, import("xstate").EventObject>;
+        id: string | undefined;
+    } | {
+        src: "resolveUrl";
+        logic: import("xstate").PromiseActorLogic<string | null, {
+            trackUrl: string;
+        }, import("xstate").EventObject>;
+        id: string | undefined;
+    }, never, {
+        type: "shouldSkipHEAD";
+        params: unknown;
+    }, never, "decoding" | "done" | "error" | "fetching" | "resolvingUrl", string, import("./fetchDecode.machine").FetchDecodeContext, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+        id: "fetchDecode";
+        states: {
+            readonly resolvingUrl: {};
+            readonly fetching: {};
+            readonly decoding: {};
+            readonly done: {};
+            readonly error: {};
+        };
+    }, import("xstate").MetaObject>> | undefined;
+}, {
+    src: "fetchDecode";
+    logic: import("xstate").StateMachine<import("./fetchDecode.machine").FetchDecodeContext, import("xstate").AnyEventObject, {
+        [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, void, import("xstate").EventObject> | import("xstate").PromiseActorLogic<void, {
+            resolvedUrl: string;
+        }, import("xstate").EventObject> | import("xstate").PromiseActorLogic<string | null, {
+            trackUrl: string;
+        }, import("xstate").EventObject>> | undefined;
+    }, {
+        src: "decodeAudio";
+        logic: import("xstate").PromiseActorLogic<void, void, import("xstate").EventObject>;
+        id: string | undefined;
+    } | {
+        src: "fetchAudio";
+        logic: import("xstate").PromiseActorLogic<void, {
+            resolvedUrl: string;
+        }, import("xstate").EventObject>;
+        id: string | undefined;
+    } | {
+        src: "resolveUrl";
+        logic: import("xstate").PromiseActorLogic<string | null, {
+            trackUrl: string;
+        }, import("xstate").EventObject>;
+        id: string | undefined;
+    }, never, {
+        type: "shouldSkipHEAD";
+        params: unknown;
+    }, never, "decoding" | "done" | "error" | "fetching" | "resolvingUrl", string, import("./fetchDecode.machine").FetchDecodeContext, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+        id: "fetchDecode";
+        states: {
+            readonly resolvingUrl: {};
+            readonly fetching: {};
+            readonly decoding: {};
+            readonly done: {};
+            readonly error: {};
+        };
+    }, import("xstate").MetaObject>;
+    id: string | undefined;
+}, {
+    type: "clearIsPlaying";
+    params: unknown;
+} | {
+    type: "clearNotifiedLookahead";
+    params: unknown;
+} | {
+    type: "clearPendingPlay";
+    params: unknown;
+} | {
+    type: "clearPlayingAndSchedule";
+    params: unknown;
+} | {
+    type: "clearScheduleAndLookahead";
+    params: unknown;
+} | {
+    type: "clearScheduledStart";
+    params: unknown;
+} | {
+    type: "crossoverHtml5ToWebAudio";
+    params: unknown;
+} | {
+    type: "freezePausedTime";
+    params: unknown;
+} | {
+    type: "notifyBufferReady";
+    params: unknown;
+} | {
+    type: "notifyTrackEnded";
+    params: unknown;
+} | {
+    type: "pauseHtml5";
+    params: unknown;
+} | {
+    type: "playHtml5";
+    params: unknown;
+} | {
+    type: "reportProgress";
+    params: unknown;
+} | {
+    type: "resetHtml5Element";
+    params: unknown;
+} | {
+    type: "resetTiming";
+    params: unknown;
+} | {
+    type: "seekHtml5";
+    params: unknown;
+} | {
+    type: "seekWebAudio";
+    params: unknown;
+} | {
+    type: "setErrorState";
+    params: unknown;
+} | {
+    type: "setIsPlaying";
+    params: unknown;
+} | {
+    type: "setLoadedState";
+    params: unknown;
+} | {
+    type: "setLoadingState";
+    params: unknown;
+} | {
+    type: "setNotifiedLookahead";
+    params: unknown;
+} | {
+    type: "setPendingPlay";
+    params: unknown;
+} | {
+    type: "setPlaybackTypeWebAudio";
+    params: unknown;
+} | {
+    type: "setPlayingWebAudio";
+    params: unknown;
+} | {
+    type: "setPlayingWebAudioType";
+    params: unknown;
+} | {
+    type: "setResolvedUrl";
+    params: unknown;
+} | {
+    type: "setScheduledGapless";
+    params: unknown;
+} | {
+    type: "startProgressLoop";
+    params: unknown;
+} | {
+    type: "startScheduledSourceNode";
+    params: unknown;
+} | {
+    type: "startSourceNode";
+    params: unknown;
+} | {
+    type: "stopProgressLoop";
+    params: unknown;
+} | {
+    type: "stopSourceNode";
+    params: unknown;
+} | {
+    type: "triggerFetchForPendingPlay";
+    params: unknown;
+}, {
+    type: "canPlayWebAudio";
+    params: unknown;
+} | {
+    type: "canStartFetch";
+    params: unknown;
+} | {
+    type: "isWebAudioOnly";
+    params: unknown;
+}, never, "html5" | "idle" | "loading" | "webaudio", string, import("xstate").NonReducibleUnknown, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "track";
+    states: {
+        readonly idle: {};
+        readonly html5: {};
+        readonly loading: {};
+        readonly webaudio: {};
+    };
+}, import("xstate").MetaObject>;
+export type TrackMachine = ReturnType<typeof createTrackMachine>;
+//# sourceMappingURL=track.machine.d.ts.map

package/dist/machines/track.machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.machine.d.ts","sourceRoot":"","sources":["../../src/machines/track.machine.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAInE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;IAC3B,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,SAAS,EAAE,OAAO,CAAC;IACnB,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,+EAA+E;IAC/E,WAAW,EAAE,OAAO,CAAC;CACtB;AAID,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAIlC,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,YAAY;UArBnD,UAAU;;UACV,YAAY;;UACZ,SAAS;;UACT,gBAAgB;;UAChB,MAAM;;UACN,eAAe;;UACf,OAAO;;UACP,MAAM;UAAQ,MAAM;;UACpB,YAAY;YAAU,MAAM;;UAC5B,cAAc;;UACd,cAAc;;UACd,aAAa;;UACb,gBAAgB;;UAChB,cAAc;SAAO,MAAM;;UAC3B,aAAa;;UACb,kBAAkB;UAAQ,MAAM;;UAChC,gBAAgB;;UAChB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCA8a9B;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+export type PlaybackType = 'HTML5' | 'WEBAUDIO';
+/**
+ * Controls how audio is rendered.
+ * - `'HYBRID'` (default): Starts with HTML5 audio, then switches to Web Audio after decode. Best for remote files.
+ * - `'HTML5_ONLY'`: Uses HTML5 audio exclusively. Gapless playback is not available.
+ * - `'WEBAUDIO_ONLY'`: Uses Web Audio API exclusively. Audio must fully buffer before playing — only use for very small or local files.
+ */
+export type PlaybackMethod = 'HYBRID' | 'HTML5_ONLY' | 'WEBAUDIO_ONLY';
+export type WebAudioLoadingState = 'NONE' | 'LOADING' | 'LOADED' | 'ERROR';
+/** Metadata attached to a track (arbitrary user data). */
+export interface TrackMetadata {
+    title?: string;
+    artist?: string;
+    album?: string;
+    artwork?: MediaImage[];
+    [key: string]: unknown;
+}
+/** Options accepted by the Queue constructor. */
+export interface GaplessOptions {
+    /** Initial list of track URLs. */
+    tracks?: string[];
+    /** Called at ~60fps while playing. */
+    onProgress?: (info: TrackInfo) => void;
+    /** Called when the last track in the queue ends. */
+    onEnded?: () => void;
+    /** Called when the queue advances to the next track. */
+    onPlayNextTrack?: (info: TrackInfo) => void;
+    /** Called when the queue goes back to the previous track. */
+    onPlayPreviousTrack?: (info: TrackInfo) => void;
+    /** Called whenever a new track becomes the current track. */
+    onStartNewTrack?: (info: TrackInfo) => void;
+    /** Called on HTML5 audio errors. */
+    onError?: (error: Error) => void;
+    /** Called with internal debug messages. Only use for development. */
+    onDebug?: (msg: string) => void;
+    /** Called when autoplay is blocked by the browser. */
+    onPlayBlocked?: () => void;
+    /**
+     * Controls how audio is rendered.
+     * - `'HYBRID'` (default): Starts with HTML5 audio, switches to Web Audio after decode. Best for remote files.
+     * - `'HTML5_ONLY'`: HTML5 audio only. Gapless playback is not available.
+     * - `'WEBAUDIO_ONLY'`: Web Audio API only. Audio must fully buffer before playing.
+     */
+    playbackMethod?: PlaybackMethod;
+    /** Per-track metadata (aligned to the tracks array by index). */
+    trackMetadata?: TrackMetadata[];
+    /** Initial volume, 0.0–1.0. Defaults to 1. */
+    volume?: number;
+    /**
+     * Number of tracks to preload ahead of the current track.
+     * Defaults to 2. Set to 0 to disable preloading.
+     */
+    preloadNumTracks?: number;
+    /**
+     * Initial playback rate, 0.25–4.0. Defaults to 1.
+     */
+    playbackRate?: number;
+}
+/** Options for dynamically adding a track. */
+export interface AddTrackOptions {
+    /**
+     * Skip the HEAD request used to resolve redirects.
+     * Set true when the URL is already a direct, final URL.
+     */
+    skipHEAD?: boolean;
+    metadata?: TrackMetadata;
+}
+/**
+ * A plain-data snapshot of a track's current state.
+ * Returned by Queue getters and passed to callbacks.
+ * No methods — pure data.
+ */
+export interface TrackInfo {
+    /** Zero-based position of this track in the queue. */
+    index: number;
+    /** Current playback position in seconds. */
+    currentTime: number;
+    /** Total duration in seconds (NaN until loaded). */
+    duration: number;
+    /** True if currently playing. */
+    isPlaying: boolean;
+    /** True if explicitly paused. */
+    isPaused: boolean;
+    /** Current volume, 0.0–1.0. */
+    volume: number;
+    /** The resolved URL of the audio file. */
+    trackUrl: string;
+    /** Which backend is currently producing sound. */
+    playbackType: PlaybackType;
+    /** Whether the Web Audio buffer has been decoded. */
+    webAudioLoadingState: WebAudioLoadingState;
+    /** Arbitrary metadata supplied when the track was added. */
+    metadata?: TrackMetadata;
+    /** Current playback rate. */
+    playbackRate: number;
+    /** Current xstate machine state for this track (e.g. 'idle', 'html5', 'webaudio'). */
+    machineState: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,YAAY,GAAG,eAAe,CAAC;AAEvE,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3E,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,sCAAsC;IACtC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACvC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,wDAAwD;IACxD,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAC5C,6DAA6D;IAC7D,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAChD,6DAA6D;IAC7D,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAC5C,oCAAoC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iEAAiE;IACjE,aAAa,CAAC,EAAE,aAAa,EAAE,CAAC;IAChC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,YAAY,EAAE,YAAY,CAAC;IAC3B,qDAAqD;IACrD,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/utils/audioContext.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Return the shared AudioContext if it has already been created, otherwise null.
+ *
+ * Does NOT create the context — call resumeAudioContext() from a user-gesture
+ * handler to create and resume it. This prevents the browser warning:
+ * "An AudioContext was prevented from starting automatically."
+ */
+export declare function getAudioContext(): AudioContext | null;
+/**
+ * Create (if needed) and resume the AudioContext.
+ * Must be called from a user-gesture handler (click, keydown, etc.).
+ * Safe to call multiple times — subsequent calls are cheap no-ops.
+ */
+export declare function resumeAudioContext(): Promise<void>;
+/**
+ * Reset the cached AudioContext — used in tests so each test gets a fresh mock.
+ * @internal
+ */
+export declare function _resetAudioContext(): void;
+/**
+ * Directly set the cached AudioContext — used in tests to inject a mock instance.
+ * @internal
+ */
+export declare function _setAudioContext(ctx: AudioContext | null): void;
+//# sourceMappingURL=audioContext.d.ts.map

package/dist/utils/audioContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioContext.d.ts","sourceRoot":"","sources":["../../src/utils/audioContext.ts"],"names":[],"mappings":"AAuBA;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAMrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CASlD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAE/D"}

package/dist/utils/mediaSession.d.ts

@@ -0,0 +1,17 @@
+import type { TrackMetadata } from '../types';
+export interface MediaSessionHandlers {
+    onPlay: () => void;
+    onPause: () => void;
+    onNext: () => void;
+    onPrevious: () => void;
+    onSeek: (time: number) => void;
+}
+/** Register Media Session action handlers. Call once after construction. */
+export declare function setupMediaSession(handlers: MediaSessionHandlers): void;
+/** Update the OS metadata display (title, artist, album, artwork). */
+export declare function updateMediaSessionMetadata(metadata?: TrackMetadata): void;
+/** Sync the OS playback state indicator (playing / paused). */
+export declare function updateMediaSessionPlaybackState(isPlaying: boolean): void;
+/** Update the OS position/duration display (lock screen scrubber). */
+export declare function updateMediaSessionPositionState(duration: number, position: number, playbackRate?: number): void;
+//# sourceMappingURL=mediaSession.d.ts.map

package/dist/utils/mediaSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaSession.d.ts","sourceRoot":"","sources":["../../src/utils/mediaSession.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAK9C,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAUtE;AAED,sEAAsE;AACtE,wBAAgB,0BAA0B,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI,CAYzE;AAED,+DAA+D;AAC/D,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,OAAO,GACjB,IAAI,CAGN;AAED,sEAAsE;AACtE,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,YAAY,SAAI,GACf,IAAI,CAON"}

package/dist/utils/throttle.d.ts

@@ -0,0 +1,3 @@
+/** Returns a throttled version of `fn` that fires at most once per `ms`. */
+export declare function throttle<T extends (...args: any[]) => void>(fn: T, ms: number): (...args: Parameters<T>) => void;
+//# sourceMappingURL=throttle.d.ts.map

package/dist/utils/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../src/utils/throttle.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EACzD,EAAE,EAAE,CAAC,EACL,EAAE,EAAE,MAAM,GACT,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAQlC"}