audio-channel-queue 1.12.0 → 1.12.1-beta.2

package/src/volume.ts

@@ -12,12 +12,26 @@ import {
   MAX_CHANNELS
 } from './types';
 import { audioChannels } from './info';
+import {
+  shouldUseWebAudio,
+  getAudioContext,
+  createWebAudioNodes,
+  setWebAudioVolume,
+  resumeAudioContext,
+  cleanupWebAudioNodes
+} from './web-audio';
 
 // Store active volume transitions to handle interruptions
 const activeTransitions: Map<number, number> = new Map();
 // Track which timer type was used for each channel
 const timerTypes: Map<number, TimerType> = new Map();
 
+/**
+ * Global volume multiplier that affects all channels
+ * Acts as a global volume control (0-1)
+ */
+let globalVolume: number = 1.0;
+
 /**
  * Global volume ducking configuration
  * Stores the volume ducking settings that apply to all channels
@@ -132,7 +146,7 @@ export const transitionVolume = async (
   const easingFn = easingFunctions[easing];
 
   return new Promise<void>((resolve) => {
-    const updateVolume = (): void => {
+    const updateVolume = async (): Promise<void> => {
       const elapsed: number = performance.now() - startTime;
       const progress: number = Math.min(elapsed / duration, 1);
       const easedProgress: number = easingFn(progress);
@@ -143,7 +157,7 @@ export const transitionVolume = async (
       // Apply volume to both channel config and current audio
       channel.volume = clampedVolume;
       if (channel.queue.length > 0) {
-        channel.queue[0].volume = clampedVolume;
+        await setVolumeForAudio(channel.queue[0], clampedVolume, channelNumber);
       }
 
       if (progress >= 1) {
@@ -154,12 +168,12 @@ export const transitionVolume = async (
       } else {
         // Use requestAnimationFrame in browser, setTimeout in tests
         if (typeof requestAnimationFrame !== 'undefined') {
-          const rafId = requestAnimationFrame(updateVolume);
+          const rafId = requestAnimationFrame(() => updateVolume());
           activeTransitions.set(channelNumber, rafId as unknown as number);
           timerTypes.set(channelNumber, TimerType.RequestAnimationFrame);
         } else {
           // In test environment, use shorter intervals
-          const timeoutId = setTimeout(updateVolume, 1);
+          const timeoutId = setTimeout(() => updateVolume(), 1);
           activeTransitions.set(channelNumber, timeoutId as unknown as number);
           timerTypes.set(channelNumber, TimerType.Timeout);
         }
@@ -172,6 +186,7 @@ export const transitionVolume = async (
 
 /**
  * Sets the volume for a specific channel with optional smooth transition
+ * Automatically uses Web Audio API on iOS devices for enhanced volume control
  * @param channelNumber - The channel number to set volume for
  * @param volume - Volume level (0-1)
  * @param transitionDuration - Optional transition duration in milliseconds
@@ -217,16 +232,22 @@ export const setChannelVolume = async (
     return;
   }
 
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+
+  // Initialize Web Audio API if needed and supported
+  if (shouldUseWebAudio() && !channel.webAudioContext) {
+    await initializeWebAudioForChannel(channelNumber);
+  }
+
   if (transitionDuration && transitionDuration > 0) {
     // Smooth transition
     await transitionVolume(channelNumber, clampedVolume, transitionDuration, easing);
   } else {
     // Instant change (backward compatibility)
-    audioChannels[channelNumber].volume = clampedVolume;
-    const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+    channel.volume = clampedVolume;
     if (channel.queue.length > 0) {
       const currentAudio: HTMLAudioElement = channel.queue[0];
-      currentAudio.volume = clampedVolume;
+      await setVolumeForAudio(currentAudio, clampedVolume, channelNumber);
     }
   }
 };
@@ -278,6 +299,50 @@ export const setAllChannelsVolume = async (volume: number): Promise<void> => {
   await Promise.all(promises);
 };
 
+/**
+ * Sets the global volume multiplier that affects all channels
+ * This acts as a global volume control - individual channel volumes are multiplied by this value
+ * @param volume - Global volume level (0-1, will be clamped to this range)
+ * @example
+ * ```typescript
+ * // Set channel-specific volumes
+ * await setChannelVolume(0, 0.8); // SFX at 80%
+ * await setChannelVolume(1, 0.6); // Music at 60%
+ *
+ * // Apply global volume of 50% - all channels play at half their set volume
+ * await setGlobalVolume(0.5); // SFX now plays at 40%, music at 30%
+ * ```
+ */
+export const setGlobalVolume = async (volume: number): Promise<void> => {
+  // Clamp to valid range
+  globalVolume = Math.max(0, Math.min(1, volume));
+
+  // Update all currently playing audio to reflect the new global volume
+  // Note: setVolumeForAudio internally multiplies channel.volume by globalVolume
+  const updatePromises: Promise<void>[] = [];
+  audioChannels.forEach((channel: ExtendedAudioQueueChannel, channelNumber: number) => {
+    if (channel && channel.queue.length > 0) {
+      const currentAudio: HTMLAudioElement = channel.queue[0];
+      updatePromises.push(setVolumeForAudio(currentAudio, channel.volume, channelNumber));
+    }
+  });
+
+  await Promise.all(updatePromises);
+};
+
+/**
+ * Gets the current global volume multiplier
+ * @returns Current global volume level (0-1), defaults to 1.0
+ * @example
+ * ```typescript
+ * const globalVol = getGlobalVolume();
+ * console.log(`Global volume is ${globalVol * 100}%`);
+ * ```
+ */
+export const getGlobalVolume = (): number => {
+  return globalVolume;
+};
+
 /**
  * Configures volume ducking for channels. When the priority channel plays audio,
  * all other channels will be automatically reduced to the ducking volume level
@@ -364,14 +429,14 @@ export const applyVolumeDucking = async (activeChannelNumber: number): Promise<v
       // Only change audio volume, preserve channel.volume as desired volume
       const currentAudio: HTMLAudioElement = channel.queue[0];
       transitionPromises.push(
-        transitionAudioVolume(currentAudio, config.priorityVolume, duration, easing)
+        transitionAudioVolume(currentAudio, config.priorityVolume, duration, easing, channelNumber)
       );
     } else {
       // This is a background channel - duck it
       // Only change audio volume, preserve channel.volume as desired volume
       const currentAudio: HTMLAudioElement = channel.queue[0];
       transitionPromises.push(
-        transitionAudioVolume(currentAudio, config.duckingVolume, duration, easing)
+        transitionAudioVolume(currentAudio, config.duckingVolume, duration, easing, channelNumber)
       );
     }
   });
@@ -414,7 +479,9 @@ export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise
 
     // Only transition the audio element volume, keep channel.volume as the desired volume
     const currentAudio: HTMLAudioElement = channel.queue[0];
-    transitionPromises.push(transitionAudioVolume(currentAudio, targetVolume, duration, easing));
+    transitionPromises.push(
+      transitionAudioVolume(currentAudio, targetVolume, duration, easing, channelNumber)
+    );
   });
 
   // Wait for all transitions to complete
@@ -424,10 +491,12 @@ export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise
 /**
  * Transitions only the audio element volume without affecting channel.volume
  * This is used for ducking/restoration where channel.volume represents desired volume
+ * Uses Web Audio API when available for enhanced volume control
  * @param audio - The audio element to transition
  * @param targetVolume - Target volume level (0-1)
  * @param duration - Transition duration in milliseconds
  * @param easing - Easing function type
+ * @param channelNumber - The channel number this audio belongs to (for Web Audio API)
  * @returns Promise that resolves when transition completes
  * @internal
  */
