audio-channel-queue 1.10.0 → 1.12.0

package/src/index.ts

@@ -60,17 +60,16 @@ export {
 
 // Volume control and ducking functions
 export {
+  cancelAllVolumeTransitions,
+  cancelVolumeTransition,
   clearVolumeDucking,
-  fadeVolume,
   getAllChannelsVolume,
   getChannelVolume,
   getFadeConfig,
   setAllChannelsVolume,
   setChannelVolume,
   setVolumeDucking,
-  transitionVolume,
-  cancelVolumeTransition,
-  cancelAllVolumeTransitions
+  transitionVolume
 } from './volume';
 
 // Audio information and progress tracking functions
@@ -78,9 +77,11 @@ export {
   getAllChannelsInfo,
   getCurrentAudioInfo,
   getQueueSnapshot,
+  offAudioComplete,
   offAudioPause,
   offAudioProgress,
   offAudioResume,
+  offAudioStart,
   offQueueChange,
   onAudioComplete,
   onAudioPause,
@@ -130,4 +131,11 @@ export type {
 } from './types';
 
 // Enums and constants
-export { EasingType, FadeType, MAX_CHANNELS, TimerType, GLOBAL_PROGRESS_KEY } from './types';
+export {
+  AudioErrorType,
+  EasingType,
+  FadeType,
+  MAX_CHANNELS,
+  TimerType,
+  GLOBAL_PROGRESS_KEY
+} from './types';

package/src/info.ts

@@ -18,6 +18,73 @@ import {
 import { getAudioInfoFromElement, createQueueSnapshot } from './utils';
 import { setupProgressTracking, cleanupProgressTracking } from './events';
 
+/**
+ * Gets the current list of whitelisted channel properties
+ * This is automatically derived from the ExtendedAudioQueueChannel interface
+ * @returns Array of whitelisted property names
+ * @internal
+ */
+export const getWhitelistedChannelProperties = (): string[] => {
+  // Create a sample channel object to extract property names
+  const sampleChannel: ExtendedAudioQueueChannel = {
+    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
+};
+
+/**
+ * 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 const getNonWhitelistedChannelProperties = (channelNumber: number = 0): string[] => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) {
+    return [];
+  }
+
+  const whitelistedProperties: string[] = getWhitelistedChannelProperties();
+  const allChannelProperties: string[] = Object.getOwnPropertyNames(channel);
+
+  // Filter out properties that are in the whitelist
+  const nonWhitelistedProperties: string[] = allChannelProperties.filter(
+    (property: string) => !whitelistedProperties.includes(property)
+  );
+
+  return nonWhitelistedProperties;
+};
+
 /**
  * Global array to store audio channels with their queues and callback management
  * Each channel maintains its own audio queue and event callback sets
@@ -56,10 +123,10 @@ export const audioChannels: ExtendedAudioQueueChannel[] = new Proxy(
             channelValue: unknown
           ): boolean {
             // Allow internal modifications but warn about direct property changes
-            if (
-              typeof channelProp === 'string' &&
-              !['queue', 'volume', 'isPaused', 'isLocked', 'volumeConfig'].includes(channelProp)
-            ) {
+            // Use the automatically-derived whitelist from the interface
+            const whitelistedProperties = getWhitelistedChannelProperties();
+
+            if (typeof channelProp === 'string' && !whitelistedProperties.includes(channelProp)) {
               // eslint-disable-next-line no-console
               console.warn(
                 `Warning: Direct modification of channel.${channelProp} detected. ` +
@@ -284,13 +351,14 @@ export const onQueueChange = (channelNumber: number, callback: QueueChangeCallba
 
 /**
  * Removes queue change listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offQueueChange(0); // Stop receiving queue change notifications for channel 0
+ * offQueueChange(); // Stop receiving queue change notifications for default channel (0)
+ * offQueueChange(1); // Stop receiving queue change notifications for channel 1
  * ```
  */
-export const offQueueChange = (channelNumber: number): void => {
+export const offQueueChange = (channelNumber: number = 0): void => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.queueChangeCallbacks) return;
 
@@ -457,13 +525,14 @@ export const onAudioResume = (channelNumber: number, callback: AudioResumeCallba
 
 /**
  * Removes pause event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioPause(0); // Stop receiving pause notifications for channel 0
+ * offAudioPause(); // Stop receiving pause notifications for default channel (0)
+ * offAudioPause(1); // Stop receiving pause notifications for channel 1
  * ```
  */
-export const offAudioPause = (channelNumber: number): void => {
+export const offAudioPause = (channelNumber: number = 0): void => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.audioPauseCallbacks) return;
 
@@ -472,15 +541,48 @@ export const offAudioPause = (channelNumber: number): void => {
 
 /**
  * Removes resume event listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioResume(0); // Stop receiving resume notifications for channel 0
+ * offAudioResume(); // Stop receiving resume notifications for default channel (0)
+ * offAudioResume(1); // Stop receiving resume notifications for channel 1
  * ```
  */
-export const offAudioResume = (channelNumber: number): void => {
+export const offAudioResume = (channelNumber: number = 0): void => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.audioResumeCallbacks) return;
 
   channel.audioResumeCallbacks.clear();
 };
+
+/**
+ * Removes audio start event listeners for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @example
+ * ```typescript
+ * offAudioStart(); // Stop receiving start notifications for default channel (0)
+ * offAudioStart(1); // Stop receiving start notifications for channel 1
+ * ```
+ */
+export const offAudioStart = (channelNumber: number = 0): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.audioStartCallbacks) return;
+
+  channel.audioStartCallbacks.clear();
+};
+
+/**
+ * Removes audio complete event listeners for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @example
+ * ```typescript
+ * offAudioComplete(); // Stop receiving completion notifications for default channel (0)
+ * offAudioComplete(1); // Stop receiving completion notifications for channel 1
+ * ```
+ */
+export const offAudioComplete = (channelNumber: number = 0): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.audioCompleteCallbacks) return;
+
+  channel.audioCompleteCallbacks.clear();
+};

package/src/types.ts

@@ -29,15 +29,15 @@ export interface AudioQueueChannel {
  * Volume ducking configuration for channels
  */
 export interface VolumeConfig {
+  /** Duration in milliseconds for volume duck transition (defaults to 250ms) */
+  duckTransitionDuration?: number;
+  /** Volume level for all other channels when priority channel is active (0-1) */
+  duckingVolume: number;
   /** The channel number that should have priority */
   priorityChannel: number;
   /** Volume level for the priority channel (0-1) */
   priorityVolume: number;
-  /** Volume level for all other channels when priority channel is active (0-1) */
-  duckingVolume: number;
-  /** Duration in milliseconds for volume duck transition (defaults to 250ms) */
-  duckTransitionDuration?: number;
-  /** Duration in milliseconds for volume restore transition (defaults to 500ms) */
+  /** Duration in milliseconds for volume restore transition (defaults to 250ms) */
   restoreTransitionDuration?: number;
   /** Easing function for volume transitions (defaults to 'ease-out') */
   transitionEasing?: EasingType;
@@ -53,8 +53,6 @@ export interface AudioQueueOptions {
   loop?: boolean;
   /** Maximum number of items allowed in the queue (defaults to unlimited) */
   maxQueueSize?: number;
-  /** @deprecated Use addToFront instead. Legacy support for priority queuing */
-  priority?: boolean;
   /** Volume level for this specific audio (0-1) */
   volume?: number;
 }
@@ -212,41 +210,74 @@ export type AudioPauseCallback = (channelNumber: number, audioInfo: AudioInfo) =
 export type AudioResumeCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
 
 /**
- * Information about an audio error that occurred
+ * Types of audio errors that can occur during playback
+ */
+export enum AudioErrorType {
+  Abort = 'abort',
+  Decode = 'decode',
+  Network = 'network',
+  Permission = 'permission',
+  Timeout = 'timeout',
+  Unknown = 'unknown',
+  Unsupported = 'unsupported'
+}
+
+/**
+ * Information about an audio error that occurred during playback or loading
  */
 export interface AudioErrorInfo {
+  /** Channel number where the error occurred */
   channelNumber: number;
-  src: string;
-  fileName: string;
+  /** The actual error object that was thrown */
   error: Error;
-  errorType: 'network' | 'decode' | 'unsupported' | 'permission' | 'abort' | 'timeout' | 'unknown';
-  timestamp: number;
-  retryAttempt?: number;
+  /** Categorized type of error for handling different scenarios */
+  errorType: AudioErrorType;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Number of audio files remaining in the queue after this error */
   remainingInQueue: number;
+  /** Current retry attempt number (if retrying is enabled) */
+  retryAttempt?: number;
+  /** Audio file source URL that failed */
+  src: string;
+  /** Unix timestamp when the error occurred */
+  timestamp: number;
 }
 
 /**
  * Configuration for automatic retry behavior when audio fails to load or play
  */
 export interface RetryConfig {
-  enabled: boolean;
-  maxRetries: number;
+  /** Initial delay in milliseconds before first retry attempt */
   baseDelay: number;
+  /** Whether automatic retries are enabled for this channel */
+  enabled: boolean;
+  /** Whether to use exponential backoff (doubling delay each retry) */
   exponentialBackoff: boolean;
-  timeoutMs: number;
-  fallbackUrls?: string[];
+  /** Alternative URLs to try if the primary source fails */
+  fallbackUrls: string[];
+  /** Maximum number of retry attempts before giving up */
+  maxRetries: number;
+  /** Whether to skip to next track in queue if all retries fail */
   skipOnFailure: boolean;
+  /** Timeout in milliseconds for each individual retry attempt */
+  timeoutMs: number;
 }
 
 /**
- * Configuration options for error recovery mechanisms
+ * Configuration options for error recovery mechanisms across the audio system
  */
 export interface ErrorRecoveryOptions {
+  /** Whether to automatically retry failed audio loads/plays */
   autoRetry: boolean;
-  showUserFeedback: boolean;
+  /** Whether to automatically skip to next track when current fails */
+  fallbackToNextTrack: boolean;
+  /** Whether to send error data to analytics systems */
   logErrorsToAnalytics: boolean;
+  /** Whether to maintain queue integrity when errors occur */
   preserveQueueOnError: boolean;
-  fallbackToNextTrack: boolean;
+  /** Whether to display user-visible error feedback */
+  showUserFeedback: boolean;
 }
 
 /**
@@ -255,29 +286,41 @@ export interface ErrorRecoveryOptions {
 export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
 
 /**
- * Extended audio channel with queue management and callback support
+ * Extended audio channel with comprehensive queue management, callback support, and state tracking
  */
 export interface ExtendedAudioQueueChannel {
+  /** Set of callbacks triggered when audio completes playback */
   audioCompleteCallbacks: Set<AudioCompleteCallback>;
+  /** Set of callbacks triggered when audio errors occur */
   audioErrorCallbacks: Set<AudioErrorCallback>;
+  /** Set of callbacks triggered when audio is paused */
   audioPauseCallbacks: Set<AudioPauseCallback>;
+  /** Set of callbacks triggered when audio is resumed */
   audioResumeCallbacks: Set<AudioResumeCallback>;
+  /** Set of callbacks triggered when audio starts playing */
   audioStartCallbacks: Set<AudioStartCallback>;
+  /** Current fade state if pause/resume with fade is active */
   fadeState?: ChannelFadeState;
+  /** Whether the channel is currently paused */
   isPaused: boolean;
   /** Active operation lock to prevent race conditions */
   isLocked?: boolean;
   /** Maximum allowed queue size for this channel */
   maxQueueSize?: number;
+  /** Map of progress callbacks keyed by audio element or global symbol */
   progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
+  /** Array of HTMLAudioElement objects in the queue */
   queue: HTMLAudioElement[];
+  /** Set of callbacks triggered when the queue changes */
   queueChangeCallbacks: Set<QueueChangeCallback>;
+  /** Retry configuration for failed audio loads/plays */
   retryConfig?: RetryConfig;
+  /** Current volume level for the channel (0-1) */
   volume: number;
 }
 
 /**
- * Easing function types for volume transitions
+ * Easing function types for smooth volume transitions and animations
  */
 export enum EasingType {
   Linear = 'linear',
@@ -287,7 +330,7 @@ export enum EasingType {
 }
 
 /**
- * Fade type for pause/resume operations with integrated volume transitions
+ * Predefined fade types for pause/resume operations with different transition characteristics
  */
 export enum FadeType {
   Linear = 'linear',
@@ -296,7 +339,7 @@ export enum FadeType {
 }
 
 /**
- * Timer types for volume transitions to ensure proper cleanup
+ * Timer implementation types used for volume transitions to ensure proper cleanup
  */
 export enum TimerType {
   RequestAnimationFrame = 'raf',

package/src/volume.ts

@@ -380,28 +380,6 @@ export const applyVolumeDucking = async (activeChannelNumber: number): Promise<v
   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 queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing
@@ -430,7 +408,7 @@ export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise
     }
 
     // Restore this channel to its desired volume
-    const duration = config.restoreTransitionDuration ?? 500;
+    const duration = config.restoreTransitionDuration ?? 250;
     const easing = config.transitionEasing ?? EasingType.EaseOut;
     const targetVolume = channel.volume ?? 1.0;