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

package/dist/core.js

@@ -244,6 +244,8 @@ const queueAudio = (audioUrl_1, ...args_1) => __awaiter(void 0, [audioUrl_1, ...
     (0, errors_1.setupAudioErrorHandling)(audio, channelNumber, validatedUrl, (error) => __awaiter(void 0, void 0, void 0, function* () {
         yield (0, errors_1.handleAudioError)(audio, channelNumber, validatedUrl, error);
     }));
+    // Initialize Web Audio API support if needed
+    yield (0, volume_1.initializeWebAudioForAudio)(audio, channelNumber);
     // Apply options if provided
     if (options) {
         if (typeof options.loop === 'boolean') {
@@ -378,6 +380,7 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
                 // For non-looping audio, remove from queue and play next
                 currentAudio.pause();
                 (0, events_1.cleanupProgressTracking)(currentAudio, channelNumber, info_1.audioChannels);
+                (0, volume_1.cleanupWebAudioForAudio)(currentAudio, channelNumber);
                 channel.queue.shift();
                 channel.isPaused = false; // Reset pause state
                 // Restore volume levels AFTER removing audio from queue

package/dist/errors.js

@@ -56,7 +56,6 @@ let globalErrorRecovery = {
     showUserFeedback: false
 };
 const retryAttempts = new WeakMap();
-const loadTimeouts = new WeakMap();
 /**
  * Subscribes to audio error events for a specific channel
  * @param channelNumber - The channel number to listen to (defaults to 0)
@@ -306,37 +305,9 @@ const setupAudioErrorHandling = (audio, channelNumber, originalUrl, onError) =>
     const channel = info_1.audioChannels[channelNumber];
     if (!channel)
         return;
-    // Set up loading timeout with test environment compatibility
-    let timeoutId;
-    if (typeof setTimeout !== 'undefined') {
-        timeoutId = setTimeout(() => {
-            if (audio.networkState === HTMLMediaElement.NETWORK_LOADING) {
-                const timeoutError = new Error(`Audio loading timeout after ${globalRetryConfig.timeoutMs}ms`);
-                (0, exports.handleAudioError)(audio, channelNumber, originalUrl, timeoutError);
-            }
-        }, globalRetryConfig.timeoutMs);
-        loadTimeouts.set(audio, timeoutId);
-    }
-    // Clear timeout when metadata loads successfully
-    const handleLoadSuccess = () => {
-        if (typeof setTimeout !== 'undefined') {
-            const timeoutId = loadTimeouts.get(audio);
-            if (timeoutId) {
-                clearTimeout(timeoutId);
-                loadTimeouts.delete(audio);
-            }
-        }
-    };
     // Handle various error events
     const handleError = (_event) => {
         var _a;
-        if (typeof setTimeout !== 'undefined') {
-            const timeoutId = loadTimeouts.get(audio);
-            if (timeoutId) {
-                clearTimeout(timeoutId);
-                loadTimeouts.delete(audio);
-            }
-        }
         const error = new Error(`Audio loading failed: ${((_a = audio.error) === null || _a === void 0 ? void 0 : _a.message) || 'Unknown error'}`);
         (0, exports.handleAudioError)(audio, channelNumber, originalUrl, error);
     };
@@ -352,8 +323,6 @@ const setupAudioErrorHandling = (audio, channelNumber, originalUrl, onError) =>
     audio.addEventListener('error', handleError);
     audio.addEventListener('abort', handleAbort);
     audio.addEventListener('stalled', handleStall);
-    audio.addEventListener('loadedmetadata', handleLoadSuccess);
-    audio.addEventListener('canplay', handleLoadSuccess);
     // Custom play error handling
     if (onError) {
         const originalPlay = audio.play.bind(audio);
@@ -451,19 +420,10 @@ exports.handleAudioError = handleAudioError;
 const createProtectedAudioElement = (url, channelNumber) => __awaiter(void 0, void 0, void 0, function* () {
     const audio = new Audio();
     return new Promise((resolve, reject) => {
-        const cleanup = () => {
-            const timeoutId = loadTimeouts.get(audio);
-            if (timeoutId) {
-                clearTimeout(timeoutId);
-                loadTimeouts.delete(audio);
-            }
-        };
         const handleSuccess = () => {
-            cleanup();
             resolve(audio);
         };
         const handleError = (error) => {
-            cleanup();
             reject(error);
         };
         // Set up error handling

package/dist/index.d.ts

@@ -8,8 +8,9 @@ export { clearQueueAfterCurrent, getQueueItemInfo, getQueueLength, removeQueuedI
 export { getErrorRecovery, getRetryConfig, offAudioError, onAudioError, retryFailedAudio, setErrorRecovery, setRetryConfig } from './errors';
 export { getAllChannelsPauseState, isChannelPaused, pauseAllChannels, pauseAllWithFade, pauseChannel, pauseWithFade, resumeAllChannels, resumeAllWithFade, resumeChannel, resumeWithFade, togglePauseAllChannels, togglePauseAllWithFade, togglePauseChannel, togglePauseWithFade } from './pause';
 export { cancelAllVolumeTransitions, cancelVolumeTransition, clearVolumeDucking, getAllChannelsVolume, getChannelVolume, getFadeConfig, setAllChannelsVolume, setChannelVolume, setVolumeDucking, transitionVolume } from './volume';
+export { cleanupWebAudioNodes, createWebAudioNodes, getAudioContext, getWebAudioConfig, getWebAudioSupport, getWebAudioVolume, isIOSDevice, isWebAudioSupported, resumeAudioContext, setWebAudioConfig, setWebAudioVolume, shouldUseWebAudio } from './web-audio';
 export { getAllChannelsInfo, getCurrentAudioInfo, getQueueSnapshot, offAudioComplete, offAudioPause, offAudioProgress, offAudioResume, offAudioStart, offQueueChange, onAudioComplete, onAudioPause, onAudioProgress, onAudioResume, onAudioStart, onQueueChange } from './info';
 export { audioChannels } from './info';
 export { cleanWebpackFilename, createQueueSnapshot, extractFileName, getAudioInfoFromElement, sanitizeForDisplay, validateAudioUrl } from './utils';
-export type { AudioCompleteCallback, AudioCompleteInfo, AudioErrorCallback, AudioErrorInfo, AudioInfo, AudioPauseCallback, AudioQueueOptions, AudioResumeCallback, AudioStartCallback, AudioStartInfo, ChannelFadeState, ErrorRecoveryOptions, ExtendedAudioQueueChannel, FadeConfig, ProgressCallback, QueueChangeCallback, QueueItem, QueueManipulationResult, QueueSnapshot, RetryConfig, VolumeConfig, QueueConfig } from './types';
+export type { AudioCompleteCallback, AudioCompleteInfo, AudioErrorCallback, AudioErrorInfo, AudioInfo, AudioPauseCallback, AudioQueueOptions, AudioResumeCallback, AudioStartCallback, AudioStartInfo, ChannelFadeState, ErrorRecoveryOptions, ExtendedAudioQueueChannel, FadeConfig, ProgressCallback, QueueChangeCallback, QueueConfig, QueueItem, QueueManipulationResult, QueueSnapshot, RetryConfig, VolumeConfig, WebAudioConfig, WebAudioNodeSet, WebAudioSupport } from './types';
 export { AudioErrorType, EasingType, FadeType, MAX_CHANNELS, TimerType, GLOBAL_PROGRESS_KEY } from './types';

package/dist/index.js

@@ -5,8 +5,8 @@
  * volume management with ducking, progress tracking, and comprehensive event system
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCurrentAudioInfo = exports.getAllChannelsInfo = exports.transitionVolume = exports.setVolumeDucking = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getFadeConfig = exports.getChannelVolume = exports.getAllChannelsVolume = exports.clearVolumeDucking = exports.cancelVolumeTransition = exports.cancelAllVolumeTransitions = exports.togglePauseWithFade = exports.togglePauseChannel = exports.togglePauseAllWithFade = exports.togglePauseAllChannels = exports.resumeWithFade = exports.resumeChannel = exports.resumeAllWithFade = exports.resumeAllChannels = exports.pauseWithFade = exports.pauseChannel = exports.pauseAllWithFade = exports.pauseAllChannels = exports.isChannelPaused = exports.getAllChannelsPauseState = exports.setRetryConfig = exports.setErrorRecovery = exports.retryFailedAudio = exports.onAudioError = exports.offAudioError = exports.getRetryConfig = exports.getErrorRecovery = exports.swapQueueItems = exports.reorderQueue = exports.removeQueuedItem = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.setChannelQueueLimit = exports.getQueueConfig = exports.setQueueConfig = exports.destroyAllChannels = exports.destroyChannel = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
-exports.GLOBAL_PROGRESS_KEY = exports.TimerType = exports.MAX_CHANNELS = exports.FadeType = exports.EasingType = exports.AudioErrorType = exports.validateAudioUrl = exports.sanitizeForDisplay = exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = exports.audioChannels = exports.onQueueChange = exports.onAudioStart = exports.onAudioResume = exports.onAudioProgress = exports.onAudioPause = exports.onAudioComplete = exports.offQueueChange = exports.offAudioStart = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.offAudioComplete = exports.getQueueSnapshot = void 0;
+exports.createWebAudioNodes = exports.cleanupWebAudioNodes = exports.transitionVolume = exports.setVolumeDucking = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getFadeConfig = exports.getChannelVolume = exports.getAllChannelsVolume = exports.clearVolumeDucking = exports.cancelVolumeTransition = exports.cancelAllVolumeTransitions = exports.togglePauseWithFade = exports.togglePauseChannel = exports.togglePauseAllWithFade = exports.togglePauseAllChannels = exports.resumeWithFade = exports.resumeChannel = exports.resumeAllWithFade = exports.resumeAllChannels = exports.pauseWithFade = exports.pauseChannel = exports.pauseAllWithFade = exports.pauseAllChannels = exports.isChannelPaused = exports.getAllChannelsPauseState = exports.setRetryConfig = exports.setErrorRecovery = exports.retryFailedAudio = exports.onAudioError = exports.offAudioError = exports.getRetryConfig = exports.getErrorRecovery = exports.swapQueueItems = exports.reorderQueue = exports.removeQueuedItem = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.setChannelQueueLimit = exports.getQueueConfig = exports.setQueueConfig = exports.destroyAllChannels = exports.destroyChannel = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
+exports.GLOBAL_PROGRESS_KEY = exports.TimerType = exports.MAX_CHANNELS = exports.FadeType = exports.EasingType = exports.AudioErrorType = exports.validateAudioUrl = exports.sanitizeForDisplay = exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = exports.audioChannels = exports.onQueueChange = exports.onAudioStart = exports.onAudioResume = exports.onAudioProgress = exports.onAudioPause = exports.onAudioComplete = exports.offQueueChange = exports.offAudioStart = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.offAudioComplete = exports.getQueueSnapshot = exports.getCurrentAudioInfo = exports.getAllChannelsInfo = exports.shouldUseWebAudio = exports.setWebAudioVolume = exports.setWebAudioConfig = exports.resumeAudioContext = exports.isWebAudioSupported = exports.isIOSDevice = exports.getWebAudioVolume = exports.getWebAudioSupport = exports.getWebAudioConfig = exports.getAudioContext = void 0;
 // Core queue management functions
 var core_1 = require("./core");
 Object.defineProperty(exports, "queueAudio", { enumerable: true, get: function () { return core_1.queueAudio; } });
@@ -65,6 +65,20 @@ Object.defineProperty(exports, "setAllChannelsVolume", { enumerable: true, get:
 Object.defineProperty(exports, "setChannelVolume", { enumerable: true, get: function () { return volume_1.setChannelVolume; } });
 Object.defineProperty(exports, "setVolumeDucking", { enumerable: true, get: function () { return volume_1.setVolumeDucking; } });
 Object.defineProperty(exports, "transitionVolume", { enumerable: true, get: function () { return volume_1.transitionVolume; } });
+// Web Audio API support functions
+var web_audio_1 = require("./web-audio");
+Object.defineProperty(exports, "cleanupWebAudioNodes", { enumerable: true, get: function () { return web_audio_1.cleanupWebAudioNodes; } });
+Object.defineProperty(exports, "createWebAudioNodes", { enumerable: true, get: function () { return web_audio_1.createWebAudioNodes; } });
+Object.defineProperty(exports, "getAudioContext", { enumerable: true, get: function () { return web_audio_1.getAudioContext; } });
+Object.defineProperty(exports, "getWebAudioConfig", { enumerable: true, get: function () { return web_audio_1.getWebAudioConfig; } });
+Object.defineProperty(exports, "getWebAudioSupport", { enumerable: true, get: function () { return web_audio_1.getWebAudioSupport; } });
+Object.defineProperty(exports, "getWebAudioVolume", { enumerable: true, get: function () { return web_audio_1.getWebAudioVolume; } });
+Object.defineProperty(exports, "isIOSDevice", { enumerable: true, get: function () { return web_audio_1.isIOSDevice; } });
+Object.defineProperty(exports, "isWebAudioSupported", { enumerable: true, get: function () { return web_audio_1.isWebAudioSupported; } });
+Object.defineProperty(exports, "resumeAudioContext", { enumerable: true, get: function () { return web_audio_1.resumeAudioContext; } });
+Object.defineProperty(exports, "setWebAudioConfig", { enumerable: true, get: function () { return web_audio_1.setWebAudioConfig; } });
+Object.defineProperty(exports, "setWebAudioVolume", { enumerable: true, get: function () { return web_audio_1.setWebAudioVolume; } });
+Object.defineProperty(exports, "shouldUseWebAudio", { enumerable: true, get: function () { return web_audio_1.shouldUseWebAudio; } });
 // Audio information and progress tracking functions
 var info_1 = require("./info");
 Object.defineProperty(exports, "getAllChannelsInfo", { enumerable: true, get: function () { return info_1.getAllChannelsInfo; } });

package/dist/types.d.ts

@@ -260,6 +260,39 @@ export interface ErrorRecoveryOptions {
  * Callback function type for audio error events
  */
 export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
+/**
+ * Web Audio API configuration options
+ */
+export interface WebAudioConfig {
+    /** Whether to automatically use Web Audio API on iOS devices */
+    autoDetectIOS: boolean;
+    /** Whether Web Audio API support is enabled */
+    enabled: boolean;
+    /** Whether to force Web Audio API usage on all devices */
+    forceWebAudio: boolean;
+}
+/**
+ * Web Audio API support information
+ */
+export interface WebAudioSupport {
+    /** Whether Web Audio API is available in the current environment */
+    available: boolean;
+    /** Whether the current device is iOS */
+    isIOS: boolean;
+    /** Whether Web Audio API is currently being used */
+    usingWebAudio: boolean;
+    /** Reason for current Web Audio API usage state */
+    reason: string;
+}
+/**
+ * Web Audio API node set for audio element control
+ */
+export interface WebAudioNodeSet {
+    /** Gain node for volume control */
+    gainNode: GainNode;
+    /** Media element source node */
+    sourceNode: MediaElementAudioSourceNode;
+}
 /**
  * Extended audio channel with comprehensive queue management, callback support, and state tracking
  */
@@ -292,6 +325,10 @@ export interface ExtendedAudioQueueChannel {
     retryConfig?: RetryConfig;
     /** Current volume level for the channel (0-1) */
     volume: number;
+    /** Web Audio API context for this channel */
+    webAudioContext?: AudioContext;
+    /** Map of Web Audio API nodes for each audio element */
+    webAudioNodes?: Map<HTMLAudioElement, WebAudioNodeSet>;
 }
 /**
  * Easing function types for smooth volume transitions and animations

package/dist/volume.d.ts

@@ -28,6 +28,7 @@ export declare const getFadeConfig: (fadeType: FadeType) => FadeConfig;
 export declare const transitionVolume: (channelNumber: number, targetVolume: number, duration?: number, easing?: EasingType) => Promise<void>;
 /**
  * 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
@@ -120,3 +121,17 @@ export declare const cancelVolumeTransition: (channelNumber: number) => void;
  * @internal
  */
 export declare const cancelAllVolumeTransitions: () => void;
+/**
+ * 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 declare const initializeWebAudioForAudio: (audio: HTMLAudioElement, channelNumber: number) => Promise<void>;
+/**
+ * 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 declare const cleanupWebAudioForAudio: (audio: HTMLAudioElement, channelNumber: number) => void;

package/dist/volume.js

@@ -12,9 +12,10 @@ 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.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
@@ -119,7 +120,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 +129,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 +140,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 +194,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);
         }
     }
 });
@@ -333,13 +339,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 +382,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,14 +391,31 @@ 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) {
+    // 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, targetVolume, duration);
+                // Also update the audio element's volume property for consistency
+                audio.volume = targetVolume;
+                return;
+            }
+        }
+    }
+    // Fallback to standard HTMLAudioElement volume control with manual transition
     const startVolume = audio.volume;
     const volumeDelta = targetVolume - startVolume;
     // If no change needed, resolve immediately
@@ -401,7 +424,7 @@ const transitionAudioVolume = (audio_1, targetVolume_1, ...args_1) => __awaiter(
     }
     // Handle zero or negative duration - instant change
     if (duration <= 0) {
-        audio.volume = Math.max(0, Math.min(1, targetVolume));
+        audio.volume = targetVolume;
         return Promise.resolve();
     }
     const startTime = performance.now();
@@ -424,7 +447,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 +491,94 @@ 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 - Volume level (0-1)
+ * @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];
+    // 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, volume, transitionDuration);
+            return;
+        }
+    }
+    // Fallback to standard HTMLAudioElement volume control
+    audio.volume = volume;
+});
+/**
+ * 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;