audio-channel-queue 1.6.0 → 1.7.0

package/src/errors.ts

@@ -0,0 +1,480 @@
+/**
+ * @fileoverview Error handling, retry logic, and recovery mechanisms for the audio-channel-queue package
+ */
+
+import { AudioErrorInfo, AudioErrorCallback, RetryConfig, ErrorRecoveryOptions, ExtendedAudioQueueChannel } from './types';
+import { audioChannels } from './info';
+import { extractFileName } from './utils';
+
+let globalRetryConfig: RetryConfig = {
+  enabled: true,
+  maxRetries: 3,
+  baseDelay: 1000,
+  exponentialBackoff: true,
+  timeoutMs: 10000,
+  skipOnFailure: false
+};
+
+let globalErrorRecovery: ErrorRecoveryOptions = {
+  autoRetry: true,
+  showUserFeedback: false,
+  logErrorsToAnalytics: false,
+  preserveQueueOnError: true,
+  fallbackToNextTrack: true
+};
+
+const retryAttempts = new WeakMap<HTMLAudioElement, number>();
+
+const loadTimeouts = new WeakMap<HTMLAudioElement, number>();
+
+/**
+ * Subscribes to audio error events for a specific channel
+ * @param channelNumber - The channel number to listen to (defaults to 0)
+ * @param callback - Function to call when an audio error occurs
+ * @example
+ * ```typescript
+ * onAudioError(0, (errorInfo) => {
+ *   console.log(`Audio error: ${errorInfo.error.message}`);
+ *   console.log(`Error type: ${errorInfo.errorType}`);
+ * });
+ * ```
+ */
+export const onAudioError = (channelNumber: number = 0, callback: AudioErrorCallback): void => {
+  // Ensure channel exists
+  while (audioChannels.length <= channelNumber) {
+    audioChannels.push({
+      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
+    });
+  }
+
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel.audioErrorCallbacks) {
+    channel.audioErrorCallbacks = new Set();
+  }
+  
+  channel.audioErrorCallbacks.add(callback);
+};
+
+/**
+ * Unsubscribes from audio error events for a specific channel
+ * @param channelNumber - The channel number to stop listening to (defaults to 0)
+ * @param callback - The specific callback to remove (optional - if not provided, removes all)
+ * @example
+ * ```typescript
+ * offAudioError(0); // Remove all error callbacks for channel 0
+ * offAudioError(0, specificCallback); // Remove specific callback
+ * ```
+ */
+export const offAudioError = (channelNumber: number = 0, callback?: AudioErrorCallback): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.audioErrorCallbacks) return;
+
+  if (callback) {
+    channel.audioErrorCallbacks.delete(callback);
+  } else {
+    channel.audioErrorCallbacks.clear();
+  }
+};
+
+/**
+ * Sets the global retry configuration for audio loading failures
+ * @param config - Retry configuration options
+ * @example
+ * ```typescript
+ * setRetryConfig({
+ *   enabled: true,
+ *   maxRetries: 5,
+ *   baseDelay: 1000,
+ *   exponentialBackoff: true,
+ *   timeoutMs: 15000,
+ *   fallbackUrls: ['https://cdn.backup.com/audio/'],
+ *   skipOnFailure: true
+ * });
+ * ```
+ */
+export const setRetryConfig = (config: Partial<RetryConfig>): void => {
+  globalRetryConfig = { ...globalRetryConfig, ...config };
+};
+
+/**
+ * Gets the current global retry configuration
+ * @returns Current retry configuration
+ * @example
+ * ```typescript
+ * const config = getRetryConfig();
+ * console.log(`Max retries: ${config.maxRetries}`);
+ * ```
+ */
+export const getRetryConfig = (): RetryConfig => {
+  return { ...globalRetryConfig };
+};
+
+/**
+ * Sets the global error recovery configuration
+ * @param options - Error recovery options
+ * @example
+ * ```typescript
+ * setErrorRecovery({
+ *   autoRetry: true,
+ *   showUserFeedback: true,
+ *   logErrorsToAnalytics: true,
+ *   preserveQueueOnError: true,
+ *   fallbackToNextTrack: true
+ * });
+ * ```
+ */
+export const setErrorRecovery = (options: Partial<ErrorRecoveryOptions>): void => {
+  globalErrorRecovery = { ...globalErrorRecovery, ...options };
+};
+
+/**
+ * Gets the current global error recovery configuration
+ * @returns Current error recovery configuration
+ * @example
+ * ```typescript
+ * const recovery = getErrorRecovery();
+ * console.log(`Auto retry enabled: ${recovery.autoRetry}`);
+ * ```
+ */
+export const getErrorRecovery = (): ErrorRecoveryOptions => {
+  return { ...globalErrorRecovery };
+};
+
+/**
+ * Manually retries loading failed audio for a specific channel
+ * @param channelNumber - The channel number to retry (defaults to 0)
+ * @returns Promise that resolves to true if retry was successful, false otherwise
+ * @example
+ * ```typescript
+ * const success = await retryFailedAudio(0);
+ * if (success) {
+ *   console.log('Audio retry successful');
+ * } else {
+ *   console.log('Audio retry failed');
+ * }
+ * ```
+ */
+export const retryFailedAudio = async (channelNumber: number = 0): Promise<boolean> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || channel.queue.length === 0) return false;
+
+  const currentAudio: HTMLAudioElement = channel.queue[0];
+  const currentAttempts = retryAttempts.get(currentAudio) || 0;
+  
+  if (currentAttempts >= globalRetryConfig.maxRetries) {
+    return false;
+  }
+
+  try {
+    // Reset the audio element
+    currentAudio.currentTime = 0;
+    await currentAudio.play();
+    
+    // Reset retry counter on successful play
+    retryAttempts.delete(currentAudio);
+    return true;
+  } catch (error) {
+    // Increment retry counter
+    retryAttempts.set(currentAudio, currentAttempts + 1);
+    return false;
+  }
+};
+
+/**
+ * Emits an audio error event to all registered listeners for a specific channel
+ * @param channelNumber - The channel number where the error occurred
+ * @param errorInfo - Information about the error
+ * @param audioChannels - Array of audio channels
+ * @internal
+ */
+export const emitAudioError = (
+  channelNumber: number,
+  errorInfo: AudioErrorInfo,
+  audioChannels: ExtendedAudioQueueChannel[]
+): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.audioErrorCallbacks) return;
+
+  // Log to analytics if enabled
+  if (globalErrorRecovery.logErrorsToAnalytics) {
+    console.warn('Audio Error Analytics:', errorInfo);
+  }
+
+  channel.audioErrorCallbacks.forEach(callback => {
+    try {
+      callback(errorInfo);
+    } catch (error) {
+      console.error('Error in audio error callback:', error);
+    }
+  });
+};
+
+/**
+ * Determines the error type based on the error object and context
+ * @param error - The error that occurred
+ * @param audio - The audio element that failed
+ * @returns The categorized error type
+ * @internal
+ */
+export const categorizeError = (error: Error, audio: HTMLAudioElement): AudioErrorInfo['errorType'] => {
+  const errorMessage = error.message.toLowerCase();
+  
+  if (errorMessage.includes('network') || errorMessage.includes('fetch')) {
+    return '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';
+  }
+  
+  if (errorMessage.includes('decode') || errorMessage.includes('format')) {
+    return 'decode';
+  }
+  
+  if (errorMessage.includes('permission') || errorMessage.includes('blocked')) {
+    return 'permission';
+  }
+  
+  if (errorMessage.includes('abort')) {
+    return 'abort';
+  }
+  
+  if (errorMessage.includes('timeout')) {
+    return 'timeout';
+  }
+  
+  // Check audio element network state for more context
+  if (audio.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) {
+    return 'network';
+  }
+  
+  if (audio.networkState === HTMLMediaElement.NETWORK_LOADING) {
+    return 'timeout';
+  }
+  
+  return 'unknown';
+};
+
+/**
+ * Sets up comprehensive error handling for an audio element
+ * @param audio - The audio element to set up error handling for
+ * @param channelNumber - The channel number this audio belongs to
+ * @param originalUrl - The original URL that was requested
+ * @param onError - Callback for when an error occurs
+ * @internal
+ */
+export const setupAudioErrorHandling = (
+  audio: HTMLAudioElement,
+  channelNumber: number,
+  originalUrl: string,
+  onError?: (error: Error) => Promise<void>
+): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) return;
+
+  // Set up loading timeout with test environment compatibility
+  let timeoutId: number;
+  if (typeof setTimeout !== 'undefined') {
+    timeoutId = setTimeout(() => {
+      if (audio.networkState === HTMLMediaElement.NETWORK_LOADING) {
+        const timeoutError = new Error(`Audio loading timeout after ${globalRetryConfig.timeoutMs}ms`);
+        handleAudioError(audio, channelNumber, originalUrl, timeoutError);
+      }
+    }, globalRetryConfig.timeoutMs) as unknown as number;
+    
+    loadTimeouts.set(audio, timeoutId);
+  }
+
+  // Clear timeout when metadata loads successfully
+  const handleLoadSuccess = (): void => {
+    if (typeof setTimeout !== 'undefined') {
+      const timeoutId = loadTimeouts.get(audio);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        loadTimeouts.delete(audio);
+      }
+    }
+  };
+
+  // Handle various error events
+  const handleError = (event: Event): void => {
+    if (typeof setTimeout !== 'undefined') {
+      const timeoutId = loadTimeouts.get(audio);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        loadTimeouts.delete(audio);
+      }
+    }
+
+    const error = new Error(`Audio loading failed: ${audio.error?.message || 'Unknown error'}`);
+    handleAudioError(audio, channelNumber, originalUrl, error);
+  };
+
+  const handleAbort = (): void => {
+    const error = new Error('Audio loading was aborted');
+    handleAudioError(audio, channelNumber, originalUrl, error);
+  };
+
+  const handleStall = (): void => {
+    const error = new Error('Audio loading stalled');
+    handleAudioError(audio, channelNumber, originalUrl, error);
+  };
+
+  // Add event listeners
+  audio.addEventListener('error', handleError);
+  audio.addEventListener('abort', handleAbort);
+  audio.addEventListener('stalled', handleStall);
+  audio.addEventListener('loadedmetadata', handleLoadSuccess);
+  audio.addEventListener('canplay', handleLoadSuccess);
+
+  // Custom play error handling
+  if (onError) {
+    const originalPlay = audio.play.bind(audio);
+    const wrappedPlay = async () => {
+      try {
+        await originalPlay();
+      } catch (error) {
+        await onError(error as Error);
+        throw error;
+      }
+    };
+    
+    audio.play = wrappedPlay;
+  }
+};
+
+/**
+ * Handles audio errors with retry logic and recovery mechanisms
+ * @param audio - The audio element that failed
+ * @param channelNumber - The channel number
+ * @param originalUrl - The original URL that was requested
+ * @param error - The error that occurred
+ * @internal
+ */
+export const handleAudioError = async (
+  audio: HTMLAudioElement,
+  channelNumber: number,
+  originalUrl: string,
+  error: Error
+): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) return;
+
+  const currentAttempts = retryAttempts.get(audio) || 0;
+  const retryConfig = channel.retryConfig || globalRetryConfig;
+  
+  const errorInfo: AudioErrorInfo = {
+    channelNumber,
+    src: originalUrl,
+    fileName: extractFileName(originalUrl),
+    error,
+    errorType: categorizeError(error, audio),
+    timestamp: Date.now(),
+    retryAttempt: currentAttempts,
+    remainingInQueue: channel.queue.length - 1
+  };
+
+  // Emit error event
+  emitAudioError(channelNumber, errorInfo, audioChannels);
+
+  // Attempt retry if enabled and within limits
+  if (retryConfig.enabled && currentAttempts < retryConfig.maxRetries && globalErrorRecovery.autoRetry) {
+    const delay = retryConfig.exponentialBackoff 
+      ? retryConfig.baseDelay * Math.pow(2, currentAttempts)
+      : retryConfig.baseDelay;
+
+    retryAttempts.set(audio, currentAttempts + 1);
+
+    const retryFunction = async () => {
+      try {
+        // Try fallback URLs if available
+        if (retryConfig.fallbackUrls && retryConfig.fallbackUrls.length > 0) {
+          const fallbackIndex = currentAttempts % retryConfig.fallbackUrls.length;
+          const fallbackUrl = retryConfig.fallbackUrls[fallbackIndex] + extractFileName(originalUrl);
+          audio.src = fallbackUrl;
+        }
+
+        await audio.load();
+        await audio.play();
+        
+        // Reset retry counter on success
+        retryAttempts.delete(audio);
+      } catch (retryError) {
+        await handleAudioError(audio, channelNumber, originalUrl, retryError as Error);
+      }
+    };
+
+    setTimeout(retryFunction, delay);
+  } else {
+    // Max retries reached or retry disabled
+    if (retryConfig.skipOnFailure || globalErrorRecovery.fallbackToNextTrack) {
+      // Skip to next track in queue
+      channel.queue.shift();
+      
+      // Import and use playAudioQueue to continue with next track
+      const { playAudioQueue } = await import('./core');
+      playAudioQueue(channelNumber).catch(console.error);
+    } else if (!globalErrorRecovery.preserveQueueOnError) {
+      // Clear the entire queue on failure
+      channel.queue = [];
+    }
+  }
+};
+
+/**
+ * Creates a timeout-protected audio element with comprehensive error handling
+ * @param url - The audio URL to load
+ * @param channelNumber - The channel number this audio belongs to
+ * @returns Promise that resolves to the configured audio element
+ * @internal
+ */
+export const createProtectedAudioElement = async (
+  url: string,
+  channelNumber: number
+): Promise<HTMLAudioElement> => {
+  const audio = new Audio();
+  
+  return new Promise((resolve, reject) => {
+    const cleanup = (): void => {
+      const timeoutId = loadTimeouts.get(audio);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        loadTimeouts.delete(audio);
+      }
+    };
+
+    const handleSuccess = (): void => {
+      cleanup();
+      resolve(audio);
+    };
+
+    const handleError = (error: Error): void => {
+      cleanup();
+      reject(error);
+    };
+
+    // Set up error handling
+    setupAudioErrorHandling(audio, channelNumber, url, async (error: Error) => {
+      handleError(error);
+    });
+
+    // Set up success handlers
+    audio.addEventListener('canplay', handleSuccess, { once: true });
+    audio.addEventListener('loadedmetadata', handleSuccess, { once: true });
+
+    // Start loading
+    audio.src = url;
+    audio.load();
+  });
+}; 

