audioq 2.0.0

package/dist/queue-manipulation.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * @fileoverview Queue manipulation functions for the audioq package
+ * Provides advanced queue management including item removal, reordering, and clearing
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.swapQueueItems = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.reorderQueue = exports.removeQueuedItem = void 0;
+const info_1 = require("./info");
+const events_1 = require("./events");
+const events_2 = require("./events");
+const utils_1 = require("./utils");
+/**
+ * Removes a specific item from the queue by its slot number (0-based index)
+ * Cannot remove the currently playing item (index 0) - use stopCurrentAudioInChannel instead
+ * @param queuedSlotNumber - Zero-based index of the item to remove (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to remove currently playing item or invalid slot number
+ * @example
+ * ```typescript
+ * // Remove the second item in queue (index 1)
+ * const result = await removeQueuedItem(1, 0);
+ * if (result.success) {
+ *   console.log(`Removed item, queue now has ${result.updatedQueue.totalItems} items`);
+ * }
+ *
+ * // Remove the third item from channel 1
+ * await removeQueuedItem(2, 1);
+ * ```
+ */
+const removeQueuedItem = (queuedSlotNumber_1, ...args_1) => __awaiter(void 0, [queuedSlotNumber_1, ...args_1], void 0, function* (queuedSlotNumber, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (queuedSlotNumber < 0 || queuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid slot number ${queuedSlotNumber}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (queuedSlotNumber === 0) {
+        return {
+            error: 'Cannot remove currently playing item (index 0). ' +
+                'Use stopCurrentAudioInChannel() instead',
+            success: false
+        };
+    }
+    // Remove the audio element from the queue
+    const removedAudio = channel.queue.splice(queuedSlotNumber, 1)[0];
+    // Clean up any progress tracking for the removed audio
+    (0, events_2.cleanupProgressTracking)(removedAudio, channelNumber, info_1.audioChannels);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.removeQueuedItem = removeQueuedItem;
+/**
+ * Reorders a queue item by moving it from one position to another
+ * Cannot reorder the currently playing item (index 0)
+ * @param currentQueuedSlotNumber - Current zero-based index of the item to move (must be > 0)
+ * @param newQueuedSlotNumber - New zero-based index where the item should be placed (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to reorder currently playing item or invalid slot numbers
+ * @example
+ * ```typescript
+ * // Move item from position 2 to position 1 (make it play next)
+ * const result = await reorderQueue(2, 1, 0);
+ * if (result.success) {
+ *   console.log('Item moved successfully');
+ * }
+ *
+ * // Move item from position 1 to end of queue
+ * await reorderQueue(1, 4, 0); // Assuming queue has 5+ items
+ * ```
+ */
+const reorderQueue = (currentQueuedSlotNumber_1, newQueuedSlotNumber_1, ...args_1) => __awaiter(void 0, [currentQueuedSlotNumber_1, newQueuedSlotNumber_1, ...args_1], void 0, function* (currentQueuedSlotNumber, newQueuedSlotNumber, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber < 0 || currentQueuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid current slot number ${currentQueuedSlotNumber}. Queue has ` +
+                `${channel.queue.length} items (indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (newQueuedSlotNumber < 0 || newQueuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid new slot number ${newQueuedSlotNumber}. Queue has ` +
+                `${channel.queue.length} items (indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber === 0) {
+        return {
+            error: 'Cannot reorder currently playing item (index 0). ' + 'Stop current audio first if needed',
+            success: false
+        };
+    }
+    if (newQueuedSlotNumber === 0) {
+        return {
+            error: 'Cannot move item to currently playing position (index 0). ' +
+                'Use queueAudioPriority() to add items to front of queue',
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber === newQueuedSlotNumber) {
+        // No change needed, but return success
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Remove the item from its current position
+    const audioToMove = channel.queue.splice(currentQueuedSlotNumber, 1)[0];
+    // Insert it at the new position
+    channel.queue.splice(newQueuedSlotNumber, 0, audioToMove);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.reorderQueue = reorderQueue;
+/**
+ * Clears all queued audio items after the currently playing item
+ * The current audio will continue playing but nothing will follow it
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Let current song finish but clear everything after it
+ * const result = await clearQueueAfterCurrent(0);
+ * if (result.success) {
+ *   console.log(`Cleared queue, current audio will be the last to play`);
+ * }
+ * ```
+ */
+const clearQueueAfterCurrent = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        // For empty/non-existent channels, we can consider this a successful no-op
+        // since there's nothing to clear anyway
+        return {
+            success: true,
+            updatedQueue: {
+                channelNumber,
+                currentIndex: -1,
+                isPaused: false,
+                items: [],
+                totalItems: 0,
+                volume: 1.0
+            }
+        };
+    }
+    if (channel.queue.length <= 1) {
+        // Nothing to clear - either empty queue or only current audio
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Clean up progress tracking for all items except the current one
+    for (let i = 1; i < channel.queue.length; i++) {
+        (0, events_2.cleanupProgressTracking)(channel.queue[i], channelNumber, info_1.audioChannels);
+    }
+    // Keep only the currently playing audio (index 0)
+    channel.queue = channel.queue.slice(0, 1);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.clearQueueAfterCurrent = clearQueueAfterCurrent;
+/**
+ * Gets information about a specific queue item by its slot number
+ * @param queueSlotNumber - Zero-based index of the queue item
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns QueueItem information or null if slot doesn't exist
+ * @example
+ * ```typescript
+ * const itemInfo = getQueueItemInfo(1, 0);
+ * if (itemInfo) {
+ *   console.log(`Next to play: ${itemInfo.fileName}`);
+ *   console.log(`Duration: ${itemInfo.duration}ms`);
+ * }
+ * ```
+ */
+const getQueueItemInfo = (queueSlotNumber, channelNumber = 0) => {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel || queueSlotNumber < 0 || queueSlotNumber >= channel.queue.length) {
+        return null;
+    }
+    const audio = channel.queue[queueSlotNumber];
+    const audioInfo = (0, utils_1.getAudioInfoFromElement)(audio, channelNumber, info_1.audioChannels);
+    if (!audioInfo) {
+        return null;
+    }
+    const { duration, fileName, isLooping, isPlaying, src, volume } = audioInfo;
+    return {
+        duration,
+        fileName,
+        isCurrentlyPlaying: queueSlotNumber === 0 && isPlaying,
+        isLooping,
+        src,
+        volume
+    };
+};
+exports.getQueueItemInfo = getQueueItemInfo;
+/**
+ * Gets the current queue length for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Number of items in the queue, or 0 if channel doesn't exist
+ * @example
+ * ```typescript
+ * const queueSize = getQueueLength(0);
+ * console.log(`Channel 0 has ${queueSize} items in queue`);
+ * ```
+ */
+const getQueueLength = (channelNumber = 0) => {
+    const channel = info_1.audioChannels[channelNumber];
+    return channel ? channel.queue.length : 0;
+};
+exports.getQueueLength = getQueueLength;
+/**
+ * Swaps the positions of two queue items
+ * Cannot swap with the currently playing item (index 0)
+ * @param slotA - Zero-based index of first item to swap (must be > 0)
+ * @param slotB - Zero-based index of second item to swap (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Swap the second and third items in queue
+ * const result = await swapQueueItems(1, 2, 0);
+ * if (result.success) {
+ *   console.log('Items swapped successfully');
+ * }
+ * ```
+ */
+const swapQueueItems = (slotA_1, slotB_1, ...args_1) => __awaiter(void 0, [slotA_1, slotB_1, ...args_1], void 0, function* (slotA, slotB, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (slotA < 0 || slotA >= channel.queue.length) {
+        return {
+            error: `Invalid slot A ${slotA}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (slotB < 0 || slotB >= channel.queue.length) {
+        return {
+            error: `Invalid slot B ${slotB}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (slotA === 0 || slotB === 0) {
+        return {
+            error: 'Cannot swap with currently playing item (index 0)',
+            success: false
+        };
+    }
+    if (slotA === slotB) {
+        // No change needed, but return success
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Swap the audio elements
+    const temp = channel.queue[slotA];
+    channel.queue[slotA] = channel.queue[slotB];
+    channel.queue[slotB] = temp;
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.swapQueueItems = swapQueueItems;

package/dist/types.d.ts

@@ -0,0 +1,382 @@
+/**
+ * @fileoverview Type definitions for the audioq package
+ */
+/**
+ * Maximum number of audio channels allowed to prevent memory exhaustion
+ */
+export declare const MAX_CHANNELS: number;
+/**
+ * Symbol used as a key for global (channel-wide) progress callbacks
+ * This avoids the need for `null as any` type assertions
+ */
+export declare const GLOBAL_PROGRESS_KEY: unique symbol;
+/**
+ * Array of HTMLAudioElement objects representing an audio queue
+ */
+export type AudioQueue = HTMLAudioElement[];
+/**
+ * Basic audio queue channel structure
+ */
+export interface AudioQueueChannel {
+    queue: AudioQueue;
+}
+/**
+ * Volume ducking configuration for channels
+ */
+export interface VolumeConfig {
+    /** Duration in milliseconds for volume duck transition (defaults to 250ms) */
+    duckTransitionDuration?: number;
+    /** Volume level for all other channels when priority channel is active (0-1) */
+    duckingVolume: number;
+    /** The channel number that should have priority */
+    priorityChannel: number;
+    /** Volume level for the priority channel (0-1) */
+    priorityVolume: number;
+    /** Duration in milliseconds for volume restore transition (defaults to 250ms) */
+    restoreTransitionDuration?: number;
+    /** Easing function for volume transitions (defaults to 'ease-out') */
+    transitionEasing?: EasingType;
+}
+/**
+ * Configuration options for queuing audio
+ */
+export interface AudioQueueOptions {
+    /** Whether to add this audio to the front of the queue (after currently playing) */
+    addToFront?: boolean;
+    /** Whether the audio should loop when it finishes */
+    loop?: boolean;
+    /** Maximum number of items allowed in the queue (defaults to unlimited) */
+    maxQueueSize?: number;
+    /** Volume level for this specific audio (0-1) */
+    volume?: number;
+}
+/**
+ * Global queue configuration options
+ */
+export interface QueueConfig {
+    /** Default maximum queue size across all channels (defaults to unlimited) */
+    defaultMaxQueueSize?: number;
+    /** Whether to drop oldest items when queue is full (defaults to false - reject new items) */
+    dropOldestWhenFull?: boolean;
+    /** Whether to show warnings when queue limits are reached (defaults to true) */
+    showQueueWarnings?: boolean;
+}
+/**
+ * Comprehensive audio information interface providing metadata about currently playing audio
+ */
+export interface AudioInfo {
+    /** Current playback position in milliseconds */
+    currentTime: number;
+    /** Total audio duration in milliseconds */
+    duration: number;
+    /** Extracted filename from the source URL */
+    fileName: string;
+    /** Whether the audio is set to loop */
+    isLooping: boolean;
+    /** Whether the audio is currently paused */
+    isPaused: boolean;
+    /** Whether the audio is currently playing */
+    isPlaying: boolean;
+    /** Playback progress as a decimal (0-1) */
+    progress: number;
+    /** Number of audio files remaining in the queue after current */
+    remainingInQueue: number;
+    /** Audio file source URL */
+    src: string;
+    /** Current volume level (0-1) */
+    volume: number;
+}
+/**
+ * Information provided when an audio file completes playback
+ */
+export interface AudioCompleteInfo {
+    /** Channel number where the audio completed */
+    channelNumber: number;
+    /** Extracted filename from the source URL */
+    fileName: string;
+    /** Number of audio files remaining in the queue after completion */
+    remainingInQueue: number;
+    /** Audio file source URL */
+    src: string;
+}
+/**
+ * Information provided when an audio file starts playing
+ */
+export interface AudioStartInfo {
+    /** Channel number where the audio is starting */
+    channelNumber: number;
+    /** Total audio duration in milliseconds */
+    duration: number;
+    /** Extracted filename from the source URL */
+    fileName: string;
+    /** Audio file source URL */
+    src: string;
+}
+/**
+ * Information about a single item in an audio queue
+ */
+export interface QueueItem {
+    /** Total audio duration in milliseconds */
+    duration: number;
+    /** Extracted filename from the source URL */
+    fileName: string;
+    /** Whether this item is currently playing */
+    isCurrentlyPlaying: boolean;
+    /** Whether this item is set to loop */
+    isLooping: boolean;
+    /** Audio file source URL */
+    src: string;
+    /** Volume level for this item (0-1) */
+    volume: number;
+}
+/**
+ * Complete snapshot of a queue's current state
+ */
+export interface QueueSnapshot {
+    /** Channel number this snapshot represents */
+    channelNumber: number;
+    /** Zero-based index of the currently playing item */
+    currentIndex: number;
+    /** Whether the current audio is paused */
+    isPaused: boolean;
+    /** Array of audio items in the queue with their metadata */
+    items: QueueItem[];
+    /** Total number of items in the queue */
+    totalItems: number;
+    /** Current volume level for the channel (0-1) */
+    volume: number;
+}
+/**
+ * Information about a queue manipulation operation result
+ */
+export interface QueueManipulationResult {
+    /** Error message if operation failed */
+    error?: string;
+    /** Whether the operation was successful */
+    success: boolean;
+    /** The queue snapshot after the operation (if successful) */
+    updatedQueue?: QueueSnapshot;
+}
+/**
+ * Callback function type for audio progress updates
+ * @param info Current audio information
+ */
+export type ProgressCallback = (info: AudioInfo) => void;
+/**
+ * Callback function type for queue change notifications
+ * @param queueSnapshot Current state of the queue
+ */
+export type QueueChangeCallback = (queueSnapshot: QueueSnapshot) => void;
+/**
+ * Callback function type for audio start notifications
+ * @param audioInfo Information about the audio that started
+ */
+export type AudioStartCallback = (audioInfo: AudioStartInfo) => void;
+/**
+ * Callback function type for audio complete notifications
+ * @param audioInfo Information about the audio that completed
+ */
+export type AudioCompleteCallback = (audioInfo: AudioCompleteInfo) => void;
+/**
+ * Callback function type for audio pause notifications
+ * @param channelNumber Channel that was paused
+ * @param audioInfo Information about the audio that was paused
+ */
+export type AudioPauseCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
+/**
+ * Callback function type for audio resume notifications
+ * @param channelNumber Channel that was resumed
+ * @param audioInfo Information about the audio that was resumed
+ */
+export type AudioResumeCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
+/**
+ * Types of audio errors that can occur during playback
+ */
+export declare enum AudioErrorType {
+    Abort = "abort",
+    Decode = "decode",
+    Network = "network",
+    Permission = "permission",
+    Timeout = "timeout",
+    Unknown = "unknown",
+    Unsupported = "unsupported"
+}
+/**
+ * Information about an audio error that occurred during playback or loading
+ */
+export interface AudioErrorInfo {
+    /** Channel number where the error occurred */
+    channelNumber: number;
+    /** The actual error object that was thrown */
+    error: Error;
+    /** Categorized type of error for handling different scenarios */
+    errorType: AudioErrorType;
+    /** Extracted filename from the source URL */
+    fileName: string;
+    /** Number of audio files remaining in the queue after this error */
+    remainingInQueue: number;
+    /** Current retry attempt number (if retrying is enabled) */
+    retryAttempt?: number;
+    /** Audio file source URL that failed */
+    src: string;
+    /** Unix timestamp when the error occurred */
+    timestamp: number;
+}
+/**
+ * Configuration for automatic retry behavior when audio fails to load or play
+ */
+export interface RetryConfig {
+    /** Initial delay in milliseconds before first retry attempt */
+    baseDelay: number;
+    /** Whether automatic retries are enabled for this channel */
+    enabled: boolean;
+    /** Whether to use exponential backoff (doubling delay each retry) */
+    exponentialBackoff: boolean;
+    /** Alternative URLs to try if the primary source fails */
+    fallbackUrls: string[];
+    /** Maximum number of retry attempts before giving up */
+    maxRetries: number;
+    /** Whether to skip to next track in queue if all retries fail */
+    skipOnFailure: boolean;
+    /** Timeout in milliseconds for each individual retry attempt */
+    timeoutMs: number;
+}
+/**
+ * Configuration options for error recovery mechanisms across the audio system
+ */
+export interface ErrorRecoveryOptions {
+    /** Whether to automatically retry failed audio loads/plays */
+    autoRetry: boolean;
+    /** Whether to automatically skip to next track when current fails */
+    fallbackToNextTrack: boolean;
+    /** Whether to send error data to analytics systems */
+    logErrorsToAnalytics: boolean;
+    /** Whether to maintain queue integrity when errors occur */
+    preserveQueueOnError: boolean;
+    /** Whether to display user-visible error feedback */
+    showUserFeedback: boolean;
+}
+/**
+ * Callback function type for audio error events
+ */
+export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
+/**
+ * Web Audio API configuration options
+ */
+export interface WebAudioConfig {
+    /** Whether to automatically use Web Audio API on iOS devices */
+    autoDetectIOS: boolean;
+    /** Whether Web Audio API support is enabled */
+    enabled: boolean;
+    /** Whether to force Web Audio API usage on all devices */
+    forceWebAudio: boolean;
+}
+/**
+ * Web Audio API support information
+ */
+export interface WebAudioSupport {
+    /** Whether Web Audio API is available in the current environment */
+    available: boolean;
+    /** Whether the current device is iOS */
+    isIOS: boolean;
+    /** Whether Web Audio API is currently being used */
+    usingWebAudio: boolean;
+    /** Reason for current Web Audio API usage state */
+    reason: string;
+}
+/**
+ * Web Audio API node set for audio element control
+ */
+export interface WebAudioNodeSet {
+    /** Gain node for volume control */
+    gainNode: GainNode;
+    /** Media element source node */
+    sourceNode: MediaElementAudioSourceNode;
+}
+/**
+ * Extended audio channel with comprehensive queue management, callback support, and state tracking
+ */
+export interface ExtendedAudioQueueChannel {
+    /** Set of callbacks triggered when audio completes playback */
+    audioCompleteCallbacks: Set<AudioCompleteCallback>;
+    /** Set of callbacks triggered when audio errors occur */
+    audioErrorCallbacks: Set<AudioErrorCallback>;
+    /** Set of callbacks triggered when audio is paused */
+    audioPauseCallbacks: Set<AudioPauseCallback>;
+    /** Set of callbacks triggered when audio is resumed */
+    audioResumeCallbacks: Set<AudioResumeCallback>;
+    /** Set of callbacks triggered when audio starts playing */
+    audioStartCallbacks: Set<AudioStartCallback>;
+    /** Current fade state if pause/resume with fade is active */
+    fadeState?: ChannelFadeState;
+    /** Whether the channel is currently paused */
+    isPaused: boolean;
+    /** Active operation lock to prevent race conditions */
+    isLocked?: boolean;
+    /** Maximum allowed queue size for this channel */
+    maxQueueSize?: number;
+    /** Map of progress callbacks keyed by audio element or global symbol */
+    progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
+    /** Array of HTMLAudioElement objects in the queue */
+    queue: HTMLAudioElement[];
+    /** Set of callbacks triggered when the queue changes */
+    queueChangeCallbacks: Set<QueueChangeCallback>;
+    /** Retry configuration for failed audio loads/plays */
+    retryConfig?: RetryConfig;
+    /** Current volume level for the channel (0-1) */
+    volume: number;
+    /** Web Audio API context for this channel */
+    webAudioContext?: AudioContext;
+    /** Map of Web Audio API nodes for each audio element */
+    webAudioNodes?: Map<HTMLAudioElement, WebAudioNodeSet>;
+}
+/**
+ * Easing function types for smooth volume transitions and animations
+ */
+export declare enum EasingType {
+    Linear = "linear",
+    EaseIn = "ease-in",
+    EaseOut = "ease-out",
+    EaseInOut = "ease-in-out"
+}
+/**
+ * Predefined fade types for pause/resume operations with different transition characteristics
+ */
+export declare enum FadeType {
+    Linear = "linear",
+    Gentle = "gentle",
+    Dramatic = "dramatic"
+}
+/**
+ * Timer implementation types used for volume transitions to ensure proper cleanup
+ */
+export declare enum TimerType {
+    RequestAnimationFrame = "raf",
+    Timeout = "timeout"
+}
+/**
+ * Configuration for fade transitions
+ */
+export interface FadeConfig {
+    /** Duration in milliseconds for the fade transition */
+    duration: number;
+    /** Easing curve to use when pausing (fading out) */
+    pauseCurve: EasingType;
+    /** Easing curve to use when resuming (fading in) */
+    resumeCurve: EasingType;
+}
+/**
+ * Internal fade state tracking for pause/resume with fade functionality
+ */
+export interface ChannelFadeState {
+    /** The original volume level before fading began */
+    originalVolume: number;
+    /** The type of fade being used */
+    fadeType: FadeType;
+    /** Whether the channel is currently paused due to fade */
+    isPaused: boolean;
+    /** Custom duration in milliseconds if specified (overrides fade type default) */
+    customDuration?: number;
+    /** Whether the channel is currently transitioning (during any fade operation) to prevent capturing intermediate volumes during rapid pause/resume toggles */
+    isTransitioning?: boolean;
+}