audio-channel-queue 1.10.0 → 1.12.0

package/dist/info.js

@@ -3,11 +3,71 @@
  * @fileoverview Audio information and progress tracking functions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.offAudioResume = exports.offAudioPause = exports.onAudioResume = exports.onAudioPause = exports.onAudioComplete = exports.onAudioStart = exports.offQueueChange = exports.onQueueChange = exports.onAudioProgress = exports.getQueueSnapshot = exports.getAllChannelsInfo = exports.getCurrentAudioInfo = exports.audioChannels = void 0;
+exports.offAudioComplete = exports.offAudioStart = exports.offAudioResume = exports.offAudioPause = exports.onAudioResume = exports.onAudioPause = exports.onAudioComplete = exports.onAudioStart = exports.offQueueChange = exports.onQueueChange = exports.onAudioProgress = exports.getQueueSnapshot = exports.getAllChannelsInfo = exports.getCurrentAudioInfo = exports.audioChannels = exports.getNonWhitelistedChannelProperties = exports.getWhitelistedChannelProperties = void 0;
 exports.offAudioProgress = offAudioProgress;
 const types_1 = require("./types");
 const utils_1 = require("./utils");
 const events_1 = require("./events");
+/**
+ * Gets the current list of whitelisted channel properties
+ * This is automatically derived from the ExtendedAudioQueueChannel interface
+ * @returns Array of whitelisted property names
+ * @internal
+ */
+const getWhitelistedChannelProperties = () => {
+    // Create a sample channel object to extract property names
+    const sampleChannel = {
+        audioCompleteCallbacks: new Set(),
+        audioErrorCallbacks: new Set(),
+        audioPauseCallbacks: new Set(),
+        audioResumeCallbacks: new Set(),
+        audioStartCallbacks: new Set(),
+        isPaused: false,
+        progressCallbacks: new Map(),
+        queue: [],
+        queueChangeCallbacks: new Set(),
+        volume: 1.0
+    };
+    // Get all property names from the interface (including optional ones)
+    const propertyNames = [
+        ...Object.getOwnPropertyNames(sampleChannel),
+        // Add optional properties that might not be present on the sample
+        'fadeState',
+        'isLocked',
+        'maxQueueSize',
+        'retryConfig',
+        'volumeConfig' // Legacy property that might still be used
+    ];
+    return [...new Set(propertyNames)]; // Remove duplicates
+};
+exports.getWhitelistedChannelProperties = getWhitelistedChannelProperties;
+/**
+ * Returns the list of non-whitelisted properties found on a specific channel
+ * These are properties that will trigger warnings when modified directly
+ * @param channelNumber - The channel number to inspect (defaults to 0)
+ * @returns Array of property names that are not in the whitelist, or empty array if channel doesn't exist
+ * @example
+ * ```typescript
+ * // Add some custom property to a channel
+ * (audioChannels[0] as any).customProperty = 'test';
+ *
+ * const nonWhitelisted = getNonWhitelistedChannelProperties(0);
+ * console.log(nonWhitelisted); // ['customProperty']
+ * ```
+ * @internal
+ */
+const getNonWhitelistedChannelProperties = (channelNumber = 0) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!channel) {
+        return [];
+    }
+    const whitelistedProperties = (0, exports.getWhitelistedChannelProperties)();
+    const allChannelProperties = Object.getOwnPropertyNames(channel);
+    // Filter out properties that are in the whitelist
+    const nonWhitelistedProperties = allChannelProperties.filter((property) => !whitelistedProperties.includes(property));
+    return nonWhitelistedProperties;
+};
+exports.getNonWhitelistedChannelProperties = getNonWhitelistedChannelProperties;
 /**
  * Global array to store audio channels with their queues and callback management
  * Each channel maintains its own audio queue and event callback sets
@@ -35,8 +95,9 @@ exports.audioChannels = new Proxy([], {
             return new Proxy(value, {
                 set(channelTarget, channelProp, channelValue) {
                     // Allow internal modifications but warn about direct property changes
-                    if (typeof channelProp === 'string' &&
-                        !['queue', 'volume', 'isPaused', 'isLocked', 'volumeConfig'].includes(channelProp)) {
+                    // Use the automatically-derived whitelist from the interface
+                    const whitelistedProperties = (0, exports.getWhitelistedChannelProperties)();
+                    if (typeof channelProp === 'string' && !whitelistedProperties.includes(channelProp)) {
                         // eslint-disable-next-line no-console
                         console.warn(`Warning: Direct modification of channel.${channelProp} detected. ` +
                             'Use API functions for safer channel management.');
@@ -240,13 +301,14 @@ const onQueueChange = (channelNumber, callback) => {
 exports.onQueueChange = onQueueChange;
 /**
  * Removes queue change listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offQueueChange(0); // Stop receiving queue change notifications for channel 0
+ * offQueueChange(); // Stop receiving queue change notifications for default channel (0)
+ * offQueueChange(1); // Stop receiving queue change notifications for channel 1
  * ```
  */
