audio-channel-queue 1.4.0 → 1.5.0

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @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>;
+};

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * @fileoverview Type definitions for the audio-channel-queue package
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Utility functions for the audio-channel-queue package
+ */
+import { AudioInfo, QueueSnapshot, ExtendedAudioQueueChannel } 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 declare const extractFileName: (url: string) => string;
+/**
+ * Extracts comprehensive audio information from an HTMLAudioElement
+ * @param audio - The HTML audio element to extract information from
+ * @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)
+ * ```
+ */
+export declare const getAudioInfoFromElement: (audio: HTMLAudioElement) => AudioInfo | null;
+/**
+ * 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 declare const createQueueSnapshot: (channelNumber: number, audioChannels: ExtendedAudioQueueChannel[]) => QueueSnapshot | null;
+/**
+ * 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 declare const cleanWebpackFilename: (fileName: string) => string;

package/dist/utils.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * @fileoverview Utility functions for the audio-channel-queue package
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanWebpackFilename = exports.createQueueSnapshot = exports.getAudioInfoFromElement = exports.extractFileName = void 0;
+/**
+ * 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'
+ * ```
+ */
+const extractFileName = (url) => {
+    try {
+        const urlObj = new URL(url);
+        const pathname = urlObj.pathname;
+        const segments = pathname.split('/');
+        const fileName = segments[segments.length - 1];
+        return fileName || 'unknown';
+    }
+    catch (_a) {
+        // If URL parsing fails, try simple string manipulation
+        const segments = url.split('/');
+        const fileName = segments[segments.length - 1];
+        return fileName || 'unknown';
+    }
+};
+exports.extractFileName = extractFileName;
+/**
+ * Extracts comprehensive audio information from an HTMLAudioElement
+ * @param audio - The HTML audio element to extract information from
+ * @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)
+ * ```
+ */
+const getAudioInfoFromElement = (audio) => {
+    if (!audio)
+        return null;
+    const duration = isNaN(audio.duration) ? 0 : audio.duration * 1000; // Convert to milliseconds
+    const currentTime = isNaN(audio.currentTime) ? 0 : audio.currentTime * 1000; // Convert to milliseconds
+    const progress = duration > 0 ? Math.min(currentTime / duration, 1) : 0;
+    const isPlaying = !audio.paused && !audio.ended && audio.readyState > 2;
+    return {
+        currentTime,
+        duration,
+        fileName: (0, exports.extractFileName)(audio.src),
+        isPlaying,
+        progress,
+        src: audio.src
+    };
+};
+exports.getAudioInfoFromElement = getAudioInfoFromElement;
+/**
+ * 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`);
+ * ```
+ */
+const createQueueSnapshot = (channelNumber, audioChannels) => {
+    const channel = audioChannels[channelNumber];
+    if (!channel)
+        return null;
+    const items = channel.queue.map((audio, index) => ({
+        duration: isNaN(audio.duration) ? 0 : audio.duration * 1000,
+        fileName: (0, exports.extractFileName)(audio.src),
+        isCurrentlyPlaying: index === 0 && !audio.paused && !audio.ended,
+        src: audio.src
+    }));
+    return {
+        channelNumber,
+        currentIndex: 0, // Current playing is always index 0 in our queue structure
+        items,
+        totalItems: channel.queue.length
+    };
+};
+exports.createQueueSnapshot = createQueueSnapshot;
+/**
+ * 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)
+ * ```
+ */
+const cleanWebpackFilename = (fileName) => {
+    // Remove webpack hash pattern: filename.hash.ext → filename.ext
+    return fileName.replace(/\.[a-f0-9]{8,}\./i, '.');
+};
+exports.cleanWebpackFilename = cleanWebpackFilename;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "audio-channel-queue",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Allows you to queue audio files to different playback channels.",
-  "main": "dist/audio.js",
-  "types": "dist/audio.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist",
     "src"
