audio-channel-queue 1.11.0 → 1.12.0

package/README.md

@@ -75,8 +75,8 @@ Install this package by running either of these commands (typescript packages ar
 ```typescript
 // Add an audio file to the queue and start playing it automatically.
 queueAudio(audioUrl, channelNumber?, options?);
-queueAudio('hello.mp3'); // Add to default channel 0
-queueAudio('laser.mp3', 1, { loop: true, volume: 0.8 }); // Add to channel 1 with options
+await queueAudio('hello.mp3'); // Add to default channel 0
+await queueAudio('laser.mp3', 1, { loop: true, volume: 0.8 }); // Add to channel 1 with options
 ```
 
 
@@ -84,8 +84,8 @@ queueAudio('laser.mp3', 1, { loop: true, volume: 0.8 }); // Add to channel 1 wit
 ```typescript
 // Add a file to the front of the queue (plays after current audio finishes).
 queueAudioPriority(audioUrl, channelNumber?, options?);
-queueAudioPriority('urgent.mp3'); // Add to front of default channel 0
-queueAudioPriority('announcement.mp3', 1, { volume: 1.0 }); // Add to front of channel 1
+await queueAudioPriority('urgent.mp3'); // Add to front of default channel 0
+await queueAudioPriority('announcement.mp3', 1, { volume: 1.0 }); // Add to front of channel 1
 ```
 
 
@@ -93,8 +93,8 @@ queueAudioPriority('announcement.mp3', 1, { volume: 1.0 }); // Add to front of c
 ```typescript
 // Stop the current audio and automatically start playing the next one in queue.
 stopCurrentAudioInChannel(channelNumber?);
-stopCurrentAudioInChannel(); // Stop current audio in default channel (0)
-stopCurrentAudioInChannel(2); // Stop current audio in channel 2
+await stopCurrentAudioInChannel(); // Stop current audio in default channel (0)
+await stopCurrentAudioInChannel(2); // Stop current audio in channel 2
 ```
 
 
@@ -102,14 +102,14 @@ stopCurrentAudioInChannel(2); // Stop current audio in channel 2
 ```typescript
 // Stop all audio in a channel and remove all enqueued files.
 stopAllAudioInChannel(channelNumber?);
-stopAllAudioInChannel(); // Stop and clear all audio in default channel (0)
-stopAllAudioInChannel(1); // Stop and clear all audio in channel 1
+await stopAllAudioInChannel(); // Stop and clear all audio in default channel (0)
+await stopAllAudioInChannel(1); // Stop and clear all audio in channel 1
 ```
 
 ### Stop All Audio
 ```typescript
 // Stop all audio in all channels and remove all enqueued files.
-stopAllAudio();
+await stopAllAudio();
 ```
 
 ## 🔄 Advanced Queue Manipulation:
@@ -118,32 +118,32 @@ stopAllAudio();
 ```typescript
 // Remove a specific item from the queue by its position (cannot remove currently playing item at index 0).
 removeQueuedItem(queuedSlotNumber, channelNumber?);
-const result = removeQueuedItem(2); // Remove item at index 2 from default channel (0)
-const result = removeQueuedItem(1, 1); // Remove item at index 1 from channel 1
+const result = await removeQueuedItem(2); // Remove item at index 2 from default channel (0)
+const result = await removeQueuedItem(1, 1); // Remove item at index 1 from channel 1
 ```
 
 ### Reorder Queue Items
 ```typescript
 // Move a queue item from one position to another (cannot move currently playing item at index 0).
 reorderQueue(currentQueuedSlotNumber, newQueuedSlotNumber, channelNumber?);
-const result = reorderQueue(3, 1); // Move item from index 3 to index 1 in default channel (0)
-const result = reorderQueue(2, 4, 1); // Move item from index 2 to index 4 in channel 1
+const result = await reorderQueue(3, 1); // Move item from index 3 to index 1 in default channel (0)
+const result = await reorderQueue(2, 4, 1); // Move item from index 2 to index 4 in channel 1
 ```
 
 ### Clear Queue After Current
 ```typescript
 // Remove all items from the queue except the currently playing audio.
 clearQueueAfterCurrent(channelNumber?);
-const result = clearQueueAfterCurrent(); // Clear queue after current in default channel (0)
-const result = clearQueueAfterCurrent(2); // Clear queue after current in channel 2
+const result = await clearQueueAfterCurrent(); // Clear queue after current in default channel (0)
+const result = await clearQueueAfterCurrent(2); // Clear queue after current in channel 2
 ```
 
 ### Swap Queue Items
 ```typescript
 // Swap the positions of two items in the queue (cannot involve currently playing item at index 0).
 swapQueueItems(firstQueuedSlotNumber, secondQueuedSlotNumber, channelNumber?);
-const result = swapQueueItems(1, 3); // Swap items at index 1 and 3 in default channel (0)
-const result = swapQueueItems(2, 4, 1); // Swap items at index 2 and 4 in channel 1
+const result = await swapQueueItems(1, 3); // Swap items at index 1 and 3 in default channel (0)
+const result = await swapQueueItems(2, 4, 1); // Swap items at index 2 and 4 in channel 1
 ```
 
 ### Get Queue Item Info
@@ -177,8 +177,8 @@ interface QueueManipulationResult {
 ```typescript
 // Set the volume for a specific channel (0-1 range).
 setChannelVolume(channelNumber, volume);
-setChannelVolume(0, 0.5); // Set channel 0 to 50% volume
-setChannelVolume(1, 0.8); // Set channel 1 to 80% volume
+await setChannelVolume(0, 0.5); // Set channel 0 to 50% volume
+await setChannelVolume(1, 0.8); // Set channel 1 to 80% volume
 ```
 
 ### Get Channel Volume
@@ -193,8 +193,8 @@ console.log(`Channel volume: ${(getChannelVolume(2) * 100).toFixed(0)}%`); // Ge
 ```typescript
 // Set the same volume level for all channels.
 setAllChannelsVolume(volume);
-setAllChannelsVolume(0.6); // Set all channels to 60% volume
-setAllChannelsVolume(0.0); // Mute all channels
+await setAllChannelsVolume(0.6); // Set all channels to 60% volume
+await setAllChannelsVolume(0.0); // Mute all channels
 ```
 
 ### Volume Ducking (Background Audio Reduction)
@@ -356,6 +356,13 @@ onQueueChange(channelNumber, callback);
 onQueueChange(0, (snapshot) => updateQueueDisplay(snapshot)); // Update UI on queue changes
 ```
 
+```typescript
+// Unsubscribe from queue change events (removes ALL queue change callbacks for the channel)
+offQueueChange(channelNumber?);
+offQueueChange(); // Stop receiving all queue change notifications for default channel (0)
+offQueueChange(1); // Stop receiving all queue change notifications for channel 1
+```
+
 ```typescript
 // Subscribe to audio start events.
 onAudioStart(channelNumber, callback);
@@ -364,8 +371,9 @@ onAudioStart(0, (info) => console.log(`Started: ${info.fileName}`)); // Log audi
 
 ```typescript
 // Unsubscribe from audio start events (removes ALL start callbacks for the channel)
-offAudioStart(channelNumber);
-offAudioStart(0); // Stop receiving all start notifications for channel 0
+offAudioStart(channelNumber?);
+offAudioStart(); // Stop receiving all start notifications for default channel (0)
+offAudioStart(1); // Stop receiving all start notifications for channel 1
 ```
 
 ```typescript
@@ -376,8 +384,9 @@ onAudioComplete(0, (info) => logPlayHistory(info)); // Track completed audio
 
 ```typescript
 // Unsubscribe from audio completion events (removes ALL complete callbacks for the channel)
-offAudioComplete(channelNumber);
-offAudioComplete(0); // Stop receiving all completion notifications for channel 0
+offAudioComplete(channelNumber?);
+offAudioComplete(); // Stop receiving all completion notifications for default channel (0)
+offAudioComplete(1); // Stop receiving all completion notifications for channel 1
 ```
 
 ```typescript
@@ -386,12 +395,26 @@ onAudioPause(channelNumber, callback);
 onAudioPause(0, (info) => showPauseIcon(info)); // Show pause state in UI
 ```
 
+```typescript
+// Unsubscribe from audio pause events (removes ALL pause callbacks for the channel)
+offAudioPause(channelNumber?);
+offAudioPause(); // Stop receiving all pause notifications for default channel (0)
+offAudioPause(1); // Stop receiving all pause notifications for channel 1
+```
+
 ```typescript
 // Subscribe to audio resume events.
 onAudioResume(channelNumber, callback);
 onAudioResume(0, (info) => showPlayIcon(info)); // Show play state in UI
 ```
 
+```typescript
+// Unsubscribe from audio resume events (removes ALL resume callbacks for the channel)
+offAudioResume(channelNumber?);
+offAudioResume(); // Stop receiving all resume notifications for default channel (0)
+offAudioResume(1); // Stop receiving all resume notifications for channel 1
+```
+
 ### TypeScript Support
 If you cannot import audio files into your app, you may need a `custom.d.ts` file in the root directory. An example of one is shown here:
 

package/dist/core.js

@@ -260,9 +260,9 @@ const queueAudio = (audioUrl_1, ...args_1) => __awaiter(void 0, [audioUrl_1, ...
             channel.maxQueueSize = options.maxQueueSize;
         }
     }
-    // Handle priority option (same as addToFront for backward compatibility)
-    const shouldAddToFront = (options === null || options === void 0 ? void 0 : options.addToFront) || (options === null || options === void 0 ? void 0 : options.priority);
-    // Add to queue based on priority/addToFront option
+    // Handle addToFront option
+    const shouldAddToFront = options === null || options === void 0 ? void 0 : options.addToFront;
+    // 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);

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Error handling, retry logic, and recovery mechanisms for the audio-channel-queue package
  */
-import { AudioErrorInfo, AudioErrorCallback, RetryConfig, ErrorRecoveryOptions, ExtendedAudioQueueChannel } from './types';
+import { AudioErrorInfo, AudioErrorCallback, AudioErrorType, RetryConfig, ErrorRecoveryOptions, ExtendedAudioQueueChannel } from './types';
 /**
  * Subscribes to audio error events for a specific channel
  * @param channelNumber - The channel number to listen to (defaults to 0)
@@ -61,10 +61,10 @@ export declare const getRetryConfig: () => RetryConfig;
  * ```typescript
  * setErrorRecovery({
  *   autoRetry: true,
- *   showUserFeedback: true,
+ *   fallbackToNextTrack: true,
  *   logErrorsToAnalytics: true,
  *   preserveQueueOnError: true,
- *   fallbackToNextTrack: true
+ *   showUserFeedback: true
  * });
  * ```
  */
@@ -109,7 +109,7 @@ export declare const emitAudioError: (channelNumber: number, errorInfo: AudioErr
  * @returns The categorized error type
  * @internal
  */
-export declare const categorizeError: (error: Error, audio: HTMLAudioElement) => AudioErrorInfo["errorType"];
+export declare const categorizeError: (error: Error, audio: HTMLAudioElement) => AudioErrorType;
 /**
  * Sets up comprehensive error handling for an audio element
  * @param audio - The audio element to set up error handling for

package/dist/errors.js

@@ -43,6 +43,7 @@ let globalRetryConfig = {
     baseDelay: 1000,
     enabled: true,
     exponentialBackoff: true,
+    fallbackUrls: [],
     maxRetries: 3,
     skipOnFailure: false,
     timeoutMs: 10000
@@ -161,10 +162,10 @@ exports.getRetryConfig = getRetryConfig;
  * ```typescript
  * setErrorRecovery({
  *   autoRetry: true,
- *   showUserFeedback: true,
+ *   fallbackToNextTrack: true,
  *   logErrorsToAnalytics: true,
  *   preserveQueueOnError: true,
- *   fallbackToNextTrack: true
+ *   showUserFeedback: true
  * });
  * ```
  */
@@ -263,34 +264,34 @@ exports.emitAudioError = emitAudioError;
 const categorizeError = (error, audio) => {
     const errorMessage = error.message.toLowerCase();
     if (errorMessage.includes('network') || errorMessage.includes('fetch')) {
-        return 'network';
+        return types_1.AudioErrorType.Network;
     }
     // Check for unsupported format first (more specific than decode)
     if (errorMessage.includes('not supported') ||
         errorMessage.includes('unsupported') ||
         errorMessage.includes('format not supported')) {
-        return 'unsupported';
+        return types_1.AudioErrorType.Unsupported;
     }
     if (errorMessage.includes('decode') || errorMessage.includes('format')) {
-        return 'decode';
+        return types_1.AudioErrorType.Decode;
     }
     if (errorMessage.includes('permission') || errorMessage.includes('blocked')) {
-        return 'permission';
+        return types_1.AudioErrorType.Permission;
     }
     if (errorMessage.includes('abort')) {
-        return 'abort';
+        return types_1.AudioErrorType.Abort;
     }
     if (errorMessage.includes('timeout')) {
-        return 'timeout';
+        return types_1.AudioErrorType.Timeout;
     }
     // Check audio element network state for more context
     if (audio.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) {
-        return 'network';
+        return types_1.AudioErrorType.Network;
     }
     if (audio.networkState === HTMLMediaElement.NETWORK_LOADING) {
-        return 'timeout';
+        return types_1.AudioErrorType.Timeout;
     }
-    return 'unknown';
+    return types_1.AudioErrorType.Unknown;
 };
 exports.categorizeError = categorizeError;
 /**

package/dist/index.d.ts

@@ -7,9 +7,9 @@ export { queueAudio, queueAudioPriority, stopCurrentAudioInChannel, stopAllAudio
 export { clearQueueAfterCurrent, getQueueItemInfo, getQueueLength, removeQueuedItem, reorderQueue, swapQueueItems } from './queue-manipulation';
 export { getErrorRecovery, getRetryConfig, offAudioError, onAudioError, retryFailedAudio, setErrorRecovery, setRetryConfig } from './errors';
 export { getAllChannelsPauseState, isChannelPaused, pauseAllChannels, pauseAllWithFade, pauseChannel, pauseWithFade, resumeAllChannels, resumeAllWithFade, resumeChannel, resumeWithFade, togglePauseAllChannels, togglePauseAllWithFade, togglePauseChannel, togglePauseWithFade } from './pause';
-export { clearVolumeDucking, fadeVolume, getAllChannelsVolume, getChannelVolume, getFadeConfig, setAllChannelsVolume, setChannelVolume, setVolumeDucking, transitionVolume, cancelVolumeTransition, cancelAllVolumeTransitions } from './volume';
+export { cancelAllVolumeTransitions, cancelVolumeTransition, clearVolumeDucking, getAllChannelsVolume, getChannelVolume, getFadeConfig, setAllChannelsVolume, setChannelVolume, setVolumeDucking, transitionVolume } from './volume';
 export { getAllChannelsInfo, getCurrentAudioInfo, getQueueSnapshot, offAudioComplete, offAudioPause, offAudioProgress, offAudioResume, offAudioStart, offQueueChange, onAudioComplete, onAudioPause, onAudioProgress, onAudioResume, onAudioStart, onQueueChange } from './info';
 export { audioChannels } from './info';
 export { cleanWebpackFilename, createQueueSnapshot, extractFileName, getAudioInfoFromElement, sanitizeForDisplay, validateAudioUrl } from './utils';
 export type { AudioCompleteCallback, AudioCompleteInfo, AudioErrorCallback, AudioErrorInfo, AudioInfo, AudioPauseCallback, AudioQueueOptions, AudioResumeCallback, AudioStartCallback, AudioStartInfo, ChannelFadeState, ErrorRecoveryOptions, ExtendedAudioQueueChannel, FadeConfig, ProgressCallback, QueueChangeCallback, QueueItem, QueueManipulationResult, QueueSnapshot, RetryConfig, VolumeConfig, QueueConfig } from './types';
-export { EasingType, FadeType, MAX_CHANNELS, TimerType, GLOBAL_PROGRESS_KEY } from './types';
+export { AudioErrorType, EasingType, FadeType, MAX_CHANNELS, TimerType, GLOBAL_PROGRESS_KEY } from './types';

package/dist/index.js

@@ -5,8 +5,8 @@
  * volume management with ducking, progress tracking, and comprehensive event system
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAllChannelsInfo = exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = exports.transitionVolume = exports.setVolumeDucking = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getFadeConfig = exports.getChannelVolume = exports.getAllChannelsVolume = exports.fadeVolume = exports.clearVolumeDucking = exports.togglePauseWithFade = exports.togglePauseChannel = exports.togglePauseAllWithFade = exports.togglePauseAllChannels = exports.resumeWithFade = exports.resumeChannel = exports.resumeAllWithFade = exports.resumeAllChannels = exports.pauseWithFade = exports.pauseChannel = exports.pauseAllWithFade = exports.pauseAllChannels = exports.isChannelPaused = exports.getAllChannelsPauseState = exports.setRetryConfig = exports.setErrorRecovery = exports.retryFailedAudio = exports.onAudioError = exports.offAudioError = exports.getRetryConfig = exports.getErrorRecovery = exports.swapQueueItems = exports.reorderQueue = exports.removeQueuedItem = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.setChannelQueueLimit = exports.getQueueConfig = exports.setQueueConfig = exports.destroyAllChannels = exports.destroyChannel = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
-exports.GLOBAL_PROGRESS_KEY = exports.TimerType = exports.MAX_CHANNELS = exports.FadeType = exports.EasingType = exports.validateAudioUrl = exports.sanitizeForDisplay = exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = exports.audioChannels = exports.onQueueChange = exports.onAudioStart = exports.onAudioResume = exports.onAudioProgress = exports.onAudioPause = exports.onAudioComplete = exports.offQueueChange = exports.offAudioStart = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.offAudioComplete = exports.getQueueSnapshot = exports.getCurrentAudioInfo = void 0;
+exports.getCurrentAudioInfo = exports.getAllChannelsInfo = exports.transitionVolume = exports.setVolumeDucking = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getFadeConfig = exports.getChannelVolume = exports.getAllChannelsVolume = exports.clearVolumeDucking = exports.cancelVolumeTransition = exports.cancelAllVolumeTransitions = exports.togglePauseWithFade = exports.togglePauseChannel = exports.togglePauseAllWithFade = exports.togglePauseAllChannels = exports.resumeWithFade = exports.resumeChannel = exports.resumeAllWithFade = exports.resumeAllChannels = exports.pauseWithFade = exports.pauseChannel = exports.pauseAllWithFade = exports.pauseAllChannels = exports.isChannelPaused = exports.getAllChannelsPauseState = exports.setRetryConfig = exports.setErrorRecovery = exports.retryFailedAudio = exports.onAudioError = exports.offAudioError = exports.getRetryConfig = exports.getErrorRecovery = exports.swapQueueItems = exports.reorderQueue = exports.removeQueuedItem = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.setChannelQueueLimit = exports.getQueueConfig = exports.setQueueConfig = exports.destroyAllChannels = exports.destroyChannel = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
+exports.GLOBAL_PROGRESS_KEY = exports.TimerType = exports.MAX_CHANNELS = exports.FadeType = exports.EasingType = exports.AudioErrorType = exports.validateAudioUrl = exports.sanitizeForDisplay = exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = exports.audioChannels = exports.onQueueChange = exports.onAudioStart = exports.onAudioResume = exports.onAudioProgress = exports.onAudioPause = exports.onAudioComplete = exports.offQueueChange = exports.offAudioStart = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.offAudioComplete = exports.getQueueSnapshot = void 0;
 // Core queue management functions
 var core_1 = require("./core");
 Object.defineProperty(exports, "queueAudio", { enumerable: true, get: function () { return core_1.queueAudio; } });
@@ -55,8 +55,9 @@ Object.defineProperty(exports, "togglePauseChannel", { enumerable: true, get: fu
 Object.defineProperty(exports, "togglePauseWithFade", { enumerable: true, get: function () { return pause_1.togglePauseWithFade; } });
 // Volume control and ducking functions
 var volume_1 = require("./volume");
+Object.defineProperty(exports, "cancelAllVolumeTransitions", { enumerable: true, get: function () { return volume_1.cancelAllVolumeTransitions; } });
+Object.defineProperty(exports, "cancelVolumeTransition", { enumerable: true, get: function () { return volume_1.cancelVolumeTransition; } });
 Object.defineProperty(exports, "clearVolumeDucking", { enumerable: true, get: function () { return volume_1.clearVolumeDucking; } });
-Object.defineProperty(exports, "fadeVolume", { enumerable: true, get: function () { return volume_1.fadeVolume; } });
 Object.defineProperty(exports, "getAllChannelsVolume", { enumerable: true, get: function () { return volume_1.getAllChannelsVolume; } });
 Object.defineProperty(exports, "getChannelVolume", { enumerable: true, get: function () { return volume_1.getChannelVolume; } });
 Object.defineProperty(exports, "getFadeConfig", { enumerable: true, get: function () { return volume_1.getFadeConfig; } });
@@ -64,8 +65,6 @@ Object.defineProperty(exports, "setAllChannelsVolume", { enumerable: true, get:
 Object.defineProperty(exports, "setChannelVolume", { enumerable: true, get: function () { return volume_1.setChannelVolume; } });
 Object.defineProperty(exports, "setVolumeDucking", { enumerable: true, get: function () { return volume_1.setVolumeDucking; } });
 Object.defineProperty(exports, "transitionVolume", { enumerable: true, get: function () { return volume_1.transitionVolume; } });
-Object.defineProperty(exports, "cancelVolumeTransition", { enumerable: true, get: function () { return volume_1.cancelVolumeTransition; } });
-Object.defineProperty(exports, "cancelAllVolumeTransitions", { enumerable: true, get: function () { return volume_1.cancelAllVolumeTransitions; } });
 // Audio information and progress tracking functions
 var info_1 = require("./info");
 Object.defineProperty(exports, "getAllChannelsInfo", { enumerable: true, get: function () { return info_1.getAllChannelsInfo; } });
@@ -96,6 +95,7 @@ Object.defineProperty(exports, "sanitizeForDisplay", { enumerable: true, get: fu
 Object.defineProperty(exports, "validateAudioUrl", { enumerable: true, get: function () { return utils_1.validateAudioUrl; } });
 // Enums and constants
 var types_1 = require("./types");
+Object.defineProperty(exports, "AudioErrorType", { enumerable: true, get: function () { return types_1.AudioErrorType; } });
 Object.defineProperty(exports, "EasingType", { enumerable: true, get: function () { return types_1.EasingType; } });
 Object.defineProperty(exports, "FadeType", { enumerable: true, get: function () { return types_1.FadeType; } });
 Object.defineProperty(exports, "MAX_CHANNELS", { enumerable: true, get: function () { return types_1.MAX_CHANNELS; } });

package/dist/info.d.ts

@@ -116,13 +116,14 @@ export declare function offAudioProgress(channelNumber?: number): void;
 export declare const onQueueChange: (channelNumber: number, callback: QueueChangeCallback) => void;
 /**
  * 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
  * ```
  */
-export declare const offQueueChange: (channelNumber: number) => void;
+export declare const offQueueChange: (channelNumber?: number) => void;
 /**
  * Subscribes to audio start events for a specific channel
  * @param channelNumber - The channel number to monitor
@@ -183,37 +184,41 @@ export declare const onAudioPause: (channelNumber: number, callback: AudioPauseC
 export declare const onAudioResume: (channelNumber: number, callback: AudioResumeCallback) => void;
 /**
  * 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
  * ```
  */
-export declare const offAudioPause: (channelNumber: number) => void;
+export declare const offAudioPause: (channelNumber?: number) => void;
 /**
  * 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
  * ```
  */
-export declare const offAudioResume: (channelNumber: number) => void;
+export declare const offAudioResume: (channelNumber?: number) => void;
 /**
  * Removes audio start event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * offAudioStart(); // Stop receiving start notifications for default channel (0)
+ * offAudioStart(1); // Stop receiving start notifications for channel 1
  * ```
  */
-export declare const offAudioStart: (channelNumber: number) => void;
+export declare const offAudioStart: (channelNumber?: number) => void;
 /**
  * Removes audio complete event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * offAudioComplete(); // Stop receiving completion notifications for default channel (0)
+ * offAudioComplete(1); // Stop receiving completion notifications for channel 1
  * ```
  */
-export declare const offAudioComplete: (channelNumber: number) => void;
+export declare const offAudioComplete: (channelNumber?: number) => void;

package/dist/info.js

@@ -301,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;
@@ -462,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;
@@ -477,13 +479,14 @@ 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;
@@ -492,13 +495,14 @@ const offAudioResume = (channelNumber) => {
 exports.offAudioResume = offAudioResume;
 /**
  * Removes audio start event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * offAudioStart(); // Stop receiving start notifications for default channel (0)
+ * offAudioStart(1); // Stop receiving start notifications for channel 1
  * ```
  */
-const offAudioStart = (channelNumber) => {
+const offAudioStart = (channelNumber = 0) => {
     const channel = exports.audioChannels[channelNumber];
     if (!(channel === null || channel === void 0 ? void 0 : channel.audioStartCallbacks))
         return;
@@ -507,13 +511,14 @@ const offAudioStart = (channelNumber) => {
 exports.offAudioStart = offAudioStart;
 /**
  * Removes audio complete event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * offAudioComplete(); // Stop receiving completion notifications for default channel (0)
+ * offAudioComplete(1); // Stop receiving completion notifications for channel 1
  * ```
  */
-const offAudioComplete = (channelNumber) => {
+const offAudioComplete = (channelNumber = 0) => {
     const channel = exports.audioChannels[channelNumber];
     if (!(channel === null || channel === void 0 ? void 0 : channel.audioCompleteCallbacks))
         return;

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.11.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);

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;
 };
 
 /**

package/src/index.ts

@@ -60,17 +60,16 @@ export {
 
 // Volume control and ducking functions
 export {
+  cancelAllVolumeTransitions,
+  cancelVolumeTransition,
   clearVolumeDucking,
-  fadeVolume,
   getAllChannelsVolume,
   getChannelVolume,
   getFadeConfig,
   setAllChannelsVolume,
   setChannelVolume,
   setVolumeDucking,
-  transitionVolume,
-  cancelVolumeTransition,
-  cancelAllVolumeTransitions
+  transitionVolume
 } from './volume';
 
 // Audio information and progress tracking functions
@@ -132,4 +131,11 @@ export type {
 } from './types';
 
 // Enums and constants
-export { EasingType, FadeType, MAX_CHANNELS, TimerType, GLOBAL_PROGRESS_KEY } from './types';
+export {
+  AudioErrorType,
+  EasingType,
+  FadeType,
+  MAX_CHANNELS,
+  TimerType,
+  GLOBAL_PROGRESS_KEY
+} from './types';

package/src/info.ts

@@ -351,13 +351,14 @@ export const onQueueChange = (channelNumber: number, callback: QueueChangeCallba
 
 /**
  * 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
  * ```
  */
-export const offQueueChange = (channelNumber: number): void => {
+export const offQueueChange = (channelNumber: number = 0): void => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.queueChangeCallbacks) return;
 
@@ -524,13 +525,14 @@ export const onAudioResume = (channelNumber: number, callback: AudioResumeCallba
 
 /**
  * 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
  * ```
  */
-export const offAudioPause = (channelNumber: number): void => {
+export const offAudioPause = (channelNumber: number = 0): void => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.audioPauseCallbacks) return;
 
@@ -539,13 +541,14 @@ export const offAudioPause = (channelNumber: number): void => {
 
 /**
  * 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
  * ```
  */
-export const offAudioResume = (channelNumber: number): void => {
+export const offAudioResume = (channelNumber: number = 0): void => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.audioResumeCallbacks) return;
 
@@ -554,13 +557,14 @@ export const offAudioResume = (channelNumber: number): void => {
 
 /**
  * Removes audio start event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * offAudioStart(); // Stop receiving start notifications for default channel (0)
+ * offAudioStart(1); // Stop receiving start notifications for channel 1
  * ```
  */
-export const offAudioStart = (channelNumber: number): void => {
+export const offAudioStart = (channelNumber: number = 0): void => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.audioStartCallbacks) return;
 
@@ -569,13 +573,14 @@ export const offAudioStart = (channelNumber: number): void => {
 
 /**
  * Removes audio complete event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * offAudioComplete(); // Stop receiving completion notifications for default channel (0)
+ * offAudioComplete(1); // Stop receiving completion notifications for channel 1
  * ```
  */
-export const offAudioComplete = (channelNumber: number): void => {
+export const offAudioComplete = (channelNumber: number = 0): void => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.audioCompleteCallbacks) return;
 

package/src/types.ts

@@ -29,15 +29,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;
@@ -53,8 +53,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;
 }
@@ -212,41 +210,74 @@ 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 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;
 }
 
 /**
@@ -255,29 +286,41 @@ export interface ErrorRecoveryOptions {
 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 enum EasingType {
   Linear = 'linear',
@@ -287,7 +330,7 @@ export enum EasingType {
 }
 
 /**
- * Fade type for pause/resume operations with integrated volume transitions
+ * Predefined fade types for pause/resume operations with different transition characteristics
  */
 export enum FadeType {
   Linear = 'linear',
@@ -296,7 +339,7 @@ export enum FadeType {
 }
 
 /**
- * Timer types for volume transitions to ensure proper cleanup
+ * Timer implementation types used for volume transitions to ensure proper cleanup
  */
 export enum TimerType {
   RequestAnimationFrame = 'raf',

package/src/volume.ts

@@ -380,28 +380,6 @@ export const applyVolumeDucking = async (activeChannelNumber: number): Promise<v
   await Promise.all(transitionPromises);
 };
 
-/**
- * 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 const fadeVolume = async (
-  channelNumber: number,
-  targetVolume: number,
-  duration: number = 250,
-  easing: EasingType = EasingType.EaseOut
-): Promise<void> => {
-  return transitionVolume(channelNumber, targetVolume, duration, easing);
-};
-
 /**
  * Restores normal volume levels when priority channel queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -430,7 +408,7 @@ export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise
     }
 
     // Restore this channel to its desired volume
-    const duration = config.restoreTransitionDuration ?? 500;
+    const duration = config.restoreTransitionDuration ?? 250;
     const easing = config.transitionEasing ?? EasingType.EaseOut;
     const targetVolume = channel.volume ?? 1.0;