Skip to main content

Troubleshooting

Common issues and solutions when using AudioQ.

Audio Not Playing​

Browser Autoplay Policies​

Modern browsers require user interaction before playing audio:

// Wait for user interaction
document.addEventListener('click', () => {
  await queueAudio('sounds/music.mp3');
}, { once: true });

File Path Issues​

Ensure audio files are accessible:

// ✅ Correct - relative to public directory
await queueAudio('sounds/music.mp3');

// ❌ Incorrect - absolute paths usually don't work
await queueAudio('/Users/myuser/sounds/music.mp3');

Performance Issues​

Too Many Channels​

Limit the number of active channels:

// ✅ Good - reasonable number of channels
for (let i = 0; i < 4; i++) {
  await queueAudio('sound.mp3', i);
}

// ❌ Avoid - too many channels can impact performance
for (let i = 0; i < 100; i++) {
  await queueAudio('sound.mp3', i);
}

Browser Compatibility​

Safari Issues​

Safari has stricter audio policies. Ensure user interaction before audio playback.

Mobile Browsers​

Some mobile browsers have additional restrictions on background audio.

Need More Help?​