audio-channel-queue 1.9.0 → 1.11.0

package/README.md

@@ -1,6 +1,10 @@
 # Audio Channel Queue
 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
@@ -22,6 +26,8 @@ NPM package can be found [here](https://www.npmjs.com/package/audio-channel-queu
 
 GitHub Repo can be found [here](https://github.com/tonycarpenter21/audio-channel-queue).
 
+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.
@@ -66,111 +72,206 @@ Install this package by running either of these commands (typescript packages ar
 ## Basic Queue Management Functions:
 
 ### Queue Audio
-```queueAudio(audioFileGoesHere, channelNumber, options);```
-Use the `queueAudio()` function to add a file to the queue and start playing it automatically. It takes three arguments:
-- The first argument is an imported sound file.
-- The second argument is optional and it allows you to choose a different queue channel.
-- The third argument is optional configuration for loop, volume, and priority.
+```typescript
+// Add an audio file to the queue and start playing it automatically.
+queueAudio(audioUrl, channelNumber?, options?);
+queueAudio('hello.mp3'); // Add to default channel 0
+queueAudio('laser.mp3', 1, { loop: true, volume: 0.8 }); // Add to channel 1 with options
+```
+
 
 ### Queue Audio with Priority
-```queueAudioPriority(audioFileGoesHere, channelNumber, options);```
-Use the `queueAudioPriority()` function to add a file to the front of the queue (plays after current audio finishes). Perfect for urgent announcements!
+```typescript
+// Add a file to the front of the queue (plays after current audio finishes).
+queueAudioPriority(audioUrl, channelNumber?, options?);
+queueAudioPriority('urgent.mp3'); // Add to front of default channel 0
+queueAudioPriority('announcement.mp3', 1, { volume: 1.0 }); // Add to front of channel 1
+```
+
 
 ### Stop Current Audio
-```stopCurrentAudioInChannel(queueChannelNumberGoesHere);```
-Use the `stopCurrentAudioInChannel()` function to stop the current playback of a file in a queue and start playing the next one automatically.
+```typescript
+// Stop the current audio and automatically start playing the next one in queue.
+stopCurrentAudioInChannel(channelNumber?);
+stopCurrentAudioInChannel(); // Stop current audio in default channel (0)
+stopCurrentAudioInChannel(2); // Stop current audio in channel 2
+```
+
 
 ### Stop All Audio in Channel
-```stopAllAudioInChannel(queueChannelNumberGoesHere);```
-Use the `stopAllAudioInChannel()` function to stop the current playback of all files in a queue and removes all enqueued files.
+```typescript
+// Stop all audio in a channel and remove all enqueued files.
+stopAllAudioInChannel(channelNumber?);
+stopAllAudioInChannel(); // Stop and clear all audio in default channel (0)
+stopAllAudioInChannel(1); // Stop and clear all audio in channel 1
+```
 
 ### Stop All Audio
-```stopAllAudio();```
-Use the `stopAllAudio()` function to stop the current playback of all files in all queues. It takes no arguments.
+```typescript
+// Stop all audio in all channels and remove all enqueued files.
+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 = removeQueuedItem(2); // Remove item at index 2 from default channel (0)
+const result = 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 = reorderQueue(3, 1); // Move item from index 3 to index 1 in default channel (0)
+const result = 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 = clearQueueAfterCurrent(); // Clear queue after current in default channel (0)
+const result = 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 = swapQueueItems(1, 3); // Swap items at index 1 and 3 in default channel (0)
+const result = 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
-```setChannelVolume(channelNumber, volume);```
-Set the volume for a specific channel (0-1 range).
 ```typescript
+// Set the volume for a specific channel (0-1 range).
+setChannelVolume(channelNumber, volume);
 setChannelVolume(0, 0.5); // Set channel 0 to 50% volume
 setChannelVolume(1, 0.8); // Set channel 1 to 80% volume
 ```
 
 ### Get Channel Volume
-```getChannelVolume(channelNumber);```
-Get the current volume level for a specific channel.
 ```typescript
-const volume = getChannelVolume(0);
-console.log(`Channel 0 volume: ${volume * 100}%`);
+// 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
-```setAllChannelsVolume(volume);```
-Set the same volume level for all channels.
 ```typescript
+// Set the same volume level for all channels.
+setAllChannelsVolume(volume);
 setAllChannelsVolume(0.6); // Set all channels to 60% volume
+setAllChannelsVolume(0.0); // Mute all channels
 ```
 
 ### Volume Ducking (Background Audio Reduction)
-```setVolumeDucking(config);```
-Automatically reduce other channels' volume when priority audio plays - perfect for voice announcements over background music!
 ```typescript
-// When channel 1 plays, reduce all other channels to 20% volume
+// 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
-});
+  duckingVolume: 0.2,
+  transitionDuration: 500
+}); // Full configuration
 ```
 
-```clearVolumeDucking();```
-Remove volume ducking configuration from all channels.
+```typescript
+// Remove volume ducking configuration from all channels.
+clearVolumeDucking();
+```
 
 ## ⏯️ Pause/Resume Functions:
 
 ### Pause Channel
-```pauseChannel(channelNumber);```
-Pause audio playback in a specific channel.
 ```typescript
-await pauseChannel(0); // Pause audio in channel 0
-await pauseChannel(); // Pause audio in default channel
+// 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
-```resumeChannel(channelNumber);```
-Resume audio playback in a specific channel.
 ```typescript
-await resumeChannel(0); // Resume audio in channel 0
+// 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
-```togglePauseChannel(channelNumber);```
-Toggle between pause and resume states.
 ```typescript
-await togglePauseChannel(0); // Pause if playing, resume if paused
+// Toggle between pause and resume states.
+togglePauseChannel(channelNumber?);
+await togglePauseChannel(); // Toggle default channel (0)
+await togglePauseChannel(1); // Toggle channel 1
 ```
 
 ### Pause/Resume All Channels
-```pauseAllChannels();``` and ```resumeAllChannels();```
-Control all channels simultaneously.
 ```typescript
-await pauseAllChannels(); // Emergency pause - everything stops
-await resumeAllChannels(); // Resume everything that was paused
+// Pause all channels simultaneously.
+pauseAllChannels();
+await pauseAllChannels();
+```
+
+```typescript
+// Resume all channels that were paused.
+resumeAllChannels();
+await resumeAllChannels();
 ```
 
 ### Global Toggle Pause/Resume
-```togglePauseAllChannels();```
-Smart toggle that pauses all channels if any are playing, or resumes all if all are paused.
 ```typescript
-await togglePauseAllChannels(); // Pause all if any playing, resume all if all paused
+// Smart toggle that pauses all channels if any are playing, or resumes all if all are paused.
+togglePauseAllChannels();
+await togglePauseAllChannels();
 ```
 
 ### Check Pause State
-```isChannelPaused(channelNumber);``` and ```getAllChannelsPauseState();```
 ```typescript
-const isPaused = isChannelPaused(0);
+// 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();
 ```
 
@@ -193,16 +294,27 @@ interface AudioInfo {
 ```
 
 ### Get Current Audio Info
-```getCurrentAudioInfo(channelNumber);```
-Get information about the currently playing audio in a specific channel. Returns `AudioInfo | null`.
+```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
-```getAllChannelsInfo();```
-Get audio information for all channels. Returns an array of `AudioInfo | null` objects.
+```typescript
+// Get audio information for all channels.
+getAllChannelsInfo();
+const allChannelsInfo = getAllChannelsInfo();
+```
 
 ### Queue State Management
-```getQueueSnapshot(channelNumber);```
-Get a complete snapshot of the queue state for a specific channel. Returns `QueueSnapshot | null`.
+```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 {
@@ -223,247 +335,62 @@ interface QueueSnapshot {
 ```
 
 ### Real-time Progress Tracking
-```onAudioProgress(channelNumber, callback);```
-Subscribe to real-time progress updates for a specific channel.
+```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
+```
 
-```offAudioProgress(channelNumber);```
-Remove all progress listeners for a specific channel.
+```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
-```onQueueChange(channelNumber, callback);```
-Subscribe to queue change events for visual updates.
-
-```onAudioStart(channelNumber, callback);```
-Subscribe to audio start events.
-
-```onAudioComplete(channelNumber, callback);```
-Subscribe to audio completion events.
-
-```onAudioPause(channelNumber, callback);```
-Subscribe to audio pause events.
-
-```onAudioResume(channelNumber, callback);```
-Subscribe to audio resume events.
-
-### Example Usage with All New Features:
-
-`App.tsx`
-```typescript
-import backgroundMusic from './audio/background.mp3';
-import announcement from './audio/announcement.wav';
-import { 
-  queueAudio, 
-  queueAudioPriority,
-  getCurrentAudioInfo,
-  pauseChannel,
-  resumeChannel,
-  togglePauseAllChannels,
-  setChannelVolume,
-  setVolumeDucking,
-  onAudioProgress,
-  onAudioPause,
-  onAudioResume,
-  onQueueChange,
-  AudioInfo,
-  QueueSnapshot 
-} from 'audio-channel-queue';
-import { useState, useEffect } from 'react';
-
-function App(): JSX.Element {
-  const [currentInfo, setCurrentInfo] = useState<AudioInfo | null>(null);
-  const [queueSnapshot, setQueueSnapshot] = useState<QueueSnapshot | null>(null);
-  const [isPaused, setIsPaused] = useState(false);
-
-  useEffect(() => {
-    // Set up background music with looping
-    const setupBackgroundMusic = async () => {
-      await queueAudio(backgroundMusic, 0, { 
-        loop: true, 
-        volume: 0.3 
-      });
-      setChannelVolume(0, 0.3); // 30% volume for background
-    };
-
-    // Configure volume ducking for announcements
-    setVolumeDucking({
-      priorityChannel: 1,     // Announcements on channel 1
-      priorityVolume: 1.0,    // Full volume for announcements
-      duckingVolume: 0.1      // Reduce background to 10% during announcements
-    });
-
-    // Set up event listeners
-    onAudioProgress(0, (info: AudioInfo) => {
-      setCurrentInfo(info);
-    });
-
-    onQueueChange(0, (snapshot: QueueSnapshot) => {
-      setQueueSnapshot(snapshot);
-    });
-
-    onAudioPause(0, (channelNumber, info) => {
-      setIsPaused(true);
-      console.log(`Channel ${channelNumber} paused: ${info.fileName}`);
-    });
-
-    onAudioResume(0, (channelNumber, info) => {
-      setIsPaused(false);
-      console.log(`Channel ${channelNumber} resumed: ${info.fileName}`);
-    });
-
-    setupBackgroundMusic();
-  }, []);
-
-  const playAnnouncement = async () => {
-    // Priority queue - plays next, automatically ducks background music
-    await queueAudioPriority(announcement, 1);
-  };
-
-  const toggleBackgroundMusic = async () => {
-    if (isPaused) {
-      await resumeChannel(0);
-    } else {
-      await pauseChannel(0);
-    }
-  };
-
-  const adjustBackgroundVolume = (volume: number) => {
-    setChannelVolume(0, volume);
-  };
-
-  const emergencyToggleAll = async () => {
-    await togglePauseAllChannels(); // Smart toggle - pause all if any playing, resume all if all paused
-  };
-
-  return (
-    <div className="App">
-      <h2>Audio Control Center</h2>
-      
-      {/* Background Music Controls */}
-      <div className="background-controls">
-        <h3>Background Music</h3>
-        <button onClick={toggleBackgroundMusic}>
-          {isPaused ? '▶️ Resume' : '⏸️ Pause'}
-        </button>
-        <label>
-          Volume: 
-          <input 
-            type="range" 
-            min="0" 
-            max="1" 
-            step="0.1"
-            onChange={(e) => adjustBackgroundVolume(Number(e.target.value))}
-          />
-        </label>
-      </div>
-
-      {/* Announcement Controls */}
-      <div className="announcement-controls">
-        <h3>Announcements</h3>
-        <button onClick={playAnnouncement}>
-          📢 Play Announcement (Auto-ducks background)
-        </button>
-      </div>
-
-      {/* Emergency Controls */}
-      <div className="emergency-controls">
-        <h3>Emergency Controls</h3>
-        <button onClick={emergencyToggleAll}>
-          🚨 Toggle All Audio (Smart Pause/Resume)
-        </button>
-      </div>
-
-      {/* Current Audio Info */}
-      {currentInfo && (
-        <div className="current-info">
-          <h3>Now Playing:</h3>
-          <p>🎵 {currentInfo.fileName}</p>
-          <p>⏱️ {(currentInfo.currentTime / 1000).toFixed(1)}s / {(currentInfo.duration / 1000).toFixed(1)}s</p>
-          <p>📊 Progress: {(currentInfo.progress * 100).toFixed(1)}%</p>
-          <p>🔊 Volume: {(currentInfo.volume * 100).toFixed(0)}%</p>
-          <p>🔄 Looping: {currentInfo.isLooping ? 'Yes' : 'No'}</p>
-          <p>⏸️ Paused: {currentInfo.isPaused ? 'Yes' : 'No'}</p>
-          
-          {/* Progress Bar */}
-          <div className="progress-bar">
-            <div 
-              className="progress-fill" 
-              style={{ width: `${currentInfo.progress * 100}%` }}
-            />
-          </div>
-        </div>
-      )}
-
-      {/* Queue Status */}
-      {queueSnapshot && (
-        <div className="queue-status">
-          <h3>Queue Status (Channel {queueSnapshot.channelNumber}):</h3>
-          <p>📋 Total Items: {queueSnapshot.totalItems}</p>
-          <p>🔊 Channel Volume: {(queueSnapshot.volume * 100).toFixed(0)}%</p>
-          <p>⏸️ Channel Paused: {queueSnapshot.isPaused ? 'Yes' : 'No'}</p>
-          
-          <h4>Queue Items:</h4>
-          <ul>
-            {queueSnapshot.items.map((item, index) => (
-              <li key={index} style={{ 
-                fontWeight: item.isCurrentlyPlaying ? 'bold' : 'normal',
-                color: item.isCurrentlyPlaying ? '#007bff' : 'inherit'
-              }}>
-                {item.fileName} ({(item.duration / 1000).toFixed(1)}s)
-                {item.isCurrentlyPlaying && ' ▶️ PLAYING'}
-                {item.isLooping && ' 🔄 LOOP'}
-              </li>
-            ))}
-          </ul>
-        </div>
-      )}
-    </div>
-  );
-}
-
-export default App;
+```typescript
+// Subscribe to queue change events for visual updates.
+onQueueChange(channelNumber, callback);
+onQueueChange(0, (snapshot) => updateQueueDisplay(snapshot)); // Update UI on queue changes
 ```
 
-### Advanced Usage Examples:
-
-#### Gaming Audio System
 ```typescript
-// Background music (channel 0)
-await queueAudio('./music/background.mp3', 0, { loop: true, volume: 0.4 });
-
-// Sound effects (channel 1)
-await queueAudio('./sfx/explosion.wav', 1);
-
-// Voice chat (channel 2) - ducks other audio
-setVolumeDucking({
-  priorityChannel: 2,
-  priorityVolume: 1.0,
-  duckingVolume: 0.2
-});
-
-// Critical game announcements (priority)
-await queueAudioPriority('./voice/game-over.wav', 2);
+// Subscribe to audio start events.
+onAudioStart(channelNumber, callback);
+onAudioStart(0, (info) => console.log(`Started: ${info.fileName}`)); // Log audio starts
 ```
 
-#### Podcast/Radio App
 ```typescript
-// Main content (channel 0)
-await queueAudio('./podcast/episode1.mp3', 0);
+// Unsubscribe from audio start events (removes ALL start callbacks for the channel)
+offAudioStart(channelNumber);
+offAudioStart(0); // Stop receiving all start notifications for channel 0
+```
 
-// Jingles and ads (channel 1) - interrupt at natural breaks
-await queueAudioPriority('./ads/sponsor.mp3', 0);
+```typescript
+// Subscribe to audio completion events.
+onAudioComplete(channelNumber, callback);
+onAudioComplete(0, (info) => logPlayHistory(info)); // Track completed audio
+```
 
-// Background ambient (channel 2)
-await queueAudio('./ambient/coffee-shop.mp3', 2, { 
-  loop: true, 
-  volume: 0.1 
-});
+```typescript
+// Unsubscribe from audio completion events (removes ALL complete callbacks for the channel)
+offAudioComplete(channelNumber);
+offAudioComplete(0); // Stop receiving all completion notifications for channel 0
+```
 
-// Pause everything for phone calls
-onPhoneCall(() => pauseAllChannels());
+```typescript
+// Subscribe to audio pause events.
+onAudioPause(channelNumber, callback);
+onAudioPause(0, (info) => showPauseIcon(info)); // Show pause state in UI
 ```
 
-### Legacy Access
-If you need to expose the queue array for logging or other purposes, it is available to you as well: `audioChannels`.
+```typescript
+// Subscribe to audio resume events.
+onAudioResume(channelNumber, callback);
+onAudioResume(0, (info) => showPlayIcon(info)); // Show play state in UI
+```
 
 ### 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:
@@ -476,39 +403,10 @@ declare module '*.mp3' {
 }
 ```
 
-## Features:
-- ✅ Queue management across multiple channels
-- ✅ Pause and resume functionality for individual channels and all channels
-- ✅ Volume control with per-channel precision (0-1 range)
-- ✅ Volume ducking for priority audio (automatic background reduction)
-- ✅ Audio looping capabilities for background music and ambient sounds
-- ✅ Priority queueing system for urgent audio playback
-- ✅ Real-time audio progress tracking with enhanced metadata
-- ✅ Comprehensive event system (start, complete, pause, resume, queue changes)
-- ✅ Audio duration and metadata extraction with loop and volume info
-- ✅ Automatic filename extraction from URLs
-- ✅ Queue state snapshots with pause and volume information
-- ✅ TypeScript support with full type definitions
-- ✅ Modular architecture with clean separation of concerns
-- ✅ Comprehensive JSDoc documentation with examples
-- ✅ Zero dependencies
-- ✅ Backward compatible with existing implementations
-- ✅ Comprehensive error handling with graceful degradation
-
 ## Development & Contributing 🛠️
 
 The package uses a modular TypeScript architecture that makes it easy to contribute and extend:
 
-### File Structure:
-- **`src/types.ts`** - Interface definitions and type exports
-- **`src/core.ts`** - Main queue management logic and priority queueing
-- **`src/pause.ts`** - Pause and resume functionality
-- **`src/volume.ts`** - Volume control and ducking management  
-- **`src/info.ts`** - Audio information and progress tracking
-- **`src/events.ts`** - Event system and callback management
-- **`src/utils.ts`** - Helper functions and utilities
-- **`src/index.ts`** - Public API exports
-
 ### Testing:
 The package includes a comprehensive test suite with 74+ tests covering all functionality:
 
@@ -522,5 +420,3 @@ npm run test:watch
 # Run tests with coverage report
 npm run test:coverage
 ```
-
-**Test Coverage**: 85%+ code coverage across all modules with realistic HTMLAudioElement mocking using jsdom.