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

package/dist/volume.js

@@ -12,13 +12,19 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = exports.restoreVolumeLevels = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = exports.getFadeConfig = void 0;
+exports.cleanupWebAudioForAudio = exports.initializeWebAudioForAudio = exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = exports.restoreVolumeLevels = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.getGlobalVolume = exports.setGlobalVolume = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = exports.getFadeConfig = void 0;
 const types_1 = require("./types");
 const info_1 = require("./info");
+const web_audio_1 = require("./web-audio");
 // Store active volume transitions to handle interruptions
 const activeTransitions = new Map();
 // Track which timer type was used for each channel
 const timerTypes = new Map();
+/**
+ * Global volume multiplier that affects all channels
+ * Acts as a global volume control (0-1)
+ */
+let globalVolume = 1.0;
 /**
  * Global volume ducking configuration
  * Stores the volume ducking settings that apply to all channels
@@ -119,7 +125,7 @@ const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __await
     const startTime = performance.now();
     const easingFn = easingFunctions[easing];
     return new Promise((resolve) => {
-        const updateVolume = () => {
+        const updateVolume = () => __awaiter(void 0, void 0, void 0, function* () {
             const elapsed = performance.now() - startTime;
             const progress = Math.min(elapsed / duration, 1);
             const easedProgress = easingFn(progress);
@@ -128,7 +134,7 @@ const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __await
             // Apply volume to both channel config and current audio
             channel.volume = clampedVolume;
             if (channel.queue.length > 0) {
-                channel.queue[0].volume = clampedVolume;
+                yield setVolumeForAudio(channel.queue[0], clampedVolume, channelNumber);
             }
             if (progress >= 1) {
                 // Transition complete
@@ -139,24 +145,25 @@ const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __await
             else {
                 // Use requestAnimationFrame in browser, setTimeout in tests
                 if (typeof requestAnimationFrame !== 'undefined') {
-                    const rafId = requestAnimationFrame(updateVolume);
+                    const rafId = requestAnimationFrame(() => updateVolume());
                     activeTransitions.set(channelNumber, rafId);
                     timerTypes.set(channelNumber, types_1.TimerType.RequestAnimationFrame);
                 }
                 else {
                     // In test environment, use shorter intervals
-                    const timeoutId = setTimeout(updateVolume, 1);
+                    const timeoutId = setTimeout(() => updateVolume(), 1);
                     activeTransitions.set(channelNumber, timeoutId);
                     timerTypes.set(channelNumber, types_1.TimerType.Timeout);
                 }
             }
-        };
+        });
         updateVolume();
     });
 });
 exports.transitionVolume = transitionVolume;
 /**
  * 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
@@ -192,17 +199,21 @@ const setChannelVolume = (channelNumber, volume, transitionDuration, easing) =>
         };
         return;
     }
+    const channel = info_1.audioChannels[channelNumber];
+    // Initialize Web Audio API if needed and supported
+    if ((0, web_audio_1.shouldUseWebAudio)() && !channel.webAudioContext) {
+        yield initializeWebAudioForChannel(channelNumber);
+    }
     if (transitionDuration && transitionDuration > 0) {
         // Smooth transition
         yield (0, exports.transitionVolume)(channelNumber, clampedVolume, transitionDuration, easing);
     }
     else {
         // Instant change (backward compatibility)
-        info_1.audioChannels[channelNumber].volume = clampedVolume;
-        const channel = info_1.audioChannels[channelNumber];
+        channel.volume = clampedVolume;
         if (channel.queue.length > 0) {
             const currentAudio = channel.queue[0];
-            currentAudio.volume = clampedVolume;
+            yield setVolumeForAudio(currentAudio, clampedVolume, channelNumber);
         }
     }
 });
@@ -255,6 +266,48 @@ const setAllChannelsVolume = (volume) => __awaiter(void 0, void 0, void 0, funct
     yield Promise.all(promises);
 });
 exports.setAllChannelsVolume = setAllChannelsVolume;
+/**
+ * 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%
+ * ```
+ */
+const setGlobalVolume = (volume) => __awaiter(void 0, void 0, void 0, function* () {
+    // 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 = [];
+    info_1.audioChannels.forEach((channel, channelNumber) => {
+        if (channel && channel.queue.length > 0) {
+            const currentAudio = channel.queue[0];
+            updatePromises.push(setVolumeForAudio(currentAudio, channel.volume, channelNumber));
+        }
+    });
+    yield Promise.all(updatePromises);
+});
+exports.setGlobalVolume = setGlobalVolume;
+/**
+ * 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}%`);
+ * ```
+ */
+const getGlobalVolume = () => {
+    return globalVolume;
+};
+exports.getGlobalVolume = getGlobalVolume;
 /**
  * Configures volume ducking for channels. When the priority channel plays audio,
  * all other channels will be automatically reduced to the ducking volume level
@@ -333,13 +386,13 @@ const applyVolumeDucking = (activeChannelNumber) => __awaiter(void 0, void 0, vo
             // This is the priority channel - set to priority volume
             // Only change audio volume, preserve channel.volume as desired volume
             const currentAudio = channel.queue[0];
-            transitionPromises.push(transitionAudioVolume(currentAudio, config.priorityVolume, duration, easing));
+            transitionPromises.push(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 = channel.queue[0];
-            transitionPromises.push(transitionAudioVolume(currentAudio, config.duckingVolume, duration, easing));
+            transitionPromises.push(transitionAudioVolume(currentAudio, config.duckingVolume, duration, easing, channelNumber));
         }
     });
     // Wait for all transitions to complete
@@ -376,7 +429,7 @@ const restoreVolumeLevels = (stoppedChannelNumber) => __awaiter(void 0, void 0,
         const targetVolume = (_c = channel.volume) !== null && _c !== void 0 ? _c : 1.0;
         // Only transition the audio element volume, keep channel.volume as the desired volume
         const currentAudio = channel.queue[0];
-        transitionPromises.push(transitionAudioVolume(currentAudio, targetVolume, duration, easing));
+        transitionPromises.push(transitionAudioVolume(currentAudio, targetVolume, duration, easing, channelNumber));
     });
     // Wait for all transitions to complete
     yield Promise.all(transitionPromises);
@@ -385,23 +438,42 @@ exports.restoreVolumeLevels = restoreVolumeLevels;
 /**
  * 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
  */
