audio-channel-queue 1.6.0 → 1.8.0

package/dist/volume.js

@@ -12,18 +12,41 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.restoreVolumeLevels = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = void 0;
+exports.restoreVolumeLevels = exports.fadeVolume = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = exports.getFadeConfig = void 0;
+const types_1 = require("./types");
 const info_1 = require("./info");
 // Store active volume transitions to handle interruptions
 const activeTransitions = new Map();
+/**
+ * Predefined fade configurations for different transition types
+ */
+const FADE_CONFIGS = {
+    [types_1.FadeType.Dramatic]: { duration: 800, pauseCurve: types_1.EasingType.EaseIn, resumeCurve: types_1.EasingType.EaseOut },
+    [types_1.FadeType.Gentle]: { duration: 800, pauseCurve: types_1.EasingType.EaseOut, resumeCurve: types_1.EasingType.EaseIn },
+    [types_1.FadeType.Linear]: { duration: 800, pauseCurve: types_1.EasingType.Linear, resumeCurve: types_1.EasingType.Linear }
+};
+/**
+ * Gets the fade configuration for a specific fade type
+ * @param fadeType - The fade type to get configuration for
+ * @returns Fade configuration object
+ * @example
+ * ```typescript
+ * const config = getFadeConfig('gentle');
+ * console.log(`Gentle fade duration: ${config.duration}ms`);
+ * ```
+ */
+const getFadeConfig = (fadeType) => {
+    return Object.assign({}, FADE_CONFIGS[fadeType]);
+};
+exports.getFadeConfig = getFadeConfig;
 /**
  * Easing functions for smooth volume transitions
  */
 const easingFunctions = {
-    linear: (t) => t,
-    'ease-in': (t) => t * t,
-    'ease-out': (t) => t * (2 - t),
-    'ease-in-out': (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
+    [types_1.EasingType.Linear]: (t) => t,
+    [types_1.EasingType.EaseIn]: (t) => t * t,
+    [types_1.EasingType.EaseOut]: (t) => t * (2 - t),
+    [types_1.EasingType.EaseInOut]: (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
 };
 /**
  * Smoothly transitions volume for a specific channel over time
@@ -37,7 +60,7 @@ const easingFunctions = {
  * await transitionVolume(0, 0.2, 500, 'ease-out'); // Duck to 20% over 500ms
  * ```
  */
-const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(void 0, [channelNumber_1, targetVolume_1, ...args_1], void 0, function* (channelNumber, targetVolume, duration = 250, easing = 'ease-out') {
+const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(void 0, [channelNumber_1, targetVolume_1, ...args_1], void 0, function* (channelNumber, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut) {
     const channel = info_1.audioChannels[channelNumber];
     if (!channel || channel.queue.length === 0)
         return;
@@ -55,7 +78,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 +138,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 +231,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 +247,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(),
@@ -263,7 +289,7 @@ const applyVolumeDucking = (activeChannelNumber) => __awaiter(void 0, void 0, vo
             const config = channel.volumeConfig;
             if (activeChannelNumber === config.priorityChannel) {
                 const duration = config.duckTransitionDuration || 250;
-                const easing = config.transitionEasing || 'ease-out';
+                const easing = config.transitionEasing || types_1.EasingType.EaseOut;
                 // Priority channel is active, duck other channels
                 if (channelNumber === config.priorityChannel) {
                     transitionPromises.push((0, exports.transitionVolume)(channelNumber, config.priorityVolume, duration, easing));
@@ -278,6 +304,23 @@ const applyVolumeDucking = (activeChannelNumber) => __awaiter(void 0, void 0, vo
     yield Promise.all(transitionPromises);
 });
 exports.applyVolumeDucking = applyVolumeDucking;
+/**
+ * Fades the volume for a specific channel over time (alias for transitionVolume with improved naming)
+ * @param channelNumber - The channel number to fade
+ * @param targetVolume - Target volume level (0-1)
+ * @param duration - Fade duration in milliseconds (defaults to 250)
+ * @param easing - Easing function type (defaults to 'ease-out')
+ * @returns Promise that resolves when fade completes
+ * @example
+ * ```typescript
+ * await fadeVolume(0, 0, 800, 'ease-in'); // Fade out over 800ms
+ * await fadeVolume(0, 1, 600, 'ease-out'); // Fade in over 600ms
+ * ```
+ */
+const fadeVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(void 0, [channelNumber_1, targetVolume_1, ...args_1], void 0, function* (channelNumber, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut) {
+    return (0, exports.transitionVolume)(channelNumber, targetVolume, duration, easing);
+});
+exports.fadeVolume = fadeVolume;
 /**
  * Restores normal volume levels when priority channel stops with smooth transitions
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -290,7 +333,7 @@ const restoreVolumeLevels = (stoppedChannelNumber) => __awaiter(void 0, void 0,
             const config = channel.volumeConfig;
             if (stoppedChannelNumber === config.priorityChannel) {
                 const duration = config.restoreTransitionDuration || 500;
-                const easing = config.transitionEasing || 'ease-out';
+                const easing = config.transitionEasing || types_1.EasingType.EaseOut;
                 // Priority channel stopped, restore normal volumes
                 transitionPromises.push((0, exports.transitionVolume)(channelNumber, channel.volume || 1.0, duration, easing));
             }

package/package.json

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