audio-channel-queue 1.4.0 → 1.6.0

package/src/types.ts

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview Type definitions for the audio-channel-queue package
+ */
+
+/**
+ * Array of HTMLAudioElement objects representing an audio queue
+ */
+export type AudioQueue = HTMLAudioElement[];
+
+/**
+ * Basic audio queue channel structure
+ */
+export type AudioQueueChannel = {
+  queue: AudioQueue;
+}
+
+/**
+ * Volume ducking configuration for channels
+ */
+export interface VolumeConfig {
+  /** 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) */
+  restoreTransitionDuration?: number;
+  /** Easing function for volume transitions (defaults to 'ease-out') */
+  transitionEasing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+}
+
+/**
+ * Audio file configuration for queueing
+ */
+export interface AudioQueueOptions {
+  /** Whether to add the audio to the front of the queue (defaults to false) */
+  addToFront?: boolean;
+  /** Whether the audio should loop when it finishes */
+  loop?: boolean;
+  /** Whether to add the audio with priority (same as addToFront) */
+  priority?: boolean;
+  /** Volume level for this specific audio file (0-1, defaults to channel volume) */
+  volume?: number;
+}
+
+/**
+ * Comprehensive audio information interface providing metadata about currently playing audio
+ */
+export interface AudioInfo {
+  /** Current playback position in milliseconds */
+  currentTime: number;
+  /** Total audio duration in milliseconds */
+  duration: number;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Whether the audio is set to loop */
+  isLooping: boolean;
+  /** Whether the audio is currently paused */
+  isPaused: boolean;
+  /** Whether the audio is currently playing */
+  isPlaying: boolean;
+  /** Playback progress as a decimal (0-1) */
+  progress: number;
+  /** Number of audio files remaining in the queue after current */
+  remainingInQueue: number;
+  /** Audio file source URL */
+  src: string;
+  /** Current volume level (0-1) */
+  volume: number;
+}
+
+/**
+ * Information provided when an audio file completes playback
+ */
+export interface AudioCompleteInfo {
+  /** Channel number where the audio completed */
+  channelNumber: number;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Number of audio files remaining in the queue after completion */
+  remainingInQueue: number;
+  /** Audio file source URL */
+  src: string;
+}
+
+/**
+ * Information provided when an audio file starts playing
+ */
+export interface AudioStartInfo {
+  /** Channel number where the audio is starting */
+  channelNumber: number;
+  /** Total audio duration in milliseconds */
+  duration: number;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Audio file source URL */
+  src: string;
+}
+
+/**
+ * Information about a single item in an audio queue
+ */
+export interface QueueItem {
+  /** Total audio duration in milliseconds */
+  duration: number;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Whether this item is currently playing */
+  isCurrentlyPlaying: boolean;
+  /** Whether this item is set to loop */
+  isLooping: boolean;
+  /** Audio file source URL */
+  src: string;
+  /** Volume level for this item (0-1) */
+  volume: number;
+}
+
+/**
+ * Complete snapshot of a queue's current state
+ */
+export interface QueueSnapshot {
+  /** Channel number this snapshot represents */
+  channelNumber: number;
+  /** Zero-based index of the currently playing item */
+  currentIndex: number;
+  /** Whether the current audio is paused */
+  isPaused: boolean;
+  /** Array of audio items in the queue with their metadata */
+  items: QueueItem[];
+  /** Total number of items in the queue */
+  totalItems: number;
+  /** Current volume level for the channel (0-1) */
+  volume: number;
+}
+
+/**
+ * Callback function type for audio progress updates
+ * @param info Current audio information
+ */
+export type ProgressCallback = (info: AudioInfo) => void;
+
+/**
+ * Callback function type for queue change notifications
+ * @param queueSnapshot Current state of the queue
+ */
+export type QueueChangeCallback = (queueSnapshot: QueueSnapshot) => void;
+
+/**
+ * Callback function type for audio start notifications
+ * @param audioInfo Information about the audio that started
+ */
+export type AudioStartCallback = (audioInfo: AudioStartInfo) => void;
+
+/**
+ * Callback function type for audio complete notifications
+ * @param audioInfo Information about the audio that completed
+ */
+export type AudioCompleteCallback = (audioInfo: AudioCompleteInfo) => void;
+
+/**
+ * Callback function type for audio pause notifications
+ * @param channelNumber Channel that was paused
+ * @param audioInfo Information about the audio that was paused
+ */
+export type AudioPauseCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
+
+/**
+ * Callback function type for audio resume notifications
+ * @param channelNumber Channel that was resumed
+ * @param audioInfo Information about the audio that was resumed
+ */
+export type AudioResumeCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
+
+/**
+ * Extended audio queue channel with event callback management and additional features
+ */
+export type ExtendedAudioQueueChannel = AudioQueueChannel & {
+  /** Set of callbacks for audio completion events */
+  audioCompleteCallbacks?: Set<AudioCompleteCallback>;
+  /** Set of callbacks for audio pause events */
+  audioPauseCallbacks?: Set<AudioPauseCallback>;
+  /** Set of callbacks for audio resume events */
+  audioResumeCallbacks?: Set<AudioResumeCallback>;
+  /** Set of callbacks for audio start events */
+  audioStartCallbacks?: Set<AudioStartCallback>;
+  /** Whether the current audio in this channel is paused */
+  isPaused?: boolean;
+  /** Map of audio elements to their progress callback sets */
+  progressCallbacks?: Map<HTMLAudioElement, Set<ProgressCallback>>;
+  /** Set of callbacks for queue change events */
+  queueChangeCallbacks?: Set<QueueChangeCallback>;
+  /** Current volume level for this channel (0-1) */
+  volume?: number;
+  /** Volume ducking configuration for this channel */
+  volumeConfig?: VolumeConfig;
+} 

