audio-channel-queue 1.8.0 → 1.10.0

package/dist/utils.js

@@ -3,7 +3,92 @@
  * @fileoverview Utility functions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cleanWebpackFilename = exports.createQueueSnapshot = exports.getAudioInfoFromElement = exports.extractFileName = void 0;
+exports.cleanWebpackFilename = exports.createQueueSnapshot = exports.getAudioInfoFromElement = exports.extractFileName = exports.sanitizeForDisplay = exports.validateAudioUrl = void 0;
+/**
+ * Validates an audio URL for security and correctness
+ * @param url - The URL to validate
+ * @returns The validated URL
+ * @throws Error if the URL is invalid or potentially malicious
+ * @example
+ * ```typescript
+ * validateAudioUrl('https://example.com/audio.mp3'); // Valid
+ * validateAudioUrl('./sounds/local.wav'); // Valid relative path
+ * validateAudioUrl('javascript:alert("XSS")'); // Throws error
+ * validateAudioUrl('data:text/html,<script>alert("XSS")</script>'); // Throws error
+ * ```
+ */
+const validateAudioUrl = (url) => {
+    if (!url || typeof url !== 'string') {
+        throw new Error('Audio URL must be a non-empty string');
+    }
+    // Trim whitespace
+    const trimmedUrl = url.trim();
+    // Check for dangerous protocols
+    const dangerousProtocols = [
+        'javascript:',
+        'data:',
+        'vbscript:',
+        'file:',
+        'about:',
+        'chrome:',
+        'chrome-extension:'
+    ];
+    const lowerUrl = trimmedUrl.toLowerCase();
+    for (const protocol of dangerousProtocols) {
+        if (lowerUrl.startsWith(protocol)) {
+            throw new Error(`Invalid audio URL: dangerous protocol "${protocol}" is not allowed`);
+        }
+    }
+    // Check for path traversal attempts
+    if (trimmedUrl.includes('../') || trimmedUrl.includes('..\\')) {
+        throw new Error('Invalid audio URL: path traversal attempts are not allowed');
+    }
+    // For relative URLs, ensure they don't start with dangerous characters
+    if (!trimmedUrl.startsWith('http://') && !trimmedUrl.startsWith('https://')) {
+        // Check for protocol-less URLs that might be interpreted as protocols
+        if (trimmedUrl.includes(':') && !trimmedUrl.startsWith('//')) {
+            const colonIndex = trimmedUrl.indexOf(':');
+            const beforeColon = trimmedUrl.substring(0, colonIndex);
+            // Allow only if it looks like a Windows drive letter (e.g., C:)
+            if (!/^[a-zA-Z]$/.test(beforeColon)) {
+                throw new Error('Invalid audio URL: suspicious protocol-like pattern detected');
+            }
+        }
+    }
+    // Validate common audio file extensions (warning, not error)
+    const hasAudioExtension = /\.(mp3|wav|ogg|m4a|webm|aac|flac|opus|weba|mp4)$/i.test(trimmedUrl);
+    if (!hasAudioExtension && !trimmedUrl.includes('?')) {
+        // Log warning but don't throw - some valid URLs might not have extensions
+        // eslint-disable-next-line no-console
+        console.warn(`Audio URL "${trimmedUrl}" does not have a recognized audio file extension`);
+    }
+    return trimmedUrl;
+};
+exports.validateAudioUrl = validateAudioUrl;
+/**
+ * Sanitizes a string for safe display in HTML contexts
+ * @param text - The text to sanitize
+ * @returns The sanitized text safe for display
+ * @example
+ * ```typescript
+ * sanitizeForDisplay('<script>alert("XSS")</script>'); // Returns: '&lt;script&gt;alert("XSS")&lt;/script&gt;'
+ * sanitizeForDisplay('normal-file.mp3'); // Returns: 'normal-file.mp3'
+ * ```
+ */
+const sanitizeForDisplay = (text) => {
+    if (!text || typeof text !== 'string') {
+        return '';
+    }
+    // Replace HTML special characters
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#x27;')
+        .replace(/\//g, '&#x2F;');
+};
+exports.sanitizeForDisplay = sanitizeForDisplay;
 /**
  * Extracts the filename from a URL string
  * @param url - The URL to extract the filename from
@@ -15,18 +100,21 @@ exports.cleanWebpackFilename = exports.createQueueSnapshot = exports.getAudioInf
  * ```
  */
 const extractFileName = (url) => {
+    if (!url || typeof url !== 'string') {
+        return (0, exports.sanitizeForDisplay)('unknown');
+    }
+    // Always use simple string manipulation for consistency
+    const segments = url.split('/');
+    const lastSegment = segments[segments.length - 1] || '';
+    // Remove query parameters and hash
+    const fileName = lastSegment.split('?')[0].split('#')[0];
+    // Decode URI components and sanitize
     try {
-        const urlObj = new URL(url);
-        const pathname = urlObj.pathname;
-        const segments = pathname.split('/');
-        const fileName = segments[segments.length - 1];
-        return fileName || 'unknown';
+        return (0, exports.sanitizeForDisplay)(decodeURIComponent(fileName || 'unknown'));
     }
     catch (_a) {
-        // If URL parsing fails, try simple string manipulation
-        const segments = url.split('/');
-        const fileName = segments[segments.length - 1];
-        return fileName || 'unknown';
+        // If decoding fails, return the sanitized raw filename
+        return (0, exports.sanitizeForDisplay)(fileName || 'unknown');
     }
 };
 exports.extractFileName = extractFileName;
@@ -56,7 +144,7 @@ const getAudioInfoFromElement = (audio, channelNumber, audioChannels) => {
     const isPlaying = !audio.paused && !audio.ended && audio.readyState > 2;
     // Calculate remainingInQueue if channel context is provided
     let remainingInQueue = 0;
-    if (channelNumber !== undefined && audioChannels && audioChannels[channelNumber]) {
+    if (channelNumber !== undefined && (audioChannels === null || audioChannels === void 0 ? void 0 : audioChannels[channelNumber])) {
         const channel = audioChannels[channelNumber];
         remainingInQueue = Math.max(0, channel.queue.length - 1); // Exclude current playing audio
     }
@@ -86,6 +174,7 @@ exports.getAudioInfoFromElement = getAudioInfoFromElement;
  * ```
  */
 const createQueueSnapshot = (channelNumber, audioChannels) => {
+    var _a, _b;
     const channel = audioChannels[channelNumber];
     if (!channel)
         return null;
@@ -100,10 +189,10 @@ const createQueueSnapshot = (channelNumber, audioChannels) => {
     return {
         channelNumber,
         currentIndex: 0, // Current playing is always index 0 in our queue structure
-        isPaused: channel.isPaused || false,
+        isPaused: (_a = channel.isPaused) !== null && _a !== void 0 ? _a : false,
         items,
         totalItems: channel.queue.length,
-        volume: channel.volume || 1.0
+        volume: (_b = channel.volume) !== null && _b !== void 0 ? _b : 1.0
     };
 };
 exports.createQueueSnapshot = createQueueSnapshot;

package/dist/volume.d.ts

@@ -32,6 +32,7 @@ export declare const transitionVolume: (channelNumber: number, targetVolume: num
  * @param volume - Volume level (0-1)
  * @param transitionDuration - Optional transition duration in milliseconds
  * @param easing - Optional easing function
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * setChannelVolume(0, 0.5); // Set channel 0 to 50%
@@ -76,6 +77,7 @@ export declare const setAllChannelsVolume: (volume: number) => Promise<void>;
  * Configures volume ducking for channels. When the priority channel plays audio,
  * all other channels will be automatically reduced to the ducking volume level
  * @param config - Volume ducking configuration
+ * @throws Error if the priority channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * // When channel 1 plays, reduce all other channels to 20% volume
@@ -116,8 +118,19 @@ export declare const applyVolumeDucking: (activeChannelNumber: number) => Promis
  */
 export declare const fadeVolume: (channelNumber: number, targetVolume: number, duration?: number, easing?: EasingType) => Promise<void>;
 /**
- * Restores normal volume levels when priority channel stops with smooth transitions
+ * Restores normal volume levels when priority channel queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing
  * @internal
  */
 export declare const restoreVolumeLevels: (stoppedChannelNumber: number) => Promise<void>;
+/**
+ * Cancels any active volume transition for a specific channel
+ * @param channelNumber - The channel number to cancel transitions for
+ * @internal
+ */
+export declare const cancelVolumeTransition: (channelNumber: number) => void;
+/**
+ * Cancels all active volume transitions across all channels
+ * @internal
+ */
+export declare const cancelAllVolumeTransitions: () => void;

package/dist/volume.js

@@ -12,18 +12,37 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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;
 const types_1 = require("./types");
 const info_1 = require("./info");
 // 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 ducking configuration
+ * Stores the volume ducking settings that apply to all channels
+ */
+let globalVolumeConfig = null;
 /**
  * Predefined fade configurations for different transition types
  */
-const FADE_CONFIGS = {
-    [types_1.FadeType.Dramatic]: { duration: 800, pauseCurve: types_1.EasingType.EaseIn, resumeCurve: types_1.EasingType.EaseOut },
-    [types_1.FadeType.Gentle]: { duration: 800, pauseCurve: types_1.EasingType.EaseOut, resumeCurve: types_1.EasingType.EaseIn },
-    [types_1.FadeType.Linear]: { duration: 800, pauseCurve: types_1.EasingType.Linear, resumeCurve: types_1.EasingType.Linear }
+const fadeConfigs = {
+    [types_1.FadeType.Dramatic]: {
+        duration: 800,
+        pauseCurve: types_1.EasingType.EaseIn,
+        resumeCurve: types_1.EasingType.EaseOut
+    },
+    [types_1.FadeType.Gentle]: {
+        duration: 800,
+        pauseCurve: types_1.EasingType.EaseOut,
+        resumeCurve: types_1.EasingType.EaseIn
+    },
+    [types_1.FadeType.Linear]: {
+        duration: 800,
+        pauseCurve: types_1.EasingType.Linear,
+        resumeCurve: types_1.EasingType.Linear
+    }
 };
 /**
  * Gets the fade configuration for a specific fade type
@@ -36,7 +55,7 @@ const FADE_CONFIGS = {
  * ```
  */
 const getFadeConfig = (fadeType) => {
-    return Object.assign({}, FADE_CONFIGS[fadeType]);
+    return Object.assign({}, fadeConfigs[fadeType]);
 };
 exports.getFadeConfig = getFadeConfig;
 /**
@@ -46,7 +65,7 @@ const easingFunctions = {
     [types_1.EasingType.Linear]: (t) => t,
     [types_1.EasingType.EaseIn]: (t) => t * t,
     [types_1.EasingType.EaseOut]: (t) => t * (2 - t),
-    [types_1.EasingType.EaseInOut]: (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
+    [types_1.EasingType.EaseInOut]: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t)
 };
 /**
  * Smoothly transitions volume for a specific channel over time
@@ -69,16 +88,28 @@ const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __await
     const volumeDelta = targetVolume - startVolume;
     // Cancel any existing transition for this channel
     if (activeTransitions.has(channelNumber)) {
-        clearTimeout(activeTransitions.get(channelNumber));
+        const transitionId = activeTransitions.get(channelNumber);
+        const timerType = timerTypes.get(channelNumber);
+        if (transitionId) {
+            // Cancel based on the timer type that was actually used
+            if (timerType === types_1.TimerType.RequestAnimationFrame &&
+                typeof cancelAnimationFrame !== 'undefined') {
+                cancelAnimationFrame(transitionId);
+            }
+            else if (timerType === types_1.TimerType.Timeout) {
+                clearTimeout(transitionId);
+            }
+        }
         activeTransitions.delete(channelNumber);
+        timerTypes.delete(channelNumber);
     }
     // If no change needed, resolve immediately
     if (Math.abs(volumeDelta) < 0.001) {
         channel.volume = targetVolume;
         return Promise.resolve();
     }
-    // Handle zero duration - instant change
-    if (duration === 0) {
+    // Handle zero or negative duration - instant change
+    if (duration <= 0) {
         channel.volume = targetVolume;
         if (channel.queue.length > 0) {
             channel.queue[0].volume = targetVolume;
@@ -92,7 +123,7 @@ const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __await
             const elapsed = performance.now() - startTime;
             const progress = Math.min(elapsed / duration, 1);
             const easedProgress = easingFn(progress);
-            const currentVolume = startVolume + (volumeDelta * easedProgress);
+            const currentVolume = startVolume + volumeDelta * easedProgress;
             const clampedVolume = Math.max(0, Math.min(1, currentVolume));
             // Apply volume to both channel config and current audio
             channel.volume = clampedVolume;
@@ -102,6 +133,7 @@ const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __await
             if (progress >= 1) {
                 // Transition complete
                 activeTransitions.delete(channelNumber);
+                timerTypes.delete(channelNumber);
                 resolve();
             }
             else {
@@ -109,11 +141,13 @@ const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __await
                 if (typeof requestAnimationFrame !== 'undefined') {
                     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);
                     activeTransitions.set(channelNumber, timeoutId);
+                    timerTypes.set(channelNumber, types_1.TimerType.Timeout);
                 }
             }
         };
@@ -127,6 +161,7 @@ exports.transitionVolume = transitionVolume;
  * @param volume - Volume level (0-1)
  * @param transitionDuration - Optional transition duration in milliseconds
  * @param easing - Optional easing function
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * setChannelVolume(0, 0.5); // Set channel 0 to 50%
@@ -135,6 +170,13 @@ exports.transitionVolume = transitionVolume;
  */
 const setChannelVolume = (channelNumber, volume, transitionDuration, easing) => __awaiter(void 0, void 0, void 0, function* () {
     const clampedVolume = Math.max(0, Math.min(1, volume));
+    // Check channel number limits
+    if (channelNumber < 0) {
+        throw new Error('Channel number must be non-negative');
+    }
+    if (channelNumber >= types_1.MAX_CHANNELS) {
+        throw new Error(`Channel number ${channelNumber} exceeds maximum allowed channels (${types_1.MAX_CHANNELS})`);
+    }
     if (!info_1.audioChannels[channelNumber]) {
         info_1.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -177,8 +219,9 @@ exports.setChannelVolume = setChannelVolume;
  * ```
  */
 const getChannelVolume = (channelNumber = 0) => {
+    var _a;
     const channel = info_1.audioChannels[channelNumber];
-    return (channel === null || channel === void 0 ? void 0 : channel.volume) || 1.0;
+    return (_a = channel === null || channel === void 0 ? void 0 : channel.volume) !== null && _a !== void 0 ? _a : 1.0;
 };
 exports.getChannelVolume = getChannelVolume;
 /**
@@ -193,7 +236,7 @@ exports.getChannelVolume = getChannelVolume;
  * ```
  */
 const getAllChannelsVolume = () => {
-    return info_1.audioChannels.map((channel) => (channel === null || channel === void 0 ? void 0 : channel.volume) || 1.0);
+    return info_1.audioChannels.map((channel) => { var _a; return (_a = channel === null || channel === void 0 ? void 0 : channel.volume) !== null && _a !== void 0 ? _a : 1.0; });
 };
 exports.getAllChannelsVolume = getAllChannelsVolume;
 /**
@@ -216,6 +259,7 @@ exports.setAllChannelsVolume = setAllChannelsVolume;
  * Configures volume ducking for channels. When the priority channel plays audio,
  * all other channels will be automatically reduced to the ducking volume level
  * @param config - Volume ducking configuration
+ * @throws Error if the priority channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * // When channel 1 plays, reduce all other channels to 20% volume
@@ -227,8 +271,18 @@ exports.setAllChannelsVolume = setAllChannelsVolume;
  * ```
  */
 const setVolumeDucking = (config) => {
-    // First, ensure we have enough channels for the priority channel
-    while (info_1.audioChannels.length <= config.priorityChannel) {
+    const { priorityChannel } = config;
+    // Check priority channel limits
+    if (priorityChannel < 0) {
+        throw new Error('Priority channel number must be non-negative');
+    }
+    if (priorityChannel >= types_1.MAX_CHANNELS) {
+        throw new Error(`Priority channel ${priorityChannel} exceeds maximum allowed channels (${types_1.MAX_CHANNELS})`);
+    }
+    // Store the configuration globally
+    globalVolumeConfig = config;
+    // Ensure we have enough channels for the priority channel
+    while (info_1.audioChannels.length <= priorityChannel) {
         info_1.audioChannels.push({
             audioCompleteCallbacks: new Set(),
             audioErrorCallbacks: new Set(),
@@ -242,24 +296,6 @@ const setVolumeDucking = (config) => {
             volume: 1.0
         });
     }
-    // Apply the config to all existing channels
-    info_1.audioChannels.forEach((channel, index) => {
-        if (!info_1.audioChannels[index]) {
-            info_1.audioChannels[index] = {
-                audioCompleteCallbacks: new Set(),
-                audioErrorCallbacks: new Set(),
-                audioPauseCallbacks: new Set(),
-                audioResumeCallbacks: new Set(),
-                audioStartCallbacks: new Set(),
-                isPaused: false,
-                progressCallbacks: new Map(),
-                queue: [],
-                queueChangeCallbacks: new Set(),
-                volume: 1.0
-            };
-        }
-        info_1.audioChannels[index].volumeConfig = config;
-    });
 };
 exports.setVolumeDucking = setVolumeDucking;
 /**
@@ -270,11 +306,7 @@ exports.setVolumeDucking = setVolumeDucking;
  * ```
  */
 const clearVolumeDucking = () => {
-    info_1.audioChannels.forEach((channel) => {
-        if (channel) {
-            delete channel.volumeConfig;
-        }
-    });
+    globalVolumeConfig = null;
 };
 exports.clearVolumeDucking = clearVolumeDucking;
 /**
@@ -283,21 +315,31 @@ exports.clearVolumeDucking = clearVolumeDucking;
  * @internal
  */
 const applyVolumeDucking = (activeChannelNumber) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    // Check if ducking is configured and this channel is the priority channel
+    if (!globalVolumeConfig || globalVolumeConfig.priorityChannel !== activeChannelNumber) {
+        return; // No ducking configured for this channel
+    }
+    const config = globalVolumeConfig;
     const transitionPromises = [];
+    const duration = (_a = config.duckTransitionDuration) !== null && _a !== void 0 ? _a : 250;
+    const easing = (_b = config.transitionEasing) !== null && _b !== void 0 ? _b : types_1.EasingType.EaseOut;
+    // Duck all channels except the priority channel
     info_1.audioChannels.forEach((channel, channelNumber) => {
-        if (channel === null || channel === void 0 ? void 0 : channel.volumeConfig) {
-            const config = channel.volumeConfig;
-            if (activeChannelNumber === config.priorityChannel) {
-                const duration = config.duckTransitionDuration || 250;
-                const easing = config.transitionEasing || types_1.EasingType.EaseOut;
-                // Priority channel is active, duck other channels
-                if (channelNumber === config.priorityChannel) {
-                    transitionPromises.push((0, exports.transitionVolume)(channelNumber, config.priorityVolume, duration, easing));
-                }
-                else {
-                    transitionPromises.push((0, exports.transitionVolume)(channelNumber, config.duckingVolume, duration, easing));
-                }
-            }
+        if (!channel || channel.queue.length === 0) {
+            return; // Skip channels without audio
+        }
+        if (channelNumber === activeChannelNumber) {
+            // 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));
+        }
+        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));
         }
     });
     // Wait for all transitions to complete
@@ -322,24 +364,123 @@ const fadeVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(voi
 });
 exports.fadeVolume = fadeVolume;
 /**
- * Restores normal volume levels when priority channel stops with smooth transitions
+ * Restores normal volume levels when priority channel queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing
  * @internal
  */
 const restoreVolumeLevels = (stoppedChannelNumber) => __awaiter(void 0, void 0, void 0, function* () {
+    // Check if ducking is configured and this channel is the priority channel
+    if (!globalVolumeConfig || globalVolumeConfig.priorityChannel !== stoppedChannelNumber) {
+        return; // No ducking configured for this channel
+    }
+    // Check if the priority channel queue is now empty
+    const priorityChannel = info_1.audioChannels[stoppedChannelNumber];
+    if (priorityChannel && priorityChannel.queue.length > 0) {
+        return; // Priority channel still has audio queued, don't restore yet
+    }
+    const config = globalVolumeConfig;
     const transitionPromises = [];
+    // Restore volume for all channels EXCEPT the priority channel
     info_1.audioChannels.forEach((channel, channelNumber) => {
-        if (channel === null || channel === void 0 ? void 0 : channel.volumeConfig) {
-            const config = channel.volumeConfig;
-            if (stoppedChannelNumber === config.priorityChannel) {
-                const duration = config.restoreTransitionDuration || 500;
-                const easing = config.transitionEasing || types_1.EasingType.EaseOut;
-                // Priority channel stopped, restore normal volumes
-                transitionPromises.push((0, exports.transitionVolume)(channelNumber, channel.volume || 1.0, duration, easing));
-            }
+        var _a, _b, _c;
+        // Skip the priority channel itself and channels without audio
+        if (channelNumber === stoppedChannelNumber || !channel || channel.queue.length === 0) {
+            return;
         }
+        // Restore this channel to its desired volume
+        const duration = (_a = config.restoreTransitionDuration) !== null && _a !== void 0 ? _a : 500;
+        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));
     });
     // Wait for all transitions to complete
     yield Promise.all(transitionPromises);
 });
 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
+ * @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
+ * @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 startVolume = audio.volume;
+    const volumeDelta = targetVolume - 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));
+        return Promise.resolve();
+    }
+    const startTime = performance.now();
+    const easingFn = easingFunctions[easing];
+    return new Promise((resolve) => {
+        const updateVolume = () => {
+            const elapsed = performance.now() - startTime;
+            const progress = Math.min(elapsed / duration, 1);
+            const easedProgress = easingFn(progress);
+            const currentVolume = startVolume + volumeDelta * easedProgress;
+            const clampedVolume = Math.max(0, Math.min(1, currentVolume));
+            // Only apply volume to audio element, not channel.volume
+            audio.volume = clampedVolume;
+            if (progress >= 1) {
+                resolve();
+            }
+            else {
+                // Use requestAnimationFrame in browser, setTimeout in tests
+                if (typeof requestAnimationFrame !== 'undefined') {
+                    requestAnimationFrame(updateVolume);
+                }
+                else {
+                    setTimeout(updateVolume, 1);
+                }
+            }
+        };
+        updateVolume();
+    });
+});
+/**
+ * Cancels any active volume transition for a specific channel
+ * @param channelNumber - The channel number to cancel transitions for
+ * @internal
+ */
+const cancelVolumeTransition = (channelNumber) => {
+    if (activeTransitions.has(channelNumber)) {
+        const transitionId = activeTransitions.get(channelNumber);
+        const timerType = timerTypes.get(channelNumber);
+        if (transitionId) {
+            // Cancel based on the timer type that was actually used
+            if (timerType === types_1.TimerType.RequestAnimationFrame &&
+                typeof cancelAnimationFrame !== 'undefined') {
+                cancelAnimationFrame(transitionId);
+            }
+            else if (timerType === types_1.TimerType.Timeout) {
+                clearTimeout(transitionId);
+            }
+        }
+        activeTransitions.delete(channelNumber);
+        timerTypes.delete(channelNumber);
+    }
+};
+exports.cancelVolumeTransition = cancelVolumeTransition;
+/**
+ * Cancels all active volume transitions across all channels
+ * @internal
+ */
+const cancelAllVolumeTransitions = () => {
+    // Get all active channel numbers to avoid modifying Map while iterating
+    const activeChannels = Array.from(activeTransitions.keys());
+    activeChannels.forEach((channelNumber) => {
+        (0, exports.cancelVolumeTransition)(channelNumber);
+    });
+};
+exports.cancelAllVolumeTransitions = cancelAllVolumeTransitions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-channel-queue",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Allows you to queue audio files to different playback channels.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,20 @@
     "prepare": "npm run build",
     "test": "jest",
     "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage"
+    "test:coverage": "jest --coverage",
+    "lint": "npx eslint src/**/*.ts __tests__/**/*.ts",
+    "lint:fix": "npx eslint src/**/*.ts __tests__/**/*.ts --fix",
+    "format": "npx prettier --write src/**/*.ts __tests__/**/*.ts",
+    "format:check": "npx prettier --check src/**/*.ts __tests__/**/*.ts",
+    "clean": "rimraf dist",
+    "prebuild": "npm run clean",
+    "prepack": "npm run validate && npm run build",
+    "validate": "npm run format:check && npm run lint && npm run test",
+    "publish:patch": "npm version patch && npm run publish:release",
+    "publish:minor": "npm version minor && npm run publish:release",
+    "publish:major": "npm version major && npm run publish:release",
+    "publish:release": "npm run validate && npm run build && npm publish",
+    "publish:dry": "npm run validate && npm run build && npm publish --dry-run"
   },
   "repository": {
     "type": "git",
@@ -38,7 +51,9 @@
     "@types/jest": "^29.5.13",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "rimraf": "^6.0.1",
     "ts-jest": "^29.2.5",
-    "typescript": "^5.6.2"
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.34.1"
   }
 }