Skip to main content

Quick Reference

Quick examples for all audioq functions. For detailed documentation, click the function names.

Basic Queue Operations​

queueAudio()​

// Basic usage - plays on channel 0
await queueAudio('./sounds/music.mp3');

// Specific channel with options
await queueAudio('./sounds/bgm.mp3', 0, { 
  loop: true,    // Repeat forever
  volume: 0.5    // 50% volume
});

// Queue multiple files - play in order
await queueAudio('./track1.mp3');
await queueAudio('./track2.mp3');  // Plays after track1

queueAudioPriority()​

// Add to front of queue - plays next
await queueAudioPriority('./urgent-alert.mp3');

// With channel and options
await queueAudioPriority('./announcement.mp3', 1, { volume: 1.0 });

// Common pattern: interrupt current audio
await queueAudioPriority('./boss-music.mp3');
await stopCurrentAudioInChannel();  // Skip current, play boss music immediately

stopCurrentAudioInChannel()​

// Skip to next in queue - channel 0 (default)
await stopCurrentAudioInChannel();

// Skip on specific channel
await stopCurrentAudioInChannel(1);

// Best practice: check if audio exists first
if (getCurrentAudioInfo()) {
  await stopCurrentAudioInChannel();
}

stopAllAudioInChannel()​

// Clear entire queue and stop - channel 0 (default)
stopAllAudioInChannel();

// Clear specific channel
stopAllAudioInChannel(2);

// Common: reset before new playlist
stopAllAudioInChannel();
await queueAudio('./new-playlist/song1.mp3');

stopAllAudio()​

// Nuclear option - stop everything
await stopAllAudio();

// Common: panic button
document.getElementById('emergency-stop').onclick = async () => {
  await stopAllAudio();
};

Volume Control​

setChannelVolume()​

// Set volume (0-1 range)
await setChannelVolume(0, 0.5);  // Channel 0 at 50%
await setChannelVolume(1, 0.8);  // Channel 1 at 80%

// Mute/unmute pattern
await setChannelVolume(0, 0);    // Mute
await setChannelVolume(0, 0.7);  // Restore

// With smooth transitions
await setChannelVolume(0, 0.3, 500, EasingType.EaseOut);  // Fade over 500ms

getChannelVolume()​

// Get current volume - channel 0 (default)
const volume = getChannelVolume();

// Specific channel
const bgmVolume = getChannelVolume(0);
console.log(`BGM: ${(bgmVolume * 100).toFixed(0)}%`);

getAllChannelsVolume()​

// Get all channel volumes as array
const volumes = getAllChannelsVolume();
volumes.forEach((vol, ch) => console.log(`Ch${ch}: ${vol * 100}%`));

setGlobalVolume()​

// Set global volume multiplier (preserves channel ratios)
await setGlobalVolume(0.5); // 50% global volume

// Example: Volume control
await setChannelVolume(0, 0.3); // SFX at 30%
await setChannelVolume(1, 0.7); // Music at 70%
await setGlobalVolume(0.5);     // Global 50% (SFX now 15%, Music now 35%)

// Quick global mute without losing channel settings
await setGlobalVolume(0);   // Mute all
await setGlobalVolume(1.0); // Restore all ratios

getGlobalVolume()​

// Get current global volume multiplier
const globalVol = getGlobalVolume();
console.log(`Global volume: ${(globalVol * 100).toFixed(0)}%`);

// Check if globally muted
if (getGlobalVolume() === 0) {
  console.log('All audio globally muted');
}

setAllChannelsVolume()​

// Set all channels volume control
await setAllChannelsVolume(0.5);  // All channels 50%
await setAllChannelsVolume(0);    // Mute all

// Fade out pattern
for (let v = 1.0; v >= 0; v -= 0.1) {
  await setAllChannelsVolume(v);
  await new Promise(r => setTimeout(r, 100));
}

setVolumeDucking()​

// Simple ducking - reduce others when priority plays
setVolumeDucking({ 
  priorityChannel: 1,     // Announcements
  duckingVolume: 0.2      // Others at 20%
});

// Full config with smooth transition
setVolumeDucking({
  priorityChannel: 2,
  priorityVolume: 1.0,           // Priority at 100%
  duckingVolume: 0.1,            // Others at 10%
  duckTransitionDuration: 300,   // 300ms duck
  restoreTransitionDuration: 500 // 500ms restore
});

// Remove ducking
clearVolumeDucking();

transitionVolume()​

// Smooth volume transitions
await transitionVolume(0, 0, 1000);         // Fade out over 1s
await transitionVolume(0, 1, 500, EasingType.EaseOut); // Fade in over 500ms

// Cross-fade between channels
await Promise.all([
  transitionVolume(0, 0, 800, EasingType.EaseIn),
  transitionVolume(1, 1, 800, EasingType.EaseOut)
]);

Pause & Resume​

pauseChannel()​

// Pause channel 0 (default)
await pauseChannel();

// Pause specific channel
await pauseChannel(1);

// Common: pause on focus loss
window.addEventListener('blur', async () => await pauseChannel());

resumeChannel()​

// Resume channel 0 (default)
await resumeChannel();

// Resume specific channel
await resumeChannel(1);

// Common: resume on focus
window.addEventListener('focus', async () => await resumeChannel());

togglePauseChannel()​

// Toggle pause state - channel 0 (default)
await togglePauseChannel();

// Space bar pause pattern
document.addEventListener('keydown', async (e) => {
  if (e.code === 'Space') {
    await togglePauseChannel();
  }
});

pauseAllChannels() / resumeAllChannels()​

// Pause everything
await pauseAllChannels();

// Resume everything
await resumeAllChannels();

