audio-channel-queue 1.9.0 → 1.11.0

package/dist/index.d.ts

@@ -3,12 +3,13 @@
  * Exports all public functions and types for audio queue management, pause/resume controls,
  * volume management with ducking, progress tracking, and comprehensive event system
  */
-export { queueAudio, queueAudioPriority, stopCurrentAudioInChannel, stopAllAudioInChannel, stopAllAudio, playAudioQueue } from './core';
+export { queueAudio, queueAudioPriority, stopCurrentAudioInChannel, stopAllAudioInChannel, stopAllAudio, playAudioQueue, destroyChannel, destroyAllChannels, setQueueConfig, getQueueConfig, setChannelQueueLimit } from './core';
+export { clearQueueAfterCurrent, getQueueItemInfo, getQueueLength, removeQueuedItem, reorderQueue, swapQueueItems } from './queue-manipulation';
 export { getErrorRecovery, getRetryConfig, offAudioError, onAudioError, retryFailedAudio, setErrorRecovery, setRetryConfig } from './errors';
 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 { clearVolumeDucking, fadeVolume, getAllChannelsVolume, getChannelVolume, getFadeConfig, setAllChannelsVolume, setChannelVolume, setVolumeDucking, transitionVolume, cancelVolumeTransition, cancelAllVolumeTransitions } from './volume';
+export { getAllChannelsInfo, getCurrentAudioInfo, getQueueSnapshot, offAudioComplete, offAudioPause, offAudioProgress, offAudioResume, offAudioStart, 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, ChannelFadeState, ErrorRecoveryOptions, ExtendedAudioQueueChannel, FadeConfig, ProgressCallback, QueueChangeCallback, QueueItem, QueueSnapshot, RetryConfig, VolumeConfig } from './types';
-export { EasingType, FadeType, GLOBAL_PROGRESS_KEY } from './types';
+export { cleanWebpackFilename, createQueueSnapshot, extractFileName, getAudioInfoFromElement, sanitizeForDisplay, validateAudioUrl } from './utils';
+export type { AudioCompleteCallback, AudioCompleteInfo, AudioErrorCallback, AudioErrorInfo, AudioInfo, AudioPauseCallback, AudioQueueOptions, AudioResumeCallback, AudioStartCallback, AudioStartInfo, ChannelFadeState, ErrorRecoveryOptions, ExtendedAudioQueueChannel, FadeConfig, ProgressCallback, QueueChangeCallback, QueueItem, QueueManipulationResult, QueueSnapshot, RetryConfig, VolumeConfig, QueueConfig } from './types';
+export { EasingType, FadeType, MAX_CHANNELS, TimerType, GLOBAL_PROGRESS_KEY } from './types';

package/dist/index.js

@@ -5,8 +5,8 @@
  * volume management with ducking, progress tracking, and comprehensive event system
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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.GLOBAL_PROGRESS_KEY = exports.FadeType = exports.EasingType = exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = void 0;
+exports.getAllChannelsInfo = exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = 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.swapQueueItems = exports.reorderQueue = exports.removeQueuedItem = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.setChannelQueueLimit = exports.getQueueConfig = exports.setQueueConfig = exports.destroyAllChannels = exports.destroyChannel = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
+exports.GLOBAL_PROGRESS_KEY = exports.TimerType = exports.MAX_CHANNELS = exports.FadeType = exports.EasingType = exports.validateAudioUrl = exports.sanitizeForDisplay = 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.offAudioStart = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.offAudioComplete = exports.getQueueSnapshot = exports.getCurrentAudioInfo = void 0;
 // Core queue management functions
 var core_1 = require("./core");
 Object.defineProperty(exports, "queueAudio", { enumerable: true, get: function () { return core_1.queueAudio; } });
