audio-channel-queue 1.7.0 → 1.9.0

package/src/volume.ts

@@ -2,20 +2,55 @@
  * @fileoverview Volume management functions for the audio-channel-queue package
  */
 
-import { ExtendedAudioQueueChannel, VolumeConfig } from './types';
+import { ExtendedAudioQueueChannel, VolumeConfig, FadeType, FadeConfig, EasingType } from './types';
 import { audioChannels } from './info';
 
 // Store active volume transitions to handle interruptions
-const activeTransitions = new Map<number, number>();
+const activeTransitions: Map<number, number> = new Map();
+
+/**
+ * Predefined fade configurations for different transition types
+ */
+const fadeConfigs: Record<FadeType, FadeConfig> = {
+  [FadeType.Dramatic]: {
+    duration: 800,
+    pauseCurve: EasingType.EaseIn,
+    resumeCurve: EasingType.EaseOut
+  },
+  [FadeType.Gentle]: {
+    duration: 800,
+    pauseCurve: EasingType.EaseOut,
+    resumeCurve: EasingType.EaseIn
+  },
+  [FadeType.Linear]: {
+    duration: 800,
+    pauseCurve: EasingType.Linear,
+    resumeCurve: 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`);
+ * ```
+ */
+export const getFadeConfig = (fadeType: FadeType): FadeConfig => {
+  return { ...fadeConfigs[fadeType] };
+};
 
 /**
  * Easing functions for smooth volume transitions
  */
-const easingFunctions = {
-  linear: (t: number): number => t,
-  'ease-in': (t: number): number => t * t,
-  'ease-out': (t: number): number => t * (2 - t),
-  'ease-in-out': (t: number): number => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
+const easingFunctions: Record<EasingType, (t: number) => number> = {
+  [EasingType.Linear]: (t: number): number => t,
+  [EasingType.EaseIn]: (t: number): number => t * t,
+  [EasingType.EaseOut]: (t: number): number => t * (2 - t),
+  [EasingType.EaseInOut]: (t: number): number => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t)
 };
 
 /**
@@ -34,7 +69,7 @@ export const transitionVolume = async (
   channelNumber: number,
   targetVolume: number,
   duration: number = 250,
-  easing: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' = 'ease-out'
+  easing: EasingType = EasingType.EaseOut
 ): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel || channel.queue.length === 0) return;
@@ -42,10 +77,17 @@ export const transitionVolume = async (
   const currentAudio: HTMLAudioElement = channel.queue[0];
   const startVolume: number = currentAudio.volume;
   const volumeDelta: number = targetVolume - startVolume;
-  
+
   // Cancel any existing transition for this channel
   if (activeTransitions.has(channelNumber)) {
-    clearTimeout(activeTransitions.get(channelNumber));
+    const transitionId = activeTransitions.get(channelNumber);
+    if (transitionId) {
+      // Handle both requestAnimationFrame and setTimeout IDs
+      if (typeof cancelAnimationFrame !== 'undefined') {
+        cancelAnimationFrame(transitionId);
+      }
+      clearTimeout(transitionId);
+    }
     activeTransitions.delete(channelNumber);
   }
 
@@ -72,10 +114,10 @@ export const transitionVolume = async (
       const elapsed: number = performance.now() - startTime;
       const progress: number = Math.min(elapsed / duration, 1);
       const easedProgress: number = easingFn(progress);
-      
-      const currentVolume: number = startVolume + (volumeDelta * easedProgress);
+
+      const currentVolume: number = startVolume + volumeDelta * easedProgress;
       const clampedVolume: number = Math.max(0, Math.min(1, currentVolume));
-      
+
       // Apply volume to both channel config and current audio
       channel.volume = clampedVolume;
       if (channel.queue.length > 0) {
@@ -116,13 +158,13 @@ export const transitionVolume = async (
  * ```
  */
 export const setChannelVolume = async (
-  channelNumber: number, 
+  channelNumber: number,
   volume: number,
   transitionDuration?: number,
-  easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out'
+  easing?: EasingType
 ): Promise<void> => {
   const clampedVolume: number = Math.max(0, Math.min(1, volume));
-  
+
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = {
       audioCompleteCallbacks: new Set(),
@@ -166,7 +208,7 @@ export const setChannelVolume = async (
  */
 export const getChannelVolume = (channelNumber: number = 0): number => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
-  return channel?.volume || 1.0;
+  return channel?.volume ?? 1.0;
 };
 
 /**
@@ -181,9 +223,7 @@ export const getChannelVolume = (channelNumber: number = 0): number => {
  * ```
  */
 export const getAllChannelsVolume = (): number[] => {
-  return audioChannels.map((channel: ExtendedAudioQueueChannel) => 
-    channel?.volume || 1.0
-  );
+  return audioChannels.map((channel: ExtendedAudioQueueChannel) => channel?.volume ?? 1.0);
 };
 
 /**
@@ -279,11 +319,11 @@ export const applyVolumeDucking = async (activeChannelNumber: number): Promise<v
   audioChannels.forEach((channel: ExtendedAudioQueueChannel, channelNumber: number) => {
     if (channel?.volumeConfig) {
       const config: VolumeConfig = channel.volumeConfig;
-      
+
       if (activeChannelNumber === config.priorityChannel) {
-        const duration = config.duckTransitionDuration || 250;
-        const easing = config.transitionEasing || 'ease-out';
-        
+        const duration = config.duckTransitionDuration ?? 250;
+        const easing = config.transitionEasing ?? EasingType.EaseOut;
+
         // Priority channel is active, duck other channels
         if (channelNumber === config.priorityChannel) {
           transitionPromises.push(
@@ -302,6 +342,28 @@ export const applyVolumeDucking = async (activeChannelNumber: number): Promise<v
   await Promise.all(transitionPromises);
 };
 
+/**
+ * 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
+ * ```
+ */
+export const fadeVolume = async (
+  channelNumber: number,
+  targetVolume: number,
+  duration: number = 250,
+  easing: EasingType = EasingType.EaseOut
+): Promise<void> => {
+  return transitionVolume(channelNumber, targetVolume, duration, easing);
+};
+
 /**
  * Restores normal volume levels when priority channel stops with smooth transitions
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -313,14 +375,14 @@ export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise
   audioChannels.forEach((channel: ExtendedAudioQueueChannel, channelNumber: number) => {
     if (channel?.volumeConfig) {
       const config: VolumeConfig = channel.volumeConfig;
-      
+
       if (stoppedChannelNumber === config.priorityChannel) {
-        const duration = config.restoreTransitionDuration || 500;
-        const easing = config.transitionEasing || 'ease-out';
-        
+        const duration = config.restoreTransitionDuration ?? 500;
+        const easing = config.transitionEasing ?? EasingType.EaseOut;
+
         // Priority channel stopped, restore normal volumes
         transitionPromises.push(
-          transitionVolume(channelNumber, channel.volume || 1.0, duration, easing)
+          transitionVolume(channelNumber, channel.volume ?? 1.0, duration, easing)
         );
       }
     }
@@ -328,4 +390,4 @@ export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise
 
   // Wait for all transitions to complete
   await Promise.all(transitionPromises);
-}; 
+};