audio-channel-queue 1.7.0 → 1.8.0

package/dist/index.d.ts

@@ -5,9 +5,10 @@
  */
 export { queueAudio, queueAudioPriority, stopCurrentAudioInChannel, stopAllAudioInChannel, stopAllAudio, playAudioQueue } from './core';
 export { getErrorRecovery, getRetryConfig, offAudioError, onAudioError, retryFailedAudio, setErrorRecovery, setRetryConfig, } from './errors';
-export { getAllChannelsPauseState, isChannelPaused, pauseAllChannels, pauseChannel, resumeAllChannels, resumeChannel, togglePauseAllChannels, togglePauseChannel, } from './pause';
-export { clearVolumeDucking, getAllChannelsVolume, getChannelVolume, setAllChannelsVolume, setChannelVolume, setVolumeDucking, } from './volume';
+export { getAllChannelsPauseState, isChannelPaused, pauseAllChannels, pauseAllWithFade, pauseChannel, pauseWithFade, resumeAllChannels, resumeAllWithFade, resumeChannel, resumeWithFade, togglePauseAllChannels, togglePauseAllWithFade, togglePauseChannel, togglePauseWithFade, } from './pause';
+export { clearVolumeDucking, fadeVolume, getAllChannelsVolume, getChannelVolume, getFadeConfig, setAllChannelsVolume, setChannelVolume, setVolumeDucking, transitionVolume, } from './volume';
 export { getAllChannelsInfo, getCurrentAudioInfo, getQueueSnapshot, offAudioPause, offAudioProgress, offAudioResume, offQueueChange, onAudioComplete, onAudioPause, onAudioProgress, onAudioResume, onAudioStart, onQueueChange, } from './info';
 export { audioChannels } from './info';
 export { cleanWebpackFilename, createQueueSnapshot, extractFileName, getAudioInfoFromElement } from './utils';
-export type { AudioCompleteCallback, AudioCompleteInfo, AudioErrorCallback, AudioErrorInfo, AudioInfo, AudioPauseCallback, AudioQueueOptions, AudioResumeCallback, AudioStartCallback, AudioStartInfo, ErrorRecoveryOptions, ExtendedAudioQueueChannel, ProgressCallback, QueueChangeCallback, QueueItem, QueueSnapshot, RetryConfig, VolumeConfig } from './types';
+export type { AudioCompleteCallback, AudioCompleteInfo, AudioErrorCallback, AudioErrorInfo, AudioInfo, AudioPauseCallback, AudioQueueOptions, AudioResumeCallback, AudioStartCallback, AudioStartInfo, ChannelFadeState, ErrorRecoveryOptions, ExtendedAudioQueueChannel, FadeConfig, ProgressCallback, QueueChangeCallback, QueueItem, QueueSnapshot, RetryConfig, VolumeConfig } from './types';
+export { EasingType, FadeType } from './types';

package/dist/index.js

@@ -5,7 +5,8 @@
  * volume management with ducking, progress tracking, and comprehensive event system
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = exports.audioChannels = exports.onQueueChange = exports.onAudioStart = exports.onAudioResume = exports.onAudioProgress = exports.onAudioPause = exports.onAudioComplete = exports.offQueueChange = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.getQueueSnapshot = exports.getCurrentAudioInfo = exports.getAllChannelsInfo = exports.setVolumeDucking = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getChannelVolume = exports.getAllChannelsVolume = exports.clearVolumeDucking = exports.togglePauseChannel = exports.togglePauseAllChannels = exports.resumeChannel = exports.resumeAllChannels = exports.pauseChannel = exports.pauseAllChannels = exports.isChannelPaused = exports.getAllChannelsPauseState = exports.setRetryConfig = exports.setErrorRecovery = exports.retryFailedAudio = exports.onAudioError = exports.offAudioError = exports.getRetryConfig = exports.getErrorRecovery = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
+exports.audioChannels = exports.onQueueChange = exports.onAudioStart = exports.onAudioResume = exports.onAudioProgress = exports.onAudioPause = exports.onAudioComplete = exports.offQueueChange = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.getQueueSnapshot = exports.getCurrentAudioInfo = exports.getAllChannelsInfo = exports.transitionVolume = exports.setVolumeDucking = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getFadeConfig = exports.getChannelVolume = exports.getAllChannelsVolume = exports.fadeVolume = exports.clearVolumeDucking = exports.togglePauseWithFade = exports.togglePauseChannel = exports.togglePauseAllWithFade = exports.togglePauseAllChannels = exports.resumeWithFade = exports.resumeChannel = exports.resumeAllWithFade = exports.resumeAllChannels = exports.pauseWithFade = exports.pauseChannel = exports.pauseAllWithFade = exports.pauseAllChannels = exports.isChannelPaused = exports.getAllChannelsPauseState = exports.setRetryConfig = exports.setErrorRecovery = exports.retryFailedAudio = exports.onAudioError = exports.offAudioError = exports.getRetryConfig = exports.getErrorRecovery = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
+exports.FadeType = exports.EasingType = exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = void 0;
 // Core queue management functions
 var core_1 = require("./core");
 Object.defineProperty(exports, "queueAudio", { enumerable: true, get: function () { return core_1.queueAudio; } });