@@ -15,6 +15,19 @@ Object.defineProperty(exports, "stopCurrentAudioInChannel", { enumerable: true,
 Object.defineProperty(exports, "stopAllAudioInChannel", { enumerable: true, get: function () { return core_1.stopAllAudioInChannel; } });
 Object.defineProperty(exports, "stopAllAudio", { enumerable: true, get: function () { return core_1.stopAllAudio; } });
 Object.defineProperty(exports, "playAudioQueue", { enumerable: true, get: function () { return core_1.playAudioQueue; } });
+Object.defineProperty(exports, "destroyChannel", { enumerable: true, get: function () { return core_1.destroyChannel; } });
+Object.defineProperty(exports, "destroyAllChannels", { enumerable: true, get: function () { return core_1.destroyAllChannels; } });
+Object.defineProperty(exports, "setQueueConfig", { enumerable: true, get: function () { return core_1.setQueueConfig; } });
+Object.defineProperty(exports, "getQueueConfig", { enumerable: true, get: function () { return core_1.getQueueConfig; } });
+Object.defineProperty(exports, "setChannelQueueLimit", { enumerable: true, get: function () { return core_1.setChannelQueueLimit; } });
+// Queue manipulation functions
+var queue_manipulation_1 = require("./queue-manipulation");
+Object.defineProperty(exports, "clearQueueAfterCurrent", { enumerable: true, get: function () { return queue_manipulation_1.clearQueueAfterCurrent; } });
+Object.defineProperty(exports, "getQueueItemInfo", { enumerable: true, get: function () { return queue_manipulation_1.getQueueItemInfo; } });
+Object.defineProperty(exports, "getQueueLength", { enumerable: true, get: function () { return queue_manipulation_1.getQueueLength; } });
+Object.defineProperty(exports, "removeQueuedItem", { enumerable: true, get: function () { return queue_manipulation_1.removeQueuedItem; } });
+Object.defineProperty(exports, "reorderQueue", { enumerable: true, get: function () { return queue_manipulation_1.reorderQueue; } });
+Object.defineProperty(exports, "swapQueueItems", { enumerable: true, get: function () { return queue_manipulation_1.swapQueueItems; } });
 // Error handling and recovery functions
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "getErrorRecovery", { enumerable: true, get: function () { return errors_1.getErrorRecovery; } });
@@ -51,14 +64,18 @@ Object.defineProperty(exports, "setAllChannelsVolume", { enumerable: true, get:
 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; } });
+Object.defineProperty(exports, "cancelVolumeTransition", { enumerable: true, get: function () { return volume_1.cancelVolumeTransition; } });
+Object.defineProperty(exports, "cancelAllVolumeTransitions", { enumerable: true, get: function () { return volume_1.cancelAllVolumeTransitions; } });
 // Audio information and progress tracking functions
 var info_1 = require("./info");
 Object.defineProperty(exports, "getAllChannelsInfo", { enumerable: true, get: function () { return info_1.getAllChannelsInfo; } });
 Object.defineProperty(exports, "getCurrentAudioInfo", { enumerable: true, get: function () { return info_1.getCurrentAudioInfo; } });
 Object.defineProperty(exports, "getQueueSnapshot", { enumerable: true, get: function () { return info_1.getQueueSnapshot; } });
+Object.defineProperty(exports, "offAudioComplete", { enumerable: true, get: function () { return info_1.offAudioComplete; } });
 Object.defineProperty(exports, "offAudioPause", { enumerable: true, get: function () { return info_1.offAudioPause; } });
 Object.defineProperty(exports, "offAudioProgress", { enumerable: true, get: function () { return info_1.offAudioProgress; } });
 Object.defineProperty(exports, "offAudioResume", { enumerable: true, get: function () { return info_1.offAudioResume; } });
+Object.defineProperty(exports, "offAudioStart", { enumerable: true, get: function () { return info_1.offAudioStart; } });
 Object.defineProperty(exports, "offQueueChange", { enumerable: true, get: function () { return info_1.offQueueChange; } });
 Object.defineProperty(exports, "onAudioComplete", { enumerable: true, get: function () { return info_1.onAudioComplete; } });
 Object.defineProperty(exports, "onAudioPause", { enumerable: true, get: function () { return info_1.onAudioPause; } });
@@ -75,8 +92,12 @@ 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; } });
+Object.defineProperty(exports, "sanitizeForDisplay", { enumerable: true, get: function () { return utils_1.sanitizeForDisplay; } });
+Object.defineProperty(exports, "validateAudioUrl", { enumerable: true, get: function () { return utils_1.validateAudioUrl; } });
 // Enums and constants
 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; } });
+Object.defineProperty(exports, "MAX_CHANNELS", { enumerable: true, get: function () { return types_1.MAX_CHANNELS; } });
+Object.defineProperty(exports, "TimerType", { enumerable: true, get: function () { return types_1.TimerType; } });
 Object.defineProperty(exports, "GLOBAL_PROGRESS_KEY", { enumerable: true, get: function () { return types_1.GLOBAL_PROGRESS_KEY; } });

