audio-channel-queue 1.4.0 → 1.6.0

package/src/info.ts

@@ -0,0 +1,380 @@
+/**
+ * @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';
+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, channelNumber, audioChannels);
+};
+
+/**
+ * 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(),
+      audioPauseCallbacks: new Set(),
+      audioResumeCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      isPaused: false,
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set(),
+      volume: 1.0
+    };
+  }
+
+  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(),
+      audioPauseCallbacks: new Set(),
+      audioResumeCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      isPaused: false,
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set(),
+      volume: 1.0
+    };
+  }
+
+  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(),
+      audioPauseCallbacks: new Set(),
+      audioResumeCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      isPaused: false,
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set(),
+      volume: 1.0
+    };
+  }
+
+  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(),
+      audioPauseCallbacks: new Set(),
+      audioResumeCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      isPaused: false,
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set(),
+      volume: 1.0
+    };
+  }
+
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel.audioCompleteCallbacks) {
+    channel.audioCompleteCallbacks = new Set();
+  }
+
+  channel.audioCompleteCallbacks.add(callback);
+};
+
+/**
+ * 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
+ * @example
+ * ```typescript
+ * onAudioPause(0, (channelNumber, info) => {
+ *   showPauseIndicator();
+ *   logPauseEvent(info.fileName, info.currentTime);
+ * });
+ * ```
+ */
+export const onAudioPause = (channelNumber: number, callback: AudioPauseCallback): void => {
+  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: 1.0
+    };
+  }
+
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel.audioPauseCallbacks) {
+    channel.audioPauseCallbacks = new Set();
+  }
+
+  channel.audioPauseCallbacks.add(callback);
+};
+
+/**
+ * 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
+ * @example
+ * ```typescript
+ * onAudioResume(0, (channelNumber, info) => {
+ *   hidePauseIndicator();
+ *   logResumeEvent(info.fileName, info.currentTime);
+ * });
+ * ```
+ */
+export const onAudioResume = (channelNumber: number, callback: AudioResumeCallback): void => {
+  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: 1.0
+    };
+  }
+
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel.audioResumeCallbacks) {
+    channel.audioResumeCallbacks = new Set();
+  }
+
+  channel.audioResumeCallbacks.add(callback);
+};
+
+/**
+ * Removes pause event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioPause(0); // Stop receiving pause notifications for channel 0
+ * ```
+ */
+export const offAudioPause = (channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || !channel.audioPauseCallbacks) return;
+
+  channel.audioPauseCallbacks.clear();
+};
+
+/**
+ * Removes resume event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioResume(0); // Stop receiving resume notifications for channel 0
+ * ```
+ */
+export const offAudioResume = (channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel || !channel.audioResumeCallbacks) return;
+
+  channel.audioResumeCallbacks.clear();
+}; 