@@ -28,19 +29,28 @@ var pause_1 = require("./pause");
 Object.defineProperty(exports, "getAllChannelsPauseState", { enumerable: true, get: function () { return pause_1.getAllChannelsPauseState; } });
 Object.defineProperty(exports, "isChannelPaused", { enumerable: true, get: function () { return pause_1.isChannelPaused; } });
 Object.defineProperty(exports, "pauseAllChannels", { enumerable: true, get: function () { return pause_1.pauseAllChannels; } });
+Object.defineProperty(exports, "pauseAllWithFade", { enumerable: true, get: function () { return pause_1.pauseAllWithFade; } });
 Object.defineProperty(exports, "pauseChannel", { enumerable: true, get: function () { return pause_1.pauseChannel; } });
+Object.defineProperty(exports, "pauseWithFade", { enumerable: true, get: function () { return pause_1.pauseWithFade; } });
 Object.defineProperty(exports, "resumeAllChannels", { enumerable: true, get: function () { return pause_1.resumeAllChannels; } });
+Object.defineProperty(exports, "resumeAllWithFade", { enumerable: true, get: function () { return pause_1.resumeAllWithFade; } });
 Object.defineProperty(exports, "resumeChannel", { enumerable: true, get: function () { return pause_1.resumeChannel; } });
+Object.defineProperty(exports, "resumeWithFade", { enumerable: true, get: function () { return pause_1.resumeWithFade; } });
 Object.defineProperty(exports, "togglePauseAllChannels", { enumerable: true, get: function () { return pause_1.togglePauseAllChannels; } });
+Object.defineProperty(exports, "togglePauseAllWithFade", { enumerable: true, get: function () { return pause_1.togglePauseAllWithFade; } });
 Object.defineProperty(exports, "togglePauseChannel", { enumerable: true, get: function () { return pause_1.togglePauseChannel; } });
+Object.defineProperty(exports, "togglePauseWithFade", { enumerable: true, get: function () { return pause_1.togglePauseWithFade; } });
 // Volume control and ducking functions
 var volume_1 = require("./volume");
 Object.defineProperty(exports, "clearVolumeDucking", { enumerable: true, get: function () { return volume_1.clearVolumeDucking; } });
+Object.defineProperty(exports, "fadeVolume", { enumerable: true, get: function () { return volume_1.fadeVolume; } });
 Object.defineProperty(exports, "getAllChannelsVolume", { enumerable: true, get: function () { return volume_1.getAllChannelsVolume; } });
 Object.defineProperty(exports, "getChannelVolume", { enumerable: true, get: function () { return volume_1.getChannelVolume; } });
+Object.defineProperty(exports, "getFadeConfig", { enumerable: true, get: function () { return volume_1.getFadeConfig; } });
 Object.defineProperty(exports, "setAllChannelsVolume", { enumerable: true, get: function () { return volume_1.setAllChannelsVolume; } });
 Object.defineProperty(exports, "setChannelVolume", { enumerable: true, get: function () { return volume_1.setChannelVolume; } });
 Object.defineProperty(exports, "setVolumeDucking", { enumerable: true, get: function () { return volume_1.setVolumeDucking; } });
+Object.defineProperty(exports, "transitionVolume", { enumerable: true, get: function () { return volume_1.transitionVolume; } });
 // Audio information and progress tracking functions
 var info_1 = require("./info");
 Object.defineProperty(exports, "getAllChannelsInfo", { enumerable: true, get: function () { return info_1.getAllChannelsInfo; } });