package/dist/info.d.ts

@@ -2,9 +2,35 @@
  * @fileoverview Audio information and progress tracking functions for the audio-channel-queue package
  */
 import { AudioInfo, QueueSnapshot, ProgressCallback, QueueChangeCallback, AudioStartCallback, AudioCompleteCallback, AudioPauseCallback, AudioResumeCallback, ExtendedAudioQueueChannel } from './types';
+/**
+ * Gets the current list of whitelisted channel properties
+ * This is automatically derived from the ExtendedAudioQueueChannel interface
+ * @returns Array of whitelisted property names
+ * @internal
+ */
+export declare const getWhitelistedChannelProperties: () => string[];
+/**
+ * Returns the list of non-whitelisted properties found on a specific channel
+ * These are properties that will trigger warnings when modified directly
+ * @param channelNumber - The channel number to inspect (defaults to 0)
+ * @returns Array of property names that are not in the whitelist, or empty array if channel doesn't exist
+ * @example
+ * ```typescript
+ * // Add some custom property to a channel
+ * (audioChannels[0] as any).customProperty = 'test';
+ *
+ * const nonWhitelisted = getNonWhitelistedChannelProperties(0);
+ * console.log(nonWhitelisted); // ['customProperty']
+ * ```
+ * @internal
+ */
+export declare const getNonWhitelistedChannelProperties: (channelNumber?: number) => string[];
 /**
  * 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.
  */
 export declare const audioChannels: ExtendedAudioQueueChannel[];
 /**
@@ -37,22 +63,24 @@ export declare const getCurrentAudioInfo: (channelNumber?: number) => AudioInfo
 export declare const getAllChannelsInfo: () => (AudioInfo | null)[];
 /**
  * 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);
  * ```
  */
-export declare const getQueueSnapshot: (channelNumber: number) => QueueSnapshot | null;
+export declare const getQueueSnapshot: (channelNumber?: number) => QueueSnapshot | null;
 /**
  * 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) => {
@@ -64,17 +92,19 @@ export declare const getQueueSnapshot: (channelNumber: number) => QueueSnapshot
 export declare const onAudioProgress: (channelNumber: number, callback: ProgressCallback) => void;
 /**
  * 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
  * ```
  */
-export declare const offAudioProgress: (channelNumber: number) => void;
+export declare function offAudioProgress(channelNumber?: number): void;
 /**
  * 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) => {
@@ -97,6 +127,7 @@ export declare const offQueueChange: (channelNumber: number) => void;
  * 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) => {
@@ -110,6 +141,7 @@ export declare const onAudioStart: (channelNumber: number, callback: AudioStartC
  * 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) => {
@@ -125,6 +157,7 @@ export declare const onAudioComplete: (channelNumber: number, callback: AudioCom
  * 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) => {
@@ -138,6 +171,7 @@ export declare const onAudioPause: (channelNumber: number, callback: AudioPauseC
  * 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) => {
@@ -165,3 +199,21 @@ export declare const offAudioPause: (channelNumber: number) => void;
  * ```
  */
 export declare const offAudioResume: (channelNumber: number) => void;
+/**
+ * Removes audio start event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * ```
+ */
+export declare const offAudioStart: (channelNumber: number) => void;
+/**
+ * Removes audio complete event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * ```
+ */
+export declare const offAudioComplete: (channelNumber: number) => void;

package/dist/info.js

@@ -3,15 +3,134 @@
  * @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.offAudioComplete = exports.offAudioStart = 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 = exports.getNonWhitelistedChannelProperties = exports.getWhitelistedChannelProperties = void 0;
+exports.offAudioProgress = offAudioProgress;
 const types_1 = require("./types");
 const utils_1 = require("./utils");
 const events_1 = require("./events");