@@ -435,10 +504,30 @@ const transitionAudioVolume = async (
   audio: HTMLAudioElement,
   targetVolume: number,
   duration: number = 250,
-  easing: EasingType = EasingType.EaseOut
+  easing: EasingType = EasingType.EaseOut,
+  channelNumber?: number
 ): Promise<void> => {
+  // Apply global volume multiplier
+  const actualTargetVolume: number = targetVolume * globalVolume;
+
+  // Try to use Web Audio API if available and channel number is provided
+  if (channelNumber !== undefined) {
+    const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+    if (channel?.webAudioContext && channel.webAudioNodes) {
+      const nodes = channel.webAudioNodes.get(audio);
+      if (nodes) {
+        // Use Web Audio API for smooth transitions
+        setWebAudioVolume(nodes.gainNode, actualTargetVolume, duration);
+        // Also update the audio element's volume property for consistency
+        audio.volume = actualTargetVolume;
+        return;
+      }
+    }
+  }
+
+  // Fallback to standard HTMLAudioElement volume control with manual transition
   const startVolume: number = audio.volume;
-  const volumeDelta: number = targetVolume - startVolume;
+  const volumeDelta: number = actualTargetVolume - startVolume;
 
   // If no change needed, resolve immediately
   if (Math.abs(volumeDelta) < 0.001) {
@@ -447,7 +536,7 @@ const transitionAudioVolume = async (
 
   // Handle zero or negative duration - instant change
   if (duration <= 0) {
-    audio.volume = Math.max(0, Math.min(1, targetVolume));
+    audio.volume = actualTargetVolume;
     return Promise.resolve();
   }
 
@@ -473,7 +562,8 @@ const transitionAudioVolume = async (
         if (typeof requestAnimationFrame !== 'undefined') {
           requestAnimationFrame(updateVolume);
         } else {
-          setTimeout(updateVolume, 1);
+          // In test environment, use longer intervals to prevent stack overflow
+          setTimeout(updateVolume, 16);
         }
       }
     };
@@ -521,3 +611,113 @@ export const cancelAllVolumeTransitions = (): void => {
     cancelVolumeTransition(channelNumber);
   });
 };
