audioq 2.0.0

package/dist/types.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * @fileoverview Type definitions for the audioq package
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+ */
+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
+ */
+exports.GLOBAL_PROGRESS_KEY = Symbol('global-progress-callbacks');
+/**
+ * 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) {
+    EasingType["Linear"] = "linear";
+    EasingType["EaseIn"] = "ease-in";
+    EasingType["EaseOut"] = "ease-out";
+    EasingType["EaseInOut"] = "ease-in-out";
+})(EasingType || (exports.EasingType = EasingType = {}));
+/**
+ * Predefined fade types for pause/resume operations with different transition characteristics
+ */
+var FadeType;
+(function (FadeType) {
+    FadeType["Linear"] = "linear";
+    FadeType["Gentle"] = "gentle";
+    FadeType["Dramatic"] = "dramatic";
+})(FadeType || (exports.FadeType = FadeType = {}));
+/**
+ * Timer implementation types used 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

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Utility functions for the audioq 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
+ * @returns The extracted filename or 'unknown' if extraction fails
+ * @example
+ * ```typescript
+ * extractFileName('https://example.com/audio/song.mp3') // Returns: 'song.mp3'
+ * extractFileName('/path/to/audio.wav') // Returns: 'audio.wav'
+ * ```
+ */
+export declare const extractFileName: (url: string) => string;
+/**
+ * Extracts comprehensive audio information from an HTMLAudioElement
+ * @param audio - The HTML audio element to extract information from
+ * @param channelNumber - Optional channel number to include remaining queue info
+ * @param audioChannels - Optional audio channels array to calculate remainingInQueue
+ * @returns AudioInfo object with current playback state or null if audio is invalid
+ * @example
+ * ```typescript
+ * const audioElement = new Audio('song.mp3');
+ * const info = getAudioInfoFromElement(audioElement);
+ * console.log(info?.progress); // Current progress as decimal (0-1)
+ *
+ * // With channel context for remainingInQueue
+ * const infoWithQueue = getAudioInfoFromElement(audioElement, 0, audioChannels);
+ * console.log(infoWithQueue?.remainingInQueue); // Number of items left in queue
+ * ```
+ */
+export declare const getAudioInfoFromElement: (audio: HTMLAudioElement, channelNumber?: number, audioChannels?: ExtendedAudioQueueChannel[]) => AudioInfo | null;
+/**
+ * Creates a complete snapshot of a queue's current state
+ * @param channelNumber - The channel number to create a snapshot for
+ * @param audioChannels - Array of audio channels
+ * @returns QueueSnapshot object or null if channel doesn't exist
+ * @example
+ * ```typescript
+ * const snapshot = createQueueSnapshot(0, audioChannels);
+ * console.log(`Queue has ${snapshot?.totalItems} items`);
+ * ```
+ */
+export declare const createQueueSnapshot: (channelNumber: number, audioChannels: ExtendedAudioQueueChannel[]) => QueueSnapshot | null;
+/**
+ * Removes webpack hash patterns from filenames to get clean, readable names
+ * @param fileName - The filename that may contain webpack hashes
+ * @returns The cleaned filename with webpack hashes removed
+ * @example
+ * ```typescript
+ * cleanWebpackFilename('song.a1b2c3d4.mp3') // Returns: 'song.mp3'
+ * cleanWebpackFilename('notification.1a2b3c4d5e6f7890.wav') // Returns: 'notification.wav'
+ * cleanWebpackFilename('music.12345678.ogg') // Returns: 'music.ogg'
+ * cleanWebpackFilename('clean-file.mp3') // Returns: 'clean-file.mp3' (unchanged)
+ * ```
+ */
+export declare const cleanWebpackFilename: (fileName: string) => string;

