Skip to main content

🎵 Queue Management Functions

This section covers all functions related to managing audio queues - adding audio, priority queuing, and stopping playback.

queueAudio()​

Add an audio file to the end of a queue and start playing it automatically.

Syntax​

queueAudio(audioFile: string, channelNumber?: number, options?: AudioOptions): Promise<void>

Parameters​

ParameterTypeDefaultDescription
audioFilestringRequiredPath or URL to the audio file
channelNumbernumber0Channel number (0, 1, 2, etc.)
optionsAudioOptions{}Configuration options

AudioOptions​

interface AudioOptions {
  loop?: boolean;     // Loop the audio when it finishes
  volume?: number;    // Initial volume (0-1 range)
  priority?: boolean; // Same as queueAudioPriority if true
}

Examples​

Basic Usage

import { queueAudio } from 'audio-channel-queue';

// Play on default channel (0)
await queueAudio('./sounds/welcome.mp3');

// Play on specific channel
await queueAudio('./music/background.mp3', 1);

With Options

// Background music with loop and volume
await queueAudio('./music/ambient.mp3', 0, {
  loop: true,
  volume: 0.3
});

// Sound effect at full volume
await queueAudio('./sfx/explosion.wav', 1, {
  volume: 1.0
});

Multiple Files in Queue

// Queue multiple songs - they'll play in order
await queueAudio('./music/song1.mp3', 0);
await queueAudio('./music/song2.mp3', 0);
await queueAudio('./music/song3.mp3', 0);

Return Value​

Returns a Promise<void> that resolves when the audio has been successfully added to the queue.

queueAudioPriority()​

Add an audio file to the front of the queue (plays after current audio finishes). Perfect for urgent announcements!

Syntax​

queueAudioPriority(audioFile: string, channelNumber?: number, options?: AudioOptions): Promise<void>

Parameters​

Same as queueAudio() - the only difference is queue position.

Examples​

Urgent Announcements

// Queue some background music
await queueAudio('./music/song1.mp3', 0);
await queueAudio('./music/song2.mp3', 0);
await queueAudio('./music/song3.mp3', 0);

// Emergency announcement - plays immediately!
await queueAudioPriority('./voice/emergency.mp3', 0);
// Stop the current sound so the priority announcement plays near immediately
stopCurrentAudioInChannel(); // Note: defaults to channel 0

// The emergency message now plays right away instead of waiting

Gaming Example

// Background music playing
await queueAudio('./music/level-theme.mp3', 0, { loop: true });

// Boss appears - urgent battle music needs to start now!
await queueAudioPriority('./music/boss-battle.mp3', 0);
stopCurrentAudioInChannel(); // Immediately stop level theme, start boss music

// Boss music plays instantly instead of waiting for level theme to finish

stopCurrentAudioInChannel()​

Stop the currently playing audio in a specific channel and automatically start the next queued item.

Syntax​

stopCurrentAudioInChannel(channelNumber?: number): void

Parameters​

ParameterTypeDefaultDescription
channelNumbernumber0Channel to stop current audio

Note: channelNumber is optional and defaults to 0. Functions like stopCurrentAudioInChannel(), stopAllAudioInChannel(), and several others use channel 0 by default when no channel is specified.

Examples​

import { stopCurrentAudioInChannel } from 'audio-channel-queue';

// Skip to next song on default channel (0)
stopCurrentAudioInChannel();

// Skip to next song on specific channel
stopCurrentAudioInChannel(1);

// Gaming example - immediate audio switching
function handleBossFight(): void {
  // Stop current background music and play boss theme
  stopCurrentAudioInChannel(); // Skip current song
  queueAudioPriority('./music/boss-theme.mp3');
}

Real-world Usage​

class MusicPlayer {
  private currentChannel: number = 0;

  skipToNext(): void {
    console.log('Skipping to next track...');
    if (this.currentChannel === 0) {
      stopCurrentAudioInChannel(); // Use default for channel 0
    } else {
      stopCurrentAudioInChannel(this.currentChannel);
    }
  }

  skipToPrevious(): void {
    // In a real app, you'd track the previous song
    console.log('Going to previous track...');
    if (this.currentChannel === 0) {
      stopCurrentAudioInChannel();
    } else {
      stopCurrentAudioInChannel(this.currentChannel);
    }
    // Then queue the previous song with priority
  }

