audio-channel-queue 1.8.0 → 1.10.0

package/dist/info.js

@@ -3,14 +3,73 @@
  * @fileoverview Audio information and progress tracking functions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.offAudioResume = exports.offAudioPause = exports.onAudioResume = exports.onAudioPause = exports.onAudioComplete = exports.onAudioStart = exports.offQueueChange = exports.onQueueChange = exports.offAudioProgress = exports.onAudioProgress = exports.getQueueSnapshot = exports.getAllChannelsInfo = exports.getCurrentAudioInfo = exports.audioChannels = void 0;
+exports.offAudioResume = exports.offAudioPause = exports.onAudioResume = exports.onAudioPause = exports.onAudioComplete = exports.onAudioStart = exports.offQueueChange = exports.onQueueChange = exports.onAudioProgress = exports.getQueueSnapshot = exports.getAllChannelsInfo = exports.getCurrentAudioInfo = exports.audioChannels = void 0;
+exports.offAudioProgress = offAudioProgress;
+const types_1 = require("./types");
 const utils_1 = require("./utils");
 const events_1 = require("./events");
 /**
  * Global array to store audio channels with their queues and callback management
  * Each channel maintains its own audio queue and event callback sets
+ *
+ * Note: While you can inspect this array for debugging, direct modification is discouraged.
+ * Use the provided API functions for safe channel management.
  */
-exports.audioChannels = [];
+exports.audioChannels = new Proxy([], {
+    deleteProperty(target, prop) {
+        if (typeof prop === 'string' && !isNaN(Number(prop))) {
+            // eslint-disable-next-line no-console
+            console.warn('Warning: Direct deletion from audioChannels detected. ' +
+                'Consider using stopAllAudioInChannel() for proper cleanup.');
+        }
+        delete target[prop];
+        return true;
+    },
+    get(target, prop) {
+        const value = target[prop];
+        // Return channel objects with warnings on modification attempts
+        if (typeof value === 'object' &&
+            value !== null &&
+            typeof prop === 'string' &&
+            !isNaN(Number(prop))) {
+            return new Proxy(value, {
+                set(channelTarget, channelProp, channelValue) {
+                    // Allow internal modifications but warn about direct property changes
+                    if (typeof channelProp === 'string' &&
+                        !['queue', 'volume', 'isPaused', 'isLocked', 'volumeConfig'].includes(channelProp)) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`Warning: Direct modification of channel.${channelProp} detected. ` +
+                            'Use API functions for safer channel management.');
+                    }
+                    const key = typeof channelProp === 'symbol' ? channelProp.toString() : channelProp;
+                    channelTarget[key] = channelValue;
+                    return true;
+                }
+            });
+        }
+        return value;
+    },
+    set(target, prop, value) {
+        // Allow normal array operations
+        const key = typeof prop === 'symbol' ? prop.toString() : prop;
+        target[key] = value;
+        return true;
+    }
+});
+/**
+ * Validates a channel number against MAX_CHANNELS limit
+ * @param channelNumber - The channel number to validate
+ * @throws Error if the channel number is invalid
+ * @internal
+ */
+const validateChannelNumber = (channelNumber) => {
+    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})`);
+    }
+};
 /**
  * Gets current audio information for a specific channel
  * @param channelNumber - The channel number (defaults to 0)
@@ -56,18 +115,19 @@ const getAllChannelsInfo = () => {
 exports.getAllChannelsInfo = getAllChannelsInfo;
 /**
  * Gets a complete snapshot of the queue state for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @returns QueueSnapshot object or null if channel doesn't exist
  * @example
  * ```typescript
- * const snapshot = getQueueSnapshot(0);
+ * const snapshot = getQueueSnapshot();
  * if (snapshot) {
  *   console.log(`Queue has ${snapshot.totalItems} items`);
  *   console.log(`Currently playing: ${snapshot.items[0]?.fileName}`);
  * }