package/src/index.ts

@@ -1,104 +1,91 @@
 /**
  * @fileoverview Main entry point for the audio-channel-queue package
- * 
- * A comprehensive audio queue management system with real-time progress tracking,
- * multi-channel support, pause/resume functionality, volume control with ducking,
- * looping capabilities, and extensive event handling.
- * 
- * @example Basic Usage
- * ```typescript
- * import { queueAudio, onAudioProgress, pauseChannel } from 'audio-channel-queue';
- * 
- * // Queue an audio file
- * await queueAudio('song.mp3');
- * 
- * // Track progress
- * onAudioProgress(0, (info) => {
- *   console.log(`Progress: ${info.progress * 100}%`);
- * });
- * 
- * // Pause playback
- * await pauseChannel(0);
- * ```
+ * Exports all public functions and types for audio queue management, pause/resume controls,
+ * volume management with ducking, progress tracking, and comprehensive event system
  */
 
-// Export all type definitions
-export type {
-  AudioCompleteCallback,
-  AudioCompleteInfo,
-  AudioInfo,
-  AudioPauseCallback,
-  AudioQueue,
-  AudioQueueChannel,
-  AudioQueueOptions,
-  AudioResumeCallback,
-  AudioStartCallback,
-  AudioStartInfo,
-  ExtendedAudioQueueChannel,
-  ProgressCallback,
-  QueueChangeCallback,
-  QueueItem,
-  QueueSnapshot,
-  VolumeConfig
-} from './types';
+// Core queue management functions
+export { queueAudio, queueAudioPriority, stopCurrentAudioInChannel, stopAllAudioInChannel, stopAllAudio, playAudioQueue } from './core';
 
