audio-channel-queue 1.11.0 → 1.12.1-beta.0

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
@@ -32,8 +34,6 @@ let globalErrorRecovery: ErrorRecoveryOptions = {
 
 const retryAttempts: WeakMap<HTMLAudioElement, number> = new WeakMap();
 
-const loadTimeouts: WeakMap<HTMLAudioElement, number> = new WeakMap();
-
 /**
  * Subscribes to audio error events for a specific channel
  * @param channelNumber - The channel number to listen to (defaults to 0)
@@ -143,10 +143,10 @@ export const getRetryConfig = (): RetryConfig => {
  * ```typescript
  * setErrorRecovery({
  *   autoRetry: true,
- *   showUserFeedback: true,
+ *   fallbackToNextTrack: true,
  *   logErrorsToAnalytics: true,
  *   preserveQueueOnError: true,
- *   fallbackToNextTrack: true
+ *   showUserFeedback: true
  * });
  * ```
  */
@@ -247,14 +247,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 +260,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;
 };
 
 /**
@@ -311,42 +308,8 @@ export const setupAudioErrorHandling = (
   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);
   };
@@ -365,8 +328,6 @@ export const setupAudioErrorHandling = (
   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) {
@@ -424,7 +385,7 @@ export const handleAudioError = async (
     currentAttempts < retryConfig.maxRetries &&
     globalErrorRecovery.autoRetry
   ) {
-    const delay = retryConfig.exponentialBackoff
+    const delay: number = retryConfig.exponentialBackoff
       ? retryConfig.baseDelay * Math.pow(2, currentAttempts)
       : retryConfig.baseDelay;
 
@@ -482,21 +443,11 @@ export const createProtectedAudioElement = async (
   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);
     };
 

package/src/index.ts

@@ -60,19 +60,34 @@ export {
 
 // Volume control and ducking functions
 export {
+  cancelAllVolumeTransitions,
+  cancelVolumeTransition,
   clearVolumeDucking,
-  fadeVolume,
   getAllChannelsVolume,
   getChannelVolume,
   getFadeConfig,
   setAllChannelsVolume,
   setChannelVolume,
   setVolumeDucking,
-  transitionVolume,
-  cancelVolumeTransition,
-  cancelAllVolumeTransitions
+  transitionVolume
 } from './volume';
 
+// Web Audio API support functions
+export {
+  cleanupWebAudioNodes,
+  createWebAudioNodes,
+  getAudioContext,
+  getWebAudioConfig,
+  getWebAudioSupport,
+  getWebAudioVolume,
+  isIOSDevice,
+  isWebAudioSupported,
+  resumeAudioContext,
+  setWebAudioConfig,
+  setWebAudioVolume,
+  shouldUseWebAudio
+} from './web-audio';
+
 // Audio information and progress tracking functions
 export {
   getAllChannelsInfo,
@@ -123,13 +138,23 @@ export type {
   FadeConfig,
   ProgressCallback,
   QueueChangeCallback,
+  QueueConfig,
   QueueItem,
   QueueManipulationResult,
   QueueSnapshot,
   RetryConfig,
   VolumeConfig,
-  QueueConfig
+  WebAudioConfig,
+  WebAudioNodeSet,
+  WebAudioSupport
 } 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,81 @@ export interface ErrorRecoveryOptions {
 export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
 
 /**
- * Extended audio channel with queue management and callback support
+ * Web Audio API configuration options
+ */
+export interface WebAudioConfig {
+  /** Whether to automatically use Web Audio API on iOS devices */
+  autoDetectIOS: boolean;
+  /** Whether Web Audio API support is enabled */
+  enabled: boolean;
+  /** Whether to force Web Audio API usage on all devices */
+  forceWebAudio: boolean;
+}
+
+/**
+ * Web Audio API support information
+ */
+export interface WebAudioSupport {
+  /** Whether Web Audio API is available in the current environment */
+  available: boolean;
+  /** Whether the current device is iOS */
+  isIOS: boolean;
+  /** Whether Web Audio API is currently being used */
+  usingWebAudio: boolean;
+  /** Reason for current Web Audio API usage state */
+  reason: string;
+}
+
+/**
+ * Web Audio API node set for audio element control
+ */
+export interface WebAudioNodeSet {
+  /** Gain node for volume control */
+  gainNode: GainNode;
+  /** Media element source node */
+  sourceNode: MediaElementAudioSourceNode;
+}
+
+/**
+ * Extended audio channel with comprehensive queue management, callback support, and state tracking
  */
 export interface ExtendedAudioQueueChannel {
+  /** Set of callbacks triggered when audio completes playback */
   audioCompleteCallbacks: Set<AudioCompleteCallback>;
+  /** Set of callbacks triggered when audio errors occur */
   audioErrorCallbacks: Set<AudioErrorCallback>;
+  /** Set of callbacks triggered when audio is paused */
   audioPauseCallbacks: Set<AudioPauseCallback>;
+  /** Set of callbacks triggered when audio is resumed */
   audioResumeCallbacks: Set<AudioResumeCallback>;
+  /** Set of callbacks triggered when audio starts playing */
   audioStartCallbacks: Set<AudioStartCallback>;
+  /** Current fade state if pause/resume with fade is active */
   fadeState?: ChannelFadeState;
+  /** Whether the channel is currently paused */
   isPaused: boolean;
   /** Active operation lock to prevent race conditions */
   isLocked?: boolean;
   /** Maximum allowed queue size for this channel */
   maxQueueSize?: number;
+  /** Map of progress callbacks keyed by audio element or global symbol */
   progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
+  /** Array of HTMLAudioElement objects in the queue */
   queue: HTMLAudioElement[];
+  /** Set of callbacks triggered when the queue changes */
   queueChangeCallbacks: Set<QueueChangeCallback>;
+  /** Retry configuration for failed audio loads/plays */
   retryConfig?: RetryConfig;
+  /** Current volume level for the channel (0-1) */
   volume: number;
+  /** Web Audio API context for this channel */
+  webAudioContext?: AudioContext;
+  /** Map of Web Audio API nodes for each audio element */
+  webAudioNodes?: Map<HTMLAudioElement, WebAudioNodeSet>;
 }
 
 /**
- * Easing function types for volume transitions
+ * Easing function types for smooth volume transitions and animations
  */
 export enum EasingType {
   Linear = 'linear',
@@ -287,7 +370,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 +379,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',