audio-channel-queue 1.8.0 → 1.10.0

package/src/pause.ts

@@ -2,20 +2,17 @@
  * @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';
-
-/**
- * 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 }
-};
+import { transitionVolume, getFadeConfig } from './volume';
 
 /**
  * Gets the current volume for a channel, accounting for synchronous state
@@ -24,7 +21,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 +43,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,104 +121,146 @@ 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 +269,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 +294,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 +316,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 +348,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 +380,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 +402,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 +420,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 +440,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 +455,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 +470,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 +482,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 +490,4 @@ export const togglePauseAllChannels = async (): Promise<void> => {
   } else {
     await resumeAllChannels();
   }
-}; 
+};