audio-channel-queue 1.6.0 → 1.7.0

package/dist/types.d.ts

@@ -159,25 +159,58 @@ export type AudioPauseCallback = (channelNumber: number, audioInfo: AudioInfo) =
  */
 export type AudioResumeCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
 /**
- * Extended audio queue channel with event callback management and additional features
- */
-export type ExtendedAudioQueueChannel = AudioQueueChannel & {
-    /** Set of callbacks for audio completion events */
-    audioCompleteCallbacks?: Set<AudioCompleteCallback>;
-    /** Set of callbacks for audio pause events */
-    audioPauseCallbacks?: Set<AudioPauseCallback>;
-    /** Set of callbacks for audio resume events */
-    audioResumeCallbacks?: Set<AudioResumeCallback>;
-    /** Set of callbacks for audio start events */
-    audioStartCallbacks?: Set<AudioStartCallback>;
-    /** Whether the current audio in this channel is paused */
+ * Information about an audio error that occurred
+ */
+export interface AudioErrorInfo {
+    channelNumber: number;
+    src: string;
+    fileName: string;
+    error: Error;
+    errorType: 'network' | 'decode' | 'unsupported' | 'permission' | 'abort' | 'timeout' | 'unknown';
+    timestamp: number;
+    retryAttempt?: number;
+    remainingInQueue: number;
+}
+/**
+ * Configuration for automatic retry behavior when audio fails to load or play
+ */
+export interface RetryConfig {
+    enabled: boolean;
+    maxRetries: number;
+    baseDelay: number;
+    exponentialBackoff: boolean;
+    timeoutMs: number;
+    fallbackUrls?: string[];
+    skipOnFailure: boolean;
+}
+/**
+ * Configuration options for error recovery mechanisms
+ */
+export interface ErrorRecoveryOptions {
+    autoRetry: boolean;
+    showUserFeedback: boolean;
+    logErrorsToAnalytics: boolean;
+    preserveQueueOnError: boolean;
+    fallbackToNextTrack: boolean;
+}
+/**
+ * Callback function type for audio error events
+ */
+export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
+/**
+ * Extended audio queue channel with error handling capabilities
+ */
+export interface ExtendedAudioQueueChannel {
+    audioCompleteCallbacks: Set<AudioCompleteCallback>;
+    audioErrorCallbacks: Set<AudioErrorCallback>;
+    audioPauseCallbacks: Set<AudioPauseCallback>;
+    audioResumeCallbacks: Set<AudioResumeCallback>;
+    audioStartCallbacks: Set<AudioStartCallback>;
     isPaused?: boolean;
-    /** Map of audio elements to their progress callback sets */
-    progressCallbacks?: Map<HTMLAudioElement, Set<ProgressCallback>>;
-    /** Set of callbacks for queue change events */
-    queueChangeCallbacks?: Set<QueueChangeCallback>;
-    /** Current volume level for this channel (0-1) */
+    progressCallbacks: Map<HTMLAudioElement | null, Set<ProgressCallback>>;
+    queue: HTMLAudioElement[];
+    queueChangeCallbacks: Set<QueueChangeCallback>;
+    retryConfig?: RetryConfig;
     volume?: number;
-    /** Volume ducking configuration for this channel */
     volumeConfig?: VolumeConfig;
-};
+}

package/dist/volume.js

@@ -55,7 +55,7 @@ const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __await
         return Promise.resolve();
     }
     // Handle zero duration - instant change
