audio-channel-queue 1.8.0 → 1.9.0

package/src/pause.ts

@@ -2,20 +2,19 @@
  * @fileoverview Pause and resume management functions for the audio-channel-queue package
  */
 
-import { ExtendedAudioQueueChannel, AudioInfo, FadeType, FadeConfig, ChannelFadeState, EasingType } from './types';
+import {
+  ExtendedAudioQueueChannel,
+  AudioInfo,
+  FadeType,
+  FadeConfig,
+  ChannelFadeState
+} from './types';
 import { audioChannels } from './info';
 import { getAudioInfoFromElement } from './utils';
 import { emitAudioPause, emitAudioResume } from './events';
-import { transitionVolume } from './volume';
+import { transitionVolume, getFadeConfig } from './volume';
+
 
-/**
- * Predefined fade configurations for different transition types
- */
-const FADE_CONFIGS: Record<FadeType, FadeConfig> = {
-  [FadeType.Linear]: { duration: 800, pauseCurve: EasingType.Linear, resumeCurve: EasingType.Linear },
-  [FadeType.Gentle]: { duration: 800, pauseCurve: EasingType.EaseOut, resumeCurve: EasingType.EaseIn },
-  [FadeType.Dramatic]: { duration: 800, pauseCurve: EasingType.EaseIn, resumeCurve: EasingType.EaseOut }
-};
 
 /**
  * Gets the current volume for a channel, accounting for synchronous state
@@ -24,7 +23,7 @@ const FADE_CONFIGS: Record<FadeType, FadeConfig> = {
  */
 const getChannelVolumeSync = (channelNumber: number): number => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  return channel?.volume || 1.0;
+  return channel?.volume ?? 1.0;
 };
 
 /**
@@ -46,46 +45,77 @@ const setChannelVolumeSync = (channelNumber: number, volume: number): void => {
  * Pauses the currently playing audio in a specific channel with smooth volume fade
  * @param fadeType - Type of fade transition to apply
  * @param channelNumber - The channel number to pause (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when the pause and fade are complete
  * @example
  * ```typescript
  * await pauseWithFade(FadeType.Gentle, 0); // Pause with gentle fade out over 800ms
- * await pauseWithFade(FadeType.Dramatic, 1); // Pause with dramatic fade out over 800ms
- * await pauseWithFade(FadeType.Linear, 2); // Linear pause with 800ms fade
+ * await pauseWithFade(FadeType.Dramatic, 1, 1500); // Pause with dramatic fade out over 1.5s
+ * await pauseWithFade(FadeType.Linear, 2, 500); // Linear pause with custom 500ms fade
  * ```
  */
