audio-channel-queue 1.7.0 → 1.9.0

package/dist/pause.js

@@ -12,10 +12,264 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.togglePauseAllChannels = exports.getAllChannelsPauseState = exports.isChannelPaused = exports.resumeAllChannels = exports.pauseAllChannels = exports.togglePauseChannel = exports.resumeChannel = exports.pauseChannel = void 0;
+exports.togglePauseAllChannels = exports.getAllChannelsPauseState = exports.isChannelPaused = exports.resumeAllChannels = exports.pauseAllChannels = exports.togglePauseChannel = exports.resumeChannel = exports.pauseChannel = exports.togglePauseAllWithFade = exports.resumeAllWithFade = exports.pauseAllWithFade = exports.togglePauseWithFade = exports.resumeWithFade = exports.pauseWithFade = void 0;
+const types_1 = require("./types");
 const info_1 = require("./info");
 const utils_1 = require("./utils");
 const events_1 = require("./events");
+const volume_1 = require("./volume");
+/**
+ * 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 (_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
+ * @param channelNumber - The channel number
+ * @param volume - Volume level (0-1)
+ */
+const setChannelVolumeSync = (channelNumber, volume) => {
+    const channel = info_1.audioChannels[channelNumber];
+    if (channel) {
+        channel.volume = volume;
+        if (channel.queue.length > 0) {
+            channel.queue[0].volume = 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, 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, duration) {
+    var _a, _b, _c;
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel || channel.queue.length === 0)
+        return;
+    const currentAudio = channel.queue[0];
+    // Don't pause if already paused or ended
+    if (currentAudio.paused || currentAudio.ended)
+        return;
+    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 = {
+        customDuration: duration,
+        fadeType,
+        isPaused: true,
+        isTransitioning: true,
+        originalVolume
+    };
+    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, 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;
+/**
+ * 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, 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, duration) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel || channel.queue.length === 0)
+        return;
+    const fadeState = channel.fadeState;
+    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 !== 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);
+    // 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, 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, duration);
+    }
+    else {
+        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(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, duration) {
+    const pausePromises = [];
+    info_1.audioChannels.forEach((_channel, 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, 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 = (fadeType, duration) => __awaiter(void 0, void 0, void 0, function* () {
+    const resumePromises = [];
+    info_1.audioChannels.forEach((_channel, index) => {
+        resumePromises.push((0, exports.resumeWithFade)(fadeType, index, duration));
+    });
+    yield Promise.all(resumePromises);
+});
+exports.resumeAllWithFade = resumeAllWithFade;
+/**
+ * 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(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, duration) {
+    let hasPlayingChannel = false;
+    // Check if any channel is currently playing
+    for (let i = 0; i < info_1.audioChannels.length; i++) {
+        const channel = info_1.audioChannels[i];
+        if (channel && channel.queue.length > 0) {
+            const currentAudio = channel.queue[0];
+            if (!currentAudio.paused && !currentAudio.ended) {
+                hasPlayingChannel = true;
+                break;
+            }
+        }
+    }
+    // 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, duration);
+    }
+    else {
+        yield (0, exports.resumeAllWithFade)(fadeType, duration);
+    }
+});
+exports.togglePauseAllWithFade = togglePauseAllWithFade;
 /**
  * Pauses the currently playing audio in a specific channel
  * @param channelNumber - The channel number to pause (defaults to 0)
@@ -132,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;
 /**
@@ -148,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;
 /**

package/dist/types.d.ts

@@ -1,6 +1,11 @@
 /**
  * @fileoverview Type definitions for the audio-channel-queue package
  */
+/**
+ * Symbol used as a key for global (channel-wide) progress callbacks
+ * This avoids the need for `null as any` type assertions
+ */
+export declare const GLOBAL_PROGRESS_KEY: unique symbol;
 /**
  * Array of HTMLAudioElement objects representing an audio queue
  */
@@ -8,9 +13,9 @@ export type AudioQueue = HTMLAudioElement[];
 /**
  * Basic audio queue channel structure
  */
-export type AudioQueueChannel = {
+export interface AudioQueueChannel {
     queue: AudioQueue;
-};
+}
 /**
  * Volume ducking configuration for channels
  */
@@ -26,7 +31,7 @@ export interface VolumeConfig {
     /** Duration in milliseconds for volume restore transition (defaults to 500ms) */
     restoreTransitionDuration?: number;
     /** Easing function for volume transitions (defaults to 'ease-out') */
-    transitionEasing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+    transitionEasing?: EasingType;
 }
 /**
  * Audio file configuration for queueing
@@ -206,11 +211,55 @@ export interface ExtendedAudioQueueChannel {
     audioPauseCallbacks: Set<AudioPauseCallback>;
     audioResumeCallbacks: Set<AudioResumeCallback>;
     audioStartCallbacks: Set<AudioStartCallback>;
+    fadeState?: ChannelFadeState;
     isPaused?: boolean;
-    progressCallbacks: Map<HTMLAudioElement | null, Set<ProgressCallback>>;
+    progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
     queue: HTMLAudioElement[];
     queueChangeCallbacks: Set<QueueChangeCallback>;
     retryConfig?: RetryConfig;
     volume?: number;
     volumeConfig?: VolumeConfig;
 }
+/**
+ * Easing function types for volume transitions
+ */
+export declare enum EasingType {
+    Linear = "linear",
+    EaseIn = "ease-in",
+    EaseOut = "ease-out",
+    EaseInOut = "ease-in-out"
+}
+/**
+ * Fade type for pause/resume operations with integrated volume transitions
+ */
+export declare enum FadeType {
+    Linear = "linear",
+    Gentle = "gentle",
+    Dramatic = "dramatic"
+}
+/**
+ * Configuration for fade transitions
+ */
+export interface FadeConfig {
+    /** Duration in milliseconds for the fade transition */
+    duration: number;
+    /** Easing curve to use when pausing (fading out) */
+    pauseCurve: EasingType;
+    /** Easing curve to use when resuming (fading in) */
+    resumeCurve: EasingType;
+}
+/**
+ * Internal fade state tracking for pause/resume with fade functionality
+ */
+export interface ChannelFadeState {
+    /** The original volume level before fading began */
+    originalVolume: number;
+    /** The type of fade being used */
+    fadeType: FadeType;
+    /** Whether the channel is currently paused due to fade */
+    isPaused: boolean;
+    /** Custom duration in milliseconds if specified (overrides fade type default) */
+    customDuration?: number;
+    /** Whether the channel is currently transitioning (during any fade operation) to prevent capturing intermediate volumes during rapid pause/resume toggles */
+    isTransitioning?: boolean;
+}

package/dist/types.js

@@ -3,3 +3,28 @@
  * @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;
+/**
+ * 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');
+/**
+ * Easing function types for volume transitions
+ */
+var EasingType;
+(function (EasingType) {
+    EasingType["Linear"] = "linear";
+    EasingType["EaseIn"] = "ease-in";
+    EasingType["EaseOut"] = "ease-out";
+    EasingType["EaseInOut"] = "ease-in-out";
+})(EasingType || (exports.EasingType = EasingType = {}));
+/**
+ * Fade type for pause/resume operations with integrated volume transitions
+ */
+var FadeType;
+(function (FadeType) {
+    FadeType["Linear"] = "linear";
+    FadeType["Gentle"] = "gentle";
+    FadeType["Dramatic"] = "dramatic";
+})(FadeType || (exports.FadeType = FadeType = {}));

package/dist/utils.js

@@ -56,7 +56,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 +86,7 @@ exports.getAudioInfoFromElement = getAudioInfoFromElement;
  * ```
  */
 const createQueueSnapshot = (channelNumber, audioChannels) => {
+    var _a, _b;
     const channel = audioChannels[channelNumber];
     if (!channel)
         return null;
@@ -100,10 +101,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

@@ -1,7 +1,18 @@
 /**
  * @fileoverview Volume management functions for the audio-channel-queue package
  */
-import { VolumeConfig } from './types';
+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
@@ -14,7 +25,7 @@ import { VolumeConfig } from './types';
  * await transitionVolume(0, 0.2, 500, 'ease-out'); // Duck to 20% over 500ms
  * ```
  */
-export declare const transitionVolume: (channelNumber: number, targetVolume: number, duration?: number, easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out") => Promise<void>;
+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
  * @param channelNumber - The channel number to set volume for
@@ -27,7 +38,7 @@ export declare const transitionVolume: (channelNumber: number, targetVolume: num
  * setChannelVolume(0, 0.5, 300, 'ease-out'); // Smooth transition over 300ms
  * ```
  */
-export declare const setChannelVolume: (channelNumber: number, volume: number, transitionDuration?: number, easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out") => Promise<void>;
+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)
@@ -90,6 +101,20 @@ export declare const clearVolumeDucking: () => void;
  * @internal
  */
 export declare const applyVolumeDucking: (activeChannelNumber: number) => Promise<void>;
+/**
+ * Fades the volume for a specific channel over time (alias for transitionVolume with improved naming)
+ * @param channelNumber - The channel number to fade
+ * @param targetVolume - Target volume level (0-1)
+ * @param duration - Fade duration in milliseconds (defaults to 250)
+ * @param easing - Easing function type (defaults to 'ease-out')
+ * @returns Promise that resolves when fade completes
+ * @example
+ * ```typescript
+ * await fadeVolume(0, 0, 800, 'ease-in'); // Fade out over 800ms
+ * await fadeVolume(0, 1, 600, 'ease-out'); // Fade in over 600ms
+ * ```
+ */
+export declare const fadeVolume: (channelNumber: number, targetVolume: number, duration?: number, easing?: EasingType) => Promise<void>;
 /**
  * Restores normal volume levels when priority channel stops with smooth transitions
  * @param stoppedChannelNumber - The channel that just stopped playing

package/dist/volume.js

@@ -12,18 +12,53 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.restoreVolumeLevels = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = void 0;
+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();
+/**
+ * Predefined fade configurations for different transition types
+ */
+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
+ * @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`);
+ * ```
+ */
+const getFadeConfig = (fadeType) => {
+    return Object.assign({}, fadeConfigs[fadeType]);
+};
+exports.getFadeConfig = getFadeConfig;
 /**
  * Easing functions for smooth volume transitions
  */
 const easingFunctions = {
-    linear: (t) => t,
-    'ease-in': (t) => t * t,
-    'ease-out': (t) => t * (2 - t),
-    'ease-in-out': (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
+    [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)
 };
 /**
  * Smoothly transitions volume for a specific channel over time
@@ -37,7 +72,7 @@ const easingFunctions = {
  * await transitionVolume(0, 0.2, 500, 'ease-out'); // Duck to 20% over 500ms
  * ```
  */
-const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(void 0, [channelNumber_1, targetVolume_1, ...args_1], void 0, function* (channelNumber, targetVolume, duration = 250, easing = 'ease-out') {
+const transitionVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(void 0, [channelNumber_1, targetVolume_1, ...args_1], void 0, function* (channelNumber, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut) {
     const channel = info_1.audioChannels[channelNumber];
     if (!channel || channel.queue.length === 0)
         return;
@@ -46,7 +81,14 @@ 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);
+        if (transitionId) {
+            // Handle both requestAnimationFrame and setTimeout IDs
+            if (typeof cancelAnimationFrame !== 'undefined') {
+                cancelAnimationFrame(transitionId);
+            }
+            clearTimeout(transitionId);
+        }
         activeTransitions.delete(channelNumber);
     }
     // If no change needed, resolve immediately
@@ -69,7 +111,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;
@@ -154,8 +196,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;
 /**
@@ -170,7 +213,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;
 /**
@@ -262,11 +305,12 @@ exports.clearVolumeDucking = clearVolumeDucking;
 const applyVolumeDucking = (activeChannelNumber) => __awaiter(void 0, void 0, void 0, function* () {
     const transitionPromises = [];
     info_1.audioChannels.forEach((channel, channelNumber) => {
+        var _a, _b;
         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 || 'ease-out';
+                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;
                 // Priority channel is active, duck other channels
                 if (channelNumber === config.priorityChannel) {
                     transitionPromises.push((0, exports.transitionVolume)(channelNumber, config.priorityVolume, duration, easing));
@@ -281,6 +325,23 @@ const applyVolumeDucking = (activeChannelNumber) => __awaiter(void 0, void 0, vo
     yield Promise.all(transitionPromises);
 });
 exports.applyVolumeDucking = applyVolumeDucking;
+/**
+ * Fades the volume for a specific channel over time (alias for transitionVolume with improved naming)
+ * @param channelNumber - The channel number to fade
+ * @param targetVolume - Target volume level (0-1)
+ * @param duration - Fade duration in milliseconds (defaults to 250)
+ * @param easing - Easing function type (defaults to 'ease-out')
+ * @returns Promise that resolves when fade completes
+ * @example
+ * ```typescript
+ * await fadeVolume(0, 0, 800, 'ease-in'); // Fade out over 800ms
+ * await fadeVolume(0, 1, 600, 'ease-out'); // Fade in over 600ms
+ * ```
+ */
+const fadeVolume = (channelNumber_1, targetVolume_1, ...args_1) => __awaiter(void 0, [channelNumber_1, targetVolume_1, ...args_1], void 0, function* (channelNumber, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut) {
+    return (0, exports.transitionVolume)(channelNumber, targetVolume, duration, easing);
+});
+exports.fadeVolume = fadeVolume;
 /**
  * Restores normal volume levels when priority channel stops with smooth transitions
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -289,13 +350,14 @@ exports.applyVolumeDucking = applyVolumeDucking;
 const restoreVolumeLevels = (stoppedChannelNumber) => __awaiter(void 0, void 0, void 0, function* () {
     const transitionPromises = [];
     info_1.audioChannels.forEach((channel, channelNumber) => {
+        var _a, _b, _c;
         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 || 'ease-out';
+                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;
                 // Priority channel stopped, restore normal volumes
-                transitionPromises.push((0, exports.transitionVolume)(channelNumber, channel.volume || 1.0, duration, easing));
+                transitionPromises.push((0, exports.transitionVolume)(channelNumber, (_c = channel.volume) !== null && _c !== void 0 ? _c : 1.0, duration, easing));
             }
         }
     });