audio-channel-queue 1.5.0 → 1.7.0

package/dist/core.js

@@ -12,39 +12,106 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.playAudioQueue = exports.queueAudio = void 0;
+exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.playAudioQueue = exports.queueAudioPriority = exports.queueAudio = void 0;
 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
  * @param channelNumber - The channel number to queue the audio to (defaults to 0)
+ * @param options - Optional configuration for the audio file
  * @returns Promise that resolves when the audio is queued and starts playing (if first in queue)
  * @example
  * ```typescript
  * await queueAudio('https://example.com/song.mp3', 0);
  * await queueAudio('./sounds/notification.wav'); // Uses default channel 0
+ * await queueAudio('./music/loop.mp3', 1, { loop: true }); // Loop the audio
+ * await queueAudio('./urgent.wav', 0, { addToFront: true }); // Add to front of queue
  * ```
  */
-const queueAudio = (audioUrl_1, ...args_1) => __awaiter(void 0, [audioUrl_1, ...args_1], void 0, function* (audioUrl, channelNumber = 0) {
-    if (!info_1.audioChannels[channelNumber]) {
-        info_1.audioChannels[channelNumber] = {
+const queueAudio = (audioUrl_1, ...args_1) => __awaiter(void 0, [audioUrl_1, ...args_1], void 0, function* (audioUrl, channelNumber = 0, options) {
+    // 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(),
+            isPaused: false,
             progressCallbacks: new Map(),
             queue: [],
-            queueChangeCallbacks: new Set()
-        };
+            queueChangeCallbacks: new Set(),
+            volume: 1.0
+        });
     }
+    const channel = info_1.audioChannels[channelNumber];
     const audio = new Audio(audioUrl);
-    info_1.audioChannels[channelNumber].queue.push(audio);
+    // 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;
+        }
+    }
+    // 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 (shouldAddToFront) {
+        // If queue is empty, add to front
+        channel.queue.unshift(audio);
+    }
+    else {
+        // 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) {
-        (0, exports.playAudioQueue)(channelNumber);
+    // 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;
+/**
+ * Adds an audio file to the front of the queue in a specific channel
+ * This is a convenience function that places the audio right after the currently playing track
+ * @param audioUrl - The URL of the audio file to queue
+ * @param channelNumber - The channel number to queue the audio to (defaults to 0)
+ * @param options - Optional configuration for the audio file
+ * @returns Promise that resolves when the audio is queued
+ * @example
+ * ```typescript
+ * await queueAudioPriority('./urgent-announcement.wav', 0);
+ * await queueAudioPriority('./priority-sound.mp3', 1, { loop: true });
+ * ```
+ */
+const queueAudioPriority = (audioUrl_1, ...args_1) => __awaiter(void 0, [audioUrl_1, ...args_1], void 0, function* (audioUrl, channelNumber = 0, options) {
+    const priorityOptions = Object.assign(Object.assign({}, options), { addToFront: true });
+    return (0, exports.queueAudio)(audioUrl, channelNumber, priorityOptions);
+});
+exports.queueAudioPriority = queueAudioPriority;
 /**
  * Plays the audio queue for a specific channel
  * @param channelNumber - The channel number to play
@@ -56,10 +123,16 @@ exports.queueAudio = queueAudio;
  */
 const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, function* () {
     const channel = info_1.audioChannels[channelNumber];
-    if (channel.queue.length === 0)
+    if (!channel || channel.queue.length === 0)
         return;
     const currentAudio = channel.queue[0];
+    // Apply channel volume if not already set
+    if (currentAudio.volume === 1.0 && channel.volume !== undefined) {
+        currentAudio.volume = channel.volume;
+    }
     (0, events_1.setupProgressTracking)(currentAudio, channelNumber, info_1.audioChannels);
+    // Apply volume ducking when audio starts
+    yield (0, volume_1.applyVolumeDucking)(channelNumber);
     return new Promise((resolve) => {
         let hasStarted = false;
         let metadataLoaded = false;
@@ -94,16 +167,33 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
                 remainingInQueue: channel.queue.length - 1,
                 src: currentAudio.src
             }, info_1.audioChannels);
+            // Restore volume levels when priority channel stops
+            yield (0, volume_1.restoreVolumeLevels)(channelNumber);
             // Clean up event listeners
             currentAudio.removeEventListener('loadedmetadata', handleLoadedMetadata);
             currentAudio.removeEventListener('play', handlePlay);
             currentAudio.removeEventListener('ended', handleEnded);
             (0, events_1.cleanupProgressTracking)(currentAudio, channelNumber, info_1.audioChannels);
-            channel.queue.shift();
-            // Emit queue change after completion
-            setTimeout(() => (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels), 10);
-            yield (0, exports.playAudioQueue)(channelNumber);
-            resolve();
+            // Handle looping vs non-looping audio
+            if (currentAudio.loop) {
+                // For looping audio, reset current time and continue playing
+                currentAudio.currentTime = 0;
+                try {
+                    yield currentAudio.play();
+                }
+                catch (error) {
+                    yield (0, errors_1.handleAudioError)(currentAudio, channelNumber, currentAudio.src, error);
+                }
+                resolve();
+            }
+            else {
+                // For non-looping audio, remove from queue and play next
+                channel.queue.shift();
+                // Emit queue change after completion
+                setTimeout(() => (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels), 10);
+                yield (0, exports.playAudioQueue)(channelNumber);
+                resolve();
+            }
         });
         // Add event listeners
         currentAudio.addEventListener('loadedmetadata', handleLoadedMetadata);
