gapless 4.4.0 → 4.4.2

package/dist/Queue.d.ts

@@ -0,0 +1,72 @@
+import { Track } from './Track';
+import type { TrackQueueRef } from './Track';
+import type { GaplessOptions, AddTrackOptions, TrackInfo, PlaybackMethod } from './types';
+export declare class Queue implements TrackQueueRef {
+    private _tracks;
+    private readonly _actor;
+    private readonly _onProgress?;
+    private readonly _onEnded?;
+    private readonly _onPlayNextTrack?;
+    private readonly _onPlayPreviousTrack?;
+    private readonly _onStartNewTrack?;
+    private readonly _onError?;
+    private readonly _onPlayBlocked?;
+    private readonly _onDebug?;
+    readonly playbackMethod: PlaybackMethod;
+    private _volume;
+    private _preloadNumTracks;
+    private _playbackRate;
+    /** Silent looping element that keeps the browser's MediaSession anchor alive. */
+    private _mediaSessionAnchor;
+    /** Index of the next track with a pre-scheduled gapless start, or null. */
+    private _scheduledNextIndex;
+    private _throttledUpdatePositionState;
+    constructor(options?: GaplessOptions);
+    play(): void;
+    pause(): void;
+    togglePlayPause(): void;
+    next(): void;
+    previous(): void;
+    gotoTrack(index: number, playImmediately?: boolean, startTime?: number): void;
+    seek(time: number): void;
+    setVolume(volume: number): void;
+    setPlaybackRate(rate: number): void;
+    addTrack(url: string, options?: AddTrackOptions): void;
+    removeTrack(index: number): void;
+    resumeAudioContext(): Promise<void>;
+    destroy(): void;
+    get currentTrack(): TrackInfo | undefined;
+    get currentTrackIndex(): number;
+    get tracks(): readonly TrackInfo[];
+    get isPlaying(): boolean;
+    get isPaused(): boolean;
+    get volume(): number;
+    get preloadNumTracks(): number;
+    set preloadNumTracks(value: number);
+    get playbackRate(): number;
+    /** Snapshot of the queue state machine (state name + context). For debugging. */
+    get queueSnapshot(): {
+        state: string;
+        context: {
+            currentTrackIndex: number;
+            trackCount: number;
+        };
+    };
+    onTrackEnded(track: Track): void;
+    onTrackBufferReady(track: Track): void;
+    onProgress(info: TrackInfo): void;
+    onError(error: Error): void;
+    onPlayBlocked(): void;
+    onPreloadReady(track: Track): void;
+    onDebug(msg: string): void;
+    /** Look up a track by index — safe for use inside machine actions. */
+    private _trackAt;
+    private get _currentTrack();
+    private _preloadAhead;
+    private _cancelScheduledGapless;
+    private _tryScheduleGapless;
+    private _computeTrackEndTime;
+    private _startMediaSessionAnchor;
+    private _stopMediaSessionAnchor;
+}
+//# sourceMappingURL=Queue.d.ts.map

package/dist/Queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Queue.d.ts","sourceRoot":"","sources":["../src/Queue.ts"],"names":[],"mappings":"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"}

package/dist/Track.d.ts