+ * const channelSnapshot = getQueueSnapshot(2);
  * ```
  */
-const getQueueSnapshot = (channelNumber) => {
+const getQueueSnapshot = (channelNumber = 0) => {
     return (0, utils_1.createQueueSnapshot)(channelNumber, exports.audioChannels);
 };
 exports.getQueueSnapshot = getQueueSnapshot;
@@ -75,6 +135,7 @@ exports.getQueueSnapshot = getQueueSnapshot;
  * Subscribes to real-time progress updates for a specific channel
  * @param channelNumber - The channel number
  * @param callback - Function to call with audio info updates
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioProgress(0, (info) => {
@@ -84,6 +145,7 @@ exports.getQueueSnapshot = getQueueSnapshot;
  * ```
  */
 const onAudioProgress = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -113,23 +175,24 @@ const onAudioProgress = (channelNumber, callback) => {
         (0, events_1.setupProgressTracking)(currentAudio, channelNumber, exports.audioChannels);
     }
     // Store callback for future audio elements in this channel
-    if (!channel.progressCallbacks.has(null)) {
-        channel.progressCallbacks.set(null, new Set());
+    if (!channel.progressCallbacks.has(types_1.GLOBAL_PROGRESS_KEY)) {
+        channel.progressCallbacks.set(types_1.GLOBAL_PROGRESS_KEY, new Set());
     }
-    channel.progressCallbacks.get(null).add(callback);
+    channel.progressCallbacks.get(types_1.GLOBAL_PROGRESS_KEY).add(callback);
 };
 exports.onAudioProgress = onAudioProgress;
 /**
  * Removes progress listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioProgress(0); // Stop receiving progress updates for channel 0
+ * offAudioProgress();
+ * offAudioProgress(1); // Stop receiving progress updates for channel 1
  * ```
  */
