audio-channel-queue 1.9.0 → 1.10.0

package/dist/queue-manipulation.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * @fileoverview Queue manipulation functions for the audio-channel-queue package
+ * Provides advanced queue management including item removal, reordering, and clearing
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.swapQueueItems = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.reorderQueue = exports.removeQueuedItem = void 0;
+const info_1 = require("./info");
+const events_1 = require("./events");
+const events_2 = require("./events");
+const utils_1 = require("./utils");
+/**
+ * Removes a specific item from the queue by its slot number (0-based index)
+ * Cannot remove the currently playing item (index 0) - use stopCurrentAudioInChannel instead
+ * @param queuedSlotNumber - Zero-based index of the item to remove (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to remove currently playing item or invalid slot number
+ * @example
+ * ```typescript
+ * // Remove the second item in queue (index 1)
+ * const result = await removeQueuedItem(1, 0);
+ * if (result.success) {
+ *   console.log(`Removed item, queue now has ${result.updatedQueue.totalItems} items`);
+ * }
+ *
+ * // Remove the third item from channel 1
+ * await removeQueuedItem(2, 1);
+ * ```
+ */
+const removeQueuedItem = (queuedSlotNumber_1, ...args_1) => __awaiter(void 0, [queuedSlotNumber_1, ...args_1], void 0, function* (queuedSlotNumber, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (queuedSlotNumber < 0 || queuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid slot number ${queuedSlotNumber}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (queuedSlotNumber === 0) {
+        return {
+            error: 'Cannot remove currently playing item (index 0). ' +
+                'Use stopCurrentAudioInChannel() instead',
+            success: false
+        };
+    }
+    // Remove the audio element from the queue
+    const removedAudio = channel.queue.splice(queuedSlotNumber, 1)[0];
+    // Clean up any progress tracking for the removed audio
+    (0, events_2.cleanupProgressTracking)(removedAudio, channelNumber, info_1.audioChannels);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.removeQueuedItem = removeQueuedItem;
+/**
+ * Reorders a queue item by moving it from one position to another
+ * Cannot reorder the currently playing item (index 0)
+ * @param currentQueuedSlotNumber - Current zero-based index of the item to move (must be > 0)
+ * @param newQueuedSlotNumber - New zero-based index where the item should be placed (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to reorder currently playing item or invalid slot numbers
+ * @example
+ * ```typescript
+ * // Move item from position 2 to position 1 (make it play next)
+ * const result = await reorderQueue(2, 1, 0);
+ * if (result.success) {
+ *   console.log('Item moved successfully');
+ * }
+ *
+ * // Move item from position 1 to end of queue
+ * await reorderQueue(1, 4, 0); // Assuming queue has 5+ items
+ * ```
+ */
+const reorderQueue = (currentQueuedSlotNumber_1, newQueuedSlotNumber_1, ...args_1) => __awaiter(void 0, [currentQueuedSlotNumber_1, newQueuedSlotNumber_1, ...args_1], void 0, function* (currentQueuedSlotNumber, newQueuedSlotNumber, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber < 0 || currentQueuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid current slot number ${currentQueuedSlotNumber}. Queue has ` +
+                `${channel.queue.length} items (indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (newQueuedSlotNumber < 0 || newQueuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid new slot number ${newQueuedSlotNumber}. Queue has ` +
+                `${channel.queue.length} items (indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber === 0) {
+        return {
+            error: 'Cannot reorder currently playing item (index 0). ' + 'Stop current audio first if needed',
+            success: false
+        };
+    }
+    if (newQueuedSlotNumber === 0) {
+        return {
+            error: 'Cannot move item to currently playing position (index 0). ' +
+                'Use queueAudioPriority() to add items to front of queue',
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber === newQueuedSlotNumber) {
+        // No change needed, but return success
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Remove the item from its current position
+    const audioToMove = channel.queue.splice(currentQueuedSlotNumber, 1)[0];
+    // Insert it at the new position
+    channel.queue.splice(newQueuedSlotNumber, 0, audioToMove);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.reorderQueue = reorderQueue;
+/**
+ * Clears all queued audio items after the currently playing item
+ * The current audio will continue playing but nothing will follow it
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Let current song finish but clear everything after it
+ * const result = await clearQueueAfterCurrent(0);
+ * if (result.success) {
+ *   console.log(`Cleared queue, current audio will be the last to play`);
+ * }
+ * ```
+ */
+const clearQueueAfterCurrent = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        // For empty/non-existent channels, we can consider this a successful no-op
+        // since there's nothing to clear anyway
+        return {
+            success: true,
+            updatedQueue: {
+                channelNumber,
+                currentIndex: -1,
+                isPaused: false,
+                items: [],
+                totalItems: 0,
+                volume: 1.0
+            }
+        };
+    }
+    if (channel.queue.length <= 1) {
+        // Nothing to clear - either empty queue or only current audio
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Clean up progress tracking for all items except the current one
+    for (let i = 1; i < channel.queue.length; i++) {
+        (0, events_2.cleanupProgressTracking)(channel.queue[i], channelNumber, info_1.audioChannels);
+    }
+    // Keep only the currently playing audio (index 0)
+    channel.queue = channel.queue.slice(0, 1);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.clearQueueAfterCurrent = clearQueueAfterCurrent;
+/**
+ * Gets information about a specific queue item by its slot number
+ * @param queueSlotNumber - Zero-based index of the queue item
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns QueueItem information or null if slot doesn't exist
+ * @example
+ * ```typescript
+ * const itemInfo = getQueueItemInfo(1, 0);
+ * if (itemInfo) {
+ *   console.log(`Next to play: ${itemInfo.fileName}`);
+ *   console.log(`Duration: ${itemInfo.duration}ms`);
+ * }
+ * ```
+ */
+const getQueueItemInfo = (queueSlotNumber, channelNumber = 0) => {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel || queueSlotNumber < 0 || queueSlotNumber >= channel.queue.length) {
+        return null;
+    }
+    const audio = channel.queue[queueSlotNumber];
+    const audioInfo = (0, utils_1.getAudioInfoFromElement)(audio, channelNumber, info_1.audioChannels);
+    if (!audioInfo) {
+        return null;
+    }
+    const { duration, fileName, isLooping, isPlaying, src, volume } = audioInfo;
+    return {
+        duration,
+        fileName,
+        isCurrentlyPlaying: queueSlotNumber === 0 && isPlaying,
+        isLooping,
+        src,
+        volume
+    };
+};
+exports.getQueueItemInfo = getQueueItemInfo;
+/**
+ * Gets the current queue length for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Number of items in the queue, or 0 if channel doesn't exist
+ * @example
+ * ```typescript
+ * const queueSize = getQueueLength(0);
+ * console.log(`Channel 0 has ${queueSize} items in queue`);
+ * ```
+ */
+const getQueueLength = (channelNumber = 0) => {
+    const channel = info_1.audioChannels[channelNumber];
+    return channel ? channel.queue.length : 0;
+};
+exports.getQueueLength = getQueueLength;
+/**
+ * Swaps the positions of two queue items
+ * Cannot swap with the currently playing item (index 0)
+ * @param slotA - Zero-based index of first item to swap (must be > 0)
+ * @param slotB - Zero-based index of second item to swap (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Swap the second and third items in queue
+ * const result = await swapQueueItems(1, 2, 0);
+ * if (result.success) {
+ *   console.log('Items swapped successfully');
+ * }
+ * ```
+ */
+const swapQueueItems = (slotA_1, slotB_1, ...args_1) => __awaiter(void 0, [slotA_1, slotB_1, ...args_1], void 0, function* (slotA, slotB, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (slotA < 0 || slotA >= channel.queue.length) {
+        return {
+            error: `Invalid slot A ${slotA}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (slotB < 0 || slotB >= channel.queue.length) {
+        return {
+            error: `Invalid slot B ${slotB}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (slotA === 0 || slotB === 0) {
+        return {
+            error: 'Cannot swap with currently playing item (index 0)',
+            success: false
+        };
+    }
+    if (slotA === slotB) {
+        // No change needed, but return success
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Swap the audio elements
+    const temp = channel.queue[slotA];
+    channel.queue[slotA] = channel.queue[slotB];
+    channel.queue[slotB] = temp;
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.swapQueueItems = swapQueueItems;

package/dist/types.d.ts

@@ -1,6 +1,10 @@
 /**
  * @fileoverview Type definitions for the audio-channel-queue package
  */
+/**
+ * Maximum number of audio channels allowed to prevent memory exhaustion
+ */
+export declare const MAX_CHANNELS: number;
 /**
  * Symbol used as a key for global (channel-wide) progress callbacks
  * This avoids the need for `null as any` type assertions
@@ -34,18 +38,31 @@ export interface VolumeConfig {
     transitionEasing?: EasingType;
 }
 /**
- * Audio file configuration for queueing
+ * Configuration options for queuing audio
  */
 export interface AudioQueueOptions {
-    /** Whether to add the audio to the front of the queue (defaults to false) */
+    /** Whether to add this audio to the front of the queue (after currently playing) */
     addToFront?: boolean;
     /** Whether the audio should loop when it finishes */
     loop?: boolean;
-    /** Whether to add the audio with priority (same as addToFront) */
+    /** 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 file (0-1, defaults to channel volume) */
+    /** Volume level for this specific audio (0-1) */
     volume?: number;
 }
+/**
+ * Global queue configuration options
+ */
+export interface QueueConfig {
+    /** Default maximum queue size across all channels (defaults to unlimited) */
+    defaultMaxQueueSize?: number;
+    /** Whether to drop oldest items when queue is full (defaults to false - reject new items) */
+    dropOldestWhenFull?: boolean;
+    /** Whether to show warnings when queue limits are reached (defaults to true) */
+    showQueueWarnings?: boolean;
+}
 /**
  * Comprehensive audio information interface providing metadata about currently playing audio
  */
@@ -131,6 +148,17 @@ export interface QueueSnapshot {
     /** Current volume level for the channel (0-1) */
     volume: number;
 }
+/**
+ * Information about a queue manipulation operation result
+ */
+export interface QueueManipulationResult {
+    /** Error message if operation failed */
+    error?: string;
+    /** Whether the operation was successful */
+    success: boolean;
+    /** The queue snapshot after the operation (if successful) */
+    updatedQueue?: QueueSnapshot;
+}
 /**
  * Callback function type for audio progress updates
  * @param info Current audio information
@@ -203,7 +231,7 @@ export interface ErrorRecoveryOptions {
  */
 export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
 /**
- * Extended audio queue channel with error handling capabilities
+ * Extended audio channel with queue management and callback support
  */
 export interface ExtendedAudioQueueChannel {
     audioCompleteCallbacks: Set<AudioCompleteCallback>;
@@ -212,13 +240,16 @@ export interface ExtendedAudioQueueChannel {
     audioResumeCallbacks: Set<AudioResumeCallback>;
     audioStartCallbacks: Set<AudioStartCallback>;
     fadeState?: ChannelFadeState;
-    isPaused?: boolean;
+    isPaused: boolean;
+    /** Active operation lock to prevent race conditions */
+    isLocked?: boolean;
+    /** Maximum allowed queue size for this channel */
+    maxQueueSize?: number;
     progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
     queue: HTMLAudioElement[];
     queueChangeCallbacks: Set<QueueChangeCallback>;
     retryConfig?: RetryConfig;
-    volume?: number;
-    volumeConfig?: VolumeConfig;
+    volume: number;
 }
 /**
  * Easing function types for volume transitions
@@ -237,6 +268,13 @@ export declare enum FadeType {
     Gentle = "gentle",
     Dramatic = "dramatic"
 }
+/**
+ * Timer types for volume transitions to ensure proper cleanup
+ */
+export declare enum TimerType {
+    RequestAnimationFrame = "raf",
+    Timeout = "timeout"
+}
 /**
  * Configuration for fade transitions
  */

package/dist/types.js

@@ -3,7 +3,11 @@
  * @fileoverview Type definitions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FadeType = exports.EasingType = exports.GLOBAL_PROGRESS_KEY = void 0;
+exports.TimerType = exports.FadeType = exports.EasingType = exports.GLOBAL_PROGRESS_KEY = exports.MAX_CHANNELS = void 0;
+/**
+ * Maximum number of audio channels allowed to prevent memory exhaustion
+ */
+exports.MAX_CHANNELS = 64;
 /**
  * Symbol used as a key for global (channel-wide) progress callbacks
  * This avoids the need for `null as any` type assertions
@@ -28,3 +32,11 @@ var FadeType;
     FadeType["Gentle"] = "gentle";
     FadeType["Dramatic"] = "dramatic";
 })(FadeType || (exports.FadeType = FadeType = {}));
+/**
+ * Timer types for volume transitions to ensure proper cleanup
+ */
+var TimerType;
+(function (TimerType) {
+    TimerType["RequestAnimationFrame"] = "raf";
+    TimerType["Timeout"] = "timeout";
+})(TimerType || (exports.TimerType = TimerType = {}));

package/dist/utils.d.ts

@@ -2,6 +2,31 @@
  * @fileoverview Utility functions for the audio-channel-queue package
  */
 import { AudioInfo, QueueSnapshot, ExtendedAudioQueueChannel } from './types';
+/**
+ * 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
+ * ```
+ */
+export declare const validateAudioUrl: (url: string) => string;
+/**
+ * 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'
+ * ```
+ */
+export declare const sanitizeForDisplay: (text: string) => string;
 /**
  * Extracts the filename from a URL string
  * @param url - The URL to extract the filename from

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;

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;