-const transitionAudioVolume = (audio_1, targetVolume_1, ...args_1) => __awaiter(void 0, [audio_1, targetVolume_1, ...args_1], void 0, function* (audio, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut) {
+const transitionAudioVolume = (audio_1, targetVolume_1, ...args_1) => __awaiter(void 0, [audio_1, targetVolume_1, ...args_1], void 0, function* (audio, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut, channelNumber) {
+    // Apply global volume multiplier
+    const actualTargetVolume = targetVolume * globalVolume;
+    // Try to use Web Audio API if available and channel number is provided
+    if (channelNumber !== undefined) {
+        const channel = info_1.audioChannels[channelNumber];
+        if ((channel === null || channel === void 0 ? void 0 : channel.webAudioContext) && channel.webAudioNodes) {
+            const nodes = channel.webAudioNodes.get(audio);
+            if (nodes) {
+                // Use Web Audio API for smooth transitions
+                (0, web_audio_1.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 = audio.volume;
-    const volumeDelta = targetVolume - startVolume;
+    const volumeDelta = actualTargetVolume - startVolume;
     // If no change needed, resolve immediately
     if (Math.abs(volumeDelta) < 0.001) {
         return Promise.resolve();
     }
     // 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();
     }
     const startTime = performance.now();
@@ -424,7 +496,8 @@ const transitionAudioVolume = (audio_1, targetVolume_1, ...args_1) => __awaiter(
                     requestAnimationFrame(updateVolume);
                 }
                 else {
-                    setTimeout(updateVolume, 1);
+                    // In test environment, use longer intervals to prevent stack overflow
+                    setTimeout(updateVolume, 16);
                 }
             }
         };
@@ -467,3 +540,96 @@ const cancelAllVolumeTransitions = () => {
     });
 };
 exports.cancelAllVolumeTransitions = cancelAllVolumeTransitions;
+/**
+ * Initializes Web Audio API for a specific channel
+ * @param channelNumber - The channel number to initialize Web Audio for
+ * @internal
+ */
+const initializeWebAudioForChannel = (channelNumber) => __awaiter(void 0, void 0, void 0, function* () {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel || channel.webAudioContext)
+        return;
+    const audioContext = (0, web_audio_1.getAudioContext)();
+    if (!audioContext) {
+        throw new Error('AudioContext creation failed');
+    }
+    // Resume audio context if needed (for autoplay policy)
+    yield (0, web_audio_1.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 = (0, web_audio_1.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 = (audio, volume, channelNumber, transitionDuration) => __awaiter(void 0, void 0, void 0, function* () {
+    const channel = info_1.audioChannels[channelNumber];
+    // Apply global volume multiplier to the channel volume
+    const actualVolume = volume * globalVolume;
+    // Use Web Audio API if available and initialized
+    if ((channel === null || channel === void 0 ? void 0 : channel.webAudioContext) && channel.webAudioNodes) {
+        const nodes = channel.webAudioNodes.get(audio);
+        if (nodes) {
+            (0, web_audio_1.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
+ */
+const initializeWebAudioForAudio = (audio, channelNumber) => __awaiter(void 0, void 0, void 0, function* () {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel)
+        return;
+    // Initialize Web Audio API for the channel if needed
+    if ((0, web_audio_1.shouldUseWebAudio)() && !channel.webAudioContext) {
+        yield initializeWebAudioForChannel(channelNumber);
+    }
+    // Create nodes for this specific audio element
+    if (channel.webAudioContext && channel.webAudioNodes && !channel.webAudioNodes.has(audio)) {
+        const nodes = (0, web_audio_1.createWebAudioNodes)(audio, channel.webAudioContext);
+        if (nodes) {
+            channel.webAudioNodes.set(audio, nodes);
+            // Set initial volume to match channel volume
+            nodes.gainNode.gain.value = channel.volume;
+        }
+    }
+});
+exports.initializeWebAudioForAudio = initializeWebAudioForAudio;
+/**
+ * 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
+ */
+const cleanupWebAudioForAudio = (audio, channelNumber) => {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!(channel === null || channel === void 0 ? void 0 : channel.webAudioNodes))
+        return;
+    const nodes = channel.webAudioNodes.get(audio);
+    if (nodes) {
+        (0, web_audio_1.cleanupWebAudioNodes)(nodes);
+        channel.webAudioNodes.delete(audio);
+    }
+};
+exports.cleanupWebAudioForAudio = cleanupWebAudioForAudio;

package/dist/web-audio.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Web Audio API support for enhanced volume control on iOS and other platforms
+ */
+import { WebAudioConfig, WebAudioSupport, WebAudioNodeSet } from './types';
+/**
+ * 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 declare const isIOSDevice: () => boolean;
+/**
+ * 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 declare const isWebAudioSupported: () => boolean;
+/**
+ * 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 declare const shouldUseWebAudio: () => boolean;
+/**
+ * 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 declare const getWebAudioSupport: () => WebAudioSupport;
+/**
+ * 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 declare const setWebAudioConfig: (config: Partial<WebAudioConfig>) => void;
+/**
+ * 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 declare const getWebAudioConfig: () => 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 declare const getAudioContext: () => AudioContext | 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 declare const createWebAudioNodes: (audioElement: HTMLAudioElement, audioContext: AudioContext) => WebAudioNodeSet | 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 declare const setWebAudioVolume: (gainNode: GainNode, volume: number, transitionDuration?: number) => void;
+/**
+ * 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 declare const getWebAudioVolume: (gainNode: GainNode) => number;
+/**
+ * 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 declare const resumeAudioContext: (audioContext: AudioContext) => Promise<void>;
+/**
+ * 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 declare const cleanupWebAudioNodes: (nodes: WebAudioNodeSet) => void;