package/src/pause.ts

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview Pause and resume management functions for the audio-channel-queue package
+ */
+
+import { ExtendedAudioQueueChannel, AudioInfo } from './types';
+import { audioChannels } from './info';
+import { getAudioInfoFromElement } from './utils';
+import { emitAudioPause, emitAudioResume } from './events';
+
+/**
+ * Pauses the currently playing audio in a specific channel
+ * @param channelNumber - The channel number to pause (defaults to 0)
+ * @returns Promise that resolves when the audio is paused
+ * @example
+ * ```typescript
+ * await pauseChannel(0); // Pause audio in channel 0
+ * await pauseChannel(); // Pause audio in default channel
+ * ```
+ */
+export const pauseChannel = async (channelNumber: number = 0): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  
+  if (channel && channel.queue.length > 0) {
+    const currentAudio: HTMLAudioElement = channel.queue[0];
+    
+    if (!currentAudio.paused && !currentAudio.ended) {
+      currentAudio.pause();
+      channel.isPaused = true;
+      
+      const audioInfo: AudioInfo | null = getAudioInfoFromElement(currentAudio, channelNumber, audioChannels);
+      if (audioInfo) {
+        emitAudioPause(channelNumber, audioInfo, audioChannels);
+      }
+    }
+  }
+};
+
+/**
+ * Resumes the currently paused audio in a specific channel
+ * @param channelNumber - The channel number to resume (defaults to 0)
+ * @returns Promise that resolves when the audio starts playing
+ * @example
+ * ```typescript
+ * await resumeChannel(0); // Resume audio in channel 0
+ * await resumeChannel(); // Resume audio in default channel
+ * ```
+ */
+export const resumeChannel = async (channelNumber: number = 0): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  
+  if (channel && channel.queue.length > 0) {
+    const currentAudio: HTMLAudioElement = channel.queue[0];
+    
+    // Only resume if both the channel is marked as paused AND the audio element is actually paused
+    if (channel.isPaused && currentAudio.paused && !currentAudio.ended) {
+      await currentAudio.play();
+      channel.isPaused = false;
+      
+      const audioInfo: AudioInfo | null = getAudioInfoFromElement(currentAudio, channelNumber, audioChannels);
+      if (audioInfo) {
+        emitAudioResume(channelNumber, audioInfo, audioChannels);
+      }
+    }
+  }
+};
+
+/**
+ * Toggles pause/resume state for a specific channel
+ * @param channelNumber - The channel number to toggle (defaults to 0)
+ * @returns Promise that resolves when the toggle is complete
+ * @example
+ * ```typescript
+ * await togglePauseChannel(0); // Toggle pause state for channel 0
+ * ```
+ */
+export const togglePauseChannel = async (channelNumber: number = 0): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  
+  if (channel && channel.queue.length > 0) {
+    const currentAudio: HTMLAudioElement = channel.queue[0];
+    
+    if (currentAudio.paused) {
+      await resumeChannel(channelNumber);
+    } else {
+      await pauseChannel(channelNumber);
+    }
+  }
+};
+
+/**
+ * Pauses all currently playing audio across all channels
+ * @returns Promise that resolves when all audio is paused
+ * @example
+ * ```typescript
+ * await pauseAllChannels(); // Pause everything
+ * ```
+ */
+export const pauseAllChannels = async (): Promise<void> => {
+  const pausePromises: Promise<void>[] = [];
+  
+  audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
+    pausePromises.push(pauseChannel(index));
+  });
+  
+  await Promise.all(pausePromises);
+};
+
+/**
+ * Resumes all currently paused audio across all channels
+ * @returns Promise that resolves when all audio is resumed
+ * @example
+ * ```typescript
+ * await resumeAllChannels(); // Resume everything that was paused
+ * ```
+ */
+export const resumeAllChannels = async (): Promise<void> => {
+  const resumePromises: Promise<void>[] = [];
+  
+  audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
+    resumePromises.push(resumeChannel(index));
+  });
+  
+  await Promise.all(resumePromises);
+};
+
+/**
+ * Checks if a specific channel is currently paused
+ * @param channelNumber - The channel number to check (defaults to 0)
+ * @returns True if the channel is paused, false otherwise
+ * @example
+ * ```typescript
+ * const isPaused = isChannelPaused(0);
+ * console.log(`Channel 0 is ${isPaused ? 'paused' : 'playing'}`);
+ * ```
+ */
+export const isChannelPaused = (channelNumber: number = 0): boolean => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  return channel?.isPaused || false;
+};
+
+/**
+ * Gets the pause state of all channels
+ * @returns Array of boolean values indicating pause state for each channel
+ * @example
+ * ```typescript
+ * const pauseStates = getAllChannelsPauseState();
+ * pauseStates.forEach((isPaused, index) => {
+ *   console.log(`Channel ${index}: ${isPaused ? 'paused' : 'playing'}`);
+ * });
+ * ```
+ */
+export const getAllChannelsPauseState = (): boolean[] => {
+  return audioChannels.map((channel: ExtendedAudioQueueChannel) => 
+    channel?.isPaused || false
+  );
+};
+
+/**
+ * Toggles pause/resume state for all channels globally
+ * If any channels are currently playing, all channels will be paused
+ * If all channels are paused, all channels will be resumed
+ * @returns Promise that resolves when the toggle is complete
+ * @example
+ * ```typescript
+ * await togglePauseAllChannels(); // Pause all if any are playing, resume all if all are paused
+ * ```
+ */
+export const togglePauseAllChannels = async (): Promise<void> => {
+  let hasPlayingChannel: boolean = false;
+  
+  // Check if any channel is currently playing
+  for (let i = 0; i < audioChannels.length; i++) {
+    const channel: ExtendedAudioQueueChannel = audioChannels[i];
+    if (channel && channel.queue.length > 0) {
+      const currentAudio: HTMLAudioElement = channel.queue[0];
+      if (!currentAudio.paused && !currentAudio.ended) {
+        hasPlayingChannel = true;
+        break;
+      }
+    }
+  }
+  
+  // If any channel is playing, pause all channels
+  // If no channels are playing, resume all channels
+  if (hasPlayingChannel) {
+    await pauseAllChannels();
+  } else {
+    await resumeAllChannels();
+  }
+};