audioq 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TONY CARPENTER
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,486 @@
+# AudioQ
+The purpose of this package is to help manage the playback of audio files. 
+
+🎵 [Demo](https://tonycarpenter21.github.io/audio-queue-demo/queue-management)
+
+📚 [Docs](https://tonycarpenter21.github.io/audio-queue-docs/)
+
+## Key Features
+
+- **Multi-channel queue management** - Independent audio queues for concurrent playback
+- **Pause/Resume functionality** - Full playback control for individual channels or all channels
+- **Volume control with ducking** - Dynamic volume management, global volume control, and automatic background audio reduction
+- **Loop support** - Seamless audio looping for background music and ambient sounds
+- **Priority queueing** - Add urgent audio to the front of any queue
+- **Real-time progress tracking** - Comprehensive playback monitoring and metadata
+- **Event-driven architecture** - Extensive callback system for UI integration
+- **TypeScript support** - Full type definitions and IntelliSense support
+- **Zero dependencies** - Lightweight and self-contained
+- **Backward compatible** - All existing APIs continue to work
+
+This package offers TypeScript support, has zero dependencies, and is released under the MIT license.
+
+To preview this package and see how it works with visualized code examples, check out the demo that can be found here: [AudioQ Demo](https://tonycarpenter21.github.io/audio-queue-demo/). (A link to the demo repo can be found here: [AudioQ Demo Repo](https://github.com/tonycarpenter21/audio-queue-demo).)
+
+NPM package can be found [here](https://www.npmjs.com/package/audioq).
+
+GitHub Repo can be found [here](https://github.com/tonycarpenter21/audioq).
+
+Documentation can be found [here](https://tonycarpenter21.github.io/audio-queue-docs/)
+
+## 🌐 Browser Compatibility
+
+This package is designed for **browser environments** and uses the Web Audio API (`HTMLAudioElement`). It is **not** intended for Node.js server-side use.
+
+### **Supported Browsers:**
+- **Chrome 51+** (June 2016)
+- **Firefox 54+** (June 2017)  
+- **Safari 10+** (September 2016)
+- **Edge 15+** (April 2017)
+- **Mobile browsers** with HTML5 audio support
+
+### **Development Requirements:**
+- **Node.js 14+** (for building and testing only)
+- **TypeScript 4.5+** (included in devDependencies)
+
+### **Not Supported:**
+- Node.js server environments (no HTMLAudioElement)
+- Internet Explorer (lacks ES6 support)
+- Web Workers (no DOM access)
+
+## Architecture & Code Organization 🏗️
+
+Modular architecture for maintainability and extensibility:
+
+```
+src/
+├── index.ts     # Main entry point with organized exports
+├── types.ts     # TypeScript interfaces and type definitions  
+├── core.ts      # Core queue management functions
+├── pause.ts     # Pause and resume functionality
+├── volume.ts    # Volume control and ducking management
+├── info.ts      # Audio information and progress tracking
+├── events.ts    # Event handling and emission logic
+└── utils.ts     # Helper functions and utilities
+```
+
+## How To Install This Package:
+Install this package by running either of these commands (typescript packages are included automatically):
+- For npm run `npm install audioq`
+- For yarn run `yarn add audioq`
+
+## Basic Queue Management Functions:
+
+### Queue Audio
+```typescript
+// Add an audio file to the queue and start playing it automatically.
+queueAudio(audioUrl, channelNumber?, options?);
+await queueAudio('hello.mp3'); // Add to default channel 0
+await queueAudio('laser.mp3', 1, { loop: true, volume: 0.8 }); // Add to channel 1 with options
+```
+
+
+### Queue Audio with Priority
+```typescript
+// Add a file to the front of the queue (plays after current audio finishes).
+queueAudioPriority(audioUrl, channelNumber?, options?);
+await queueAudioPriority('urgent.mp3'); // Add to front of default channel 0
+await queueAudioPriority('announcement.mp3', 1, { volume: 1.0 }); // Add to front of channel 1
+```
+
+
+### Stop Current Audio
+```typescript
+// Stop the current audio and automatically start playing the next one in queue.
+stopCurrentAudioInChannel(channelNumber?);
+await stopCurrentAudioInChannel(); // Stop current audio in default channel (0)
+await stopCurrentAudioInChannel(2); // Stop current audio in channel 2
+```
+
+
+### Stop All Audio in Channel
+```typescript
+// Stop all audio in a channel and remove all enqueued files.
+stopAllAudioInChannel(channelNumber?);
+await stopAllAudioInChannel(); // Stop and clear all audio in default channel (0)
+await stopAllAudioInChannel(1); // Stop and clear all audio in channel 1
+```
+
+### Stop All Audio
+```typescript
+// Stop all audio in all channels and remove all enqueued files.
+await stopAllAudio();
+```
+
+## 🔄 Advanced Queue Manipulation:
+
+### Remove Queued Item
+```typescript
+// Remove a specific item from the queue by its position (cannot remove currently playing item at index 0).
+removeQueuedItem(queuedSlotNumber, channelNumber?);
+const result = await removeQueuedItem(2); // Remove item at index 2 from default channel (0)
+const result = await removeQueuedItem(1, 1); // Remove item at index 1 from channel 1
+```
+
+### Reorder Queue Items
+```typescript
+// Move a queue item from one position to another (cannot move currently playing item at index 0).
+reorderQueue(currentQueuedSlotNumber, newQueuedSlotNumber, channelNumber?);
+const result = await reorderQueue(3, 1); // Move item from index 3 to index 1 in default channel (0)
+const result = await reorderQueue(2, 4, 1); // Move item from index 2 to index 4 in channel 1
+```
+
+### Clear Queue After Current
+```typescript
+// Remove all items from the queue except the currently playing audio.
+clearQueueAfterCurrent(channelNumber?);
+const result = await clearQueueAfterCurrent(); // Clear queue after current in default channel (0)
+const result = await clearQueueAfterCurrent(2); // Clear queue after current in channel 2
+```
+
+### Swap Queue Items
+```typescript
+// Swap the positions of two items in the queue (cannot involve currently playing item at index 0).
+swapQueueItems(firstQueuedSlotNumber, secondQueuedSlotNumber, channelNumber?);
+const result = await swapQueueItems(1, 3); // Swap items at index 1 and 3 in default channel (0)
+const result = await swapQueueItems(2, 4, 1); // Swap items at index 2 and 4 in channel 1
+```
+
+### Get Queue Item Info
+```typescript
+// Get information about a specific item in the queue.
+getQueueItemInfo(queuedSlotNumber, channelNumber?);
+const itemInfo = getQueueItemInfo(1); // Get info for item at index 1 in default channel (0)
+const info = getQueueItemInfo(2, 1); // Get info for item at index 2 in channel 1
+```
+
+### Get Queue Length
+```typescript
+// Get the total number of items in a channel's queue.
+getQueueLength(channelNumber?);
+const length = getQueueLength(); // Get queue length for default channel (0)
+const count = getQueueLength(2); // Get queue length for channel 2
+```
+
+```typescript
+// All queue manipulation functions return a QueueManipulationResult:
+interface QueueManipulationResult {
+  success: boolean;          // Whether the operation was successful
+  error?: string;            // Error message if operation failed
+  updatedQueue?: QueueSnapshot; // The queue snapshot after the operation (if successful)
+}
+```
+
+## 🎛️ Volume Control Functions:
+
+### Set Channel Volume
+```typescript
+// Set the volume for a specific channel (0-1 range).
+setChannelVolume(channelNumber, volume);
+await setChannelVolume(0, 0.5); // Set channel 0 to 50% volume
+await setChannelVolume(1, 0.8); // Set channel 1 to 80% volume
+```
+
+### Get Channel Volume
+```typescript
+// Get the current volume level for a specific channel.
+getChannelVolume(channelNumber?);
+const volume = getChannelVolume(); // Get default channel (0) volume
+console.log(`Channel volume: ${(getChannelVolume(2) * 100).toFixed(0)}%`); // Get channel 2 volume
+```
+
+### Set All Channels Volume
+```typescript
+// Set the same volume level for all channels.
+setAllChannelsVolume(volume);
+await setAllChannelsVolume(0.6); // Set all channels to 60% volume
+await setAllChannelsVolume(0.0); // Mute all channels
+```
+
+### Global Volume Control
+```typescript
+// Set a global volume multiplier that affects all channels while preserving their relative levels.
+setGlobalVolume(volume);
+await setGlobalVolume(0.5); // Set global volume to 50%
+```
+
+```typescript
+// Get the current global volume level.
+getGlobalVolume();
+const globalVol = getGlobalVolume(); // Returns current global volume (0-1)
+console.log(`Global volume: ${(getGlobalVolume() * 100).toFixed(0)}%`);
+```
+
+**How Global Volume Works:**
+The global volume acts as a **global volume multiplier** - it scales all channel volumes proportionally while preserving their individual settings. This is perfect for implementing a global volume slider in your UI.
+
+```typescript
+// Example: Setting up different audio types with a global volume control
+await setChannelVolume(0, 0.3); // SFX channel at 30%
+await setChannelVolume(1, 0.7); // Music channel at 70%
+await setChannelVolume(2, 0.5); // Voice channel at 50%
+
+// User adjusts global volume slider to 50%
+await setGlobalVolume(0.5);
+
+// Actual playback volumes become:
+// - SFX: 30% × 50% = 15%
+// - Music: 70% × 50% = 35%
+// - Voice: 50% × 50% = 25%
+
+// Channel volumes remain at their original settings (0.3, 0.7, 0.5)
+// So when global volume is increased, ratios are preserved
+await setGlobalVolume(1.0); // Back to full volume
+// - SFX: 30% × 100% = 30%
+// - Music: 70% × 100% = 70%
+// - Voice: 50% × 100% = 50%
+```
+
+**Note:** `setAllChannelsVolume()` sets all channels to the **same** volume, while `setGlobalVolume()` **multiplies** all channels by the same amount, preserving their relative differences.
+
+### Volume Ducking (Background Audio Reduction)
+```typescript
+// Automatically reduce other channels' volume when priority audio plays.
+setVolumeDucking(config);
+setVolumeDucking({ priorityChannel: 1, duckingVolume: 0.2 }); // Simple ducking
+setVolumeDucking({
+  priorityChannel: 1,
+  priorityVolume: 1.0,
+  duckingVolume: 0.2,
+  transitionDuration: 500
+}); // Full configuration
+```
+
+```typescript
+// Remove volume ducking configuration from all channels.
+clearVolumeDucking();
+```
+
+## ⏯️ Pause/Resume Functions:
+
+### Pause Channel
+```typescript
+// Pause audio playback in a specific channel.
+pauseChannel(channelNumber?);
+await pauseChannel(); // Pause audio in default channel (0)
+await pauseChannel(1); // Pause audio in channel 1
+```
+
+### Resume Channel
+```typescript
+// Resume audio playback in a specific channel.
+resumeChannel(channelNumber?);
+await resumeChannel(); // Resume audio in default channel (0)
+await resumeChannel(1); // Resume audio in channel 1
+```
+
+### Toggle Pause
+```typescript
+// Toggle between pause and resume states.
+togglePauseChannel(channelNumber?);
+await togglePauseChannel(); // Toggle default channel (0)
+await togglePauseChannel(1); // Toggle channel 1
+```
+
+### Pause/Resume All Channels
+```typescript
+// Pause all channels simultaneously.
+pauseAllChannels();
+await pauseAllChannels();
+```
+
+```typescript
+// Resume all channels that were paused.
+resumeAllChannels();
+await resumeAllChannels();
+```
+
+### Global Toggle Pause/Resume
+```typescript
+// Smart toggle that pauses all channels if any are playing, or resumes all if all are paused.
+togglePauseAllChannels();
+await togglePauseAllChannels();
+```
+
+### Check Pause State
+```typescript
+// Check if a specific channel is paused.
+isChannelPaused(channelNumber?);
+const isPaused = isChannelPaused(); // Check if default channel (0) is paused
+const channelPaused = isChannelPaused(2); // Check if channel 2 is paused
+```
+
+```typescript
+// Get pause state for all channels.
+getAllChannelsPauseState();
+const allPauseStates = getAllChannelsPauseState();
+```
+
+## Audio Information and Progress Tracking:
+
+### AudioInfo Interface
+The package provides detailed information about audio playback through the enhanced `AudioInfo` interface:
+```typescript
+interface AudioInfo {
+  currentTime: number;       // Current position in milliseconds
+  duration: number;          // Total duration in milliseconds
+  fileName: string;          // Extracted filename from URL
+  isLooping: boolean;        // Whether audio is set to loop
+  isPaused: boolean;         // Whether audio is currently paused
+  isPlaying: boolean;        // Whether audio is currently playing
+  progress: number;          // Progress as percentage (0-1)
+  src: string;               // Audio file source URL
+  volume: number;            // Current volume level (0-1)
+}
+```
+
+### Get Current Audio Info
+```typescript
+// Get information about the currently playing audio in a specific channel.
+getCurrentAudioInfo(channelNumber?);
+const audioInfo = getCurrentAudioInfo(); // Get current audio info for default channel (0)
+const info = getCurrentAudioInfo(1); // Get info for channel 1 - returns AudioInfo | null
+```
+
+### Get All Channels Info
+```typescript
+// Get audio information for all channels.
+getAllChannelsInfo();
+const allChannelsInfo = getAllChannelsInfo();
+```
+
+### Queue State Management
+```typescript
+// Get a complete snapshot of the queue state for a specific channel.
+getQueueSnapshot(channelNumber?);
+const queueSnapshot = getQueueSnapshot(); // Get snapshot for default channel (0)
+const snapshot = getQueueSnapshot(2); // Get snapshot for channel 2 - returns QueueSnapshot | null
+```
+
+```typescript
+interface QueueSnapshot {
+  channelNumber: number;     // Channel this snapshot represents
+  currentIndex: number;      // Index of currently playing item
+  isPaused: boolean;         // Whether current audio is paused
+  items: Array<{             // Array of queue items with metadata
+    duration: number;
+    fileName: string;
+    isCurrentlyPlaying: boolean;
+    isLooping: boolean;
+    src: string;
+    volume: number;
+  }>;
+  totalItems: number;        // Total items in queue
+  volume: number;            // Current channel volume (0-1)
+}
+```
+
+### Real-time Progress Tracking
+```typescript
+// Subscribe to real-time progress updates for a specific channel.
+onAudioProgress(channelNumber, callback);
+onAudioProgress(0, (info) => console.log(info.progress)); // Simple progress logging
+onAudioProgress(1, (info) => updateProgressBar(info.currentTime, info.duration)); // Complex UI update
+```
+
+```typescript
+// Remove all progress listeners for a specific channel.
+offAudioProgress(channelNumber?);
+offAudioProgress(); // Remove all progress listeners in default channel (0)
+offAudioProgress(1); // Remove all progress listeners in channel 1
+```
+
+### Enhanced Event System
+```typescript
+// Subscribe to queue change events for visual updates.
+onQueueChange(channelNumber, callback);
+onQueueChange(0, (snapshot) => updateQueueDisplay(snapshot)); // Update UI on queue changes
+```
+
+```typescript
+// Unsubscribe from queue change events (removes ALL queue change callbacks for the channel)
+offQueueChange(channelNumber?);
+offQueueChange(); // Stop receiving all queue change notifications for default channel (0)
+offQueueChange(1); // Stop receiving all queue change notifications for channel 1
+```
+
+```typescript
+// Subscribe to audio start events.
+onAudioStart(channelNumber, callback);
+onAudioStart(0, (info) => console.log(`Started: ${info.fileName}`)); // Log audio starts
+```
+
+```typescript
+// Unsubscribe from audio start events (removes ALL start callbacks for the channel)
+offAudioStart(channelNumber?);
+offAudioStart(); // Stop receiving all start notifications for default channel (0)
+offAudioStart(1); // Stop receiving all start notifications for channel 1
+```
+
+```typescript
+// Subscribe to audio completion events.
+onAudioComplete(channelNumber, callback);
+onAudioComplete(0, (info) => logPlayHistory(info)); // Track completed audio
+```
+
+```typescript
+// Unsubscribe from audio completion events (removes ALL complete callbacks for the channel)
+offAudioComplete(channelNumber?);
+offAudioComplete(); // Stop receiving all completion notifications for default channel (0)
+offAudioComplete(1); // Stop receiving all completion notifications for channel 1
+```
+
+```typescript
+// Subscribe to audio pause events.
+onAudioPause(channelNumber, callback);
+onAudioPause(0, (info) => showPauseIcon(info)); // Show pause state in UI
+```
+
+```typescript
+// Unsubscribe from audio pause events (removes ALL pause callbacks for the channel)
+offAudioPause(channelNumber?);
+offAudioPause(); // Stop receiving all pause notifications for default channel (0)
+offAudioPause(1); // Stop receiving all pause notifications for channel 1
+```
+
+```typescript
+// Subscribe to audio resume events.
+onAudioResume(channelNumber, callback);
+onAudioResume(0, (info) => showPlayIcon(info)); // Show play state in UI
+```
+
+```typescript
+// Unsubscribe from audio resume events (removes ALL resume callbacks for the channel)
+offAudioResume(channelNumber?);
+offAudioResume(); // Stop receiving all resume notifications for default channel (0)
+offAudioResume(1); // Stop receiving all resume notifications for channel 1
+```
+
+### TypeScript Support
+If you cannot import audio files into your app, you may need a `custom.d.ts` file in the root directory. An example of one is shown here:
+
+`custom.d.ts`
+```typescript
+declare module '*.mp3' {
+  const src: string;
+  export default src;
+}
+```
+
+## Development & Contributing 🛠️
+
+The package uses a modular TypeScript architecture that makes it easy to contribute and extend:
+
+### Testing:
+The package includes a comprehensive test suite with 74+ tests covering all functionality:
+
+```bash
+# Run tests once
+npm test
+
+# Run tests in watch mode during development
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+```

package/dist/core.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Core queue management functions for the audioq package
+ */
+import { AudioQueueOptions, QueueConfig } from './types';
+/**
+ * Sets the global queue configuration
+ * @param config - Queue configuration options
+ * @example
+ * ```typescript
+ * setQueueConfig({
+ *   defaultMaxQueueSize: 50,
+ *   dropOldestWhenFull: true,
+ *   showQueueWarnings: true
+ * });
+ * ```
+ */
+export declare const setQueueConfig: (config: Partial<QueueConfig>) => void;
+/**
+ * Gets the current global queue configuration
+ * @returns Current queue configuration
+ * @example
+ * ```typescript
+ * const config = getQueueConfig();
+ * console.log(`Default max queue size: ${config.defaultMaxQueueSize}`);
+ * ```
+ */
+export declare const getQueueConfig: () => QueueConfig;
+/**
+ * Sets the maximum queue size for a specific channel
+ * @param channelNumber - The channel number to configure
+ * @param maxSize - Maximum queue size (undefined for unlimited)
+ * @throws Error if the channel number exceeds the maximum allowed channels
+ * @example
+ * ```typescript
+ * setChannelQueueLimit(0, 25); // Limit channel 0 to 25 items
+ * setChannelQueueLimit(1, undefined); // Remove limit for channel 1
+ * ```
+ */
+export declare const setChannelQueueLimit: (channelNumber: number, maxSize?: number) => void;
+/**
+ * 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)
+ * @param options - Optional configuration for the audio file
+ * @returns Promise that resolves when the audio is queued and starts playing (if first in queue)
+ * @throws Error if the audio URL is invalid or potentially malicious
+ * @throws Error if the channel number exceeds the maximum allowed channels
+ * @throws Error if the queue size limit would be exceeded
+ * @example
+ * ```typescript
+ * await queueAudio('https://example.com/song.mp3', 0);
+ * await queueAudio('./sounds/notification.wav'); // Uses default channel 0
+ * await queueAudio('./music/loop.mp3', 1, { loop: true }); // Loop the audio
+ * await queueAudio('./urgent.wav', 0, { addToFront: true }); // Add to front of queue
+ * await queueAudio('./limited.mp3', 0, { maxQueueSize: 10 }); // Limit this queue to 10 items
+ * ```
+ */
+export declare const queueAudio: (audioUrl: string, channelNumber?: number, options?: AudioQueueOptions) => Promise<void>;
+/**
+ * Adds an audio file to the front of the queue in a specific channel
+ * This is a convenience function that places the audio right after the currently playing track
+ * @param audioUrl - The URL of the audio file to queue
+ * @param channelNumber - The channel number to queue the audio to (defaults to 0)
+ * @param options - Optional configuration for the audio file
+ * @returns Promise that resolves when the audio is queued
+ * @example
+ * ```typescript
+ * await queueAudioPriority('./urgent-announcement.wav', 0);
+ * await queueAudioPriority('./priority-sound.mp3', 1, { loop: true });
+ * ```
+ */
+export declare const queueAudioPriority: (audioUrl: string, channelNumber?: number, options?: AudioQueueOptions) => Promise<void>;
+/**
+ * Plays the audio queue for a specific channel
+ * @param channelNumber - The channel number to play
+ * @returns Promise that resolves when the audio starts playing (setup complete)
+ * @example
+ * ```typescript
+ * await playAudioQueue(0); // Start playing queue for channel 0
+ * ```
+ */
+export declare const playAudioQueue: (channelNumber: number) => Promise<void>;
+/**
+ * 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
+ * await stopCurrentAudioInChannel(); // Stop current audio in default channel (0)
+ * await stopCurrentAudioInChannel(1); // Stop current audio in channel 1
+ * ```
+ */
+export declare const stopCurrentAudioInChannel: (channelNumber?: number) => Promise<void>;
+/**
+ * Stops all audio in a specific channel and clears the entire queue
+ * @param channelNumber - The channel number (defaults to 0)
+ * @example
+ * ```typescript
+ * await stopAllAudioInChannel(); // Clear all audio in default channel (0)
+ * await stopAllAudioInChannel(1); // Clear all audio in channel 1
+ * ```
+ */
+export declare const stopAllAudioInChannel: (channelNumber?: number) => Promise<void>;
+/**
+ * Stops all audio across all channels and clears all queues
+ * @example
+ * ```typescript
+ * await stopAllAudio(); // Emergency stop - clears everything
+ * ```
+ */
+export declare const stopAllAudio: () => Promise<void>;
+/**
+ * Completely destroys a channel and cleans up all associated resources
+ * This stops all audio, cancels transitions, clears callbacks, and removes the channel
+ * @param channelNumber - The channel number to destroy (defaults to 0)
+ * @example
+ * ```typescript
+ * await destroyChannel(1); // Completely removes channel 1 and cleans up resources
+ * ```
+ */
+export declare const destroyChannel: (channelNumber?: number) => Promise<void>;
+/**
+ * Destroys all channels and cleans up all resources
+ * This is useful for complete cleanup when the audio system is no longer needed
+ * @example
+ * ```typescript
+ * await destroyAllChannels(); // Complete cleanup - removes all channels
+ * ```
+ */
+export declare const destroyAllChannels: () => Promise<void>;