audio-channel-queue 1.4.0 → 1.5.0

package/src/events.ts

@@ -0,0 +1,189 @@
+/**
+ * @fileoverview Event handling and emission for the audio-channel-queue package
+ */
+
+import { 
+  AudioStartInfo, 
+  AudioCompleteInfo, 
+  ExtendedAudioQueueChannel,
+  QueueSnapshot,
+  ProgressCallback,
+  AudioInfo,
+} from './types';
+import { createQueueSnapshot, getAudioInfoFromElement } from './utils';
+
+/**
+ * Emits a queue change event to all registered listeners for a specific channel
+ * @param channelNumber - The channel number that experienced a queue change
+ * @param audioChannels - Array of audio channels
+ * @example
+ * ```typescript
+ * emitQueueChange(0, audioChannels); // Notifies all queue change listeners
+ * ```
+ */
+export const emitQueueChange = (
+  channelNumber: number, 
+  audioChannels: ExtendedAudioQueueChannel[]
+): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || !channel.queueChangeCallbacks) return;
+
+  const snapshot: QueueSnapshot | null = createQueueSnapshot(channelNumber, audioChannels);
+  if (!snapshot) return;
+
+  channel.queueChangeCallbacks.forEach(callback => {
+    try {
+      callback(snapshot);
+    } catch (error) {
+      console.error('Error in queue change callback:', error);
+    }
+  });
+};
+
+/**
+ * Emits an audio start event to all registered listeners for a specific channel
+ * @param channelNumber - The channel number where audio started
+ * @param audioInfo - Information about the audio that started
+ * @param audioChannels - Array of audio channels
+ * @example
+ * ```typescript
+ * emitAudioStart(0, { src: 'song.mp3', fileName: 'song.mp3', duration: 180000, channelNumber: 0 }, audioChannels);
+ * ```
+ */
+export const emitAudioStart = (
+  channelNumber: number, 
+  audioInfo: AudioStartInfo,
+  audioChannels: ExtendedAudioQueueChannel[]
+): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || !channel.audioStartCallbacks) return;
+
+  channel.audioStartCallbacks.forEach(callback => {
+    try {
+      callback(audioInfo);
+    } catch (error) {
+      console.error('Error in audio start callback:', error);
+    }
+  });
+};
+
+/**
+ * Emits an audio complete event to all registered listeners for a specific channel
+ * @param channelNumber - The channel number where audio completed
+ * @param audioInfo - Information about the audio that completed
+ * @param audioChannels - Array of audio channels
+ * @example
+ * ```typescript
+ * emitAudioComplete(0, { src: 'song.mp3', fileName: 'song.mp3', channelNumber: 0, remainingInQueue: 2 }, audioChannels);
+ * ```
+ */
+export const emitAudioComplete = (
+  channelNumber: number, 
+  audioInfo: AudioCompleteInfo,
+  audioChannels: ExtendedAudioQueueChannel[]
+): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || !channel.audioCompleteCallbacks) return;
+
+  channel.audioCompleteCallbacks.forEach(callback => {
+    try {
+      callback(audioInfo);
+    } catch (error) {
+      console.error('Error in audio complete callback:', error);
+    }
+  });
+};
+
+// Store listener functions for cleanup
+const progressListeners = new WeakMap<HTMLAudioElement, () => void>();
+
+/**
+ * Sets up comprehensive progress tracking for an audio element
+ * @param audio - The HTML audio element to track
+ * @param channelNumber - The channel number this audio belongs to
+ * @param audioChannels - Array of audio channels
+ * @example
+ * ```typescript
+ * const audioElement = new Audio('song.mp3');
+ * setupProgressTracking(audioElement, 0, audioChannels);
+ * ```
+ */
+export const setupProgressTracking = (
+  audio: HTMLAudioElement, 
+  channelNumber: number,
+  audioChannels: ExtendedAudioQueueChannel[]
+): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) return;
+
+  if (!channel.progressCallbacks) {
+    channel.progressCallbacks = new Map();
+  }
+
+  // Don't set up tracking if already exists
+  if (progressListeners.has(audio)) return;
+
+  const updateProgress = (): void => {
+    // Get callbacks for this specific audio element AND the channel-wide callbacks
+    const audioCallbacks: Set<ProgressCallback> = channel.progressCallbacks?.get(audio) || new Set();
+    const channelCallbacks: Set<ProgressCallback> = channel.progressCallbacks?.get(null as any) || new Set();
+    
+    // Combine both sets of callbacks
+    const allCallbacks: Set<ProgressCallback> = new Set([...audioCallbacks, ...channelCallbacks]);
+    
+    if (allCallbacks.size === 0) return;
+
+    const info: AudioInfo | null = getAudioInfoFromElement(audio);
+    if (info) {
+      allCallbacks.forEach((callback: ProgressCallback) => {
+        try {
+          callback(info);
+        } catch (error) {
+          console.error('Error in progress callback:', error);
+        }
+      });
+    }
+  };
+
+  // Store the listener function for cleanup
+  progressListeners.set(audio, updateProgress);
+
+  // Set up comprehensive event listeners for progress tracking
+  audio.addEventListener('timeupdate', updateProgress);
+  audio.addEventListener('loadedmetadata', updateProgress);
+  audio.addEventListener('play', updateProgress);
+  audio.addEventListener('pause', updateProgress);
+  audio.addEventListener('ended', updateProgress);
+};
+
+/**
+ * Cleans up progress tracking for an audio element to prevent memory leaks
+ * @param audio - The HTML audio element to clean up
+ * @param channelNumber - The channel number this audio belongs to
+ * @param audioChannels - Array of audio channels
+ * @example
+ * ```typescript
+ * cleanupProgressTracking(audioElement, 0, audioChannels);
+ * ```
+ */
+export const cleanupProgressTracking = (
+  audio: HTMLAudioElement, 
+  channelNumber: number,
+  audioChannels: ExtendedAudioQueueChannel[]
+): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || !channel.progressCallbacks) return;
+
+  // Remove event listeners
+  const updateProgress: (() => void) | undefined = progressListeners.get(audio);
+  if (updateProgress) {
+    audio.removeEventListener('timeupdate', updateProgress);
+    audio.removeEventListener('loadedmetadata', updateProgress);
+    audio.removeEventListener('play', updateProgress);
+    audio.removeEventListener('pause', updateProgress);
+    audio.removeEventListener('ended', updateProgress);
+    progressListeners.delete(audio);
+  }
+
+  channel.progressCallbacks.delete(audio);
+}; 

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Main entry point for the audio-channel-queue package
+ * 
+ * A comprehensive audio queue management system with real-time progress tracking,
+ * multi-channel support, and extensive event handling capabilities.
+ * 
+ * @example Basic Usage
+ * ```typescript
+ * import { queueAudio, onAudioProgress } from 'audio-channel-queue';
+ * 
+ * // Queue an audio file
+ * await queueAudio('song.mp3');
+ * 
+ * // Track progress
+ * onAudioProgress(0, (info) => {
+ *   console.log(`Progress: ${info.progress * 100}%`);
+ * });
+ * ```
+ */
+
+// Export all type definitions
+export type {
+  AudioCompleteCallback,
+  AudioCompleteInfo,
+  AudioInfo,
+  AudioQueue,
+  AudioQueueChannel,
+  AudioStartCallback,
+  AudioStartInfo,
+  ExtendedAudioQueueChannel,
+  ProgressCallback,
+  QueueChangeCallback,
+  QueueItem,
+  QueueSnapshot
+} from './types';
+
+// Export core queue management functions
+export {
+  playAudioQueue,
+  queueAudio,
+  stopAllAudio,
+  stopAllAudioInChannel,
+  stopCurrentAudioInChannel
+} from './core';
+
+// Export audio information and progress tracking functions
+export {
+  audioChannels,
+  getAllChannelsInfo,
+  getCurrentAudioInfo,
+  getQueueSnapshot,
+  offAudioProgress,
+  onAudioComplete,
+  onAudioProgress,
+  onAudioStart,
+  onQueueChange,
+  offQueueChange
+} from './info';
+
+// Export utility functions (for advanced usage)
+export {
+  cleanWebpackFilename,
+  createQueueSnapshot,
+  extractFileName,
+  getAudioInfoFromElement
+} from './utils'; 

