audio-channel-queue 1.5.0 → 1.7.0

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 AND not ended
+    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();
+  }
+}; 

package/src/types.ts

@@ -1,127 +1,236 @@
-/**
- * @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>;
+/**
+ * @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;
+
+/**
+ * Information about an audio error that occurred
+ */
+export interface AudioErrorInfo {
+  channelNumber: number;
+  src: string;
+  fileName: string;
+  error: Error;
+  errorType: 'network' | 'decode' | 'unsupported' | 'permission' | 'abort' | 'timeout' | 'unknown';
+  timestamp: number;
+  retryAttempt?: number;
+  remainingInQueue: number;
+}
+
+/**
+ * Configuration for automatic retry behavior when audio fails to load or play
+ */
+export interface RetryConfig {
+  enabled: boolean;
+  maxRetries: number;
+  baseDelay: number;
+  exponentialBackoff: boolean;
+  timeoutMs: number;
+  fallbackUrls?: string[];
+  skipOnFailure: boolean;
+}
+
+/**
+ * Configuration options for error recovery mechanisms
+ */
+export interface ErrorRecoveryOptions {
+  autoRetry: boolean;
+  showUserFeedback: boolean;
+  logErrorsToAnalytics: boolean;
+  preserveQueueOnError: boolean;
+  fallbackToNextTrack: boolean;
+}
+
+/**
+ * Callback function type for audio error events
+ */
+export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
+
+/**
+ * Extended audio queue channel with error handling capabilities
+ */
+export interface ExtendedAudioQueueChannel {
+  audioCompleteCallbacks: Set<AudioCompleteCallback>;
+  audioErrorCallbacks: Set<AudioErrorCallback>;
+  audioPauseCallbacks: Set<AudioPauseCallback>;
+  audioResumeCallbacks: Set<AudioResumeCallback>;
+  audioStartCallbacks: Set<AudioStartCallback>;
+  isPaused?: boolean;
+  progressCallbacks: Map<HTMLAudioElement | null, Set<ProgressCallback>>;
+  queue: HTMLAudioElement[];
+  queueChangeCallbacks: Set<QueueChangeCallback>;
+  retryConfig?: RetryConfig;
+  volume?: number;
+  volumeConfig?: VolumeConfig;
 }