package/dist/utils.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * @fileoverview Utility functions for the audioq package
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+ * @returns The extracted filename or 'unknown' if extraction fails
+ * @example
+ * ```typescript
+ * extractFileName('https://example.com/audio/song.mp3') // Returns: 'song.mp3'
+ * extractFileName('/path/to/audio.wav') // Returns: 'audio.wav'
+ * ```
+ */
+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 {
+        return (0, exports.sanitizeForDisplay)(decodeURIComponent(fileName || 'unknown'));
+    }
+    catch (_a) {
+        // If decoding fails, return the sanitized raw filename
+        return (0, exports.sanitizeForDisplay)(fileName || 'unknown');
+    }
+};
+exports.extractFileName = extractFileName;
+/**
+ * Extracts comprehensive audio information from an HTMLAudioElement
+ * @param audio - The HTML audio element to extract information from
+ * @param channelNumber - Optional channel number to include remaining queue info
+ * @param audioChannels - Optional audio channels array to calculate remainingInQueue
+ * @returns AudioInfo object with current playback state or null if audio is invalid
+ * @example
+ * ```typescript
+ * const audioElement = new Audio('song.mp3');
+ * const info = getAudioInfoFromElement(audioElement);
+ * console.log(info?.progress); // Current progress as decimal (0-1)
+ *
+ * // With channel context for remainingInQueue
+ * const infoWithQueue = getAudioInfoFromElement(audioElement, 0, audioChannels);
+ * console.log(infoWithQueue?.remainingInQueue); // Number of items left in queue
+ * ```
+ */
+const getAudioInfoFromElement = (audio, channelNumber, audioChannels) => {
+    if (!audio)
+        return null;
+    const duration = isNaN(audio.duration) ? 0 : audio.duration * 1000; // Convert to milliseconds
+    const currentTime = isNaN(audio.currentTime) ? 0 : audio.currentTime * 1000; // Convert to milliseconds
+    const progress = duration > 0 ? Math.min(currentTime / duration, 1) : 0;
+    const isPlaying = !audio.paused && !audio.ended && audio.readyState > 2;
+    // Calculate remainingInQueue if channel context is provided
+    let remainingInQueue = 0;
+    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
+    }
+    return {
+        currentTime,
+        duration,
+        fileName: (0, exports.extractFileName)(audio.src),
+        isLooping: audio.loop,
+        isPaused: audio.paused && !audio.ended,
+        isPlaying,
+        progress,
+        remainingInQueue,
+        src: audio.src,
+        volume: audio.volume
+    };
+};
+exports.getAudioInfoFromElement = getAudioInfoFromElement;
+/**
+ * Creates a complete snapshot of a queue's current state
+ * @param channelNumber - The channel number to create a snapshot for
+ * @param audioChannels - Array of audio channels
+ * @returns QueueSnapshot object or null if channel doesn't exist
+ * @example
+ * ```typescript
+ * const snapshot = createQueueSnapshot(0, audioChannels);
+ * console.log(`Queue has ${snapshot?.totalItems} items`);
+ * ```
+ */
+const createQueueSnapshot = (channelNumber, audioChannels) => {
+    var _a, _b;
+    const channel = audioChannels[channelNumber];
+    if (!channel)
+        return null;
+    const items = channel.queue.map((audio, index) => ({
+        duration: isNaN(audio.duration) ? 0 : audio.duration * 1000,
+        fileName: (0, exports.extractFileName)(audio.src),
+        isCurrentlyPlaying: index === 0 && !audio.paused && !audio.ended,
+        isLooping: audio.loop,
+        src: audio.src,
+        volume: audio.volume
+    }));
+    return {
+        channelNumber,
+        currentIndex: 0, // Current playing is always index 0 in our queue structure
+        isPaused: (_a = channel.isPaused) !== null && _a !== void 0 ? _a : false,
+        items,
+        totalItems: channel.queue.length,
+        volume: (_b = channel.volume) !== null && _b !== void 0 ? _b : 1.0
+    };
+};
+exports.createQueueSnapshot = createQueueSnapshot;
+/**
+ * Removes webpack hash patterns from filenames to get clean, readable names
+ * @param fileName - The filename that may contain webpack hashes
+ * @returns The cleaned filename with webpack hashes removed
+ * @example
+ * ```typescript
+ * cleanWebpackFilename('song.a1b2c3d4.mp3') // Returns: 'song.mp3'
+ * cleanWebpackFilename('notification.1a2b3c4d5e6f7890.wav') // Returns: 'notification.wav'
+ * cleanWebpackFilename('music.12345678.ogg') // Returns: 'music.ogg'
+ * cleanWebpackFilename('clean-file.mp3') // Returns: 'clean-file.mp3' (unchanged)
+ * ```
+ */
+const cleanWebpackFilename = (fileName) => {
+    // Remove webpack hash pattern: filename.hash.ext → filename.ext
+    return fileName.replace(/\.[a-f0-9]{8,}\./i, '.');
+};
+exports.cleanWebpackFilename = cleanWebpackFilename;

