audio-channel-queue 1.7.0 → 1.9.0

package/src/pause.ts

@@ -2,10 +2,309 @@
  * @fileoverview Pause and resume management functions for the audio-channel-queue package
  */
 
-import { ExtendedAudioQueueChannel, AudioInfo } 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, getFadeConfig } from './volume';
+
+
+
+/**
+ * Gets the current volume for a channel, accounting for synchronous state
+ * @param channelNumber - The channel number
+ * @returns Current volume level (0-1)
+ */
+const getChannelVolumeSync = (channelNumber: number): number => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  return channel?.volume ?? 1.0;
+};
+
+/**
+ * Sets the channel volume synchronously in internal state
+ * @param channelNumber - The channel number
+ * @param volume - Volume level (0-1)
+ */
+const setChannelVolumeSync = (channelNumber: number, volume: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (channel) {
+    channel.volume = volume;
+    if (channel.queue.length > 0) {
+      channel.queue[0].volume = volume;
+    }
+  }
+};
+
+/**
+ * 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, 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,
+  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 = 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 = {
+    customDuration: duration,
+    fadeType,
+    isPaused: true,
+    isTransitioning: true,
+    originalVolume
+  };
+
+  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, 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;
+  }
+};
+
+/**
+ * Resumes the currently paused audio in a specific channel with smooth volume fade
+ * 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, 0, 1000); // Override with linear fade over 1 second
+ * ```
+ */
+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?.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 = 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);
+
+  // 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,
+  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, duration);
+  } else {
+    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(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,
+  duration?: number
+): Promise<void> => {
+  const pausePromises: Promise<void>[] = [];
+
+  audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
+    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, 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 (fadeType?: FadeType, duration?: number): Promise<void> => {
+  const resumePromises: Promise<void>[] = [];
+  
+  audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
+    resumePromises.push(resumeWithFade(fadeType, index, duration));
+  });
+  
+  await Promise.all(resumePromises);
+};
+
+/**
+ * Toggles pause/resume state for all channels with integrated fade
+ * 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(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,
+  duration?: number
+): Promise<void> => {
+  let hasPlayingChannel: boolean = false;
+
+  // Check if any channel is currently playing
+  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];
+      if (!currentAudio.paused && !currentAudio.ended) {
+        hasPlayingChannel = true;
+        break;
+      }
+    }
+  }
+
+  // If any channel is playing, pause all with fade
+  // If no channels are playing, resume all with fade
+  if (hasPlayingChannel) {
+    await pauseAllWithFade(fadeType, duration);
+  } else {
+    await resumeAllWithFade(fadeType, duration);
+  }
+};
 
 /**
  * Pauses the currently playing audio in a specific channel
@@ -19,15 +318,19 @@ import { emitAudioPause, emitAudioResume } from './events';
  */
 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);
       }
@@ -47,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);
       }
@@ -75,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 {
@@ -97,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);
 };
 
@@ -115,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);
 };
 
@@ -135,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;
 };
 
 /**
@@ -150,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);
 };
 
 /**
@@ -167,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];
@@ -179,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) {
@@ -187,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;
 }
 
@@ -29,7 +35,7 @@ export interface VolumeConfig {
   /** Duration in milliseconds for volume restore transition (defaults to 500ms) */
   restoreTransitionDuration?: number;
   /** Easing function for volume transitions (defaults to 'ease-out') */
-  transitionEasing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+  transitionEasing?: EasingType;
 }
 
 /**
@@ -226,11 +232,59 @@ export interface ExtendedAudioQueueChannel {
   audioPauseCallbacks: Set<AudioPauseCallback>;
   audioResumeCallbacks: Set<AudioResumeCallback>;
   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;
   volume?: number;
   volumeConfig?: VolumeConfig;
+}
+
+/**
+ * Easing function types for volume transitions
+ */
+export enum EasingType {
+  Linear = 'linear',
+  EaseIn = 'ease-in',
+  EaseOut = 'ease-out',
+  EaseInOut = 'ease-in-out'
+}
+
+/**
+ * Fade type for pause/resume operations with integrated volume transitions
+ */
+export enum FadeType {
+  Linear = 'linear',
+  Gentle = 'gentle',
+  Dramatic = 'dramatic'
+}
+
+/**
+ * Configuration for fade transitions
+ */
+export interface FadeConfig {
+  /** Duration in milliseconds for the fade transition */
+  duration: number;
+  /** Easing curve to use when pausing (fading out) */
+  pauseCurve: EasingType;
+  /** Easing curve to use when resuming (fading in) */
+  resumeCurve: EasingType;
+}
+
+/**
+ * Internal fade state tracking for pause/resume with fade functionality
+ */
+export interface ChannelFadeState {
+  /** The original volume level before fading began */
+  originalVolume: number;
+  /** The type of fade being used */
+  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, '.');
-}; 
+};