@@ -11,7 +11,9 @@
   "scripts": {
     "build": "tsc",
     "prepare": "npm run build",
-    "test": "jest"
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "repository": {
     "type": "git",
@@ -32,6 +34,7 @@
   "devDependencies": {
     "@types/jest": "^29.5.13",
     "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "ts-jest": "^29.2.5",
     "typescript": "^5.6.2"
   }

package/src/core.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Core queue management functions for the audio-channel-queue package
+ */
+
+import { ExtendedAudioQueueChannel } from './types';
+import { audioChannels } from './info';
+import { extractFileName } from './utils';
+import { 
+  emitQueueChange, 
+  emitAudioStart, 
+  emitAudioComplete, 
+  setupProgressTracking, 
+  cleanupProgressTracking 
+} from './events';
+
+/**
+ * Queues an audio file to a specific channel and starts playing if it's the first in queue
+ * @param audioUrl - The URL of the audio file to queue
+ * @param channelNumber - The channel number to queue the audio to (defaults to 0)
+ * @returns Promise that resolves when the audio is queued and starts playing (if first in queue)
+ * @example
+ * ```typescript
+ * await queueAudio('https://example.com/song.mp3', 0);
+ * await queueAudio('./sounds/notification.wav'); // Uses default channel 0
+ * ```
+ */
+export const queueAudio = async (audioUrl: string, channelNumber: number = 0): Promise<void> => {
+  if (!audioChannels[channelNumber]) {
+    audioChannels[channelNumber] = { 
+      audioCompleteCallbacks: new Set(),
+      audioStartCallbacks: new Set(),
+      progressCallbacks: new Map(),
+      queue: [],
+      queueChangeCallbacks: new Set()
+    };
+  }
+
+  const audio: HTMLAudioElement = new Audio(audioUrl);
+  audioChannels[channelNumber].queue.push(audio);
+
+  emitQueueChange(channelNumber, audioChannels);
+
+  if (audioChannels[channelNumber].queue.length === 1) {
+    playAudioQueue(channelNumber);
+  }
+};
+
+/**
+ * Plays the audio queue for a specific channel
+ * @param channelNumber - The channel number to play
+ * @returns Promise that resolves when the current audio finishes playing
+ * @example
+ * ```typescript
+ * await playAudioQueue(0); // Play queue for channel 0
+ * ```
+ */
+export const playAudioQueue = async (channelNumber: number): Promise<void> => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+
+  if (channel.queue.length === 0) return;
+
+  const currentAudio: HTMLAudioElement = channel.queue[0];
+
+  setupProgressTracking(currentAudio, channelNumber, audioChannels);
+
+  return new Promise<void>((resolve) => {
+    let hasStarted: boolean = false;
+    let metadataLoaded: boolean = false;
+    let playStarted: boolean = false;
+    
+    // Check if we should fire onAudioStart (both conditions met)
+    const tryFireAudioStart = (): void => {
+      if (!hasStarted && metadataLoaded && playStarted) {
+        hasStarted = true;
+        emitAudioStart(channelNumber, {
+          channelNumber,
+          duration: currentAudio.duration * 1000, // Now guaranteed to have valid duration
+          fileName: extractFileName(currentAudio.src),
+          src: currentAudio.src
+        }, audioChannels);
+      }
+    };
+
+    // Event handler for when metadata loads (duration becomes available)
+    const handleLoadedMetadata = (): void => {
+      metadataLoaded = true;
+      tryFireAudioStart();
+    };
+
+    // Event handler for when audio actually starts playing
+    const handlePlay = (): void => {
+      playStarted = true;
+      tryFireAudioStart();
+    };
+
+    // Event handler for when audio ends
+    const handleEnded = async (): Promise<void> => {
+      emitAudioComplete(channelNumber, {
+        channelNumber,
+        fileName: extractFileName(currentAudio.src),
+        remainingInQueue: channel.queue.length - 1,
+        src: currentAudio.src
+      }, audioChannels);
+
+      // Clean up event listeners
+      currentAudio.removeEventListener('loadedmetadata', handleLoadedMetadata);
+      currentAudio.removeEventListener('play', handlePlay);
+      currentAudio.removeEventListener('ended', handleEnded);
+      
+      cleanupProgressTracking(currentAudio, channelNumber, audioChannels);
+      channel.queue.shift();
+      
+      // Emit queue change after completion
+      setTimeout(() => emitQueueChange(channelNumber, audioChannels), 10);
+      
+      await playAudioQueue(channelNumber);
+      resolve();
+    };
+
+    // Add event listeners
+    currentAudio.addEventListener('loadedmetadata', handleLoadedMetadata);
+    currentAudio.addEventListener('play', handlePlay);
+    currentAudio.addEventListener('ended', handleEnded);
+
+    // Check if metadata is already loaded (in case it loads before we add the listener)
+    if (currentAudio.readyState >= 1) { // HAVE_METADATA or higher
+      metadataLoaded = true;
+    }
+
+    currentAudio.play();
+  });
+};
+
+/**
+ * Stops the currently playing audio in a specific channel and plays the next audio in queue
+ * @param channelNumber - The channel number (defaults to 0)
+ * @example
+ * ```typescript
+ * stopCurrentAudioInChannel(0); // Stop current audio in channel 0
+ * stopCurrentAudioInChannel(); // Stop current audio in default channel
+ * ```
+ */
+export const stopCurrentAudioInChannel = (channelNumber: number = 0): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (channel && channel.queue.length > 0) {
+    const currentAudio: HTMLAudioElement = channel.queue[0];
+    
+    emitAudioComplete(channelNumber, {
+      channelNumber,
+      fileName: extractFileName(currentAudio.src),
+      remainingInQueue: channel.queue.length - 1,
+      src: currentAudio.src
+    }, audioChannels);
+
+    currentAudio.pause();
+    cleanupProgressTracking(currentAudio, channelNumber, audioChannels);
+    channel.queue.shift();
+
+    emitQueueChange(channelNumber, audioChannels);
+    
+    playAudioQueue(channelNumber);
+  }
+};
+
+/**
+ * Stops all audio in a specific channel and clears the entire queue
+ * @param channelNumber - The channel number (defaults to 0)
+ * @example
+ * ```typescript
+ * stopAllAudioInChannel(0); // Clear all audio in channel 0
+ * stopAllAudioInChannel(); // Clear all audio in default channel
+ * ```
+ */
+export const stopAllAudioInChannel = (channelNumber: number = 0): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (channel) {
+    if (channel.queue.length > 0) {
+      const currentAudio: HTMLAudioElement = channel.queue[0];
+      
+      emitAudioComplete(channelNumber, {
+        channelNumber,
+        fileName: extractFileName(currentAudio.src),
+        remainingInQueue: 0, // Will be 0 since we're clearing the queue
+        src: currentAudio.src
+      }, audioChannels);
+
+      currentAudio.pause();
+      cleanupProgressTracking(currentAudio, channelNumber, audioChannels);
+    }
+    // Clean up all progress tracking for this channel
+    channel.queue.forEach(audio => cleanupProgressTracking(audio, channelNumber, audioChannels));
+    channel.queue = [];
+    
+    emitQueueChange(channelNumber, audioChannels);
+  }
+};
+
+/**
+ * Stops all audio across all channels and clears all queues
+ * @example
+ * ```typescript
+ * stopAllAudio(); // Emergency stop - clears everything
+ * ```
+ */
+export const stopAllAudio = (): void => {
+  audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
+    stopAllAudioInChannel(index);
+  });
+};