+/**
+ * Gets the current list of whitelisted channel properties
+ * This is automatically derived from the ExtendedAudioQueueChannel interface
+ * @returns Array of whitelisted property names
+ * @internal
+ */
+const getWhitelistedChannelProperties = () => {
+    // Create a sample channel object to extract property names
+    const sampleChannel = {
+        audioCompleteCallbacks: new Set(),
+        audioErrorCallbacks: new Set(),
+        audioPauseCallbacks: new Set(),
+        audioResumeCallbacks: new Set(),
+        audioStartCallbacks: new Set(),
+        isPaused: false,
+        progressCallbacks: new Map(),
+        queue: [],
+        queueChangeCallbacks: new Set(),
+        volume: 1.0
+    };
+    // Get all property names from the interface (including optional ones)
+    const propertyNames = [
+        ...Object.getOwnPropertyNames(sampleChannel),
+        // Add optional properties that might not be present on the sample
+        'fadeState',
+        'isLocked',
+        'maxQueueSize',
+        'retryConfig',
+        'volumeConfig' // Legacy property that might still be used
+    ];
+    return [...new Set(propertyNames)]; // Remove duplicates
+};
+exports.getWhitelistedChannelProperties = getWhitelistedChannelProperties;
+/**
+ * Returns the list of non-whitelisted properties found on a specific channel
+ * These are properties that will trigger warnings when modified directly
+ * @param channelNumber - The channel number to inspect (defaults to 0)
+ * @returns Array of property names that are not in the whitelist, or empty array if channel doesn't exist
+ * @example
+ * ```typescript
+ * // Add some custom property to a channel
+ * (audioChannels[0] as any).customProperty = 'test';
+ *
+ * const nonWhitelisted = getNonWhitelistedChannelProperties(0);
+ * console.log(nonWhitelisted); // ['customProperty']
+ * ```
+ * @internal
+ */
+const getNonWhitelistedChannelProperties = (channelNumber = 0) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!channel) {
+        return [];
+    }
+    const whitelistedProperties = (0, exports.getWhitelistedChannelProperties)();
+    const allChannelProperties = Object.getOwnPropertyNames(channel);
+    // Filter out properties that are in the whitelist
+    const nonWhitelistedProperties = allChannelProperties.filter((property) => !whitelistedProperties.includes(property));
+    return nonWhitelistedProperties;
+};
+exports.getNonWhitelistedChannelProperties = getNonWhitelistedChannelProperties;
 /**
  * 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
+                    // Use the automatically-derived whitelist from the interface
+                    const whitelistedProperties = (0, exports.getWhitelistedChannelProperties)();
+                    if (typeof channelProp === 'string' && !whitelistedProperties.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)
@@ -57,18 +176,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;
@@ -76,6 +196,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) => {
@@ -85,6 +206,7 @@ exports.getQueueSnapshot = getQueueSnapshot;
  * ```
  */
 const onAudioProgress = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -122,13 +244,14 @@ const onAudioProgress = (channelNumber, 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 === null || channel === void 0 ? void 0 : channel.progressCallbacks))
         return;
@@ -139,12 +262,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) => {
@@ -154,6 +277,7 @@ exports.offAudioProgress = offAudioProgress;
  * ```
  */
 const onQueueChange = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -194,6 +318,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) => {
@@ -203,6 +328,7 @@ exports.offQueueChange = offQueueChange;
  * ```
  */
 const onAudioStart = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -228,6 +354,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) => {
@@ -239,6 +366,7 @@ exports.onAudioStart = onAudioStart;
  * ```
  */
 const onAudioComplete = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -264,6 +392,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) => {
@@ -273,6 +402,7 @@ exports.onAudioComplete = onAudioComplete;
  * ```
  */
 const onAudioPause = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -298,6 +428,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) => {
@@ -307,6 +438,7 @@ exports.onAudioPause = onAudioPause;
  * ```
  */
 const onAudioResume = (channelNumber, callback) => {
+    validateChannelNumber(channelNumber);
     if (!exports.audioChannels[channelNumber]) {
         exports.audioChannels[channelNumber] = {
             audioCompleteCallbacks: new Set(),
@@ -358,3 +490,33 @@ const offAudioResume = (channelNumber) => {
     channel.audioResumeCallbacks.clear();
 };
 exports.offAudioResume = offAudioResume;
+/**
+ * Removes audio start event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * ```
+ */
+const offAudioStart = (channelNumber) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!(channel === null || channel === void 0 ? void 0 : channel.audioStartCallbacks))
+        return;
+    channel.audioStartCallbacks.clear();
+};
+exports.offAudioStart = offAudioStart;
+/**
+ * Removes audio complete event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * ```
+ */
+const offAudioComplete = (channelNumber) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!(channel === null || channel === void 0 ? void 0 : channel.audioCompleteCallbacks))
+        return;
+    channel.audioCompleteCallbacks.clear();
+};
+exports.offAudioComplete = offAudioComplete;