-// Export core queue management functions
-export {
-  playAudioQueue,
-  queueAudio,
-  queueAudioPriority,
-  stopAllAudio,
-  stopAllAudioInChannel,
-  stopCurrentAudioInChannel
-} from './core';
+// Error handling and recovery functions
+export { 
+  getErrorRecovery, 
+  getRetryConfig, 
+  offAudioError, 
+  onAudioError, 
+  retryFailedAudio,
+  setErrorRecovery, 
+  setRetryConfig, 
+} from './errors';
 
-// Export pause and resume functionality
-export {
-  getAllChannelsPauseState,
-  isChannelPaused,
-  pauseAllChannels,
-  pauseChannel,
-  resumeAllChannels,
-  resumeChannel,
+// Pause and resume management functions
+export { 
+  getAllChannelsPauseState, 
+  isChannelPaused, 
+  pauseAllChannels, 
+  pauseChannel, 
+  resumeAllChannels, 
+  resumeChannel, 
   togglePauseAllChannels,
-  togglePauseChannel
+  togglePauseChannel, 
 } from './pause';
 
-// Export volume control functions
-export {
-  applyVolumeDucking,
+// Volume control and ducking functions
+export { 
   clearVolumeDucking,
-  getAllChannelsVolume,
-  getChannelVolume,
-  restoreVolumeLevels,
-  setAllChannelsVolume,
-  setChannelVolume,
-  setVolumeDucking,
-  transitionVolume
+  getAllChannelsVolume, 
+  getChannelVolume, 
+  setAllChannelsVolume, 
+  setChannelVolume, 
+  setVolumeDucking, 
 } from './volume';
 
-// Export audio information and progress tracking functions
-export {
-  audioChannels,
-  getAllChannelsInfo,
-  getCurrentAudioInfo,
-  getQueueSnapshot,
-  offAudioPause,
-  offAudioProgress,
+// Audio information and progress tracking functions
+export { 
+  getAllChannelsInfo, 
+  getCurrentAudioInfo, 
+  getQueueSnapshot, 
+  offAudioPause, 
+  offAudioProgress, 
   offAudioResume,
-  offQueueChange,
-  onAudioComplete,
-  onAudioPause,
-  onAudioProgress,
-  onAudioResume,
-  onAudioStart,
-  onQueueChange
+  offQueueChange, 
+  onAudioComplete, 
+  onAudioPause, 
+  onAudioProgress, 
+  onAudioResume, 
+  onAudioStart, 
+  onQueueChange, 
 } from './info';
 
-// Export utility functions (for advanced usage)
+// Core data access for legacy compatibility
+export { audioChannels } from './info';
+
+// Utility helper functions
 export {
   cleanWebpackFilename,
   createQueueSnapshot,
   extractFileName,
   getAudioInfoFromElement
-} from './utils'; 
+} from './utils';
+
+// TypeScript type definitions and interfaces
+export type { 
+  AudioCompleteCallback,
+  AudioCompleteInfo,
+  AudioErrorCallback,
+  AudioErrorInfo,
+  AudioInfo, 
+  AudioPauseCallback,
+  AudioQueueOptions,
+  AudioResumeCallback,
+  AudioStartCallback,
+  AudioStartInfo,
+  ErrorRecoveryOptions,
+  ExtendedAudioQueueChannel,
+  ProgressCallback,
+  QueueChangeCallback,
+  QueueItem,
+  QueueSnapshot,
+  RetryConfig,
+  VolumeConfig 
+} from './types'; 

package/src/info.ts

@@ -17,7 +17,8 @@ import { getAudioInfoFromElement, createQueueSnapshot } from './utils';
 import { setupProgressTracking, cleanupProgressTracking } from './events';
 
 /**
- * Global array of extended audio queue channels
+ * Global array to store audio channels with their queues and callback management
+ * Each channel maintains its own audio queue and event callback sets
  */
 export const audioChannels: ExtendedAudioQueueChannel[] = [];
 
@@ -100,6 +101,7 @@ export const onAudioProgress = (channelNumber: number, callback: ProgressCallbac
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = { 
       audioCompleteCallbacks: new Set(),
+      audioErrorCallbacks: new Set(),
       audioPauseCallbacks: new Set(),
       audioResumeCallbacks: new Set(),
       audioStartCallbacks: new Set(),
@@ -173,6 +175,7 @@ export const onQueueChange = (channelNumber: number, callback: QueueChangeCallba
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = { 
       audioCompleteCallbacks: new Set(),
+      audioErrorCallbacks: new Set(),
       audioPauseCallbacks: new Set(),
       audioResumeCallbacks: new Set(),
       audioStartCallbacks: new Set(),
@@ -223,6 +226,7 @@ export const onAudioStart = (channelNumber: number, callback: AudioStartCallback
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = { 
       audioCompleteCallbacks: new Set(),
+      audioErrorCallbacks: new Set(),
       audioPauseCallbacks: new Set(),
       audioResumeCallbacks: new Set(),
       audioStartCallbacks: new Set(),
@@ -260,6 +264,7 @@ export const onAudioComplete = (channelNumber: number, callback: AudioCompleteCa
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = { 
       audioCompleteCallbacks: new Set(),
+      audioErrorCallbacks: new Set(),
       audioPauseCallbacks: new Set(),
       audioResumeCallbacks: new Set(),
       audioStartCallbacks: new Set(),
@@ -295,6 +300,7 @@ export const onAudioPause = (channelNumber: number, callback: AudioPauseCallback
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = { 
       audioCompleteCallbacks: new Set(),
+      audioErrorCallbacks: new Set(),
       audioPauseCallbacks: new Set(),
       audioResumeCallbacks: new Set(),
       audioStartCallbacks: new Set(),
@@ -330,6 +336,7 @@ export const onAudioResume = (channelNumber: number, callback: AudioResumeCallba
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = { 
       audioCompleteCallbacks: new Set(),
+      audioErrorCallbacks: new Set(),
       audioPauseCallbacks: new Set(),
       audioResumeCallbacks: new Set(),
       audioStartCallbacks: new Set(),