audio-channel-queue 1.6.0 → 1.8.0

package/src/types.ts

@@ -29,7 +29,7 @@ export interface VolumeConfig {
   /** 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';
+  transitionEasing?: EasingType;
 }
 
 /**
@@ -175,25 +175,106 @@ export type AudioPauseCallback = (channelNumber: number, audioInfo: AudioInfo) =
 export type AudioResumeCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
 
 /**
- * Extended audio queue channel with event callback management and additional features
+ * Information about an audio error that occurred
  */
-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 */
+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>;
+  fadeState?: ChannelFadeState;
   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) */
+  progressCallbacks: Map<HTMLAudioElement | null, Set<ProgressCallback>>;
+  queue: HTMLAudioElement[];
+  queueChangeCallbacks: Set<QueueChangeCallback>;
+  retryConfig?: RetryConfig;
   volume?: number;
-  /** Volume ducking configuration for this channel */
   volumeConfig?: VolumeConfig;
+}
+
+/**
+ * Easing function types for volume transitions
+ */
+export enum EasingType {
+  Linear = 'linear',
+  EaseIn = 'ease-in',
+  EaseOut = 'ease-out',
+  EaseInOut = 'ease-in-out'
+}
+
+/**
+ * Fade type for pause/resume operations with integrated volume transitions
+ */
+export enum FadeType {
+  Linear = 'linear',
+  Gentle = 'gentle',
+  Dramatic = 'dramatic'
+}
+
+/**
+ * Configuration for fade transitions
+ */
+export interface FadeConfig {
+  /** Duration in milliseconds for the fade transition */
+  duration: number;
+  /** Easing curve to use when pausing (fading out) */
+  pauseCurve: EasingType;
+  /** Easing curve to use when resuming (fading in) */
+  resumeCurve: EasingType;
+}
+
+/**
+ * Internal fade state tracking for pause/resume with fade functionality
+ */
+export interface ChannelFadeState {
+  /** The original volume level before fading began */
+  originalVolume: number;
+  /** The type of fade being used */
+  fadeType: FadeType;
+  /** Whether the channel is currently paused due to fade */
+  isPaused: boolean;
 }