+
+/**
+ * Initializes Web Audio API for a specific channel
+ * @param channelNumber - The channel number to initialize Web Audio for
+ * @internal
+ */
+const initializeWebAudioForChannel = async (channelNumber: number): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || channel.webAudioContext) return;
+
+  const audioContext = getAudioContext();
+  if (!audioContext) {
+    throw new Error('AudioContext creation failed');
+  }
+
+  // Resume audio context if needed (for autoplay policy)
+  await resumeAudioContext(audioContext);
+
+  channel.webAudioContext = audioContext;
+  channel.webAudioNodes = new Map();
+
+  // Initialize Web Audio nodes for existing audio elements
+  for (const audio of channel.queue) {
+    const nodes = createWebAudioNodes(audio, audioContext);
+    if (!nodes) {
+      throw new Error('Node creation failed');
+    }
+    channel.webAudioNodes.set(audio, nodes);
+    // Set initial volume to match channel volume
+    nodes.gainNode.gain.value = channel.volume;
+  }
+};
+
+/**
+ * Sets volume for an audio element using the appropriate method (Web Audio API or standard)
+ * @param audio - The audio element to set volume for
+ * @param volume - Channel volume level (0-1) - will be multiplied by global volume
+ * @param channelNumber - The channel number this audio belongs to
+ * @param transitionDuration - Optional transition duration in milliseconds
+ * @internal
+ */
+const setVolumeForAudio = async (
+  audio: HTMLAudioElement,
+  volume: number,
+  channelNumber: number,
+  transitionDuration?: number
+): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+
+  // Apply global volume multiplier to the channel volume
+  const actualVolume: number = volume * globalVolume;
+
+  // Use Web Audio API if available and initialized
+  if (channel?.webAudioContext && channel.webAudioNodes) {
+    const nodes = channel.webAudioNodes.get(audio);
+    if (nodes) {
+      setWebAudioVolume(nodes.gainNode, actualVolume, transitionDuration);
+      return;
+    }
+  }
+
+  // Fallback to standard HTMLAudioElement volume control
+  audio.volume = actualVolume;
+};
+
+/**
+ * Initializes Web Audio API nodes for a new audio element
+ * @param audio - The audio element to initialize nodes for
+ * @param channelNumber - The channel number this audio belongs to
+ * @internal
+ */
+export const initializeWebAudioForAudio = async (
+  audio: HTMLAudioElement,
+  channelNumber: number
+): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) return;
+
+  // Initialize Web Audio API for the channel if needed
+  if (shouldUseWebAudio() && !channel.webAudioContext) {
+    await initializeWebAudioForChannel(channelNumber);
+  }
+
+  // Create nodes for this specific audio element
+  if (channel.webAudioContext && channel.webAudioNodes && !channel.webAudioNodes.has(audio)) {
+    const nodes = createWebAudioNodes(audio, channel.webAudioContext);
+    if (nodes) {
+      channel.webAudioNodes.set(audio, nodes);
+      // Set initial volume to match channel volume
+      nodes.gainNode.gain.value = channel.volume;
+    }
+  }
+};
+
+/**
+ * Cleans up Web Audio API nodes for an audio element
+ * @param audio - The audio element to clean up nodes for
+ * @param channelNumber - The channel number this audio belongs to
+ * @internal
+ */
+export const cleanupWebAudioForAudio = (audio: HTMLAudioElement, channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.webAudioNodes) return;
+
+  const nodes = channel.webAudioNodes.get(audio);
+  if (nodes) {
+    cleanupWebAudioNodes(nodes);
+    channel.webAudioNodes.delete(audio);
+  }
+};