@@ -0,0 +1,150 @@
+import type { TrackInfo, TrackMetadata, WebAudioLoadingState, PlaybackType, PlaybackMethod } from './types';
+export interface TrackQueueRef {
+    onTrackEnded(track: Track): void;
+    onTrackBufferReady(track: Track): void;
+    onPreloadReady(track: Track): void;
+    onProgress(info: TrackInfo): void;
+    onError(error: Error): void;
+    onPlayBlocked(): void;
+    onDebug(msg: string): void;
+    readonly volume: number;
+    readonly playbackMethod: PlaybackMethod;
+    readonly playbackRate: number;
+    readonly currentTrackIndex: number;
+}
+export declare class Track {
+    readonly index: number;
+    readonly metadata: TrackMetadata;
+    private _trackUrl;
+    private _resolvedUrl;
+    private readonly skipHEAD;
+    /** Temporary holder between fetch and decode steps (unserializable — stays on Track class). */
+    private _pendingArrayBuffer;
+    readonly audio: HTMLAudioElement;
+    private readonly _playbackMethod;
+    private get ctx();
+    private gainNode;
+    private _mediaElementSource;
+    private _html5GainNode;
+    private sourceNode;
+    audioBuffer: AudioBuffer | null;
+    /** AudioContext.currentTime at the start of the current playback segment. */
+    /**
+     * Offset (in seconds) between the decoded buffer's "offset 0" and the music's
+     * "offset 0". Some MP3 files include ID3v2 metadata, encoder priming samples,
+     * or container padding at the start; HTML5 audio elements skip past these
+     * natively (audio.currentTime=0 means music start), but `decodeAudioData` in
+     * some browsers includes them in the decoded buffer (buffer offset 0 = file
+     * start, music actually starts at offset _bufferStartPaddingSec).
+     *
+     * Without this shift, calling source.start(when, audio.currentTime) plays
+     * `audio.currentTime` seconds AHEAD of what HTML5 was just outputting,
+     * sounding like a backward skip at crossover. We compute this once both
+     * the buffer and audio.duration are known, and apply it as
+     *     source.start(when, trackTime + _bufferStartPaddingSec)
+     * everywhere we read from the buffer. User-facing time (currentTime/duration
+     * getters) continues to be reported in music-time, not buffer-time.
+     */
+    private _bufferStartPaddingSec;
+    private _bufferAlignmentMeasured;
+    private _waRefCtxTime;
+    /** Track position (seconds) at the start of the current playback segment. */
+    private _waRefTrackTime;
+    /** Track-time (seconds) frozen at the moment of the most recent pause. */
+    private pausedAtTrackTime;
+    private readonly _actor;
+    private readonly queueRef;
+    private rafId;
+    private _notifiedPreloadThreshold;
+    constructor(opts: {
+        trackUrl: string;
+        index: number;
+        queue: TrackQueueRef;
+        skipHEAD?: boolean;
+        metadata?: TrackMetadata;
+    });
+    play(): void;
+    pause(): void;
+    seek(time: number): void;
+    setVolume(v: number): void;
+    setPlaybackRate(rate: number): void;
+    preload(): void;
+    seekToEnd(secondsFromEnd?: number): void;
+    activate(): void;
+    deactivate(): void;
+    destroy(): void;
+    /** Schedule the HTML5 gain node to mute at `when` — safety valve so an
+     *  HTML5 element that runs past the predicted end is silenced instead of
+     *  overlapping the next track. No-op if the HTML5 gain path isn't active. */
+    scheduleHtml5Mute(when: number): void;
+    /** Cancel any scheduled HTML5 gain mute (called when gapless is cancelled). */
+    cancelHtml5Mute(): void;
+    cancelGaplessStart(): void;
+    scheduleGaplessStart(when: number): boolean;
+    get currentTime(): number;
+    get duration(): number;
+    get isPaused(): boolean;
+    get isPlaying(): boolean;
+    get trackUrl(): string;
+    get playbackType(): PlaybackType;
+    get webAudioLoadingState(): WebAudioLoadingState;
+    get hasSourceNode(): boolean;
+    get machineState(): string;
+    get scheduledStartContextTime(): number | null;
+    /**
+     * Context-clock time at which the currently playing Web Audio source will
+     * reach the end of its buffer, derived from the live playback anchor
+     * (_waRefCtxTime/_waRefTrackTime). The anchor is re-established every time
+     * a source node starts (scheduled gapless start, resume, seek, crossover),
+     * so this stays correct across interruptions — unlike
+     * scheduledStartContextTime + duration, which goes stale the moment a
+     * pause/resume re-anchors the source at a later context time. For an
+     * uninterrupted gapless chain it is exact (the anchor IS the scheduled
+     * start), so next-track scheduling stays sample-accurate.
+     *
+     * Null when no source node is active (idle/html5/loading, or paused).
+     */
+    get playbackEndContextTime(): number | null;
+    get isBufferLoaded(): boolean;
+    toInfo(): TrackInfo;
+    private _playHtml5;
+    private _seekHtml5;
+    /**
+     * Mid-stream crossover: switch an actively-playing HTML5 track to Web Audio.
+     *
+     * Why this exists: we cannot reliably predict when an HTML5 <audio> element
+     * will fire 'ended' from within the AudioContext clock. Any prediction is
+     * at the mercy of the browser's audio pipeline (buffering stalls, codec
+     * padding differences, clock drift between audio.currentTime and
+     * ctx.currentTime over long sessions). Scheduling the next gapless track
+     * against that prediction is how overlap bugs happen.
+     *
+     * Instead, as soon as the buffer is decoded, we hand playback off to Web
+     * Audio while the track is still mid-song. From that point on, the track
+     * and all subsequent gapless transitions live on a single clock
+     * (AudioContext.currentTime), so scheduling is sample-accurate by
+     * construction — no prediction involved.
+     *
+     * Ordering: pause the HTML5 element FIRST, then start the source node at
+     * the captured offset. Pausing first ensures audio.currentTime is frozen
+     * before we read it as the Web Audio start offset, so there's no brief
+     * double-audio window at the crossover point.
+     */
+    private _crossoverHtml5ToWebAudio;
+    /**
+     * Reverted: alignment-based fixes (duration-delta and buffer-silence
+     * scanning) reduced the perceived skip on archive.org files but did not
+     * eliminate it, suggesting the residual gap isn't a buffer/timeline
+     * alignment problem at all. Leaving _bufferStartPaddingSec at 0 (no shift)
+     * until we have a confirmed root cause; the field and call sites are kept
+     * so we can re-introduce a fix without churning the source-start code.
+     */
+    private _maybeComputeBufferAlignment;
+    private _startSourceNode;
+    private _stopSourceNode;
+    private _seekWebAudio;
+    private _handleWebAudioEnded;
+    startProgressLoop(): void;
+    private _stopProgressLoop;
+}
+//# sourceMappingURL=Track.d.ts.map