package/dist/volume.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Volume management functions for the audioq package
+ */
+import { VolumeConfig, FadeType, FadeConfig, EasingType } from './types';
+/**
+ * Gets the fade configuration for a specific fade type
+ * @param fadeType - The fade type to get configuration for
+ * @returns Fade configuration object
+ * @example
+ * ```typescript
+ * const config = getFadeConfig('gentle');
+ * console.log(`Gentle fade duration: ${config.duration}ms`);
+ * ```
+ */
+export declare const getFadeConfig: (fadeType: FadeType) => FadeConfig;
+/**
+ * Smoothly transitions volume for a specific channel over time
+ * @param channelNumber - The channel number 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
+ * @example
+ * ```typescript
+ * await transitionVolume(0, 0.2, 500, 'ease-out'); // Duck to 20% over 500ms
+ * ```
+ */
+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
+ * @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%
+ * setChannelVolume(0, 0.5, 300, 'ease-out'); // Smooth transition over 300ms
+ * ```
+ */
+export declare const setChannelVolume: (channelNumber: number, volume: number, transitionDuration?: number, easing?: EasingType) => Promise<void>;
+/**
+ * Gets the current volume for a specific channel
+ * @param channelNumber - The channel number to get volume for (defaults to 0)
+ * @returns Current volume level (0-1) or 1.0 if channel doesn't exist
+ * @example
+ * ```typescript
+ * const volume = getChannelVolume(0);
+ * const defaultChannelVolume = getChannelVolume(); // Gets channel 0
+ * console.log(`Channel 0 volume: ${volume * 100}%`);
+ * ```
+ */
+export declare const getChannelVolume: (channelNumber?: number) => number;
+/**
+ * Gets the volume levels for all channels
+ * @returns Array of volume levels (0-1) for each channel
+ * @example
+ * ```typescript
+ * const volumes = getAllChannelsVolume();
+ * volumes.forEach((volume, index) => {
+ *   console.log(`Channel ${index}: ${volume * 100}%`);
+ * });
+ * ```
+ */
+export declare const getAllChannelsVolume: () => number[];
+/**
+ * Sets volume for all channels to the same level
+ * @param volume - Volume level (0-1) to apply to all channels
+ * @example
+ * ```typescript
+ * await setAllChannelsVolume(0.6); // Set all channels to 60% volume
+ * ```
+ */
+export declare const setAllChannelsVolume: (volume: number) => Promise<void>;
+/**
+ * Sets the global volume multiplier that affects all channels
+ * This acts as a global volume control - individual channel volumes are multiplied by this value
+ * @param volume - Global volume level (0-1, will be clamped to this range)
+ * @example
+ * ```typescript
+ * // Set channel-specific volumes
+ * await setChannelVolume(0, 0.8); // SFX at 80%
+ * await setChannelVolume(1, 0.6); // Music at 60%
+ *
+ * // Apply global volume of 50% - all channels play at half their set volume
+ * await setGlobalVolume(0.5); // SFX now plays at 40%, music at 30%
+ * ```
+ */
+export declare const setGlobalVolume: (volume: number) => Promise<void>;
+/**
+ * Gets the current global volume multiplier
+ * @returns Current global volume level (0-1), defaults to 1.0
+ * @example
+ * ```typescript
+ * const globalVol = getGlobalVolume();
+ * console.log(`Global volume is ${globalVol * 100}%`);
+ * ```
+ */
+export declare const getGlobalVolume: () => number;
+/**
+ * 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
+ * setVolumeDucking({
+ *   priorityChannel: 1,
+ *   priorityVolume: 1.0,
+ *   duckingVolume: 0.2
+ * });
+ * ```
+ */
+export declare const setVolumeDucking: (config: VolumeConfig) => void;
+/**
+ * Removes volume ducking configuration from all channels
+ * @example
+ * ```typescript
+ * clearVolumeDucking(); // Remove all volume ducking effects
+ * ```
+ */
+export declare const clearVolumeDucking: () => void;
+/**
+ * Applies volume ducking effects based on current playback state with smooth transitions
+ * @param activeChannelNumber - The channel that just started playing
+ * @internal
+ */
+export declare const applyVolumeDucking: (activeChannelNumber: number) => Promise<void>;
+/**
+ * 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;
+/**
+ * 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;