package/src/web-audio.ts

@@ -0,0 +1,331 @@
+/**
+ * @fileoverview Web Audio API support for enhanced volume control on iOS and other platforms
+ */
+
+import { WebAudioConfig, WebAudioSupport, WebAudioNodeSet } from './types';
+
+/**
+ * Global Web Audio API configuration
+ */
+let webAudioConfig: WebAudioConfig = {
+  autoDetectIOS: true,
+  enabled: true,
+  forceWebAudio: false
+};
+
+/**
+ * Detects if the current device is iOS
+ * @returns True if the device is iOS, false otherwise
+ * @example
+ * ```typescript
+ * if (isIOSDevice()) {
+ *   console.log('Running on iOS device');
+ * }
+ * ```
+ */
+export const isIOSDevice = (): boolean => {
+  if (typeof navigator === 'undefined') return false;
+
+  // Modern approach using User-Agent Client Hints API
+  const navWithUA = navigator as unknown as { userAgentData?: { platform: string } };
+  if ('userAgentData' in navigator && navWithUA.userAgentData) {
+    return navWithUA.userAgentData.platform === 'iOS';
+  }
+
+  // Fallback to userAgent string parsing
+  const userAgent = navigator.userAgent || '';
+  const isIOS = /iPad|iPhone|iPod/.test(userAgent);
+
+  // Additional check for modern iPads that report as Mac
+  const isMacWithTouch =
+    /Macintosh/.test(userAgent) && 'maxTouchPoints' in navigator && navigator.maxTouchPoints > 1;
+
+  return isIOS || isMacWithTouch;
+};
+
+/**
+ * Checks if Web Audio API is available in the current environment
+ * @returns True if Web Audio API is supported, false otherwise
+ * @example
+ * ```typescript
+ * if (isWebAudioSupported()) {
+ *   console.log('Web Audio API is available');
+ * }
+ * ```
+ */
+export const isWebAudioSupported = (): boolean => {
+  if (typeof window === 'undefined') {
+    // In Node.js environment (tests), check if Web Audio API globals are available
+    const globalThis = global as unknown as {
+      AudioContext?: unknown;
+      webkitAudioContext?: unknown;
+    };
+    return (
+      typeof globalThis.AudioContext !== 'undefined' ||
+      typeof globalThis.webkitAudioContext !== 'undefined'
+    );
+  }
+  const windowWithWebkit = window as unknown as { webkitAudioContext?: unknown };
+  return (
+    typeof AudioContext !== 'undefined' ||
+    typeof windowWithWebkit.webkitAudioContext !== 'undefined'
+  );
+};
+
+/**
+ * Determines if Web Audio API should be used based on configuration and device detection
+ * @returns True if Web Audio API should be used, false otherwise
+ * @example
+ * ```typescript
+ * if (shouldUseWebAudio()) {
+ *   // Use Web Audio API for volume control
+ * }
+ * ```
+ */
+export const shouldUseWebAudio = (): boolean => {
+  if (!webAudioConfig.enabled) return false;
+  if (!isWebAudioSupported()) return false;
+  if (webAudioConfig.forceWebAudio) return true;
+  if (webAudioConfig.autoDetectIOS && isIOSDevice()) return true;
+  return false;
+};
+
+/**
+ * Gets information about Web Audio API support and usage
+ * @returns Object containing Web Audio API support information
+ * @example
+ * ```typescript
+ * const support = getWebAudioSupport();
+ * console.log(`Using Web Audio: ${support.usingWebAudio}`);
+ * console.log(`Reason: ${support.reason}`);
+ * ```
+ */
+export const getWebAudioSupport = (): WebAudioSupport => {
+  const available = isWebAudioSupported();
+  const isIOS = isIOSDevice();
+  const usingWebAudio = shouldUseWebAudio();
+
+  let reason = '';
+  if (!webAudioConfig.enabled) {
+    reason = 'Web Audio API disabled in configuration';
+  } else if (!available) {
+    reason = 'Web Audio API not supported in this environment';
+  } else if (webAudioConfig.forceWebAudio) {
+    reason = 'Web Audio API forced via configuration';
+  } else if (isIOS && webAudioConfig.autoDetectIOS) {
+    reason = 'iOS device detected - using Web Audio API for volume control';
+  } else {
+    reason = 'Using standard HTMLAudioElement volume control';
+  }
+
+  return {
+    available,
+    isIOS,
+    reason,
+    usingWebAudio
+  };
+};
+
+/**
+ * Configures Web Audio API usage
+ * @param config - Configuration options for Web Audio API
+ * @example
+ * ```typescript
+ * // Force Web Audio API usage on all devices
+ * setWebAudioConfig({ forceWebAudio: true });
+ *
+ * // Disable Web Audio API entirely
+ * setWebAudioConfig({ enabled: false });
+ * ```
+ */
+export const setWebAudioConfig = (config: Partial<WebAudioConfig>): void => {
+  webAudioConfig = { ...webAudioConfig, ...config };
+};
+
+/**
+ * Gets the current Web Audio API configuration
+ * @returns Current Web Audio API configuration
+ * @example
+ * ```typescript
+ * const config = getWebAudioConfig();
+ * console.log(`Web Audio enabled: ${config.enabled}`);
+ * ```
+ */
+export const getWebAudioConfig = (): WebAudioConfig => {
+  return { ...webAudioConfig };
+};
+
+/**
+ * Creates or gets an AudioContext for Web Audio API operations
+ * @returns AudioContext instance or null if not supported
+ * @example
+ * ```typescript
+ * const context = getAudioContext();
+ * if (context) {
+ *   console.log('Audio context created successfully');
+ * }
+ * ```
+ */
+export const getAudioContext = (): AudioContext | null => {
+  if (!isWebAudioSupported()) return null;
+
+  try {
+    // In Node.js environment (tests), return null to allow mocking
+    if (typeof window === 'undefined') {
+      return null;
+    }
+
+    // Use existing AudioContext or create new one
+    const windowWithWebkit = window as unknown as { webkitAudioContext?: typeof AudioContext };
+    const AudioContextClass = window.AudioContext || windowWithWebkit.webkitAudioContext;
+    return new AudioContextClass();
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn('Failed to create AudioContext:', error);
+    return null;
+  }
+};
+
+/**
+ * Creates Web Audio API nodes for an audio element
+ * @param audioElement - The HTML audio element to create nodes for
+ * @param audioContext - The AudioContext to use
+ * @returns Web Audio API node set or null if creation fails
+ * @example
+ * ```typescript
+ * const audio = new Audio('song.mp3');
+ * const context = getAudioContext();
+ * if (context) {
+ *   const nodes = createWebAudioNodes(audio, context);
+ *   if (nodes) {
+ *     nodes.gainNode.gain.value = 0.5; // Set volume to 50%
+ *   }
+ * }
+ * ```
+ */
+export const createWebAudioNodes = (
+  audioElement: HTMLAudioElement,
+  audioContext: AudioContext
+): WebAudioNodeSet | null => {
+  try {
+    // Create media element source node
+    const sourceNode = audioContext.createMediaElementSource(audioElement);
+
+    // Create gain node for volume control
+    const gainNode = audioContext.createGain();
+
+    // Connect source to gain node
+    sourceNode.connect(gainNode);
+
+    // Connect gain node to destination (speakers)
+    gainNode.connect(audioContext.destination);
+
+    return {
+      gainNode,
+      sourceNode
+    };
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn('Failed to create Web Audio nodes:', error);
+    return null;
+  }
+};
+
+/**
+ * Sets volume using Web Audio API gain node
+ * @param gainNode - The gain node to set volume on
+ * @param volume - Volume level (0-1)
+ * @param transitionDuration - Optional transition duration in milliseconds
+ * @example
+ * ```typescript
+ * const nodes = createWebAudioNodes(audio, context);
+ * if (nodes) {
+ *   setWebAudioVolume(nodes.gainNode, 0.5); // Set to 50% volume
+ *   setWebAudioVolume(nodes.gainNode, 0.2, 300); // Fade to 20% over 300ms
+ * }
+ * ```
+ */
+export const setWebAudioVolume = (
+  gainNode: GainNode,
+  volume: number,
+  transitionDuration?: number
+): void => {
+  const clampedVolume = Math.max(0, Math.min(1, volume));
+  const currentTime = gainNode.context.currentTime;
+
+  if (transitionDuration && transitionDuration > 0) {
+    // Smooth transition using Web Audio API's built-in scheduling
+    gainNode.gain.cancelScheduledValues(currentTime);
+    gainNode.gain.setValueAtTime(gainNode.gain.value, currentTime);
+    gainNode.gain.linearRampToValueAtTime(clampedVolume, currentTime + transitionDuration / 1000);
+  } else {
+    // Instant change
+    gainNode.gain.cancelScheduledValues(currentTime);
+    gainNode.gain.setValueAtTime(clampedVolume, currentTime);
+  }
+};
+
+/**
+ * Gets the current volume from a Web Audio API gain node
+ * @param gainNode - The gain node to get volume from
+ * @returns Current volume level (0-1)
+ * @example
+ * ```typescript
+ * const nodes = createWebAudioNodes(audio, context);
+ * if (nodes) {
+ *   const volume = getWebAudioVolume(nodes.gainNode);
+ *   console.log(`Current volume: ${volume * 100}%`);
+ * }
+ * ```
+ */
+export const getWebAudioVolume = (gainNode: GainNode): number => {
+  return gainNode.gain.value;
+};
+
+/**
+ * Resumes an AudioContext if it's in suspended state (required for autoplay policy)
+ * @param audioContext - The AudioContext to resume
+ * @returns Promise that resolves when context is resumed
+ * @example
+ * ```typescript
+ * const context = getAudioContext();
+ * if (context) {
+ *   await resumeAudioContext(context);
+ * }
+ * ```
+ */
+export const resumeAudioContext = async (audioContext: AudioContext): Promise<void> => {
+  if (audioContext.state === 'suspended') {
+    try {
+      await audioContext.resume();
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.warn('Failed to resume AudioContext:', error);
+      // Don't throw - handle gracefully and continue
+    }
+  }
+};
+
+/**
+ * Cleans up Web Audio API nodes and connections
+ * @param nodes - The Web Audio API node set to clean up
+ * @example
+ * ```typescript
+ * const nodes = createWebAudioNodes(audio, context);
+ * if (nodes) {
+ *   // Use nodes...
+ *   cleanupWebAudioNodes(nodes); // Clean up when done
+ * }
+ * ```
+ */
+export const cleanupWebAudioNodes = (nodes: WebAudioNodeSet): void => {
+  try {
+    // Disconnect all nodes
+    nodes.sourceNode.disconnect();
+    nodes.gainNode.disconnect();
+  } catch (error) {
+    // Ignore errors during cleanup
+    // eslint-disable-next-line no-console
+    console.warn('Error during Web Audio cleanup:', error);
+  }
+};