@@ -113,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;
@@ -122,11 +216,11 @@ exports.playAudioQueue = playAudioQueue;
  * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * stopCurrentAudioInChannel(0); // Stop current audio in channel 0
- * stopCurrentAudioInChannel(); // Stop current audio in default channel
+ * await stopCurrentAudioInChannel(); // Stop current audio in default channel (0)
+ * await stopCurrentAudioInChannel(1); // Stop current audio in channel 1
  * ```
  */
-const stopCurrentAudioInChannel = (channelNumber = 0) => {
+const stopCurrentAudioInChannel = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (channelNumber = 0) {
     const channel = info_1.audioChannels[channelNumber];
     if (channel && channel.queue.length > 0) {
         const currentAudio = channel.queue[0];
@@ -136,24 +230,28 @@ const stopCurrentAudioInChannel = (channelNumber = 0) => {
             remainingInQueue: channel.queue.length - 1,
             src: currentAudio.src
         }, info_1.audioChannels);
+        // Restore volume levels when stopping
+        yield (0, volume_1.restoreVolumeLevels)(channelNumber);
         currentAudio.pause();
         (0, events_1.cleanupProgressTracking)(currentAudio, channelNumber, info_1.audioChannels);
         channel.queue.shift();
+        channel.isPaused = false; // Reset pause state
         (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
-        (0, exports.playAudioQueue)(channelNumber);
+        // Start next audio without waiting for it to complete
+        (0, exports.playAudioQueue)(channelNumber).catch(console.error);
     }
-};
+});
 exports.stopCurrentAudioInChannel = stopCurrentAudioInChannel;
 /**
  * Stops all audio in a specific channel and clears the entire queue
  * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * stopAllAudioInChannel(0); // Clear all audio in channel 0
- * stopAllAudioInChannel(); // Clear all audio in default channel
+ * await stopAllAudioInChannel(); // Clear all audio in default channel (0)
+ * await stopAllAudioInChannel(1); // Clear all audio in channel 1
  * ```
  */
-const stopAllAudioInChannel = (channelNumber = 0) => {
+const stopAllAudioInChannel = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (channelNumber = 0) {
     const channel = info_1.audioChannels[channelNumber];
     if (channel) {
         if (channel.queue.length > 0) {
@@ -164,26 +262,31 @@ const stopAllAudioInChannel = (channelNumber = 0) => {
                 remainingInQueue: 0, // Will be 0 since we're clearing the queue
                 src: currentAudio.src
             }, info_1.audioChannels);
+            // Restore volume levels when stopping
+            yield (0, volume_1.restoreVolumeLevels)(channelNumber);
             currentAudio.pause();
             (0, events_1.cleanupProgressTracking)(currentAudio, channelNumber, info_1.audioChannels);
         }
         // Clean up all progress tracking for this channel
         channel.queue.forEach(audio => (0, events_1.cleanupProgressTracking)(audio, channelNumber, info_1.audioChannels));
         channel.queue = [];
+        channel.isPaused = false; // Reset pause state
         (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
     }
-};
+});
 exports.stopAllAudioInChannel = stopAllAudioInChannel;
 /**
  * Stops all audio across all channels and clears all queues
  * @example
  * ```typescript
- * stopAllAudio(); // Emergency stop - clears everything
+ * await stopAllAudio(); // Emergency stop - clears everything
  * ```
  */
-const stopAllAudio = () => {
+const stopAllAudio = () => __awaiter(void 0, void 0, void 0, function* () {
+    const stopPromises = [];
     info_1.audioChannels.forEach((_channel, index) => {
-        (0, exports.stopAllAudioInChannel)(index);
+        stopPromises.push((0, exports.stopAllAudioInChannel)(index));
     });
-};
+    yield Promise.all(stopPromises);
+});
 exports.stopAllAudio = stopAllAudio;

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>;