@@ -65,3 +75,7 @@ Object.defineProperty(exports, "cleanWebpackFilename", { enumerable: true, get:
 Object.defineProperty(exports, "createQueueSnapshot", { enumerable: true, get: function () { return utils_1.createQueueSnapshot; } });
 Object.defineProperty(exports, "extractFileName", { enumerable: true, get: function () { return utils_1.extractFileName; } });
 Object.defineProperty(exports, "getAudioInfoFromElement", { enumerable: true, get: function () { return utils_1.getAudioInfoFromElement; } });
+// Enums
+var types_1 = require("./types");
+Object.defineProperty(exports, "EasingType", { enumerable: true, get: function () { return types_1.EasingType; } });
+Object.defineProperty(exports, "FadeType", { enumerable: true, get: function () { return types_1.FadeType; } });

package/dist/pause.d.ts

@@ -1,6 +1,77 @@
 /**
  * @fileoverview Pause and resume management functions for the audio-channel-queue package
  */
+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)
+ * @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
+ * ```
+ */
+export declare const pauseWithFade: (fadeType?: FadeType, channelNumber?: 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)
+ * @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
+ * ```
+ */
+export declare const resumeWithFade: (fadeType?: FadeType, channelNumber?: 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)
+ * @returns Promise that resolves when the toggle and fade are complete
+ * @example
+ * ```typescript
+ * await togglePauseWithFade(FadeType.Gentle, 0); // Toggle with gentle fade
+ * ```
+ */
+export declare const togglePauseWithFade: (fadeType?: FadeType, channelNumber?: 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
+ * @returns Promise that resolves when all channels are paused and faded
+ * @example
+ * ```typescript
+ * await pauseAllWithFade('dramatic'); // Pause everything with dramatic fade
+ * ```
+ */
+export declare const pauseAllWithFade: (fadeType?: FadeType) => 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
+ * @returns Promise that resolves when all channels are resumed and faded
+ * @example
+ * ```typescript
+ * await resumeAllWithFade(); // Resume everything with paired fade curves
+ * ```
+ */
+export declare const resumeAllWithFade: () => 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
+ * @returns Promise that resolves when all toggles and fades are complete
+ * @example
+ * ```typescript
+ * await togglePauseAllWithFade('gentle'); // Global toggle with gentle fade
+ * ```
+ */
+export declare const togglePauseAllWithFade: (fadeType?: FadeType) => 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

@@ -12,10 +12,213 @@ 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");
+/**
+ * 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) => {
+    const channel = info_1.audioChannels[channelNumber];
+    return (channel === null || channel === void 0 ? void 0 : channel.volume) || 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)
+ * @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
+ * ```
+ */
+const pauseWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle, channelNumber = 0) {
+    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 = FADE_CONFIGS[fadeType];
+    const originalVolume = getChannelVolumeSync(channelNumber);
+    // Store fade state for resumeWithFade to use
+    channel.fadeState = {
+        originalVolume,
+        fadeType,
+        isPaused: true
+    };
+    if (config.duration === 0) {
+        // Instant pause
+        yield (0, exports.pauseChannel)(channelNumber);
+        return;
+    }
+    // Fade to 0 with pause curve, then pause
+    yield (0, volume_1.transitionVolume)(channelNumber, 0, config.duration, config.pauseCurve);
+    yield (0, exports.pauseChannel)(channelNumber);
+    // Reset volume to original for resume (synchronously to avoid state issues)
+    setChannelVolumeSync(channelNumber, originalVolume);
+});
+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)
+ * @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
+ * ```
+ */
+const resumeWithFade = (fadeType_1, ...args_1) => __awaiter(void 0, [fadeType_1, ...args_1], void 0, function* (fadeType, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel || channel.queue.length === 0)
+        return;
+    const fadeState = channel.fadeState;
+    if (!fadeState || !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) {
+        // Instant resume
+        yield (0, exports.resumeChannel)(channelNumber);
+        fadeState.isPaused = false;
+        return;
+    }
+    // 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);
+    fadeState.isPaused = 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)
+ * @returns Promise that resolves when the toggle and fade are complete
+ * @example
+ * ```typescript
+ * await togglePauseWithFade(FadeType.Gentle, 0); // Toggle with gentle fade
+ * ```
+ */
+const togglePauseWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle, channelNumber = 0) {
+    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);
+    }
+    else {
+        yield (0, exports.pauseWithFade)(fadeType, channelNumber);
+    }
+});
+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
+ * @returns Promise that resolves when all channels are paused and faded
+ * @example
+ * ```typescript
+ * await pauseAllWithFade('dramatic'); // Pause everything with dramatic fade
+ * ```
+ */
+const pauseAllWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle) {
+    const pausePromises = [];
+    info_1.audioChannels.forEach((_channel, index) => {
+        pausePromises.push((0, exports.pauseWithFade)(fadeType, index));
+    });
+    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
+ * @returns Promise that resolves when all channels are resumed and faded
+ * @example
+ * ```typescript
+ * await resumeAllWithFade(); // Resume everything with paired fade curves
+ * ```
+ */
+const resumeAllWithFade = () => __awaiter(void 0, void 0, void 0, function* () {
+    const resumePromises = [];
+    info_1.audioChannels.forEach((_channel, index) => {
+        resumePromises.push((0, exports.resumeWithFade)(undefined, index));
+    });
+    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
+ * @returns Promise that resolves when all toggles and fades are complete
+ * @example
+ * ```typescript
+ * await togglePauseAllWithFade('gentle'); // Global toggle with gentle fade
+ * ```
+ */
+const togglePauseAllWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (fadeType = types_1.FadeType.Gentle) {
+    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);
+    }
+    else {
+        yield (0, exports.resumeAllWithFade)();
+    }
+});
+exports.togglePauseAllWithFade = togglePauseAllWithFade;
 /**
  * Pauses the currently playing audio in a specific channel
  * @param channelNumber - The channel number to pause (defaults to 0)

package/dist/types.d.ts

@@ -26,7 +26,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,6 +206,7 @@ export interface ExtendedAudioQueueChannel {
     audioPauseCallbacks: Set<AudioPauseCallback>;
     audioResumeCallbacks: Set<AudioResumeCallback>;
     audioStartCallbacks: Set<AudioStartCallback>;
+    fadeState?: ChannelFadeState;
     isPaused?: boolean;
     progressCallbacks: Map<HTMLAudioElement | null, Set<ProgressCallback>>;
     queue: HTMLAudioElement[];
@@ -214,3 +215,42 @@ export interface ExtendedAudioQueueChannel {
     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;
+}

package/dist/types.js

@@ -3,3 +3,23 @@
  * @fileoverview Type definitions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FadeType = exports.EasingType = void 0;
+/**
+ * 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/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,41 @@ 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 FADE_CONFIGS = {
+    [types_1.FadeType.Dramatic]: { duration: 800, pauseCurve: types_1.EasingType.EaseIn, resumeCurve: types_1.EasingType.EaseOut },
+    [types_1.FadeType.Gentle]: { duration: 800, pauseCurve: types_1.EasingType.EaseOut, resumeCurve: types_1.EasingType.EaseIn },
+    [types_1.FadeType.Linear]: { duration: 800, pauseCurve: types_1.EasingType.Linear, resumeCurve: types_1.EasingType.Linear }
+};
+/**
+ * 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({}, FADE_CONFIGS[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 +60,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;
@@ -266,7 +289,7 @@ const applyVolumeDucking = (activeChannelNumber) => __awaiter(void 0, void 0, vo
             const config = channel.volumeConfig;
             if (activeChannelNumber === config.priorityChannel) {
                 const duration = config.duckTransitionDuration || 250;
-                const easing = config.transitionEasing || 'ease-out';
+                const easing = config.transitionEasing || types_1.EasingType.EaseOut;
                 // Priority channel is active, duck other channels
                 if (channelNumber === config.priorityChannel) {
                     transitionPromises.push((0, exports.transitionVolume)(channelNumber, config.priorityVolume, duration, easing));
@@ -281,6 +304,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
@@ -293,7 +333,7 @@ const restoreVolumeLevels = (stoppedChannelNumber) => __awaiter(void 0, void 0,
             const config = channel.volumeConfig;
             if (stoppedChannelNumber === config.priorityChannel) {
                 const duration = config.restoreTransitionDuration || 500;
-                const easing = config.transitionEasing || 'ease-out';
+                const easing = config.transitionEasing || types_1.EasingType.EaseOut;
                 // Priority channel stopped, restore normal volumes
                 transitionPromises.push((0, exports.transitionVolume)(channelNumber, channel.volume || 1.0, duration, easing));
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-channel-queue",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Allows you to queue audio files to different playback channels.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -23,21 +23,30 @@ export {
   getAllChannelsPauseState, 
   isChannelPaused, 
   pauseAllChannels, 
+  pauseAllWithFade,
   pauseChannel, 
+  pauseWithFade,
   resumeAllChannels, 
+  resumeAllWithFade,
   resumeChannel, 
+  resumeWithFade,
   togglePauseAllChannels,
-  togglePauseChannel, 
+  togglePauseAllWithFade,
+  togglePauseChannel,
+  togglePauseWithFade,
 } from './pause';
 
 // Volume control and ducking functions
 export { 
   clearVolumeDucking,
+  fadeVolume,
   getAllChannelsVolume, 
   getChannelVolume, 
+  getFadeConfig,
   setAllChannelsVolume, 
   setChannelVolume, 
-  setVolumeDucking, 
+  setVolumeDucking,
+  transitionVolume,
 } from './volume';
 
 // Audio information and progress tracking functions
@@ -80,12 +89,20 @@ export type {
   AudioResumeCallback,
   AudioStartCallback,
   AudioStartInfo,
+  ChannelFadeState,
   ErrorRecoveryOptions,
   ExtendedAudioQueueChannel,
+  FadeConfig,
   ProgressCallback,
   QueueChangeCallback,
   QueueItem,
   QueueSnapshot,
   RetryConfig,
   VolumeConfig 
+} from './types';
+
+// Enums
+export { 
+  EasingType,
+  FadeType 
 } from './types'; 

package/src/pause.ts

@@ -2,10 +2,232 @@
  * @fileoverview Pause and resume management functions for the audio-channel-queue package
  */
 
-import { ExtendedAudioQueueChannel, AudioInfo } from './types';
+import { ExtendedAudioQueueChannel, AudioInfo, FadeType, FadeConfig, ChannelFadeState, EasingType } from './types';
 import { audioChannels } from './info';
 import { getAudioInfoFromElement } from './utils';
 import { emitAudioPause, emitAudioResume } from './events';
+import { transitionVolume } from './volume';
+
+/**
+ * Predefined fade configurations for different transition types
+ */
+const FADE_CONFIGS: Record<FadeType, FadeConfig> = {
+  [FadeType.Linear]: { duration: 800, pauseCurve: EasingType.Linear, resumeCurve: EasingType.Linear },
+  [FadeType.Gentle]: { duration: 800, pauseCurve: EasingType.EaseOut, resumeCurve: EasingType.EaseIn },
+  [FadeType.Dramatic]: { duration: 800, pauseCurve: EasingType.EaseIn, resumeCurve: 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: number): number => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  return channel?.volume || 1.0;
+};
+
+/**
+ * Sets the channel volume synchronously in internal state
+ * @param channelNumber - The channel number
+ * @param volume - Volume level (0-1)
+ */
+const setChannelVolumeSync = (channelNumber: number, volume: number): void => {
+  const channel: ExtendedAudioQueueChannel = 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)
+ * @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
+ * ```
+ */
+export const pauseWithFade = async (fadeType: FadeType = FadeType.Gentle, channelNumber: number = 0): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  
+  if (!channel || channel.queue.length === 0) return;
+  
+  const currentAudio: HTMLAudioElement = channel.queue[0];
+  
+  // Don't pause if already paused or ended
+  if (currentAudio.paused || currentAudio.ended) return;
+  
+  const config: FadeConfig = FADE_CONFIGS[fadeType];
+  const originalVolume: number = getChannelVolumeSync(channelNumber);
+  
+  // Store fade state for resumeWithFade to use
+  channel.fadeState = {
+    originalVolume,
+    fadeType,
+    isPaused: true
+  };
+  
+  if (config.duration === 0) {
+    // Instant pause
+    await pauseChannel(channelNumber);
+    return;
+  }
+  
+  // Fade to 0 with pause curve, then pause
+  await transitionVolume(channelNumber, 0, config.duration, config.pauseCurve);
+  await pauseChannel(channelNumber);
+  
+  // Reset volume to original for resume (synchronously to avoid state issues)
+  setChannelVolumeSync(channelNumber, originalVolume);
+};
+
+/**
+ * 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)
+ * @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
+ * ```
+ */
+export const resumeWithFade = async (fadeType?: FadeType, channelNumber: number = 0): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  
+  if (!channel || channel.queue.length === 0) return;
+  
+  const fadeState: ChannelFadeState | undefined = channel.fadeState;
+  if (!fadeState || !fadeState.isPaused) {
+    // Fall back to regular resume if no fade state
+    await resumeChannel(channelNumber);
+    return;
+  }
+  
+  // Use provided fadeType or fall back to stored fadeType from pause
+  const effectiveFadeType: FadeType = fadeType || fadeState.fadeType;
+  const config: FadeConfig = FADE_CONFIGS[effectiveFadeType];
+  
+  if (config.duration === 0) {
+    // Instant resume
+    await resumeChannel(channelNumber);
+    fadeState.isPaused = false;
+    return;
+  }
+  
+  // Set volume to 0, resume, then fade to original with resume curve
+  setChannelVolumeSync(channelNumber, 0);
+  await resumeChannel(channelNumber);
+  await transitionVolume(channelNumber, fadeState.originalVolume, config.duration, config.resumeCurve);
+  
+  fadeState.isPaused = false;
+};
+
+/**
+ * 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)
+ * @returns Promise that resolves when the toggle and fade are complete
+ * @example
+ * ```typescript
+ * await togglePauseWithFade(FadeType.Gentle, 0); // Toggle with gentle fade
+ * ```
+ */
+export const togglePauseWithFade = async (fadeType: FadeType = FadeType.Gentle, channelNumber: number = 0): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  
+  if (!channel || channel.queue.length === 0) return;
+  
+  const currentAudio: HTMLAudioElement = channel.queue[0];
+  
+  if (currentAudio.paused) {
+    await resumeWithFade(undefined, channelNumber);
+  } else {
+    await pauseWithFade(fadeType, channelNumber);
+  }
+};
+
+/**
+ * Pauses all currently playing audio across all channels with smooth volume fade
+ * @param fadeType - Type of fade transition to apply to all channels
+ * @returns Promise that resolves when all channels are paused and faded
+ * @example
+ * ```typescript
+ * await pauseAllWithFade('dramatic'); // Pause everything with dramatic fade
+ * ```
+ */
+export const pauseAllWithFade = async (fadeType: FadeType = FadeType.Gentle): Promise<void> => {
+  const pausePromises: Promise<void>[] = [];
+  
+  audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
+    pausePromises.push(pauseWithFade(fadeType, index));
+  });
+  
+  await Promise.all(pausePromises);
+};
+
+/**
+ * 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
+ * @returns Promise that resolves when all channels are resumed and faded
+ * @example
+ * ```typescript
+ * await resumeAllWithFade(); // Resume everything with paired fade curves
+ * ```
+ */
+export const resumeAllWithFade = async (): Promise<void> => {
+  const resumePromises: Promise<void>[] = [];
+  
+  audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
+    resumePromises.push(resumeWithFade(undefined, index));
+  });
+  
+  await Promise.all(resumePromises);
+};
+
+/**
+ * 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
+ * @returns Promise that resolves when all toggles and fades are complete
+ * @example
+ * ```typescript
+ * await togglePauseAllWithFade('gentle'); // Global toggle with gentle fade
+ * ```
+ */
+export const togglePauseAllWithFade = async (fadeType: FadeType = FadeType.Gentle): Promise<void> => {
+  let hasPlayingChannel: boolean = false;
+  
+  // Check if any channel is currently playing
+  for (let i = 0; i < audioChannels.length; i++) {
+    const channel: ExtendedAudioQueueChannel = audioChannels[i];
+    if (channel && channel.queue.length > 0) {
+      const currentAudio: HTMLAudioElement = 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) {
+    await pauseAllWithFade(fadeType);
+  } else {
+    await resumeAllWithFade();
+  }
+};
 
 /**
  * Pauses the currently playing audio in a specific channel

package/src/types.ts

@@ -29,7 +29,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;
 }
 
 /**
@@ -226,6 +226,7 @@ export interface ExtendedAudioQueueChannel {
   audioPauseCallbacks: Set<AudioPauseCallback>;
   audioResumeCallbacks: Set<AudioResumeCallback>;
   audioStartCallbacks: Set<AudioStartCallback>;
+  fadeState?: ChannelFadeState;
   isPaused?: boolean;
   progressCallbacks: Map<HTMLAudioElement | null, Set<ProgressCallback>>;
   queue: HTMLAudioElement[];
@@ -233,4 +234,47 @@ export interface ExtendedAudioQueueChannel {
   retryConfig?: RetryConfig;
   volume?: number;
   volumeConfig?: VolumeConfig;
+}
+
+/**
+ * Easing function types for volume transitions
+ */
+export 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 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;
 } 

