audio-channel-queue 1.6.0 → 1.7.0

package/dist/core.js

@@ -17,6 +17,7 @@ const info_1 = require("./info");
 const utils_1 = require("./utils");
 const events_1 = require("./events");
 const volume_1 = require("./volume");
+const errors_1 = require("./errors");
 /**
  * Queues an audio file to a specific channel and starts playing if it's the first in queue
  * @param audioUrl - The URL of the audio file to queue
@@ -32,9 +33,11 @@ const volume_1 = require("./volume");
  * ```
  */
 const queueAudio = (audioUrl_1, ...args_1) => __awaiter(void 0, [audioUrl_1, ...args_1], void 0, function* (audioUrl, channelNumber = 0, options) {
-    if (!info_1.audioChannels[channelNumber]) {
-        info_1.audioChannels[channelNumber] = {
+    // Ensure the channel exists
+    while (info_1.audioChannels.length <= channelNumber) {
+        info_1.audioChannels.push({
             audioCompleteCallbacks: new Set(),
+            audioErrorCallbacks: new Set(),
             audioPauseCallbacks: new Set(),
             audioResumeCallbacks: new Set(),
             audioStartCallbacks: new Set(),
@@ -43,43 +46,51 @@ const queueAudio = (audioUrl_1, ...args_1) => __awaiter(void 0, [audioUrl_1, ...
             queue: [],
             queueChangeCallbacks: new Set(),
             volume: 1.0
-        };
+        });
     }
+    const channel = info_1.audioChannels[channelNumber];
     const audio = new Audio(audioUrl);
-    // Apply audio configuration from options
-    if (options === null || options === void 0 ? void 0 : options.loop) {
-        audio.loop = true;
-    }
-    if ((options === null || options === void 0 ? void 0 : options.volume) !== undefined) {
-        const clampedVolume = Math.max(0, Math.min(1, options.volume));
-        // Handle NaN case - default to channel volume or 1.0
-        const safeVolume = isNaN(clampedVolume) ? (info_1.audioChannels[channelNumber].volume || 1.0) : clampedVolume;
-        audio.volume = safeVolume;
-        // Also update the channel volume
-        info_1.audioChannels[channelNumber].volume = safeVolume;
-    }
-    else {
-        // Use channel volume if no specific volume is set
-        const channelVolume = info_1.audioChannels[channelNumber].volume || 1.0;
-        audio.volume = channelVolume;
+    // Set up comprehensive error handling
+    (0, errors_1.setupAudioErrorHandling)(audio, channelNumber, audioUrl, (error) => __awaiter(void 0, void 0, void 0, function* () {
+        yield (0, errors_1.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 === null || options === void 0 ? void 0 : options.addToFront) || (options === null || options === void 0 ? void 0 : options.priority)) && info_1.audioChannels[channelNumber].queue.length > 0) {
-        // Insert after the currently playing audio (index 1)
-        info_1.audioChannels[channelNumber].queue.splice(1, 0, audio);
+    // 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
+    if (shouldAddToFront && channel.queue.length > 0) {
+        // Insert after currently playing track (at index 1)
+        channel.queue.splice(1, 0, audio);
     }
-    else if (((options === null || options === void 0 ? void 0 : options.addToFront) || (options === null || options === void 0 ? void 0 : options.priority)) && info_1.audioChannels[channelNumber].queue.length === 0) {
-        // If queue is empty, just add normally
-        info_1.audioChannels[channelNumber].queue.push(audio);
+    else if (shouldAddToFront) {
+        // If queue is empty, add to front
+        channel.queue.unshift(audio);
     }
     else {
-        // Default behavior - add to back of queue
-        info_1.audioChannels[channelNumber].queue.push(audio);
+        // Add to back of queue
+        channel.queue.push(audio);
     }
+    // Emit queue change event
     (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
-    if (info_1.audioChannels[channelNumber].queue.length === 1) {
-        // Don't await - let playback happen asynchronously
-        (0, exports.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(() => {
+            (0, exports.playAudioQueue)(channelNumber).catch((error) => {
+                (0, errors_1.handleAudioError)(audio, channelNumber, audioUrl, error);
+            });
+        }, 0);
     }
 });
 exports.queueAudio = queueAudio;
@@ -167,8 +178,12 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
             if (currentAudio.loop) {
                 // For looping audio, reset current time and continue playing
                 currentAudio.currentTime = 0;
-                yield currentAudio.play();
-                // Don't remove from queue, but resolve the promise so tests don't hang
+                try {
+                    yield currentAudio.play();
+                }
+                catch (error) {
+                    yield (0, errors_1.handleAudioError)(currentAudio, channelNumber, currentAudio.src, error);
+                }
                 resolve();
             }
             else {
@@ -188,7 +203,11 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
         if (currentAudio.readyState >= 1) { // HAVE_METADATA or higher
             metadataLoaded = true;
         }
-        currentAudio.play();
+        // Enhanced play with error handling
+        currentAudio.play().catch((error) => __awaiter(void 0, void 0, void 0, function* () {
+            yield (0, errors_1.handleAudioError)(currentAudio, channelNumber, currentAudio.src, error);
+            resolve(); // Resolve to prevent hanging
+        }));
     });
 });
 exports.playAudioQueue = playAudioQueue;

package/dist/errors.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Error handling, retry logic, and recovery mechanisms for the audio-channel-queue package
+ */
+import { AudioErrorInfo, AudioErrorCallback, 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)
+ * @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 declare const onAudioError: (channelNumber: number | undefined, callback: AudioErrorCallback) => void;
+/**
+ * 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 declare const offAudioError: (channelNumber?: number, callback?: AudioErrorCallback) => void;
+/**
+ * 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 declare const setRetryConfig: (config: Partial<RetryConfig>) => void;
+/**
+ * Gets the current global retry configuration
+ * @returns Current retry configuration
+ * @example
+ * ```typescript
+ * const config = getRetryConfig();
+ * console.log(`Max retries: ${config.maxRetries}`);
+ * ```
+ */
+export declare const getRetryConfig: () => RetryConfig;
+/**
+ * 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 declare const setErrorRecovery: (options: Partial<ErrorRecoveryOptions>) => void;
+/**
+ * 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 declare const getErrorRecovery: () => ErrorRecoveryOptions;
+/**
+ * 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 declare const retryFailedAudio: (channelNumber?: number) => Promise<boolean>;
+/**
+ * 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 declare const emitAudioError: (channelNumber: number, errorInfo: AudioErrorInfo, audioChannels: ExtendedAudioQueueChannel[]) => void;
+/**
+ * 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 declare const categorizeError: (error: Error, audio: HTMLAudioElement) => AudioErrorInfo["errorType"];
+/**
+ * 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 declare const setupAudioErrorHandling: (audio: HTMLAudioElement, channelNumber: number, originalUrl: string, onError?: (error: Error) => Promise<void>) => void;
+/**
+ * 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 declare const handleAudioError: (audio: HTMLAudioElement, channelNumber: number, originalUrl: string, error: Error) => Promise<void>;
+/**
+ * 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 declare const createProtectedAudioElement: (url: string, channelNumber: number) => Promise<HTMLAudioElement>;