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

package/dist/types.d.ts

@@ -24,15 +24,15 @@ export interface AudioQueueChannel {
  * Volume ducking configuration for channels
  */
 export interface VolumeConfig {
+    /** Duration in milliseconds for volume duck transition (defaults to 250ms) */
+    duckTransitionDuration?: number;
+    /** Volume level for all other channels when priority channel is active (0-1) */
+    duckingVolume: number;
     /** The channel number that should have priority */
     priorityChannel: number;
     /** Volume level for the priority channel (0-1) */
     priorityVolume: number;
-    /** Volume level for all other channels when priority channel is active (0-1) */
-    duckingVolume: number;
-    /** Duration in milliseconds for volume duck transition (defaults to 250ms) */
-    duckTransitionDuration?: number;
-    /** Duration in milliseconds for volume restore transition (defaults to 500ms) */
+    /** Duration in milliseconds for volume restore transition (defaults to 250ms) */
     restoreTransitionDuration?: number;
     /** Easing function for volume transitions (defaults to 'ease-out') */
     transitionEasing?: EasingType;
@@ -47,8 +47,6 @@ export interface AudioQueueOptions {
     loop?: boolean;
     /** Maximum number of items allowed in the queue (defaults to unlimited) */
     maxQueueSize?: number;
-    /** @deprecated Use addToFront instead. Legacy support for priority queuing */
-    priority?: boolean;
     /** Volume level for this specific audio (0-1) */
     volume?: number;
 }
@@ -192,67 +190,148 @@ export type AudioPauseCallback = (channelNumber: number, audioInfo: AudioInfo) =
  */
 export type AudioResumeCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
 /**
- * Information about an audio error that occurred
+ * Types of audio errors that can occur during playback
+ */
+export declare enum AudioErrorType {
+    Abort = "abort",
+    Decode = "decode",
+    Network = "network",
+    Permission = "permission",
+    Timeout = "timeout",
+    Unknown = "unknown",
+    Unsupported = "unsupported"
+}
+/**
+ * Information about an audio error that occurred during playback or loading
  */
 export interface AudioErrorInfo {
+    /** Channel number where the error occurred */
     channelNumber: number;
-    src: string;
-    fileName: string;
+    /** The actual error object that was thrown */
     error: Error;
-    errorType: 'network' | 'decode' | 'unsupported' | 'permission' | 'abort' | 'timeout' | 'unknown';
-    timestamp: number;
-    retryAttempt?: number;
+    /** Categorized type of error for handling different scenarios */
+    errorType: AudioErrorType;
+    /** Extracted filename from the source URL */
+    fileName: string;
+    /** Number of audio files remaining in the queue after this error */
     remainingInQueue: number;
+    /** Current retry attempt number (if retrying is enabled) */
+    retryAttempt?: number;
+    /** Audio file source URL that failed */
+    src: string;
+    /** Unix timestamp when the error occurred */
+    timestamp: number;
 }
 /**
  * Configuration for automatic retry behavior when audio fails to load or play
  */
 export interface RetryConfig {
-    enabled: boolean;
-    maxRetries: number;
+    /** Initial delay in milliseconds before first retry attempt */
     baseDelay: number;
+    /** Whether automatic retries are enabled for this channel */
+    enabled: boolean;
+    /** Whether to use exponential backoff (doubling delay each retry) */
     exponentialBackoff: boolean;
-    timeoutMs: number;
-    fallbackUrls?: string[];
+    /** Alternative URLs to try if the primary source fails */
+    fallbackUrls: string[];
+    /** Maximum number of retry attempts before giving up */
+    maxRetries: number;
+    /** Whether to skip to next track in queue if all retries fail */
     skipOnFailure: boolean;
+    /** Timeout in milliseconds for each individual retry attempt */
+    timeoutMs: number;
 }
 /**
- * Configuration options for error recovery mechanisms
+ * Configuration options for error recovery mechanisms across the audio system
  */
 export interface ErrorRecoveryOptions {
+    /** Whether to automatically retry failed audio loads/plays */
     autoRetry: boolean;
-    showUserFeedback: boolean;
+    /** Whether to automatically skip to next track when current fails */
+    fallbackToNextTrack: boolean;
+    /** Whether to send error data to analytics systems */
     logErrorsToAnalytics: boolean;
+    /** Whether to maintain queue integrity when errors occur */
     preserveQueueOnError: boolean;
-    fallbackToNextTrack: boolean;
+    /** Whether to display user-visible error feedback */
+    showUserFeedback: boolean;
 }
 /**
  * Callback function type for audio error events
  */
 export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
 /**
- * Extended audio channel with queue management and callback support
+ * 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
  */
 export interface ExtendedAudioQueueChannel {
+    /** Set of callbacks triggered when audio completes playback */
     audioCompleteCallbacks: Set<AudioCompleteCallback>;
+    /** Set of callbacks triggered when audio errors occur */
     audioErrorCallbacks: Set<AudioErrorCallback>;
+    /** Set of callbacks triggered when audio is paused */
     audioPauseCallbacks: Set<AudioPauseCallback>;
+    /** Set of callbacks triggered when audio is resumed */
     audioResumeCallbacks: Set<AudioResumeCallback>;
+    /** Set of callbacks triggered when audio starts playing */
     audioStartCallbacks: Set<AudioStartCallback>;
+    /** Current fade state if pause/resume with fade is active */
     fadeState?: ChannelFadeState;
+    /** Whether the channel is currently paused */
     isPaused: boolean;
     /** Active operation lock to prevent race conditions */
     isLocked?: boolean;
     /** Maximum allowed queue size for this channel */
     maxQueueSize?: number;
+    /** Map of progress callbacks keyed by audio element or global symbol */
     progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
+    /** Array of HTMLAudioElement objects in the queue */
     queue: HTMLAudioElement[];
+    /** Set of callbacks triggered when the queue changes */
     queueChangeCallbacks: Set<QueueChangeCallback>;
+    /** Retry configuration for failed audio loads/plays */
     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 volume transitions
+ * Easing function types for smooth volume transitions and animations
  */
 export declare enum EasingType {
     Linear = "linear",
@@ -261,7 +340,7 @@ export declare enum EasingType {
     EaseInOut = "ease-in-out"
 }
 /**
- * Fade type for pause/resume operations with integrated volume transitions
+ * Predefined fade types for pause/resume operations with different transition characteristics
  */
 export declare enum FadeType {
     Linear = "linear",
@@ -269,7 +348,7 @@ export declare enum FadeType {
     Dramatic = "dramatic"
 }
 /**
- * Timer types for volume transitions to ensure proper cleanup
+ * Timer implementation types used for volume transitions to ensure proper cleanup
  */
 export declare enum TimerType {
     RequestAnimationFrame = "raf",

package/dist/types.js

@@ -3,7 +3,7 @@
  * @fileoverview Type definitions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimerType = exports.FadeType = exports.EasingType = exports.GLOBAL_PROGRESS_KEY = exports.MAX_CHANNELS = void 0;
+exports.TimerType = exports.FadeType = exports.EasingType = exports.AudioErrorType = exports.GLOBAL_PROGRESS_KEY = exports.MAX_CHANNELS = void 0;
 /**
  * Maximum number of audio channels allowed to prevent memory exhaustion
  */
@@ -14,7 +14,20 @@ exports.MAX_CHANNELS = 64;
  */
 exports.GLOBAL_PROGRESS_KEY = Symbol('global-progress-callbacks');
 /**
- * Easing function types for volume transitions
+ * Types of audio errors that can occur during playback
+ */
+var AudioErrorType;
+(function (AudioErrorType) {
+    AudioErrorType["Abort"] = "abort";
+    AudioErrorType["Decode"] = "decode";
+    AudioErrorType["Network"] = "network";
+    AudioErrorType["Permission"] = "permission";
+    AudioErrorType["Timeout"] = "timeout";
+    AudioErrorType["Unknown"] = "unknown";
+    AudioErrorType["Unsupported"] = "unsupported";
+})(AudioErrorType || (exports.AudioErrorType = AudioErrorType = {}));
+/**
+ * Easing function types for smooth volume transitions and animations
  */
 var EasingType;
 (function (EasingType) {
@@ -24,7 +37,7 @@ var EasingType;
     EasingType["EaseInOut"] = "ease-in-out";
 })(EasingType || (exports.EasingType = EasingType = {}));
 /**
- * Fade type for pause/resume operations with integrated volume transitions
+ * Predefined fade types for pause/resume operations with different transition characteristics
  */
 var FadeType;
 (function (FadeType) {
@@ -33,7 +46,7 @@ var FadeType;
     FadeType["Dramatic"] = "dramatic";
 })(FadeType || (exports.FadeType = FadeType = {}));
 /**
- * Timer types for volume transitions to ensure proper cleanup
+ * Timer implementation types used for volume transitions to ensure proper cleanup
  */
 var TimerType;
 (function (TimerType) {

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
@@ -103,20 +104,6 @@ export declare const clearVolumeDucking: () => void;
  * @internal
  */
 export declare const applyVolumeDucking: (activeChannelNumber: number) => Promise<void>;
-/**
- * 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 declare const fadeVolume: (channelNumber: number, targetVolume: number, duration?: number, easing?: EasingType) => Promise<void>;
 /**
  * Restores normal volume levels when priority channel queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -134,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.fadeVolume = 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,36 +339,19 @@ 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
     yield Promise.all(transitionPromises);
 });
 exports.applyVolumeDucking = applyVolumeDucking;
-/**
- * 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
- * ```
- */
-const fadeVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(void 0, [channelNumber_1, targetVolume_1, ...args_1], void 0, function* (channelNumber, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut) {
-    return (0, exports.transitionVolume)(channelNumber, targetVolume, duration, easing);
-});
-exports.fadeVolume = fadeVolume;
 /**
  * Restores normal volume levels when priority channel queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -388,12 +377,12 @@ const restoreVolumeLevels = (stoppedChannelNumber) => __awaiter(void 0, void 0,
             return;
         }
         // Restore this channel to its desired volume
-        const duration = (_a = config.restoreTransitionDuration) !== null && _a !== void 0 ? _a : 500;
+        const duration = (_a = config.restoreTransitionDuration) !== null && _a !== void 0 ? _a : 250;
         const easing = (_b = config.transitionEasing) !== null && _b !== void 0 ? _b : types_1.EasingType.EaseOut;
         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);
@@ -402,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
@@ -418,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();
@@ -441,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);
                 }
             }
         };
@@ -484,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;