package/src/volume.ts

@@ -2,20 +2,43 @@
  * @fileoverview Volume management functions for the audio-channel-queue package
  */
 
-import { ExtendedAudioQueueChannel, VolumeConfig } from './types';
+import { ExtendedAudioQueueChannel, VolumeConfig, FadeType, FadeConfig, EasingType } from './types';
 import { audioChannels } from './info';
 
 // Store active volume transitions to handle interruptions
 const activeTransitions = new Map<number, number>();
 
+/**
+ * Predefined fade configurations for different transition types
+ */
+const FADE_CONFIGS: Record<FadeType, FadeConfig> = {
+  [FadeType.Dramatic]: { duration: 800, pauseCurve: EasingType.EaseIn, resumeCurve: EasingType.EaseOut },
+  [FadeType.Gentle]: { duration: 800, pauseCurve: EasingType.EaseOut, resumeCurve: EasingType.EaseIn },
+  [FadeType.Linear]: { duration: 800, pauseCurve: EasingType.Linear, resumeCurve: 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`);
+ * ```
+ */
+export const getFadeConfig = (fadeType: FadeType): FadeConfig => {
+  return { ...FADE_CONFIGS[fadeType] };
+};
+
 /**
  * Easing functions for smooth volume transitions
  */
-const easingFunctions = {
-  linear: (t: number): number => t,
-  'ease-in': (t: number): number => t * t,
-  'ease-out': (t: number): number => t * (2 - t),
-  'ease-in-out': (t: number): number => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
+const easingFunctions: Record<EasingType, (t: number) => number> = {
+  [EasingType.Linear]: (t: number): number => t,
+  [EasingType.EaseIn]: (t: number): number => t * t,
+  [EasingType.EaseOut]: (t: number): number => t * (2 - t),
+  [EasingType.EaseInOut]: (t: number): number => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
 };
 
 /**
@@ -34,7 +57,7 @@ export const transitionVolume = async (
   channelNumber: number,
   targetVolume: number,
   duration: number = 250,
-  easing: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' = 'ease-out'
+  easing: EasingType = EasingType.EaseOut
 ): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel || channel.queue.length === 0) return;
@@ -119,7 +142,7 @@ export const setChannelVolume = async (
   channelNumber: number, 
   volume: number,
   transitionDuration?: number,
-  easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out'
+  easing?: EasingType
 ): Promise<void> => {
   const clampedVolume: number = Math.max(0, Math.min(1, volume));
   
@@ -282,7 +305,7 @@ export const applyVolumeDucking = async (activeChannelNumber: number): Promise<v
       
       if (activeChannelNumber === config.priorityChannel) {
         const duration = config.duckTransitionDuration || 250;
-        const easing = config.transitionEasing || 'ease-out';
+        const easing = config.transitionEasing || EasingType.EaseOut;
         
         // Priority channel is active, duck other channels
         if (channelNumber === config.priorityChannel) {
@@ -298,10 +321,32 @@ export const applyVolumeDucking = async (activeChannelNumber: number): Promise<v
     }
   });
 
-  // Wait for all transitions to complete
+    // Wait for all transitions to complete
   await Promise.all(transitionPromises);
 };
 
+/**
+ * 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 const fadeVolume = async (
+  channelNumber: number,
+  targetVolume: number,
+  duration: number = 250,
+  easing: EasingType = EasingType.EaseOut
+): Promise<void> => {
+  return transitionVolume(channelNumber, targetVolume, duration, easing);
+}; 
+
 /**
  * Restores normal volume levels when priority channel stops with smooth transitions
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -316,7 +361,7 @@ export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise
       
       if (stoppedChannelNumber === config.priorityChannel) {
         const duration = config.restoreTransitionDuration || 500;
-        const easing = config.transitionEasing || 'ease-out';
+        const easing = config.transitionEasing || EasingType.EaseOut;
         
         // Priority channel stopped, restore normal volumes
         transitionPromises.push(