package/dist/pause.js

@@ -77,7 +77,7 @@ const pauseWithFade = (...args_1) => __awaiter(void 0, [...args_1], void 0, func
         // 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;
+        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 = {

package/dist/queue-manipulation.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Queue manipulation functions for the audio-channel-queue package
+ * Provides advanced queue management including item removal, reordering, and clearing
+ */
+import { QueueManipulationResult, QueueItem } from './types';
+/**
+ * Removes a specific item from the queue by its slot number (0-based index)
+ * Cannot remove the currently playing item (index 0) - use stopCurrentAudioInChannel instead
+ * @param queuedSlotNumber - Zero-based index of the item to remove (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to remove currently playing item or invalid slot number
+ * @example
+ * ```typescript
+ * // Remove the second item in queue (index 1)
+ * const result = await removeQueuedItem(1, 0);
+ * if (result.success) {
+ *   console.log(`Removed item, queue now has ${result.updatedQueue.totalItems} items`);
+ * }
+ *
+ * // Remove the third item from channel 1
+ * await removeQueuedItem(2, 1);
+ * ```
+ */
+export declare const removeQueuedItem: (queuedSlotNumber: number, channelNumber?: number) => Promise<QueueManipulationResult>;
+/**
+ * Reorders a queue item by moving it from one position to another
+ * Cannot reorder the currently playing item (index 0)
+ * @param currentQueuedSlotNumber - Current zero-based index of the item to move (must be > 0)
+ * @param newQueuedSlotNumber - New zero-based index where the item should be placed (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to reorder currently playing item or invalid slot numbers
+ * @example
+ * ```typescript
+ * // Move item from position 2 to position 1 (make it play next)
+ * const result = await reorderQueue(2, 1, 0);
+ * if (result.success) {
+ *   console.log('Item moved successfully');
+ * }
+ *
+ * // Move item from position 1 to end of queue
+ * await reorderQueue(1, 4, 0); // Assuming queue has 5+ items
+ * ```
+ */
+export declare const reorderQueue: (currentQueuedSlotNumber: number, newQueuedSlotNumber: number, channelNumber?: number) => Promise<QueueManipulationResult>;
+/**
+ * Clears all queued audio items after the currently playing item
+ * The current audio will continue playing but nothing will follow it
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Let current song finish but clear everything after it
+ * const result = await clearQueueAfterCurrent(0);
+ * if (result.success) {
+ *   console.log(`Cleared queue, current audio will be the last to play`);
+ * }
+ * ```
+ */
+export declare const clearQueueAfterCurrent: (channelNumber?: number) => Promise<QueueManipulationResult>;
+/**
+ * Gets information about a specific queue item by its slot number
+ * @param queueSlotNumber - Zero-based index of the queue item
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns QueueItem information or null if slot doesn't exist
+ * @example
+ * ```typescript
+ * const itemInfo = getQueueItemInfo(1, 0);
+ * if (itemInfo) {
+ *   console.log(`Next to play: ${itemInfo.fileName}`);
+ *   console.log(`Duration: ${itemInfo.duration}ms`);
+ * }
+ * ```
+ */
+export declare const getQueueItemInfo: (queueSlotNumber: number, channelNumber?: number) => QueueItem | null;
+/**
+ * Gets the current queue length for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Number of items in the queue, or 0 if channel doesn't exist
+ * @example
+ * ```typescript
+ * const queueSize = getQueueLength(0);
+ * console.log(`Channel 0 has ${queueSize} items in queue`);
+ * ```
+ */
+export declare const getQueueLength: (channelNumber?: number) => number;
+/**
+ * Swaps the positions of two queue items
+ * Cannot swap with the currently playing item (index 0)
+ * @param slotA - Zero-based index of first item to swap (must be > 0)
+ * @param slotB - Zero-based index of second item to swap (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Swap the second and third items in queue
+ * const result = await swapQueueItems(1, 2, 0);
+ * if (result.success) {
+ *   console.log('Items swapped successfully');
+ * }
+ * ```
+ */
+export declare const swapQueueItems: (slotA: number, slotB: number, channelNumber?: number) => Promise<QueueManipulationResult>;