-const offAudioProgress = (channelNumber) => {
+function offAudioProgress(channelNumber = 0) {
     const channel = exports.audioChannels[channelNumber];
-    if (!channel || !channel.progressCallbacks)
+    if (!(channel === null || channel === void 0 ? void 0 : channel.progressCallbacks))
         return;
     // Clean up event listeners for current audio if exists
     if (channel.queue.length > 0) {
@@ -138,12 +201,12 @@ const offAudioProgress = (channelNumber) => {
     }
     // Clear all callbacks for this channel
     channel.progressCallbacks.clear();
-};
-exports.offAudioProgress = offAudioProgress;
+}
 /**
  * Subscribes to queue change events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when queue changes
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onQueueChange(0, (snapshot) => {
@@ -153,6 +216,7 @@ exports.offAudioProgress = offAudioProgress;
  * ```
  */
 const onQueueChange = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -184,7 +248,7 @@ exports.onQueueChange = onQueueChange;
  */
 const offQueueChange = (channelNumber) => {
     const channel = exports.audioChannels[channelNumber];
-    if (!channel || !channel.queueChangeCallbacks)
+    if (!(channel === null || channel === void 0 ? void 0 : channel.queueChangeCallbacks))
         return;
     channel.queueChangeCallbacks.clear();
 };
@@ -193,6 +257,7 @@ exports.offQueueChange = offQueueChange;
  * Subscribes to audio start events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when audio starts playing
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioStart(0, (info) => {
@@ -202,6 +267,7 @@ exports.offQueueChange = offQueueChange;
  * ```
  */
 const onAudioStart = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -227,6 +293,7 @@ exports.onAudioStart = onAudioStart;
  * Subscribes to audio complete events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when audio completes
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioComplete(0, (info) => {
@@ -238,6 +305,7 @@ exports.onAudioStart = onAudioStart;
  * ```
  */
 const onAudioComplete = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -263,6 +331,7 @@ exports.onAudioComplete = onAudioComplete;
  * Subscribes to audio pause events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when audio is paused
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioPause(0, (channelNumber, info) => {
@@ -272,6 +341,7 @@ exports.onAudioComplete = onAudioComplete;
  * ```
  */
 const onAudioPause = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -297,6 +367,7 @@ exports.onAudioPause = onAudioPause;
  * Subscribes to audio resume events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when audio is resumed
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioResume(0, (channelNumber, info) => {
@@ -306,6 +377,7 @@ exports.onAudioPause = onAudioPause;
  * ```
  */
 const onAudioResume = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -337,7 +409,7 @@ exports.onAudioResume = onAudioResume;
  */
 const offAudioPause = (channelNumber) => {
     const channel = exports.audioChannels[channelNumber];
-    if (!channel || !channel.audioPauseCallbacks)
+    if (!(channel === null || channel === void 0 ? void 0 : channel.audioPauseCallbacks))
         return;
     channel.audioPauseCallbacks.clear();
 };
@@ -352,7 +424,7 @@ exports.offAudioPause = offAudioPause;
  */
 const offAudioResume = (channelNumber) => {
     const channel = exports.audioChannels[channelNumber];
-    if (!channel || !channel.audioResumeCallbacks)
+    if (!(channel === null || channel === void 0 ? void 0 : channel.audioResumeCallbacks))
         return;
     channel.audioResumeCallbacks.clear();
 };

package/dist/pause.d.ts

@@ -6,72 +6,84 @@ import { FadeType } from './types';
  * Pauses the currently playing audio in a specific channel with smooth volume fade
  * @param fadeType - Type of fade transition to apply
  * @param channelNumber - The channel number to pause (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when the pause and fade are complete
  * @example
  * ```typescript
  * await pauseWithFade(FadeType.Gentle, 0); // Pause with gentle fade out over 800ms
- * await pauseWithFade(FadeType.Dramatic, 1); // Pause with dramatic fade out over 800ms
- * await pauseWithFade(FadeType.Linear, 2); // Linear pause with 800ms fade
+ * await pauseWithFade(FadeType.Dramatic, 1, 1500); // Pause with dramatic fade out over 1.5s
+ * await pauseWithFade(FadeType.Linear, 2, 500); // Linear pause with custom 500ms fade
  * ```
  */
-export declare const pauseWithFade: (fadeType?: FadeType, channelNumber?: number) => Promise<void>;
+export declare const pauseWithFade: (fadeType?: FadeType, channelNumber?: number, duration?: number) => Promise<void>;
 /**
  * Resumes the currently paused audio in a specific channel with smooth volume fade
  * Uses the complementary fade curve automatically based on the pause fade type, or allows override
  * @param fadeType - Optional fade type to override the stored fade type from pause
  * @param channelNumber - The channel number to resume (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses stored or fadeType default if not provided)
  * @returns Promise that resolves when the resume and fade are complete
  * @example
  * ```typescript
  * await resumeWithFade(); // Resume with automatically paired fade curve from pause
  * await resumeWithFade(FadeType.Dramatic, 0); // Override with dramatic fade
- * await resumeWithFade(FadeType.Linear); // Override with linear fade on default channel
+ * await resumeWithFade(FadeType.Linear, 0, 1000); // Override with linear fade over 1 second
  * ```
  */
-export declare const resumeWithFade: (fadeType?: FadeType, channelNumber?: number) => Promise<void>;
+export declare const resumeWithFade: (fadeType?: FadeType, channelNumber?: number, duration?: number) => Promise<void>;
 /**
  * Toggles pause/resume state for a specific channel with integrated fade
  * @param fadeType - Type of fade transition to apply when pausing
  * @param channelNumber - The channel number to toggle (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when the toggle and fade are complete
  * @example
  * ```typescript
  * await togglePauseWithFade(FadeType.Gentle, 0); // Toggle with gentle fade
+ * await togglePauseWithFade(FadeType.Dramatic, 0, 500); // Toggle with custom 500ms fade
  * ```
  */
-export declare const togglePauseWithFade: (fadeType?: FadeType, channelNumber?: number) => Promise<void>;
+export declare const togglePauseWithFade: (fadeType?: FadeType, channelNumber?: number, duration?: number) => Promise<void>;
 /**
  * Pauses all currently playing audio across all channels with smooth volume fade
  * @param fadeType - Type of fade transition to apply to all channels
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when all channels are paused and faded
  * @example
  * ```typescript
- * await pauseAllWithFade('dramatic'); // Pause everything with dramatic fade
+ * await pauseAllWithFade(FadeType.Dramatic); // Pause everything with dramatic fade
+ * await pauseAllWithFade(FadeType.Gentle, 1200); // Pause all channels with custom 1.2s fade
  * ```
  */
-export declare const pauseAllWithFade: (fadeType?: FadeType) => Promise<void>;
+export declare const pauseAllWithFade: (fadeType?: FadeType, duration?: number) => Promise<void>;
 /**
  * Resumes all currently paused audio across all channels with smooth volume fade
- * Uses automatically paired fade curves based on each channel's pause fade type
+ * Uses automatically paired fade curves based on each channel's pause fade type, or allows override
+ * @param fadeType - Optional fade type to override stored fade types for all channels
+ * @param duration - Optional custom fade duration in milliseconds (uses stored or fadeType default if not provided)
  * @returns Promise that resolves when all channels are resumed and faded
  * @example
  * ```typescript
  * await resumeAllWithFade(); // Resume everything with paired fade curves
+ * await resumeAllWithFade(FadeType.Gentle, 800); // Override all channels with gentle fade over 800ms
+ * await resumeAllWithFade(undefined, 600); // Use stored fade types with custom 600ms duration
  * ```
  */
-export declare const resumeAllWithFade: () => Promise<void>;
+export declare const resumeAllWithFade: (fadeType?: FadeType, duration?: number) => Promise<void>;
 /**
  * Toggles pause/resume state for all channels with integrated fade
  * If any channels are playing, all will be paused with fade
  * If all channels are paused, all will be resumed with fade
  * @param fadeType - Type of fade transition to apply when pausing
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when all toggles and fades are complete
  * @example
  * ```typescript
- * await togglePauseAllWithFade('gentle'); // Global toggle with gentle fade
+ * await togglePauseAllWithFade(FadeType.Gentle); // Global toggle with gentle fade
+ * await togglePauseAllWithFade(FadeType.Dramatic, 600); // Global toggle with custom 600ms fade
  * ```
  */
-export declare const togglePauseAllWithFade: (fadeType?: FadeType) => Promise<void>;
+export declare const togglePauseAllWithFade: (fadeType?: FadeType, duration?: number) => Promise<void>;
 /**
  * Pauses the currently playing audio in a specific channel
  * @param channelNumber - The channel number to pause (defaults to 0)

package/dist/pause.js

@@ -18,22 +18,15 @@ const info_1 = require("./info");
 const utils_1 = require("./utils");
 const events_1 = require("./events");
 const volume_1 = require("./volume");
-/**
- * Predefined fade configurations for different transition types
- */
-const FADE_CONFIGS = {
-    [types_1.FadeType.Linear]: { duration: 800, pauseCurve: types_1.EasingType.Linear, resumeCurve: types_1.EasingType.Linear },
-    [types_1.FadeType.Gentle]: { duration: 800, pauseCurve: types_1.EasingType.EaseOut, resumeCurve: types_1.EasingType.EaseIn },
-    [types_1.FadeType.Dramatic]: { duration: 800, pauseCurve: types_1.EasingType.EaseIn, resumeCurve: types_1.EasingType.EaseOut }
-};
 /**
  * Gets the current volume for a channel, accounting for synchronous state
  * @param channelNumber - The channel number
  * @returns Current volume level (0-1)
  */
 const getChannelVolumeSync = (channelNumber) => {
+    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;
 };
 /**
  * Sets the channel volume synchronously in internal state
@@ -53,15 +46,17 @@ const setChannelVolumeSync = (channelNumber, volume) => {
  * Pauses the currently playing audio in a specific channel with smooth volume fade
  * @param fadeType - Type of fade transition to apply
  * @param channelNumber - The channel number to pause (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when the pause and fade are complete
  * @example
  * ```typescript
  * await pauseWithFade(FadeType.Gentle, 0); // Pause with gentle fade out over 800ms
- * await pauseWithFade(FadeType.Dramatic, 1); // Pause with dramatic fade out over 800ms
- * await pauseWithFade(FadeType.Linear, 2); // Linear pause with 800ms fade
+ * await pauseWithFade(FadeType.Dramatic, 1, 1500); // Pause with dramatic fade out over 1.5s
+ * await pauseWithFade(FadeType.Linear, 2, 500); // Linear pause with custom 500ms fade
  * ```
  */
-const pauseWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle, channelNumber = 0) {
+const pauseWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle, channelNumber = 0, duration) {
+    var _a, _b, _c;
     const channel = info_1.audioChannels[channelNumber];
     if (!channel || channel.queue.length === 0)
         return;
@@ -69,24 +64,49 @@ const pauseWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, func
     // Don't pause if already paused or ended
     if (currentAudio.paused || currentAudio.ended)
         return;
-    const config = FADE_CONFIGS[fadeType];
-    const originalVolume = getChannelVolumeSync(channelNumber);
-    // Store fade state for resumeWithFade to use
+    const config = (0, volume_1.getFadeConfig)(fadeType);
+    const effectiveDuration = duration !== null && duration !== void 0 ? duration : config.duration;
+    // Race condition fix: Use existing fadeState originalVolume if already transitioning,
+    // otherwise capture current volume
+    let originalVolume;
+    if ((_a = channel.fadeState) === null || _a === void 0 ? void 0 : _a.isTransitioning) {
+        // We're already in any kind of transition (pause or resume), preserve original volume
+        originalVolume = channel.fadeState.originalVolume;
+    }
+    else {
+        // First fade or no transition in progress, capture current volume
+        // But ensure we don't capture a volume of 0 during a transition
+        const currentVolume = getChannelVolumeSync(channelNumber);
+        originalVolume = currentVolume > 0 ? currentVolume : ((_c = (_b = channel.fadeState) === null || _b === void 0 ? void 0 : _b.originalVolume) !== null && _c !== void 0 ? _c : 1.0);
+    }
+    // Store fade state for resumeWithFade to use (including custom duration)
     channel.fadeState = {
-        originalVolume,
+        customDuration: duration,
         fadeType,
-        isPaused: true
+        isPaused: true,
+        isTransitioning: true,
+        originalVolume
     };
-    if (config.duration === 0) {
+    if (effectiveDuration === 0) {
         // Instant pause
         yield (0, exports.pauseChannel)(channelNumber);
+        // Reset volume to original for resume (synchronously to avoid state issues)
+        setChannelVolumeSync(channelNumber, originalVolume);
+        // Mark transition as complete for instant pause
+        if (channel.fadeState) {
+            channel.fadeState.isTransitioning = false;
+        }
         return;
     }
     // Fade to 0 with pause curve, then pause
-    yield (0, volume_1.transitionVolume)(channelNumber, 0, config.duration, config.pauseCurve);
+    yield (0, volume_1.transitionVolume)(channelNumber, 0, effectiveDuration, config.pauseCurve);
     yield (0, exports.pauseChannel)(channelNumber);
     // Reset volume to original for resume (synchronously to avoid state issues)
     setChannelVolumeSync(channelNumber, originalVolume);
+    // Mark transition as complete
+    if (channel.fadeState) {
+        channel.fadeState.isTransitioning = false;
+    }
 });
 exports.pauseWithFade = pauseWithFade;
 /**
@@ -94,93 +114,122 @@ exports.pauseWithFade = pauseWithFade;
  * Uses the complementary fade curve automatically based on the pause fade type, or allows override
  * @param fadeType - Optional fade type to override the stored fade type from pause
  * @param channelNumber - The channel number to resume (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses stored or fadeType default if not provided)
  * @returns Promise that resolves when the resume and fade are complete
  * @example
  * ```typescript
  * await resumeWithFade(); // Resume with automatically paired fade curve from pause
  * await resumeWithFade(FadeType.Dramatic, 0); // Override with dramatic fade
- * await resumeWithFade(FadeType.Linear); // Override with linear fade on default channel
+ * await resumeWithFade(FadeType.Linear, 0, 1000); // Override with linear fade over 1 second
  * ```
  */
-const resumeWithFade = (fadeType_1, ...args_1) => __awaiter(void 0, [fadeType_1, ...args_1], void 0, function* (fadeType, channelNumber = 0) {
+const resumeWithFade = (fadeType_1, ...args_1) => __awaiter(void 0, [fadeType_1, ...args_1], void 0, function* (fadeType, channelNumber = 0, duration) {
     const channel = info_1.audioChannels[channelNumber];
     if (!channel || channel.queue.length === 0)
         return;
     const fadeState = channel.fadeState;
-    if (!fadeState || !fadeState.isPaused) {
+    if (!(fadeState === null || fadeState === void 0 ? void 0 : fadeState.isPaused)) {
         // Fall back to regular resume if no fade state
         yield (0, exports.resumeChannel)(channelNumber);
         return;
     }
     // Use provided fadeType or fall back to stored fadeType from pause
-    const effectiveFadeType = fadeType || fadeState.fadeType;
-    const config = FADE_CONFIGS[effectiveFadeType];
-    if (config.duration === 0) {
+    const effectiveFadeType = fadeType !== null && fadeType !== void 0 ? fadeType : fadeState.fadeType;
+    const config = (0, volume_1.getFadeConfig)(effectiveFadeType);
+    // Determine effective duration: custom parameter > stored custom > fadeType default
+    let effectiveDuration;
+    if (duration !== undefined) {
+        effectiveDuration = duration;
+    }
+    else if (fadeState.customDuration !== undefined) {
+        effectiveDuration = fadeState.customDuration;
+    }
+    else {
+        effectiveDuration = config.duration;
+    }
+    if (effectiveDuration === 0) {
         // Instant resume
+        const targetVolume = fadeState.originalVolume > 0 ? fadeState.originalVolume : 1.0;
+        setChannelVolumeSync(channelNumber, targetVolume);
         yield (0, exports.resumeChannel)(channelNumber);
         fadeState.isPaused = false;
+        fadeState.isTransitioning = false;
         return;
     }
+    // Race condition fix: Ensure we have a valid original volume to restore to
+    const targetVolume = fadeState.originalVolume > 0 ? fadeState.originalVolume : 1.0;
+    // Mark as transitioning to prevent volume capture during rapid toggles
+    fadeState.isTransitioning = true;
     // Set volume to 0, resume, then fade to original with resume curve
     setChannelVolumeSync(channelNumber, 0);
     yield (0, exports.resumeChannel)(channelNumber);
-    yield (0, volume_1.transitionVolume)(channelNumber, fadeState.originalVolume, config.duration, config.resumeCurve);
+    // Use the stored original volume, not current volume, to prevent race conditions
+    yield (0, volume_1.transitionVolume)(channelNumber, targetVolume, effectiveDuration, config.resumeCurve);
     fadeState.isPaused = false;
+    fadeState.isTransitioning = false;
 });
 exports.resumeWithFade = resumeWithFade;
 /**
  * Toggles pause/resume state for a specific channel with integrated fade
  * @param fadeType - Type of fade transition to apply when pausing
  * @param channelNumber - The channel number to toggle (defaults to 0)
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when the toggle and fade are complete
  * @example
  * ```typescript
  * await togglePauseWithFade(FadeType.Gentle, 0); // Toggle with gentle fade
+ * await togglePauseWithFade(FadeType.Dramatic, 0, 500); // Toggle with custom 500ms fade
  * ```
  */
-const togglePauseWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle, channelNumber = 0) {
+const togglePauseWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle, channelNumber = 0, duration) {
     const channel = info_1.audioChannels[channelNumber];
     if (!channel || channel.queue.length === 0)
         return;
     const currentAudio = channel.queue[0];
     if (currentAudio.paused) {
-        yield (0, exports.resumeWithFade)(undefined, channelNumber);
+        yield (0, exports.resumeWithFade)(undefined, channelNumber, duration);
     }
     else {
-        yield (0, exports.pauseWithFade)(fadeType, channelNumber);
+        yield (0, exports.pauseWithFade)(fadeType, channelNumber, duration);
     }
 });
 exports.togglePauseWithFade = togglePauseWithFade;
 /**
  * Pauses all currently playing audio across all channels with smooth volume fade
  * @param fadeType - Type of fade transition to apply to all channels
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when all channels are paused and faded
  * @example
  * ```typescript
- * await pauseAllWithFade('dramatic'); // Pause everything with dramatic fade
+ * await pauseAllWithFade(FadeType.Dramatic); // Pause everything with dramatic fade
+ * await pauseAllWithFade(FadeType.Gentle, 1200); // Pause all channels with custom 1.2s fade
  * ```
  */
-const pauseAllWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle) {
+const pauseAllWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle, duration) {
     const pausePromises = [];
     info_1.audioChannels.forEach((_channel, index) => {
-        pausePromises.push((0, exports.pauseWithFade)(fadeType, index));
+        pausePromises.push((0, exports.pauseWithFade)(fadeType, index, duration));
     });
     yield Promise.all(pausePromises);
 });
 exports.pauseAllWithFade = pauseAllWithFade;
 /**
  * Resumes all currently paused audio across all channels with smooth volume fade
- * Uses automatically paired fade curves based on each channel's pause fade type
+ * Uses automatically paired fade curves based on each channel's pause fade type, or allows override
+ * @param fadeType - Optional fade type to override stored fade types for all channels
+ * @param duration - Optional custom fade duration in milliseconds (uses stored or fadeType default if not provided)
  * @returns Promise that resolves when all channels are resumed and faded
  * @example
  * ```typescript
  * await resumeAllWithFade(); // Resume everything with paired fade curves
+ * await resumeAllWithFade(FadeType.Gentle, 800); // Override all channels with gentle fade over 800ms
+ * await resumeAllWithFade(undefined, 600); // Use stored fade types with custom 600ms duration
  * ```
  */
-const resumeAllWithFade = () => __awaiter(void 0, void 0, void 0, function* () {
+const resumeAllWithFade = (fadeType, duration) => __awaiter(void 0, void 0, void 0, function* () {
     const resumePromises = [];
     info_1.audioChannels.forEach((_channel, index) => {
-        resumePromises.push((0, exports.resumeWithFade)(undefined, index));
+        resumePromises.push((0, exports.resumeWithFade)(fadeType, index, duration));
     });
     yield Promise.all(resumePromises);
 });
@@ -190,13 +239,15 @@ exports.resumeAllWithFade = resumeAllWithFade;
  * If any channels are playing, all will be paused with fade
  * If all channels are paused, all will be resumed with fade
  * @param fadeType - Type of fade transition to apply when pausing
+ * @param duration - Optional custom fade duration in milliseconds (uses fadeType default if not provided)
  * @returns Promise that resolves when all toggles and fades are complete
  * @example
  * ```typescript
- * await togglePauseAllWithFade('gentle'); // Global toggle with gentle fade
+ * await togglePauseAllWithFade(FadeType.Gentle); // Global toggle with gentle fade
+ * await togglePauseAllWithFade(FadeType.Dramatic, 600); // Global toggle with custom 600ms fade
  * ```
  */
-const togglePauseAllWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle) {
+const togglePauseAllWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle, duration) {
     let hasPlayingChannel = false;
     // Check if any channel is currently playing
     for (let i = 0; i < info_1.audioChannels.length; i++) {
@@ -212,10 +263,10 @@ const togglePauseAllWithFade = (...args_1) => __awaiter(void 0, [...args_1], voi
     // If any channel is playing, pause all with fade
     // If no channels are playing, resume all with fade
     if (hasPlayingChannel) {
-        yield (0, exports.pauseAllWithFade)(fadeType);
+        yield (0, exports.pauseAllWithFade)(fadeType, duration);
     }
     else {
-        yield (0, exports.resumeAllWithFade)();
+        yield (0, exports.resumeAllWithFade)(fadeType, duration);
     }
 });
 exports.togglePauseAllWithFade = togglePauseAllWithFade;
@@ -335,8 +386,9 @@ exports.resumeAllChannels = resumeAllChannels;
  * ```
  */
 const isChannelPaused = (channelNumber = 0) => {
+    var _a;
     const channel = info_1.audioChannels[channelNumber];
-    return (channel === null || channel === void 0 ? void 0 : channel.isPaused) || false;
+    return (_a = channel === null || channel === void 0 ? void 0 : channel.isPaused) !== null && _a !== void 0 ? _a : false;
 };
 exports.isChannelPaused = isChannelPaused;
 /**
@@ -351,7 +403,7 @@ exports.isChannelPaused = isChannelPaused;
  * ```
  */
 const getAllChannelsPauseState = () => {
-    return info_1.audioChannels.map((channel) => (channel === null || channel === void 0 ? void 0 : channel.isPaused) || false);
+    return info_1.audioChannels.map((channel) => { var _a; return (_a = channel === null || channel === void 0 ? void 0 : channel.isPaused) !== null && _a !== void 0 ? _a : false; });
 };
 exports.getAllChannelsPauseState = getAllChannelsPauseState;
 /**