-    if (duration <= 0) {
+    if (duration === 0) {
         channel.volume = targetVolume;
         if (channel.queue.length > 0) {
             channel.queue[0].volume = targetVolume;
@@ -115,6 +115,7 @@ const setChannelVolume = (channelNumber, volume, transitionDuration, easing) =>
     if (!info_1.audioChannels[channelNumber]) {
         info_1.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
+            audioErrorCallbacks: new Set(),
             audioPauseCallbacks: new Set(),
             audioResumeCallbacks: new Set(),
             audioStartCallbacks: new Set(),
@@ -207,6 +208,7 @@ const setVolumeDucking = (config) => {
     while (info_1.audioChannels.length <= config.priorityChannel) {
         info_1.audioChannels.push({
             audioCompleteCallbacks: new Set(),
+            audioErrorCallbacks: new Set(),
             audioPauseCallbacks: new Set(),
             audioResumeCallbacks: new Set(),
             audioStartCallbacks: new Set(),
@@ -222,6 +224,7 @@ const setVolumeDucking = (config) => {
         if (!info_1.audioChannels[index]) {
             info_1.audioChannels[index] = {
                 audioCompleteCallbacks: new Set(),
+                audioErrorCallbacks: new Set(),
                 audioPauseCallbacks: new Set(),
                 audioResumeCallbacks: new Set(),
                 audioStartCallbacks: new Set(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-channel-queue",
-  "version": "1.6.0",
+  "version": "1.7.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

@@ -13,6 +13,7 @@ import {
   cleanupProgressTracking 
 } from './events';
 import { applyVolumeDucking, restoreVolumeLevels } from './volume';
+import { setupAudioErrorHandling, handleAudioError } from './errors';
 
 /**
  * Queues an audio file to a specific channel and starts playing if it's the first in queue
@@ -33,9 +34,11 @@ export const queueAudio = async (
   channelNumber: number = 0, 
   options?: AudioQueueOptions
 ): Promise<void> => {
-  if (!audioChannels[channelNumber]) {
-    audioChannels[channelNumber] = { 
+  // Ensure the channel exists
+  while (audioChannels.length <= channelNumber) {
+    audioChannels.push({
       audioCompleteCallbacks: new Set(),
+      audioErrorCallbacks: new Set(),
       audioPauseCallbacks: new Set(),
       audioResumeCallbacks: new Set(),
       audioStartCallbacks: new Set(),
@@ -44,46 +47,56 @@ export const queueAudio = async (
       queue: [],
       queueChangeCallbacks: new Set(),
       volume: 1.0
-    };
+    });
   }
 
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   const audio: HTMLAudioElement = new Audio(audioUrl);
-  
-  // Apply audio configuration from options
-  if (options?.loop) {
-    audio.loop = true;
-  }
-  
-  if (options?.volume !== undefined) {
-    const clampedVolume: number = Math.max(0, Math.min(1, options.volume));
-    // Handle NaN case - default to channel volume or 1.0
-    const safeVolume: number = isNaN(clampedVolume) ? (audioChannels[channelNumber].volume || 1.0) : clampedVolume;
-    audio.volume = safeVolume;
-    // Also update the channel volume
-    audioChannels[channelNumber].volume = safeVolume;
-  } else {
-    // Use channel volume if no specific volume is set
-    const channelVolume: number = audioChannels[channelNumber].volume || 1.0;
-    audio.volume = channelVolume;
+
+  // Set up comprehensive error handling
+  setupAudioErrorHandling(audio, channelNumber, audioUrl, async (error: Error) => {
+    await handleAudioError(audio, channelNumber, audioUrl, error);
+  });
+
+  // Apply options if provided
+  if (options) {
+    if (typeof options.loop === 'boolean') {
+      audio.loop = options.loop;
+    }
+    if (typeof options.volume === 'number' && !isNaN(options.volume)) {
+      const clampedVolume = Math.max(0, Math.min(1, options.volume));
+      audio.volume = clampedVolume;
+      // Set channel volume to match the audio volume
+      channel.volume = clampedVolume;
+    }
   }
 
-  // Add to front or back of queue based on options
-  if ((options?.addToFront || options?.priority) && audioChannels[channelNumber].queue.length > 0) {
-    // Insert after the currently playing audio (index 1)
-    audioChannels[channelNumber].queue.splice(1, 0, audio);
-  } else if ((options?.addToFront || options?.priority) && audioChannels[channelNumber].queue.length === 0) {
-    // If queue is empty, just add normally
-    audioChannels[channelNumber].queue.push(audio);
+  // Handle priority option (same as addToFront for backward compatibility)
+  const shouldAddToFront = options?.addToFront || options?.priority;
+
+  // Add to queue based on priority/addToFront option
+  if (shouldAddToFront && channel.queue.length > 0) {
+    // Insert after currently playing track (at index 1)
+    channel.queue.splice(1, 0, audio);
+  } else if (shouldAddToFront) {
+    // If queue is empty, add to front
+    channel.queue.unshift(audio);
   } else {
-    // Default behavior - add to back of queue
-    audioChannels[channelNumber].queue.push(audio);
+    // Add to back of queue
+    channel.queue.push(audio);
   }
 
+  // Emit queue change event
   emitQueueChange(channelNumber, audioChannels);
 
-  if (audioChannels[channelNumber].queue.length === 1) {
-    // Don't await - let playback happen asynchronously
-    playAudioQueue(channelNumber).catch(console.error);
+  // 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, audioUrl, error);
+      });
+    }, 0);
   }
 };
 
@@ -188,8 +201,11 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
       if (currentAudio.loop) {
         // For looping audio, reset current time and continue playing
         currentAudio.currentTime = 0;
-        await currentAudio.play();
-        // Don't remove from queue, but resolve the promise so tests don't hang
+        try {
+          await currentAudio.play();
+        } catch (error) {
+          await handleAudioError(currentAudio, channelNumber, currentAudio.src, error as Error);
+        }
         resolve();
       } else {
         // For non-looping audio, remove from queue and play next
@@ -213,7 +229,11 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
       metadataLoaded = true;
     }
 
-    currentAudio.play();
+    // Enhanced play with error handling
+    currentAudio.play().catch(async (error: Error) => {
+      await handleAudioError(currentAudio, channelNumber, currentAudio.src, error);
+      resolve(); // Resolve to prevent hanging
+    });
   });
 };