package/src/info.ts

@@ -0,0 +1,262 @@
+/**
+ * @fileoverview Audio information and progress tracking functions for the audio-channel-queue package
+ */
+
+import { 
+  AudioInfo, 
+  QueueSnapshot, 
+  ProgressCallback,
+  QueueChangeCallback,
+  AudioStartCallback,
+  AudioCompleteCallback,
+  ExtendedAudioQueueChannel
+} from './types';
+import { getAudioInfoFromElement, createQueueSnapshot } from './utils';
+import { setupProgressTracking, cleanupProgressTracking } from './events';
+
+/**
+ * Global array of extended audio queue channels
+ */
+export const audioChannels: ExtendedAudioQueueChannel[] = [];
+
+/**
+ * Gets current audio information for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns AudioInfo object or null if no audio is playing
+ * @example
+ * ```typescript
+ * const info = getCurrentAudioInfo(0);
+ * if (info) {
+ *   console.log(`Currently playing: ${info.fileName}`);
+ *   console.log(`Progress: ${(info.progress * 100).toFixed(1)}%`);
+ * }
+ * ```
+ */
+export const getCurrentAudioInfo = (channelNumber: number = 0): AudioInfo | null => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || channel.queue.length === 0) {
+    return null;
+  }
+
+  const currentAudio: HTMLAudioElement = channel.queue[0];
+  return getAudioInfoFromElement(currentAudio);
+};
+
+/**
+ * Gets audio information for all channels
+ * @returns Array of AudioInfo objects (null for channels with no audio)
+ * @example
+ * ```typescript
+ * const allInfo = getAllChannelsInfo();
+ * allInfo.forEach((info, channel) => {
+ *   if (info) {
+ *     console.log(`Channel ${channel}: ${info.fileName}`);
+ *   }
+ * });
+ * ```
+ */
+export const getAllChannelsInfo = (): (AudioInfo | null)[] => {
+  const allChannelsInfo: (AudioInfo | null)[] = [];
+  
+  for (let i = 0; i < audioChannels.length; i++) {
+    allChannelsInfo.push(getCurrentAudioInfo(i));
+  }
+  
+  return allChannelsInfo;
+};
+
+/**
+ * Gets a complete snapshot of the queue state for a specific channel
+ * @param channelNumber - The channel number
+ * @returns QueueSnapshot object or null if channel doesn't exist
+ * @example
+ * ```typescript
+ * const snapshot = getQueueSnapshot(0);
+ * if (snapshot) {
+ *   console.log(`Queue has ${snapshot.totalItems} items`);
+ *   console.log(`Currently playing: ${snapshot.items[0]?.fileName}`);
+ * }
+ * ```
+ */
+export const getQueueSnapshot = (channelNumber: number): QueueSnapshot | null => {
+  return createQueueSnapshot(channelNumber, audioChannels);
+};
+
+/**
+ * Subscribes to real-time progress updates for a specific channel
+ * @param channelNumber - The channel number
+ * @param callback - Function to call with audio info updates
+ * @example
+ * ```typescript
+ * onAudioProgress(0, (info) => {
+ *   updateProgressBar(info.progress);
+ *   updateTimeDisplay(info.currentTime, info.duration);
+ * });
+ * ```
+ */
+export const onAudioProgress = (channelNumber: number, callback: ProgressCallback): void => {
+  if (!audioChannels[channelNumber]) {
+    audioChannels[channelNumber] = { 
+      audioCompleteCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set()
+    };
+  }
+
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel.progressCallbacks) {
+    channel.progressCallbacks = new Map();
+  }
+
+  // Add callback for current audio if exists
+  if (channel.queue.length > 0) {
+    const currentAudio: HTMLAudioElement = channel.queue[0];
+    if (!channel.progressCallbacks.has(currentAudio)) {
+      channel.progressCallbacks.set(currentAudio, new Set());
+    }
+    channel.progressCallbacks.get(currentAudio)!.add(callback);
+    
+    // Set up tracking if not already done
+    setupProgressTracking(currentAudio, channelNumber, audioChannels);
+  }
+
+  // Store callback for future audio elements in this channel
+  if (!channel.progressCallbacks.has(null as any)) {
+    channel.progressCallbacks.set(null as any, new Set());
+  }
+  channel.progressCallbacks.get(null as any)!.add(callback);
+};
+
+/**
+ * Removes progress listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioProgress(0); // Stop receiving progress updates for channel 0
+ * ```
+ */
+export const offAudioProgress = (channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || !channel.progressCallbacks) return;
+
+  // Clean up event listeners for current audio if exists
+  if (channel.queue.length > 0) {
+    const currentAudio: HTMLAudioElement = channel.queue[0];
+    cleanupProgressTracking(currentAudio, channelNumber, audioChannels);
+  }
+
+  // Clear all callbacks for this channel
+  channel.progressCallbacks.clear();
+};
+
+/**
+ * Subscribes to queue change events for a specific channel
+ * @param channelNumber - The channel number to monitor
+ * @param callback - Function to call when queue changes
+ * @example
+ * ```typescript
+ * onQueueChange(0, (snapshot) => {
+ *   updateQueueDisplay(snapshot.items);
+ *   updateQueueCount(snapshot.totalItems);
+ * });
+ * ```
+ */
+export const onQueueChange = (channelNumber: number, callback: QueueChangeCallback): void => {
+  if (!audioChannels[channelNumber]) {
+    audioChannels[channelNumber] = { 
+      audioCompleteCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set()
+    };
+  }
+
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel.queueChangeCallbacks) {
+    channel.queueChangeCallbacks = new Set();
+  }
+
+  channel.queueChangeCallbacks.add(callback);
+};
+
+/**
+ * Removes queue change listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offQueueChange(0); // Stop receiving queue change notifications for channel 0
+ * ```
+ */
+export const offQueueChange = (channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || !channel.queueChangeCallbacks) return;
+
+  channel.queueChangeCallbacks.clear();
+};
+
+/**
+ * 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
+ * @example
+ * ```typescript
+ * onAudioStart(0, (info) => {
+ *   showNowPlaying(info.fileName);
+ *   setTotalDuration(info.duration);
+ * });
+ * ```
+ */
+export const onAudioStart = (channelNumber: number, callback: AudioStartCallback): void => {
+  if (!audioChannels[channelNumber]) {
+    audioChannels[channelNumber] = { 
+      audioCompleteCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set()
+    };
+  }
+
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel.audioStartCallbacks) {
+    channel.audioStartCallbacks = new Set();
+  }
+
+  channel.audioStartCallbacks.add(callback);
+};
+
+/**
+ * Subscribes to audio complete events for a specific channel
+ * @param channelNumber - The channel number to monitor
+ * @param callback - Function to call when audio completes
+ * @example
+ * ```typescript
+ * onAudioComplete(0, (info) => {
+ *   logPlaybackComplete(info.fileName);
+ *   if (info.remainingInQueue === 0) {
+ *     showQueueComplete();
+ *   }
+ * });
+ * ```
+ */
+export const onAudioComplete = (channelNumber: number, callback: AudioCompleteCallback): void => {
+  if (!audioChannels[channelNumber]) {
+    audioChannels[channelNumber] = { 
+      audioCompleteCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set()
+    };
+  }
+
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel.audioCompleteCallbacks) {
+    channel.audioCompleteCallbacks = new Set();
+  }
+
+  channel.audioCompleteCallbacks.add(callback);
+}; 

package/src/types.ts

@@ -0,0 +1,127 @@
+/**
+ * @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;
+}
+
+/**
+ * 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 currently playing */
+  isPlaying: boolean;
+  /** Playback progress as a decimal (0-1) */
+  progress: number;
+  /** Audio file source URL */
+  src: string;
+}
+
+/**
+ * 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;
+  /** Audio file source URL */
+  src: string;
+}
+
+/**
+ * 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;
+  /** Array of audio items in the queue with their metadata */
+  items: QueueItem[];
+  /** Total number of items in the queue */
+  totalItems: 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;
+
+/**
+ * Extended audio queue channel with event callback management
+ */
+export type ExtendedAudioQueueChannel = AudioQueueChannel & {
+  /** Set of callbacks for audio completion events */
+  audioCompleteCallbacks?: Set<AudioCompleteCallback>;
+  /** Set of callbacks for audio start events */
+  audioStartCallbacks?: Set<AudioStartCallback>;
+  /** Map of audio elements to their progress callback sets */
+  progressCallbacks?: Map<HTMLAudioElement, Set<ProgressCallback>>;
+  /** Set of callbacks for queue change events */
+  queueChangeCallbacks?: Set<QueueChangeCallback>;
+}