package/src/utils.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Utility functions for the audio-channel-queue package
+ */
+
+import { AudioInfo, QueueSnapshot, ExtendedAudioQueueChannel, QueueItem } from './types';
+
+/**
+ * Extracts the filename from a URL string
+ * @param url - The URL to extract the filename from
+ * @returns The extracted filename or 'unknown' if extraction fails
+ * @example
+ * ```typescript
+ * extractFileName('https://example.com/audio/song.mp3') // Returns: 'song.mp3'
+ * extractFileName('/path/to/audio.wav') // Returns: 'audio.wav'
+ * ```
+ */
+export const extractFileName = (url: string): string => {
+  try {
+    const urlObj: URL = new URL(url);
+    const pathname: string = urlObj.pathname;
+    const segments: string[] = pathname.split('/');
+    const fileName: string = segments[segments.length - 1];
+    return fileName || 'unknown';
+  } catch {
+    // If URL parsing fails, try simple string manipulation
+    const segments: string[] = url.split('/');
+    const fileName: string = segments[segments.length - 1];
+    return fileName || 'unknown';
+  }
+};
+
+/**
+ * Extracts comprehensive audio information from an HTMLAudioElement
+ * @param audio - The HTML audio element to extract information from
+ * @param channelNumber - Optional channel number to include remaining queue info
+ * @param audioChannels - Optional audio channels array to calculate remainingInQueue
+ * @returns AudioInfo object with current playback state or null if audio is invalid
+ * @example
+ * ```typescript
+ * const audioElement = new Audio('song.mp3');
+ * const info = getAudioInfoFromElement(audioElement);
+ * console.log(info?.progress); // Current progress as decimal (0-1)
+ * 
+ * // With channel context for remainingInQueue
+ * const infoWithQueue = getAudioInfoFromElement(audioElement, 0, audioChannels);
+ * console.log(infoWithQueue?.remainingInQueue); // Number of items left in queue
+ * ```
+ */
+export const getAudioInfoFromElement = (
+  audio: HTMLAudioElement, 
+  channelNumber?: number,
+  audioChannels?: ExtendedAudioQueueChannel[]
+): AudioInfo | null => {
+  if (!audio) return null;
+
+  const duration: number = isNaN(audio.duration) ? 0 : audio.duration * 1000; // Convert to milliseconds
+  const currentTime: number = isNaN(audio.currentTime) ? 0 : audio.currentTime * 1000; // Convert to milliseconds
+  const progress: number = duration > 0 ? Math.min(currentTime / duration, 1) : 0;
+  const isPlaying: boolean = !audio.paused && !audio.ended && audio.readyState > 2;
+
+  // Calculate remainingInQueue if channel context is provided
+  let remainingInQueue: number = 0;
+  if (channelNumber !== undefined && audioChannels && audioChannels[channelNumber]) {
+    const channel = audioChannels[channelNumber];
+    remainingInQueue = Math.max(0, channel.queue.length - 1); // Exclude current playing audio
+  }
+
+  return {
+    currentTime,
+    duration,
+    fileName: extractFileName(audio.src),
+    isLooping: audio.loop,
+    isPaused: audio.paused && !audio.ended,
+    isPlaying,
+    progress,
+    remainingInQueue,
+    src: audio.src,
+    volume: audio.volume
+  };
+};
+
+/**
+ * Creates a complete snapshot of a queue's current state
+ * @param channelNumber - The channel number to create a snapshot for
+ * @param audioChannels - Array of audio channels
+ * @returns QueueSnapshot object or null if channel doesn't exist
+ * @example
+ * ```typescript
+ * const snapshot = createQueueSnapshot(0, audioChannels);
+ * console.log(`Queue has ${snapshot?.totalItems} items`);
+ * ```
+ */
+export const createQueueSnapshot = (
+  channelNumber: number, 
+  audioChannels: ExtendedAudioQueueChannel[]
+): QueueSnapshot | null => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) return null;
+
+  const items: QueueItem[] = channel.queue.map((audio: HTMLAudioElement, index: number) => ({
+    duration: isNaN(audio.duration) ? 0 : audio.duration * 1000,
+    fileName: extractFileName(audio.src),
+    isCurrentlyPlaying: index === 0 && !audio.paused && !audio.ended,
+    isLooping: audio.loop,
+    src: audio.src,
+    volume: audio.volume
+  }));
+
+  return {
+    channelNumber,
+    currentIndex: 0, // Current playing is always index 0 in our queue structure
+    isPaused: channel.isPaused || false,
+    items,
+    totalItems: channel.queue.length,
+    volume: channel.volume || 1.0
+  };
+};
+
+/**
+ * Removes webpack hash patterns from filenames to get clean, readable names
+ * @param fileName - The filename that may contain webpack hashes
+ * @returns The cleaned filename with webpack hashes removed
+ * @example
+ * ```typescript
+ * cleanWebpackFilename('song.a1b2c3d4.mp3') // Returns: 'song.mp3'
+ * cleanWebpackFilename('notification.1a2b3c4d5e6f7890.wav') // Returns: 'notification.wav'
+ * cleanWebpackFilename('music.12345678.ogg') // Returns: 'music.ogg'
+ * cleanWebpackFilename('clean-file.mp3') // Returns: 'clean-file.mp3' (unchanged)
+ * ```
+ */
+export const cleanWebpackFilename = (fileName: string): string => {
+  // Remove webpack hash pattern: filename.hash.ext → filename.ext
+  return fileName.replace(/\.[a-f0-9]{8,}\./i, '.');
+}; 