  emergencyStop(): void {
    // Stop whatever is playing immediately
    if (this.currentChannel === 0) {
      stopCurrentAudioInChannel();
    } else {
      stopCurrentAudioInChannel(this.currentChannel);
    }
  }
}

stopAllAudioInChannel()​

Stop the current audio and clear all queued items in a specific channel.

Syntax​

stopAllAudioInChannel(channelNumber?: number): void

Parameters​

ParameterTypeDefaultDescription
channelNumbernumber0Channel to clear completely

Examples​

// Queue multiple items
await queueAudio('./music/song1.mp3', 0);
await queueAudio('./music/song2.mp3', 0);
await queueAudio('./music/song3.mp3', 0);

// Stop everything on channel 0
stopAllAudioInChannel(0);

// Channel 0 is now silent and empty

Emergency Stop Button

function createEmergencyStopButton() {
  const button = document.createElement('button');
  button.textContent = '🛑 Emergency Stop';
  button.onclick = () => {
    stopAllAudioInChannel(0); // Clear background music
    stopAllAudioInChannel(1); // Clear sound effects
  };
  return button;
}

stopAllAudio()​

Stop all audio across all channels. Nuclear option!

Syntax​

stopAllAudio(): void

Parameters​

None.

Examples​

// Start audio on multiple channels
await queueAudio('./music/background.mp3', 0);
await queueAudio('./sfx/ambient.wav', 1);
await queueAudio('./voice/narrator.mp3', 2);

// Stop everything everywhere
stopAllAudio();

// All channels are now silent

Global Mute Implementation

let isMuted = false;

function toggleGlobalMute() {
  if (isMuted) {
    // Resume all channels
    resumeAllChannels();
    isMuted = false;
  } else {
    // Stop all audio
    stopAllAudio();
    isMuted = true;
  }
}

🎮 Real-World Usage Patterns​

Gaming Audio Manager​

class GameAudioManager {
  constructor() {
    // Set up channels
    // 0: Background music
    // 1: Sound effects
    // 2: Voice/announcements
  }

  async startLevel(levelNumber: number) {
    // Stop previous level music
    stopAllAudioInChannel(0);
    
    // Start new level music
    await queueAudio(`./music/level-${levelNumber}.mp3`, 0, {
      loop: true,
      volume: 0.4
    });
  }

  async playEffect(effectName: string) {
    await queueAudio(`./sfx/${effectName}.wav`, 1);
  }

  async playAnnouncement(message: string) {
    // Priority announcement that interrupts music briefly
    await queueAudioPriority(`./voice/${message}.mp3`, 0);
  }

  gameOver() {
    // Stop everything and play game over music
    stopAllAudio();
    queueAudio('./music/game-over.mp3', 0);
  }
}

// Usage
const audioManager = new GameAudioManager();
await audioManager.startLevel(1);
await audioManager.playEffect('jump');
await audioManager.playAnnouncement('checkpoint');

Podcast App​

class PodcastPlayer {
  async loadEpisode(episodeUrl: string) {
    // Clear any previous episode
    stopAllAudioInChannel(0);
    
    // Load new episode
    await queueAudio(episodeUrl, 0);
  }

  async insertAd(adUrl: string) {
    // Insert ad to play next (priority)
    await queueAudioPriority(adUrl, 0);
  }

  skipCurrent() {
    // Skip current segment (ad or chapter)
    stopCurrentAudioInChannel(0);
  }

  stopEpisode() {
    // Stop and clear episode
    stopAllAudioInChannel(0);
  }
}

Interactive Presentation​

class PresentationAudio {
  async startPresentation() {
    // Background ambient sound
    await queueAudio('./ambient/office.mp3', 1, {
      loop: true,
      volume: 0.1
    });
  }

  async playSlideNarration(slideNumber: number) {
    // Stop previous narration, start new one
    stopAllAudioInChannel(0);
    await queueAudio(`./narration/slide-${slideNumber}.mp3`, 0);
  }

  async playTransitionSound() {
    // Quick transition effect
    await queueAudio('./sfx/slide-transition.wav', 2);
  }

  endPresentation() {
    // Fade out and stop
    stopAllAudio();
  }
}

🔗 Related Functions​

Next: Learn about Volume Control functions →