// Common: mobile app background
document.addEventListener('visibilitychange', async () => {
  if (document.hidden) {
    await pauseAllChannels();
  } else {
    await resumeAllChannels();
  }
});

Audio Information​

getCurrentAudioInfo()​

// Get current audio info - channel 0 (default)
const info = getCurrentAudioInfo();
if (info) {
  console.log(`Playing: ${info.fileName}`);
  console.log(`Progress: ${(info.progress * 100).toFixed(0)}%`);
}

// Progress bar update
function updateProgressBar() {
  const info = getCurrentAudioInfo();
  if (info) {
    progressBar.style.width = `${info.progress * 100}%`;
    timeLabel.textContent = `${formatTime(info.currentTime)} / ${formatTime(info.duration)}`;
  }
}

getQueueSnapshot()​

// Get full queue state - channel 0 (default)
const snapshot = getQueueSnapshot();
console.log(`Queue: ${snapshot.totalItems} items`);

// Display playlist
const snapshot = getQueueSnapshot(0);
snapshot.items.forEach((item, index) => {
  const status = item.isCurrentlyPlaying ? '▶️' : '⏸️';
  console.log(`${status} ${index}: ${item.fileName}`);
});

getAllChannelsInfo()​

// Monitor all channels
const allInfo = getAllChannelsInfo();
Object.entries(allInfo).forEach(([channel, info]) => {
  if (info) {
    console.log(`Ch${channel}: ${info.fileName} (${info.isPaused ? 'paused' : 'playing'})`);
  }
});

Advanced Queue Manipulation​

removeQueuedItem()​

// Remove by position (can't remove currently playing at index 0)
const result = removeQueuedItem(2);  // Remove 3rd item
if (!result.success) console.error(result.error);

// Specific channel
removeQueuedItem(1, 1);  // Remove 2nd item from channel 1

reorderQueue()​

// Move item from position 3 to position 1
const result = reorderQueue(3, 1);

// Move up/down patterns
function moveTrackUp(index: number) {
  if (index > 1) reorderQueue(index, index - 1);
}

swapQueueItems()​

// Swap positions (can't swap with playing item at 0)
swapQueueItems(1, 3);  // Swap 2nd and 4th items

// Shuffle pattern
function shuffleQueue() {
  const length = getQueueLength();
  for (let i = 1; i < length; i++) {
    const j = Math.floor(Math.random() * (length - 1)) + 1;
    swapQueueItems(i, j);
  }
}

clearQueueAfterCurrent()​

// Keep only current, clear rest
clearQueueAfterCurrent();

// Replace upcoming tracks
clearQueueAfterCurrent();
await queueAudio('./new-track1.mp3');
await queueAudio('./new-track2.mp3');

getQueueItemInfo() / getQueueLength()​

// Get specific item info
const item = getQueueItemInfo(1);  // 2nd item
if (item) {
  console.log(`Next: ${item.fileName} (${item.duration}ms)`);
}

// Get queue size
const length = getQueueLength();  // Channel 0 (default)
console.log(`${length} tracks queued`);

Event Listeners​

onAudioStart() / onAudioComplete()​

// Track when audio starts
onAudioStart(0, (info) => {
  console.log(`Now playing: ${info.fileName}`);
  updateNowPlayingUI(info);
});

// Auto-play next playlist when done
onAudioComplete(0, async (info) => {
  const queueLength = getQueueLength();
  if (queueLength === 0) {
    await loadNextPlaylist();
  }
});

// Clean up event listeners when needed
offAudioStart(0);    // Remove all start listeners for channel 0
offAudioComplete(0); // Remove all complete listeners for channel 0

onAudioProgress()​

// Real-time progress updates
onAudioProgress(0, (info) => {
  progressBar.value = info.progress * 100;
  timeDisplay.textContent = formatTime(info.currentTime);
});

// Clean up when done
offAudioProgress(0);

onQueueChange()​

// Update UI when queue changes
onQueueChange(0, (snapshot) => {
  playlistElement.innerHTML = '';
  snapshot.items.forEach(item => {
    playlistElement.appendChild(createTrackElement(item));
  });
});

// Remove listener
offQueueChange(0);

Common Patterns​

Multi-Channel Game Audio​

const Channels = { BGM: 0, SFX: 1, VOICE: 2 };

// Background music
await queueAudio('./music/level1.mp3', Channels.BGM, { loop: true, volume: 0.4 });

// Sound effects (multiple can overlap via queue)
await queueAudio('./sfx/jump.wav', Channels.SFX);
await queueAudio('./sfx/coin.wav', Channels.SFX);

// Important dialogue
await queueAudioPriority('./voice/boss-warning.mp3', Channels.VOICE);

Playlist with Skip Controls​

// Load playlist
const tracks = ['song1.mp3', 'song2.mp3', 'song3.mp3'];
for (const track of tracks) {
  await queueAudio(`./music/${track}`);
}

// Skip button
skipButton.onclick = async () => await stopCurrentAudioInChannel();

// Previous button (simple approach)
prevButton.onclick = async () => {
  stopAllAudioInChannel();
  // Re-queue from previous track
  for (let i = currentTrackIndex - 1; i < tracks.length; i++) {
    await queueAudio(`./music/${tracks[i]}`);
  }
};

Background Audio with Interruptions​

// Ambient background
await queueAudio('./ambient/office.mp3', 0, { loop: true, volume: 0.2 });

// Notification system
async function playNotification(type: string) {
  // Duck background automatically
  setVolumeDucking({ priorityChannel: 1, duckingVolume: 0.1 });
  
  await queueAudioPriority(`./notifications/${type}.mp3`, 1);
  
  // Remove ducking after notification
  onAudioComplete(1, () => {
    clearVolumeDucking();
  });
}