package/src/volume.ts

@@ -0,0 +1,328 @@
+/**
+ * @fileoverview Volume management functions for the audio-channel-queue package
+ */
+
+import { ExtendedAudioQueueChannel, VolumeConfig } from './types';
+import { audioChannels } from './info';
+
+// Store active volume transitions to handle interruptions
+const activeTransitions = new Map<number, number>();
+
+/**
+ * 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
+};
+
+/**
+ * Smoothly transitions volume for a specific channel over time
+ * @param channelNumber - The channel number to transition
+ * @param targetVolume - Target volume level (0-1)
+ * @param duration - Transition duration in milliseconds
+ * @param easing - Easing function type
+ * @returns Promise that resolves when transition completes
+ * @example
+ * ```typescript
+ * await transitionVolume(0, 0.2, 500, 'ease-out'); // Duck to 20% over 500ms
+ * ```
+ */
+export const transitionVolume = async (
+  channelNumber: number,
+  targetVolume: number,
+  duration: number = 250,
+  easing: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' = 'ease-out'
+): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || channel.queue.length === 0) return;
+
+  const currentAudio: HTMLAudioElement = channel.queue[0];
+  const startVolume: number = currentAudio.volume;
+  const volumeDelta: number = targetVolume - startVolume;
+  
+  // Cancel any existing transition for this channel
+  if (activeTransitions.has(channelNumber)) {
+    clearTimeout(activeTransitions.get(channelNumber));
+    activeTransitions.delete(channelNumber);
+  }
+
+  // If no change needed, resolve immediately
+  if (Math.abs(volumeDelta) < 0.001) {
+    channel.volume = targetVolume;
+    return Promise.resolve();
+  }
+
+  // Handle zero duration - instant change
+  if (duration <= 0) {
+    channel.volume = targetVolume;
+    if (channel.queue.length > 0) {
+      channel.queue[0].volume = targetVolume;
+    }
+    return Promise.resolve();
+  }
+
+  const startTime: number = performance.now();
+  const easingFn = easingFunctions[easing];
+
+  return new Promise<void>((resolve) => {
+    const updateVolume = (): void => {
+      const elapsed: number = performance.now() - startTime;
+      const progress: number = Math.min(elapsed / duration, 1);
+      const easedProgress: number = easingFn(progress);
+      
+      const currentVolume: number = startVolume + (volumeDelta * easedProgress);
+      const clampedVolume: number = Math.max(0, Math.min(1, currentVolume));
+      
+      // Apply volume to both channel config and current audio
+      channel.volume = clampedVolume;
+      if (channel.queue.length > 0) {
+        channel.queue[0].volume = clampedVolume;
+      }
+
+      if (progress >= 1) {
+        // Transition complete
+        activeTransitions.delete(channelNumber);
+        resolve();
+      } else {
+        // Use requestAnimationFrame in browser, setTimeout in tests
+        if (typeof requestAnimationFrame !== 'undefined') {
+          const rafId = requestAnimationFrame(updateVolume);
+          activeTransitions.set(channelNumber, rafId as unknown as number);
+        } else {
+          // In test environment, use shorter intervals
+          const timeoutId = setTimeout(updateVolume, 1);
+          activeTransitions.set(channelNumber, timeoutId as unknown as number);
+        }
+      }
+    };
+
+    updateVolume();
+  });
+};
+
+/**
+ * Sets the volume for a specific channel with optional smooth transition
+ * @param channelNumber - The channel number to set volume for
+ * @param volume - Volume level (0-1)
+ * @param transitionDuration - Optional transition duration in milliseconds
+ * @param easing - Optional easing function
+ * @example
+ * ```typescript
+ * setChannelVolume(0, 0.5); // Set channel 0 to 50%
+ * setChannelVolume(0, 0.5, 300, 'ease-out'); // Smooth transition over 300ms
+ * ```
+ */
+export const setChannelVolume = async (
+  channelNumber: number, 
+  volume: number,
+  transitionDuration?: number,
+  easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out'
+): Promise<void> => {
+  const clampedVolume: number = Math.max(0, Math.min(1, volume));
+  
+  if (!audioChannels[channelNumber]) {
+    audioChannels[channelNumber] = { 
+      audioCompleteCallbacks: new Set(),
+      audioPauseCallbacks: new Set(),
+      audioResumeCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      isPaused: false,
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set(),
+      volume: clampedVolume
+    };
+    return;
+  }
+
+  if (transitionDuration && transitionDuration > 0) {
+    // Smooth transition
+    await transitionVolume(channelNumber, clampedVolume, transitionDuration, easing);
+  } else {
+    // Instant change (backward compatibility)
+    audioChannels[channelNumber].volume = clampedVolume;
+    const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+    if (channel.queue.length > 0) {
+      const currentAudio: HTMLAudioElement = channel.queue[0];
+      currentAudio.volume = clampedVolume;
+    }
+  }
+};
+
+/**
+ * Gets the current volume for a specific channel
+ * @param channelNumber - The channel number to get volume for (defaults to 0)
+ * @returns Current volume level (0-1) or 1.0 if channel doesn't exist
+ * @example
+ * ```typescript
+ * const volume = getChannelVolume(0);
+ * const defaultChannelVolume = getChannelVolume(); // Gets channel 0
+ * console.log(`Channel 0 volume: ${volume * 100}%`);
+ * ```
+ */
+export const getChannelVolume = (channelNumber: number = 0): number => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  return channel?.volume || 1.0;
+};
+
+/**
+ * Gets the volume levels for all channels
+ * @returns Array of volume levels (0-1) for each channel
+ * @example
+ * ```typescript
+ * const volumes = getAllChannelsVolume();
+ * volumes.forEach((volume, index) => {
+ *   console.log(`Channel ${index}: ${volume * 100}%`);
+ * });
+ * ```
+ */
+export const getAllChannelsVolume = (): number[] => {
+  return audioChannels.map((channel: ExtendedAudioQueueChannel) => 
+    channel?.volume || 1.0
+  );
+};
+
+/**
+ * Sets volume for all channels to the same level
+ * @param volume - Volume level (0-1) to apply to all channels
+ * @example
+ * ```typescript
+ * await setAllChannelsVolume(0.6); // Set all channels to 60% volume
+ * ```
+ */
+export const setAllChannelsVolume = async (volume: number): Promise<void> => {
+  const promises: Promise<void>[] = [];
+  audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
+    promises.push(setChannelVolume(index, volume));
+  });
+  await Promise.all(promises);
+};
+
+/**
+ * Configures volume ducking for channels. When the priority channel plays audio,
+ * all other channels will be automatically reduced to the ducking volume level
+ * @param config - Volume ducking configuration
+ * @example
+ * ```typescript
+ * // When channel 1 plays, reduce all other channels to 20% volume
+ * setVolumeDucking({
+ *   priorityChannel: 1,
+ *   priorityVolume: 1.0,
+ *   duckingVolume: 0.2
+ * });
+ * ```
+ */
+export const setVolumeDucking = (config: VolumeConfig): void => {
+  // First, ensure we have enough channels for the priority channel
+  while (audioChannels.length <= config.priorityChannel) {
+    audioChannels.push({
+      audioCompleteCallbacks: new Set(),
+      audioPauseCallbacks: new Set(),
+      audioResumeCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      isPaused: false,
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set(),
+      volume: 1.0
+    });
+  }
+
+  // Apply the config to all existing channels
+  audioChannels.forEach((channel: ExtendedAudioQueueChannel, index: number) => {
+    if (!audioChannels[index]) {
+      audioChannels[index] = { 
+        audioCompleteCallbacks: new Set(),
+        audioPauseCallbacks: new Set(),
+        audioResumeCallbacks: new Set(),
+        audioStartCallbacks: new Set(),
+        isPaused: false,
+        progressCallbacks: new Map(),
+        queue: [],
+        queueChangeCallbacks: new Set(),
+        volume: 1.0
+      };
+    }
+    audioChannels[index].volumeConfig = config;
+  });
+};
+
+/**
+ * Removes volume ducking configuration from all channels
+ * @example
+ * ```typescript
+ * clearVolumeDucking(); // Remove all volume ducking effects
+ * ```
+ */
+export const clearVolumeDucking = (): void => {
+  audioChannels.forEach((channel: ExtendedAudioQueueChannel) => {
+    if (channel) {
+      delete channel.volumeConfig;
+    }
+  });
+};
+
+/**
+ * Applies volume ducking effects based on current playback state with smooth transitions
+ * @param activeChannelNumber - The channel that just started playing
+ * @internal
+ */
+export const applyVolumeDucking = async (activeChannelNumber: number): Promise<void> => {
+  const transitionPromises: Promise<void>[] = [];
+
+  audioChannels.forEach((channel: ExtendedAudioQueueChannel, channelNumber: number) => {
+    if (channel?.volumeConfig) {
+      const config: VolumeConfig = channel.volumeConfig;
+      
+      if (activeChannelNumber === config.priorityChannel) {
+        const duration = config.duckTransitionDuration || 250;
+        const easing = config.transitionEasing || 'ease-out';
+        
+        // Priority channel is active, duck other channels
+        if (channelNumber === config.priorityChannel) {
+          transitionPromises.push(
+            transitionVolume(channelNumber, config.priorityVolume, duration, easing)
+          );
+        } else {
+          transitionPromises.push(
+            transitionVolume(channelNumber, config.duckingVolume, duration, easing)
+          );
+        }
+      }
+    }
+  });
+
+  // Wait for all transitions to complete
+  await Promise.all(transitionPromises);
+};
+
+/**
+ * Restores normal volume levels when priority channel stops with smooth transitions
+ * @param stoppedChannelNumber - The channel that just stopped playing
+ * @internal
+ */
+export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise<void> => {
+  const transitionPromises: Promise<void>[] = [];
+
+  audioChannels.forEach((channel: ExtendedAudioQueueChannel, channelNumber: number) => {
+    if (channel?.volumeConfig) {
+      const config: VolumeConfig = channel.volumeConfig;
+      
+      if (stoppedChannelNumber === config.priorityChannel) {
+        const duration = config.restoreTransitionDuration || 500;
+        const easing = config.transitionEasing || 'ease-out';
+        
+        // Priority channel stopped, restore normal volumes
+        transitionPromises.push(
+          transitionVolume(channelNumber, channel.volume || 1.0, duration, easing)
+        );
+      }
+    }
+  });
+
+  // Wait for all transitions to complete
+  await Promise.all(transitionPromises);
+}; 

package/dist/audio.d.ts

@@ -1,10 +0,0 @@
-export type AudioQueue = HTMLAudioElement[];
-export type AudioQueueChannel = {
-    queue: AudioQueue;
-};
-export declare const audioChannels: AudioQueueChannel[];
-export declare const queueAudio: (audioUrl: string, channelNumber?: number) => Promise<void>;
-export declare const playAudioQueue: (channelNumber: number) => Promise<void>;
-export declare const stopCurrentAudioInChannel: (channelNumber?: number) => void;
-export declare const stopAllAudioInChannel: (channelNumber?: number) => void;
-export declare const stopAllAudio: () => void;