-const offQueueChange = (channelNumber) => {
+const offQueueChange = (channelNumber = 0) => {
     const channel = exports.audioChannels[channelNumber];
     if (!(channel === null || channel === void 0 ? void 0 : channel.queueChangeCallbacks))
         return;
@@ -401,13 +463,14 @@ const onAudioResume = (channelNumber, callback) => {
 exports.onAudioResume = onAudioResume;
 /**
  * Removes pause event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioPause(0); // Stop receiving pause notifications for channel 0
+ * offAudioPause(); // Stop receiving pause notifications for default channel (0)
+ * offAudioPause(1); // Stop receiving pause notifications for channel 1
  * ```
  */
-const offAudioPause = (channelNumber) => {
+const offAudioPause = (channelNumber = 0) => {
     const channel = exports.audioChannels[channelNumber];
     if (!(channel === null || channel === void 0 ? void 0 : channel.audioPauseCallbacks))
         return;
@@ -416,16 +479,49 @@ const offAudioPause = (channelNumber) => {
 exports.offAudioPause = offAudioPause;
 /**
  * Removes resume event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioResume(0); // Stop receiving resume notifications for channel 0
+ * offAudioResume(); // Stop receiving resume notifications for default channel (0)
+ * offAudioResume(1); // Stop receiving resume notifications for channel 1
  * ```
  */
-const offAudioResume = (channelNumber) => {
+const offAudioResume = (channelNumber = 0) => {
     const channel = exports.audioChannels[channelNumber];
     if (!(channel === null || channel === void 0 ? void 0 : channel.audioResumeCallbacks))
         return;
     channel.audioResumeCallbacks.clear();
 };
 exports.offAudioResume = offAudioResume;
+/**
+ * Removes audio start event listeners for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @example
+ * ```typescript
+ * offAudioStart(); // Stop receiving start notifications for default channel (0)
+ * offAudioStart(1); // Stop receiving start notifications for channel 1
+ * ```
+ */
+const offAudioStart = (channelNumber = 0) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!(channel === null || channel === void 0 ? void 0 : channel.audioStartCallbacks))
+        return;
+    channel.audioStartCallbacks.clear();
+};
+exports.offAudioStart = offAudioStart;
+/**
+ * Removes audio complete event listeners for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @example
+ * ```typescript
+ * offAudioComplete(); // Stop receiving completion notifications for default channel (0)
+ * offAudioComplete(1); // Stop receiving completion notifications for channel 1
+ * ```
+ */
+const offAudioComplete = (channelNumber = 0) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!(channel === null || channel === void 0 ? void 0 : channel.audioCompleteCallbacks))
+        return;
+    channel.audioCompleteCallbacks.clear();
+};
+exports.offAudioComplete = offAudioComplete;

package/dist/types.d.ts

@@ -24,15 +24,15 @@ export interface AudioQueueChannel {
  * 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;
-    /** Volume level for all other channels when priority channel is active (0-1) */
-    duckingVolume: number;
-    /** Duration in milliseconds for volume duck transition (defaults to 250ms) */
-    duckTransitionDuration?: number;
-    /** Duration in milliseconds for volume restore transition (defaults to 500ms) */
+    /** Duration in milliseconds for volume restore transition (defaults to 250ms) */
     restoreTransitionDuration?: number;
     /** Easing function for volume transitions (defaults to 'ease-out') */
     transitionEasing?: EasingType;
@@ -47,8 +47,6 @@ export interface AudioQueueOptions {
     loop?: boolean;
     /** Maximum number of items allowed in the queue (defaults to unlimited) */
     maxQueueSize?: number;
-    /** @deprecated Use addToFront instead. Legacy support for priority queuing */
-    priority?: boolean;
     /** Volume level for this specific audio (0-1) */
     volume?: number;
 }
@@ -192,67 +190,111 @@ export type AudioPauseCallback = (channelNumber: number, audioInfo: AudioInfo) =
  */
 export type AudioResumeCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
 /**
- * Information about an audio error that occurred
+ * 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;
-    src: string;
-    fileName: string;
+    /** The actual error object that was thrown */
     error: Error;
-    errorType: 'network' | 'decode' | 'unsupported' | 'permission' | 'abort' | 'timeout' | 'unknown';
-    timestamp: number;
-    retryAttempt?: number;
+    /** 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 {
-    enabled: boolean;
-    maxRetries: number;
+    /** 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;
-    timeoutMs: number;
-    fallbackUrls?: string[];
+    /** 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
+ * Configuration options for error recovery mechanisms across the audio system
  */
 export interface ErrorRecoveryOptions {
+    /** Whether to automatically retry failed audio loads/plays */
     autoRetry: boolean;
-    showUserFeedback: 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;
-    fallbackToNextTrack: boolean;
+    /** Whether to display user-visible error feedback */
+    showUserFeedback: boolean;
 }
 /**
  * Callback function type for audio error events
  */
 export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
 /**
- * Extended audio channel with queue management and callback support
+ * 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;
 }
 /**
- * Easing function types for volume transitions
+ * Easing function types for smooth volume transitions and animations
  */
 export declare enum EasingType {
     Linear = "linear",
@@ -261,7 +303,7 @@ export declare enum EasingType {
     EaseInOut = "ease-in-out"
 }
 /**
- * Fade type for pause/resume operations with integrated volume transitions
+ * Predefined fade types for pause/resume operations with different transition characteristics
  */
 export declare enum FadeType {
     Linear = "linear",
@@ -269,7 +311,7 @@ export declare enum FadeType {
     Dramatic = "dramatic"
 }
 /**
- * Timer types for volume transitions to ensure proper cleanup
+ * Timer implementation types used for volume transitions to ensure proper cleanup
  */
 export declare enum TimerType {
     RequestAnimationFrame = "raf",

package/dist/types.js

@@ -3,7 +3,7 @@
  * @fileoverview Type definitions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimerType = exports.FadeType = exports.EasingType = exports.GLOBAL_PROGRESS_KEY = exports.MAX_CHANNELS = void 0;
+exports.TimerType = exports.FadeType = exports.EasingType = exports.AudioErrorType = exports.GLOBAL_PROGRESS_KEY = exports.MAX_CHANNELS = void 0;
 /**
  * Maximum number of audio channels allowed to prevent memory exhaustion
  */
@@ -14,7 +14,20 @@ exports.MAX_CHANNELS = 64;
  */
 exports.GLOBAL_PROGRESS_KEY = Symbol('global-progress-callbacks');
 /**
- * Easing function types for volume transitions
+ * Types of audio errors that can occur during playback
+ */
+var AudioErrorType;
+(function (AudioErrorType) {
+    AudioErrorType["Abort"] = "abort";
+    AudioErrorType["Decode"] = "decode";
+    AudioErrorType["Network"] = "network";
+    AudioErrorType["Permission"] = "permission";
+    AudioErrorType["Timeout"] = "timeout";
+    AudioErrorType["Unknown"] = "unknown";
+    AudioErrorType["Unsupported"] = "unsupported";
+})(AudioErrorType || (exports.AudioErrorType = AudioErrorType = {}));
+/**
+ * Easing function types for smooth volume transitions and animations
  */
 var EasingType;
 (function (EasingType) {
@@ -24,7 +37,7 @@ var EasingType;
     EasingType["EaseInOut"] = "ease-in-out";
 })(EasingType || (exports.EasingType = EasingType = {}));
 /**
- * Fade type for pause/resume operations with integrated volume transitions
+ * Predefined fade types for pause/resume operations with different transition characteristics
  */
 var FadeType;
 (function (FadeType) {
@@ -33,7 +46,7 @@ var FadeType;
     FadeType["Dramatic"] = "dramatic";
 })(FadeType || (exports.FadeType = FadeType = {}));
 /**
- * Timer types for volume transitions to ensure proper cleanup
+ * Timer implementation types used for volume transitions to ensure proper cleanup
  */
 var TimerType;
 (function (TimerType) {

package/dist/volume.d.ts

@@ -103,20 +103,6 @@ export declare const clearVolumeDucking: () => void;
  * @internal
  */
 export declare const applyVolumeDucking: (activeChannelNumber: number) => Promise<void>;
-/**
- * Fades the volume for a specific channel over time (alias for transitionVolume with improved naming)
- * @param channelNumber - The channel number to fade
- * @param targetVolume - Target volume level (0-1)
- * @param duration - Fade duration in milliseconds (defaults to 250)
- * @param easing - Easing function type (defaults to 'ease-out')
- * @returns Promise that resolves when fade completes
- * @example
- * ```typescript
- * await fadeVolume(0, 0, 800, 'ease-in'); // Fade out over 800ms
- * await fadeVolume(0, 1, 600, 'ease-out'); // Fade in over 600ms
- * ```
- */
-export declare const fadeVolume: (channelNumber: number, targetVolume: number, duration?: number, easing?: EasingType) => Promise<void>;
 /**
  * Restores normal volume levels when priority channel queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing

package/dist/volume.js

@@ -12,7 +12,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = exports.restoreVolumeLevels = exports.fadeVolume = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = exports.getFadeConfig = void 0;
+exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = exports.restoreVolumeLevels = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = exports.getFadeConfig = void 0;
 const types_1 = require("./types");
 const info_1 = require("./info");
 // Store active volume transitions to handle interruptions
@@ -346,23 +346,6 @@ const applyVolumeDucking = (activeChannelNumber) => __awaiter(void 0, void 0, vo
     yield Promise.all(transitionPromises);
 });
 exports.applyVolumeDucking = applyVolumeDucking;
-/**
- * Fades the volume for a specific channel over time (alias for transitionVolume with improved naming)
- * @param channelNumber - The channel number to fade
- * @param targetVolume - Target volume level (0-1)
- * @param duration - Fade duration in milliseconds (defaults to 250)
- * @param easing - Easing function type (defaults to 'ease-out')
- * @returns Promise that resolves when fade completes
- * @example
- * ```typescript
- * await fadeVolume(0, 0, 800, 'ease-in'); // Fade out over 800ms
- * await fadeVolume(0, 1, 600, 'ease-out'); // Fade in over 600ms
- * ```
- */
-const fadeVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(void 0, [channelNumber_1, targetVolume_1, ...args_1], void 0, function* (channelNumber, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut) {
-    return (0, exports.transitionVolume)(channelNumber, targetVolume, duration, easing);
-});
-exports.fadeVolume = fadeVolume;
 /**
  * Restores normal volume levels when priority channel queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -388,7 +371,7 @@ const restoreVolumeLevels = (stoppedChannelNumber) => __awaiter(void 0, void 0,
             return;
         }
         // Restore this channel to its desired volume
-        const duration = (_a = config.restoreTransitionDuration) !== null && _a !== void 0 ? _a : 500;
+        const duration = (_a = config.restoreTransitionDuration) !== null && _a !== void 0 ? _a : 250;
         const easing = (_b = config.transitionEasing) !== null && _b !== void 0 ? _b : types_1.EasingType.EaseOut;
         const targetVolume = (_c = channel.volume) !== null && _c !== void 0 ? _c : 1.0;
         // Only transition the audio element volume, keep channel.volume as the desired volume

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-channel-queue",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Allows you to queue audio files to different playback channels.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core.ts

@@ -300,10 +300,10 @@ export const queueAudio = async (
     }
   }
 
-  // Handle priority option (same as addToFront for backward compatibility)
-  const shouldAddToFront = options?.addToFront || options?.priority;
+  // Handle addToFront option
+  const shouldAddToFront = options?.addToFront;
 
-  // Add to queue based on priority/addToFront option
+  // Add to queue based on addToFront option
   if (shouldAddToFront && channel.queue.length > 0) {
     // Insert after currently playing track (at index 1)
     channel.queue.splice(1, 0, audio);
@@ -320,12 +320,8 @@ export const queueAudio = async (
 
   // Start playing if this is the first item and channel isn't paused
   if (channel.queue.length === 1 && !channel.isPaused) {
-    // Use setTimeout to ensure the queue change event is emitted first
-    setTimeout(() => {
-      playAudioQueue(channelNumber).catch((error: Error) => {
-        handleAudioError(audio, channelNumber, validatedUrl, error);
-      });
-    }, 0);
+    // Await the audio setup to complete before resolving queueAudio
+    await playAudioQueue(channelNumber);
   }
 };
 
@@ -354,10 +350,10 @@ export const queueAudioPriority = async (
 /**
  * Plays the audio queue for a specific channel
  * @param channelNumber - The channel number to play
- * @returns Promise that resolves when the current audio finishes playing
+ * @returns Promise that resolves when the audio starts playing (setup complete)
  * @example
  * ```typescript
- * await playAudioQueue(0); // Play queue for channel 0
+ * await playAudioQueue(0); // Start playing queue for channel 0
  * ```
  */
 export const playAudioQueue = async (channelNumber: number): Promise<void> => {
@@ -381,6 +377,7 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
     let hasStarted: boolean = false;
     let metadataLoaded: boolean = false;
     let playStarted: boolean = false;
+    let setupComplete: boolean = false;
 
     // Check if we should fire onAudioStart (both conditions met)
     const tryFireAudioStart = (): void => {
@@ -396,6 +393,12 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
           },
           audioChannels
         );
+
+        // Resolve setup promise when audio start event is fired
+        if (!setupComplete) {
+          setupComplete = true;
+          resolve();
+        }
       }
     };
 
@@ -433,7 +436,6 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
         } catch (error) {
           await handleAudioError(currentAudio, channelNumber, currentAudio.src, error as Error);
         }
-        resolve();
       } else {
         // For non-looping audio, remove from queue and play next
         currentAudio.pause();
@@ -448,7 +450,6 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
 
         // Play next audio immediately if there's more in queue
         await playAudioQueue(channelNumber);
-        resolve();
       }
     };
 
@@ -465,7 +466,10 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
     // Enhanced play with error handling
     currentAudio.play().catch(async (error: Error) => {
       await handleAudioError(currentAudio, channelNumber, currentAudio.src, error);
-      resolve(); // Resolve to prevent hanging
+      if (!setupComplete) {
+        setupComplete = true;
+        resolve(); // Resolve gracefully instead of rejecting
+      }
     });
   });
 };

package/src/errors.ts

@@ -5,6 +5,7 @@
 import {
   AudioErrorInfo,
   AudioErrorCallback,
+  AudioErrorType,
   RetryConfig,
   ErrorRecoveryOptions,
   ExtendedAudioQueueChannel,
@@ -17,6 +18,7 @@ let globalRetryConfig: RetryConfig = {
   baseDelay: 1000,
   enabled: true,
   exponentialBackoff: true,
+  fallbackUrls: [],
   maxRetries: 3,
   skipOnFailure: false,
   timeoutMs: 10000
@@ -143,10 +145,10 @@ export const getRetryConfig = (): RetryConfig => {
  * ```typescript
  * setErrorRecovery({
  *   autoRetry: true,
- *   showUserFeedback: true,
+ *   fallbackToNextTrack: true,
  *   logErrorsToAnalytics: true,
  *   preserveQueueOnError: true,
- *   fallbackToNextTrack: true
+ *   showUserFeedback: true
  * });
  * ```
  */
@@ -247,14 +249,11 @@ export const emitAudioError = (
  * @returns The categorized error type
  * @internal
  */
-export const categorizeError = (
-  error: Error,
-  audio: HTMLAudioElement
-): AudioErrorInfo['errorType'] => {
+export const categorizeError = (error: Error, audio: HTMLAudioElement): AudioErrorType => {
   const errorMessage = error.message.toLowerCase();
 
   if (errorMessage.includes('network') || errorMessage.includes('fetch')) {
-    return 'network';
+    return AudioErrorType.Network;
   }
 
   // Check for unsupported format first (more specific than decode)
@@ -263,35 +262,35 @@ export const categorizeError = (
     errorMessage.includes('unsupported') ||
     errorMessage.includes('format not supported')
   ) {
-    return 'unsupported';
+    return AudioErrorType.Unsupported;
   }
 
   if (errorMessage.includes('decode') || errorMessage.includes('format')) {
-    return 'decode';
+    return AudioErrorType.Decode;
   }
 
   if (errorMessage.includes('permission') || errorMessage.includes('blocked')) {
-    return 'permission';
+    return AudioErrorType.Permission;
   }
 
   if (errorMessage.includes('abort')) {
-    return 'abort';
+    return AudioErrorType.Abort;
   }
 
   if (errorMessage.includes('timeout')) {
-    return 'timeout';
+    return AudioErrorType.Timeout;
   }
 
   // Check audio element network state for more context
   if (audio.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) {
-    return 'network';
+    return AudioErrorType.Network;
   }
 
   if (audio.networkState === HTMLMediaElement.NETWORK_LOADING) {
-    return 'timeout';
+    return AudioErrorType.Timeout;
   }
 
-  return 'unknown';
+  return AudioErrorType.Unknown;
 };
 
 /**