-export const pauseWithFade = async (fadeType: FadeType = FadeType.Gentle, channelNumber: number = 0): Promise<void> => {
+export const pauseWithFade = async (
+  fadeType: FadeType = FadeType.Gentle,
+  channelNumber: number = 0,
+  duration?: number
+): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  
+
   if (!channel || channel.queue.length === 0) return;
-  
+
   const currentAudio: HTMLAudioElement = channel.queue[0];
-  
+
   // Don't pause if already paused or ended
   if (currentAudio.paused || currentAudio.ended) return;
-  
-  const config: FadeConfig = FADE_CONFIGS[fadeType];
-  const originalVolume: number = getChannelVolumeSync(channelNumber);
-  
-  // Store fade state for resumeWithFade to use
+
+  const config: FadeConfig = getFadeConfig(fadeType);
+  const effectiveDuration: number = duration ?? config.duration;
+
+  // Race condition fix: Use existing fadeState originalVolume if already transitioning,
+  // otherwise capture current volume
+  let originalVolume: number;
+  if (channel.fadeState?.isTransitioning) {
+    // We're already in any kind of transition (pause or resume), preserve original volume
+    originalVolume = channel.fadeState.originalVolume;
+  } else {
+    // First fade or no transition in progress, capture current volume
+    // But ensure we don't capture a volume of 0 during a transition
+    const currentVolume = getChannelVolumeSync(channelNumber);
+    originalVolume = currentVolume > 0 ? currentVolume : channel.fadeState?.originalVolume ?? 1.0;
+  }
+
+  // Store fade state for resumeWithFade to use (including custom duration)
   channel.fadeState = {
-    originalVolume,
+    customDuration: duration,
     fadeType,
-    isPaused: true
+    isPaused: true,
+    isTransitioning: true,
+    originalVolume
   };
-  
-  if (config.duration === 0) {
+
+  if (effectiveDuration === 0) {
     // Instant pause
     await pauseChannel(channelNumber);
+    // Reset volume to original for resume (synchronously to avoid state issues)
+    setChannelVolumeSync(channelNumber, originalVolume);
+    // Mark transition as complete for instant pause
+    if (channel.fadeState) {
+      channel.fadeState.isTransitioning = false;
+    }
     return;
   }
-  
+
   // Fade to 0 with pause curve, then pause
-  await transitionVolume(channelNumber, 0, config.duration, config.pauseCurve);
+  await transitionVolume(channelNumber, 0, effectiveDuration, config.pauseCurve);
   await pauseChannel(channelNumber);
-  
+
   // Reset volume to original for resume (synchronously to avoid state issues)
   setChannelVolumeSync(channelNumber, originalVolume);
+  
+  // Mark transition as complete
+  if (channel.fadeState) {
+    channel.fadeState.isTransitioning = false;
+  }
 };
 
 /**
@@ -93,102 +123,144 @@ export const pauseWithFade = async (fadeType: FadeType = FadeType.Gentle, channe
  * Uses the complementary fade curve automatically based on the pause fade type, or allows override
  * @param fadeType - Optional fade type to override the stored fade type from pause
  * @param channelNumber - The channel number to resume (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses stored or fadeType default if not provided)
  * @returns Promise that resolves when the resume and fade are complete
  * @example
  * ```typescript
  * await resumeWithFade(); // Resume with automatically paired fade curve from pause
  * await resumeWithFade(FadeType.Dramatic, 0); // Override with dramatic fade
- * await resumeWithFade(FadeType.Linear); // Override with linear fade on default channel
+ * await resumeWithFade(FadeType.Linear, 0, 1000); // Override with linear fade over 1 second
  * ```
  */
-export const resumeWithFade = async (fadeType?: FadeType, channelNumber: number = 0): Promise<void> => {
+export const resumeWithFade = async (
+  fadeType?: FadeType,
+  channelNumber: number = 0,
+  duration?: number
+): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  
+
   if (!channel || channel.queue.length === 0) return;
-  
+
   const fadeState: ChannelFadeState | undefined = channel.fadeState;
-  if (!fadeState || !fadeState.isPaused) {
+  if (!fadeState?.isPaused) {
     // Fall back to regular resume if no fade state
     await resumeChannel(channelNumber);
     return;
   }
-  
+
   // Use provided fadeType or fall back to stored fadeType from pause
-  const effectiveFadeType: FadeType = fadeType || fadeState.fadeType;
-  const config: FadeConfig = FADE_CONFIGS[effectiveFadeType];
-  
-  if (config.duration === 0) {
+  const effectiveFadeType: FadeType = fadeType ?? fadeState.fadeType;
+  const config: FadeConfig = getFadeConfig(effectiveFadeType);
+
+  // Determine effective duration: custom parameter > stored custom > fadeType default
+  let effectiveDuration: number;
+  if (duration !== undefined) {
+    effectiveDuration = duration;
+  } else if (fadeState.customDuration !== undefined) {
+    effectiveDuration = fadeState.customDuration;
+  } else {
+    effectiveDuration = config.duration;
+  }
+
+  if (effectiveDuration === 0) {
     // Instant resume
+    const targetVolume = fadeState.originalVolume > 0 ? fadeState.originalVolume : 1.0;
+    setChannelVolumeSync(channelNumber, targetVolume);
     await resumeChannel(channelNumber);
     fadeState.isPaused = false;
+    fadeState.isTransitioning = false;
     return;
   }
-  
+
+  // Race condition fix: Ensure we have a valid original volume to restore to
+  const targetVolume = fadeState.originalVolume > 0 ? fadeState.originalVolume : 1.0;
+
+  // Mark as transitioning to prevent volume capture during rapid toggles
+  fadeState.isTransitioning = true;
+
   // Set volume to 0, resume, then fade to original with resume curve
   setChannelVolumeSync(channelNumber, 0);
   await resumeChannel(channelNumber);
-  await transitionVolume(channelNumber, fadeState.originalVolume, config.duration, config.resumeCurve);
-  
+
+  // Use the stored original volume, not current volume, to prevent race conditions
+  await transitionVolume(channelNumber, targetVolume, effectiveDuration, config.resumeCurve);
+
   fadeState.isPaused = false;
+  fadeState.isTransitioning = false;
 };
 
 /**
  * Toggles pause/resume state for a specific channel with integrated fade
  * @param fadeType - Type of fade transition to apply when pausing
  * @param channelNumber - The channel number to toggle (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when the toggle and fade are complete
  * @example
  * ```typescript
  * await togglePauseWithFade(FadeType.Gentle, 0); // Toggle with gentle fade
+ * await togglePauseWithFade(FadeType.Dramatic, 0, 500); // Toggle with custom 500ms fade
  * ```
  */
-export const togglePauseWithFade = async (fadeType: FadeType = FadeType.Gentle, channelNumber: number = 0): Promise<void> => {
+export const togglePauseWithFade = async (
+  fadeType: FadeType = FadeType.Gentle,
+  channelNumber: number = 0,
+  duration?: number
+): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  
+
   if (!channel || channel.queue.length === 0) return;
-  
+
   const currentAudio: HTMLAudioElement = channel.queue[0];
-  
+
   if (currentAudio.paused) {
-    await resumeWithFade(undefined, channelNumber);
+    await resumeWithFade(undefined, channelNumber, duration);
   } else {
-    await pauseWithFade(fadeType, channelNumber);
+    await pauseWithFade(fadeType, channelNumber, duration);
   }
 };
 
 /**
  * Pauses all currently playing audio across all channels with smooth volume fade
  * @param fadeType - Type of fade transition to apply to all channels
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when all channels are paused and faded
  * @example
  * ```typescript
- * await pauseAllWithFade('dramatic'); // Pause everything with dramatic fade
+ * await pauseAllWithFade(FadeType.Dramatic); // Pause everything with dramatic fade
+ * await pauseAllWithFade(FadeType.Gentle, 1200); // Pause all channels with custom 1.2s fade
  * ```
  */
-export const pauseAllWithFade = async (fadeType: FadeType = FadeType.Gentle): Promise<void> => {
+export const pauseAllWithFade = async (
+  fadeType: FadeType = FadeType.Gentle,
+  duration?: number
+): Promise<void> => {
   const pausePromises: Promise<void>[] = [];
-  
+
   audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
-    pausePromises.push(pauseWithFade(fadeType, index));
+    pausePromises.push(pauseWithFade(fadeType, index, duration));
   });
-  
+
   await Promise.all(pausePromises);
 };
 
 /**
  * Resumes all currently paused audio across all channels with smooth volume fade
- * Uses automatically paired fade curves based on each channel's pause fade type
+ * Uses automatically paired fade curves based on each channel's pause fade type, or allows override
+ * @param fadeType - Optional fade type to override stored fade types for all channels
+ * @param duration - Optional custom fade duration in milliseconds (uses stored or fadeType default if not provided)
  * @returns Promise that resolves when all channels are resumed and faded
  * @example
  * ```typescript
  * await resumeAllWithFade(); // Resume everything with paired fade curves
+ * await resumeAllWithFade(FadeType.Gentle, 800); // Override all channels with gentle fade over 800ms
+ * await resumeAllWithFade(undefined, 600); // Use stored fade types with custom 600ms duration
  * ```
  */
-export const resumeAllWithFade = async (): Promise<void> => {
+export const resumeAllWithFade = async (fadeType?: FadeType, duration?: number): Promise<void> => {
   const resumePromises: Promise<void>[] = [];
   
   audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
-    resumePromises.push(resumeWithFade(undefined, index));
+    resumePromises.push(resumeWithFade(fadeType, index, duration));
   });
   
   await Promise.all(resumePromises);
@@ -199,17 +271,22 @@ export const resumeAllWithFade = async (): Promise<void> => {
  * If any channels are playing, all will be paused with fade
  * If all channels are paused, all will be resumed with fade
  * @param fadeType - Type of fade transition to apply when pausing
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when all toggles and fades are complete
  * @example
  * ```typescript
- * await togglePauseAllWithFade('gentle'); // Global toggle with gentle fade
+ * await togglePauseAllWithFade(FadeType.Gentle); // Global toggle with gentle fade
+ * await togglePauseAllWithFade(FadeType.Dramatic, 600); // Global toggle with custom 600ms fade
  * ```
  */
-export const togglePauseAllWithFade = async (fadeType: FadeType = FadeType.Gentle): Promise<void> => {
+export const togglePauseAllWithFade = async (
+  fadeType: FadeType = FadeType.Gentle,
+  duration?: number
+): Promise<void> => {
   let hasPlayingChannel: boolean = false;
-  
+
   // Check if any channel is currently playing
-  for (let i = 0; i < audioChannels.length; i++) {
+  for (let i: number = 0; i < audioChannels.length; i++) {
     const channel: ExtendedAudioQueueChannel = audioChannels[i];
     if (channel && channel.queue.length > 0) {
       const currentAudio: HTMLAudioElement = channel.queue[0];
@@ -219,13 +296,13 @@ export const togglePauseAllWithFade = async (fadeType: FadeType = FadeType.Gentl
       }
     }
   }
-  
+
   // If any channel is playing, pause all with fade
   // If no channels are playing, resume all with fade
   if (hasPlayingChannel) {
-    await pauseAllWithFade(fadeType);
+    await pauseAllWithFade(fadeType, duration);
   } else {
-    await resumeAllWithFade();
+    await resumeAllWithFade(fadeType, duration);
   }
 };
 
@@ -241,15 +318,19 @@ export const togglePauseAllWithFade = async (fadeType: FadeType = FadeType.Gentl
  */
 export const pauseChannel = async (channelNumber: number = 0): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  
+
   if (channel && channel.queue.length > 0) {
     const currentAudio: HTMLAudioElement = channel.queue[0];
-    
+
     if (!currentAudio.paused && !currentAudio.ended) {
       currentAudio.pause();
       channel.isPaused = true;
-      
-      const audioInfo: AudioInfo | null = getAudioInfoFromElement(currentAudio, channelNumber, audioChannels);
+
+      const audioInfo: AudioInfo | null = getAudioInfoFromElement(
+        currentAudio,
+        channelNumber,
+        audioChannels
+      );
       if (audioInfo) {
         emitAudioPause(channelNumber, audioInfo, audioChannels);
       }
@@ -269,16 +350,20 @@ export const pauseChannel = async (channelNumber: number = 0): Promise<void> =>
  */
 export const resumeChannel = async (channelNumber: number = 0): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  
+
   if (channel && channel.queue.length > 0) {
     const currentAudio: HTMLAudioElement = channel.queue[0];
-    
+
     // Only resume if both the channel is marked as paused AND the audio element is actually paused AND not ended
     if (channel.isPaused && currentAudio.paused && !currentAudio.ended) {
       await currentAudio.play();
       channel.isPaused = false;
-      
-      const audioInfo: AudioInfo | null = getAudioInfoFromElement(currentAudio, channelNumber, audioChannels);
+
+      const audioInfo: AudioInfo | null = getAudioInfoFromElement(
+        currentAudio,
+        channelNumber,
+        audioChannels
+      );
       if (audioInfo) {
         emitAudioResume(channelNumber, audioInfo, audioChannels);
       }
@@ -297,10 +382,10 @@ export const resumeChannel = async (channelNumber: number = 0): Promise<void> =>
  */
 export const togglePauseChannel = async (channelNumber: number = 0): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  
+
   if (channel && channel.queue.length > 0) {
     const currentAudio: HTMLAudioElement = channel.queue[0];
-    
+
     if (currentAudio.paused) {
       await resumeChannel(channelNumber);
     } else {
@@ -319,11 +404,11 @@ export const togglePauseChannel = async (channelNumber: number = 0): Promise<voi
  */
 export const pauseAllChannels = async (): Promise<void> => {
   const pausePromises: Promise<void>[] = [];
-  
+
   audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
     pausePromises.push(pauseChannel(index));
   });
-  
+
   await Promise.all(pausePromises);
 };
 
@@ -337,11 +422,11 @@ export const pauseAllChannels = async (): Promise<void> => {
  */
 export const resumeAllChannels = async (): Promise<void> => {
   const resumePromises: Promise<void>[] = [];
-  
+
   audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
     resumePromises.push(resumeChannel(index));
   });
-  
+
   await Promise.all(resumePromises);
 };
 
@@ -357,7 +442,7 @@ export const resumeAllChannels = async (): Promise<void> => {
  */
 export const isChannelPaused = (channelNumber: number = 0): boolean => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  return channel?.isPaused || false;
+  return channel?.isPaused ?? false;
 };
 
 /**
@@ -372,9 +457,7 @@ export const isChannelPaused = (channelNumber: number = 0): boolean => {
  * ```
  */
 export const getAllChannelsPauseState = (): boolean[] => {
-  return audioChannels.map((channel: ExtendedAudioQueueChannel) => 
-    channel?.isPaused || false
-  );
+  return audioChannels.map((channel: ExtendedAudioQueueChannel) => channel?.isPaused ?? false);
 };
 
 /**
@@ -389,9 +472,9 @@ export const getAllChannelsPauseState = (): boolean[] => {
  */
 export const togglePauseAllChannels = async (): Promise<void> => {
   let hasPlayingChannel: boolean = false;
-  
+
   // Check if any channel is currently playing
-  for (let i = 0; i < audioChannels.length; i++) {
+  for (let i: number = 0; i < audioChannels.length; i++) {
     const channel: ExtendedAudioQueueChannel = audioChannels[i];
     if (channel && channel.queue.length > 0) {
       const currentAudio: HTMLAudioElement = channel.queue[0];
@@ -401,7 +484,7 @@ export const togglePauseAllChannels = async (): Promise<void> => {
       }
     }
   }
-  
+
   // If any channel is playing, pause all channels
   // If no channels are playing, resume all channels
   if (hasPlayingChannel) {
@@ -409,4 +492,4 @@ export const togglePauseAllChannels = async (): Promise<void> => {
   } else {
     await resumeAllChannels();
   }
-}; 
+};

package/src/types.ts

@@ -2,6 +2,12 @@
  * @fileoverview Type definitions for the audio-channel-queue package
  */
 
+/**
+ * Symbol used as a key for global (channel-wide) progress callbacks
+ * This avoids the need for `null as any` type assertions
+ */
+export const GLOBAL_PROGRESS_KEY: unique symbol = Symbol('global-progress-callbacks');
+
 /**
  * Array of HTMLAudioElement objects representing an audio queue
  */
@@ -10,7 +16,7 @@ export type AudioQueue = HTMLAudioElement[];
 /**
  * Basic audio queue channel structure
  */
-export type AudioQueueChannel = {
+export interface AudioQueueChannel {
   queue: AudioQueue;
 }
 
@@ -228,7 +234,7 @@ export interface ExtendedAudioQueueChannel {
   audioStartCallbacks: Set<AudioStartCallback>;
   fadeState?: ChannelFadeState;
   isPaused?: boolean;
-  progressCallbacks: Map<HTMLAudioElement | null, Set<ProgressCallback>>;
+  progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
   queue: HTMLAudioElement[];
   queueChangeCallbacks: Set<QueueChangeCallback>;
   retryConfig?: RetryConfig;
@@ -277,4 +283,8 @@ export interface ChannelFadeState {
   fadeType: FadeType;
   /** Whether the channel is currently paused due to fade */
   isPaused: boolean;
+  /** Custom duration in milliseconds if specified (overrides fade type default) */
+  customDuration?: number;
+  /** Whether the channel is currently transitioning (during any fade operation) to prevent capturing intermediate volumes during rapid pause/resume toggles */
+  isTransitioning?: boolean;
 } 

package/src/utils.ts

@@ -40,14 +40,14 @@ export const extractFileName = (url: string): string => {
  * const audioElement = new Audio('song.mp3');
  * const info = getAudioInfoFromElement(audioElement);
  * console.log(info?.progress); // Current progress as decimal (0-1)
- * 
+ *
  * // With channel context for remainingInQueue
  * const infoWithQueue = getAudioInfoFromElement(audioElement, 0, audioChannels);
  * console.log(infoWithQueue?.remainingInQueue); // Number of items left in queue
  * ```
  */
 export const getAudioInfoFromElement = (
-  audio: HTMLAudioElement, 
+  audio: HTMLAudioElement,
   channelNumber?: number,
   audioChannels?: ExtendedAudioQueueChannel[]
 ): AudioInfo | null => {
@@ -60,7 +60,7 @@ export const getAudioInfoFromElement = (
 
   // Calculate remainingInQueue if channel context is provided
   let remainingInQueue: number = 0;
-  if (channelNumber !== undefined && audioChannels && audioChannels[channelNumber]) {
+  if (channelNumber !== undefined && audioChannels?.[channelNumber]) {
     const channel = audioChannels[channelNumber];
     remainingInQueue = Math.max(0, channel.queue.length - 1); // Exclude current playing audio
   }
@@ -91,7 +91,7 @@ export const getAudioInfoFromElement = (
  * ```
  */
 export const createQueueSnapshot = (
-  channelNumber: number, 
+  channelNumber: number,
   audioChannels: ExtendedAudioQueueChannel[]
 ): QueueSnapshot | null => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
@@ -109,10 +109,10 @@ export const createQueueSnapshot = (
   return {
     channelNumber,
     currentIndex: 0, // Current playing is always index 0 in our queue structure
-    isPaused: channel.isPaused || false,
+    isPaused: channel.isPaused ?? false,
     items,
     totalItems: channel.queue.length,
-    volume: channel.volume || 1.0
+    volume: channel.volume ?? 1.0
   };
 };
 
@@ -131,4 +131,4 @@ export const createQueueSnapshot = (
 export const cleanWebpackFilename = (fileName: string): string => {
   // Remove webpack hash pattern: filename.hash.ext → filename.ext
   return fileName.replace(/\.[a-f0-9]{8,}\./i, '.');
-}; 
+};