package/dist/Track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Track.d.ts","sourceRoot":"","sources":["../src/Track.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,318 +1,4 @@
-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.
- */
-type PlaybackMethod = 'HYBRID' | 'HTML5_ONLY' | 'WEBAUDIO_ONLY';
-type WebAudioLoadingState = 'NONE' | 'LOADING' | 'LOADED' | 'ERROR';
-/** Metadata attached to a track (arbitrary user data). */
-interface TrackMetadata {
-    title?: string;
-    artist?: string;
-    album?: string;
-    artwork?: MediaImage[];
-    [key: string]: unknown;
-}
-/** Options accepted by the Queue constructor. */
-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. */
-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.
- */
-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;
-}
-
-interface TrackQueueRef {
-    onTrackEnded(track: Track): void;
-    onTrackBufferReady(track: Track): void;
-    onPreloadReady(track: Track): void;
-    onProgress(info: TrackInfo): void;
-    onError(error: Error): void;
-    onPlayBlocked(): void;
-    onDebug(msg: string): void;
-    readonly volume: number;
-    readonly playbackMethod: PlaybackMethod;
-    readonly playbackRate: number;
-    readonly currentTrackIndex: number;
-}
-declare class Track {
-    readonly index: number;
-    readonly metadata: TrackMetadata;
-    private _trackUrl;
-    private _resolvedUrl;
-    private readonly skipHEAD;
-    /** Temporary holder between fetch and decode steps (unserializable — stays on Track class). */
-    private _pendingArrayBuffer;
-    readonly audio: HTMLAudioElement;
-    private readonly _playbackMethod;
-    private get ctx();
-    private gainNode;
-    private _mediaElementSource;
-    private _html5GainNode;
-    private sourceNode;
-    audioBuffer: AudioBuffer | null;
-    /** AudioContext.currentTime at the start of the current playback segment. */
-    /**
-     * Offset (in seconds) between the decoded buffer's "offset 0" and the music's
-     * "offset 0". Some MP3 files include ID3v2 metadata, encoder priming samples,
-     * or container padding at the start; HTML5 audio elements skip past these
-     * natively (audio.currentTime=0 means music start), but `decodeAudioData` in
-     * some browsers includes them in the decoded buffer (buffer offset 0 = file
-     * start, music actually starts at offset _bufferStartPaddingSec).
-     *
-     * Without this shift, calling source.start(when, audio.currentTime) plays
-     * `audio.currentTime` seconds AHEAD of what HTML5 was just outputting,
-     * sounding like a backward skip at crossover. We compute this once both
-     * the buffer and audio.duration are known, and apply it as
-     *     source.start(when, trackTime + _bufferStartPaddingSec)
-     * everywhere we read from the buffer. User-facing time (currentTime/duration
-     * getters) continues to be reported in music-time, not buffer-time.
-     */
-    private _bufferStartPaddingSec;
-    private _bufferAlignmentMeasured;
-    private _waRefCtxTime;
-    /** Track position (seconds) at the start of the current playback segment. */
-    private _waRefTrackTime;
-    /** Track-time (seconds) frozen at the moment of the most recent pause. */
-    private pausedAtTrackTime;
-    private readonly _actor;
-    private readonly queueRef;
-    private rafId;
-    private _notifiedPreloadThreshold;
-    constructor(opts: {
-        trackUrl: string;
-        index: number;
-        queue: TrackQueueRef;
-        skipHEAD?: boolean;
-        metadata?: TrackMetadata;
-    });
-    play(): void;
-    pause(): void;
-    seek(time: number): void;
-    setVolume(v: number): void;
-    setPlaybackRate(rate: number): void;
-    preload(): void;
-    seekToEnd(secondsFromEnd?: number): void;
-    activate(): void;
-    deactivate(): void;
-    destroy(): void;
-    /** Schedule the HTML5 gain node to mute at `when` — safety valve so an
-     *  HTML5 element that runs past the predicted end is silenced instead of
-     *  overlapping the next track. No-op if the HTML5 gain path isn't active. */
-    scheduleHtml5Mute(when: number): void;
-    /** Cancel any scheduled HTML5 gain mute (called when gapless is cancelled). */
-    cancelHtml5Mute(): void;
-    cancelGaplessStart(): void;
-    scheduleGaplessStart(when: number): boolean;
-    get currentTime(): number;
-    get duration(): number;
-    get isPaused(): boolean;
-    get isPlaying(): boolean;
-    get trackUrl(): string;
-    get playbackType(): PlaybackType;
-    get webAudioLoadingState(): WebAudioLoadingState;
-    get hasSourceNode(): boolean;
-    get machineState(): string;
-    get scheduledStartContextTime(): number | null;
-    /**
-     * Context-clock time at which the currently playing Web Audio source will
-     * reach the end of its buffer, derived from the live playback anchor
-     * (_waRefCtxTime/_waRefTrackTime). The anchor is re-established every time
-     * a source node starts (scheduled gapless start, resume, seek, crossover),
-     * so this stays correct across interruptions — unlike
-     * scheduledStartContextTime + duration, which goes stale the moment a
-     * pause/resume re-anchors the source at a later context time. For an
-     * uninterrupted gapless chain it is exact (the anchor IS the scheduled
-     * start), so next-track scheduling stays sample-accurate.
-     *
-     * Null when no source node is active (idle/html5/loading, or paused).
-     */
-    get playbackEndContextTime(): number | null;
-    get isBufferLoaded(): boolean;
-    toInfo(): TrackInfo;
-    private _playHtml5;
-    private _seekHtml5;
-    /**
-     * Mid-stream crossover: switch an actively-playing HTML5 track to Web Audio.
-     *
-     * Why this exists: we cannot reliably predict when an HTML5 <audio> element
-     * will fire 'ended' from within the AudioContext clock. Any prediction is
-     * at the mercy of the browser's audio pipeline (buffering stalls, codec
-     * padding differences, clock drift between audio.currentTime and
-     * ctx.currentTime over long sessions). Scheduling the next gapless track
-     * against that prediction is how overlap bugs happen.
-     *
-     * Instead, as soon as the buffer is decoded, we hand playback off to Web
-     * Audio while the track is still mid-song. From that point on, the track
-     * and all subsequent gapless transitions live on a single clock
-     * (AudioContext.currentTime), so scheduling is sample-accurate by
-     * construction — no prediction involved.
-     *
-     * Ordering: pause the HTML5 element FIRST, then start the source node at
-     * the captured offset. Pausing first ensures audio.currentTime is frozen
-     * before we read it as the Web Audio start offset, so there's no brief
-     * double-audio window at the crossover point.
-     */
-    private _crossoverHtml5ToWebAudio;
-    /**
-     * Reverted: alignment-based fixes (duration-delta and buffer-silence
-     * scanning) reduced the perceived skip on archive.org files but did not
-     * eliminate it, suggesting the residual gap isn't a buffer/timeline
-     * alignment problem at all. Leaving _bufferStartPaddingSec at 0 (no shift)
-     * until we have a confirmed root cause; the field and call sites are kept
-     * so we can re-introduce a fix without churning the source-start code.
-     */
-    private _maybeComputeBufferAlignment;
-    private _startSourceNode;
-    private _stopSourceNode;
-    private _seekWebAudio;
-    private _handleWebAudioEnded;
-    startProgressLoop(): void;
-    private _stopProgressLoop;
-}
-
-declare class Queue implements TrackQueueRef {
-    private _tracks;
-    private readonly _actor;
-    private readonly _onProgress?;
-    private readonly _onEnded?;
-    private readonly _onPlayNextTrack?;
-    private readonly _onPlayPreviousTrack?;
-    private readonly _onStartNewTrack?;
-    private readonly _onError?;
-    private readonly _onPlayBlocked?;
-    private readonly _onDebug?;
-    readonly playbackMethod: PlaybackMethod;
-    private _volume;
-    private _preloadNumTracks;
-    private _playbackRate;
-    /** Silent looping element that keeps the browser's MediaSession anchor alive. */
-    private _mediaSessionAnchor;
-    /** Index of the next track with a pre-scheduled gapless start, or null. */
-    private _scheduledNextIndex;
-    private _throttledUpdatePositionState;
-    constructor(options?: GaplessOptions);
-    play(): void;
-    pause(): void;
-    togglePlayPause(): void;
-    next(): void;
-    previous(): void;
-    gotoTrack(index: number, playImmediately?: boolean): void;
-    seek(time: number): void;
-    setVolume(volume: number): void;
-    setPlaybackRate(rate: number): void;
-    addTrack(url: string, options?: AddTrackOptions): void;
-    removeTrack(index: number): void;
-    resumeAudioContext(): Promise<void>;
-    destroy(): void;
-    get currentTrack(): TrackInfo | undefined;
-    get currentTrackIndex(): number;
-    get tracks(): readonly TrackInfo[];
-    get isPlaying(): boolean;
-    get isPaused(): boolean;
-    get volume(): number;
-    get preloadNumTracks(): number;
-    set preloadNumTracks(value: number);
-    get playbackRate(): number;
-    /** Snapshot of the queue state machine (state name + context). For debugging. */
-    get queueSnapshot(): {
-        state: string;
-        context: {
-            currentTrackIndex: number;
-            trackCount: number;
-        };
-    };
-    onTrackEnded(track: Track): void;
-    onTrackBufferReady(track: Track): void;
-    onProgress(info: TrackInfo): void;
-    onError(error: Error): void;
-    onPlayBlocked(): void;
-    onPreloadReady(track: Track): void;
-    onDebug(msg: string): void;
-    /** Look up a track by index — safe for use inside machine actions. */
-    private _trackAt;
-    private get _currentTrack();
-    private _preloadAhead;
-    private _cancelScheduledGapless;
-    private _tryScheduleGapless;
-    private _computeTrackEndTime;
-    private _startMediaSessionAnchor;
-    private _stopMediaSessionAnchor;
-}
-
-export { type AddTrackOptions, type GaplessOptions, type PlaybackType, Queue, type TrackInfo, type TrackMetadata, type WebAudioLoadingState, Queue as default };
+export { Queue } from './Queue';
+export type { GaplessOptions, AddTrackOptions, TrackInfo, TrackMetadata, PlaybackType, WebAudioLoadingState, } from './types';
+export { Queue as default } from './Queue';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EACV,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,EACb,YAAY,EACZ,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,KAAK,IAAI,OAAO,EAAE,MAAM,SAAS,CAAC"}