Diagnosing and Fixing Audio Playback Failures in p5.js Sketches

Recognizable Condition

When you open a p5.js sketch that references p5.sound, the canvas renders but no sound is heard. In the browser console you see an error similar to:

Uncaught (in promise) DOMException: Failed to play audio.

This is a classic symptom of browser autoplay restrictions or a loading problem.

Root Cause Table

Potential Cause	Typical Error Message	Common Sources
Autoplay policy blocks playback until user interaction	Failed to play audio.	Modern Chrome, Edge, Safari, Firefox
Unsupported audio format or MIME type	Failed to load audio file.	WAV with BigEndian PCM, OGG with unsupported codec
p5.sound’s loadSound fails silently	No error callback fired, soundFile is undefined	File not found, CORS mis‑configured
Web Audio Context is suspended at load time	AudioContext is in the suspended state	Default browser behavior before user gesture

Ordered Diagnostic Checks

1. Verify loadSound callbacks
   

   let mySound;
   function preload() {
     mySound = loadSound('assets/beat.mp3', onLoad, onError);
   }
   function onLoad() { console.log('Loaded'); }
   function onError(err) { console.error('Load error:', err); }
   

   Open DevTools, check for Loaded or Load error messages.

2. Inspect console for autoplay or MIME errors
   

   Look for messages like Autoplay is not allowed because the user has not interacted with the document or Failed to load resource: net::ERR_FAILED.

3. Confirm correct MIME type on server
   

   Use curl -I https://example.com/assets/beat.mp3 to view headers. Expect Content-Type: audio/mpeg for MP3.

4. Ensure a user gesture precedes play()
   

   Wrap the call in a mousePressed or touchStarted handler.

5. Resume the AudioContext after interaction
   

   function mousePressed() {
     if (getAudioContext().state === 'suspended') {
       getAudioContext().resume();
     }
     mySound.play();
   }
   

Fixes Tied to Findings

• Autoplay block: Wrap play() in a user‑initiated event and call AudioContext.resume() before playback.
• Unsupported format: Convert audio to MP3 or WAV (PCM 16‑bit little endian). Test with a simple test.mp3 file.
• Silent loadSound failure: Add explicit success and error callbacks, log both, and verify the file path and CORS headers.
• Suspended context: Explicitly resume the context on first interaction, as shown in the code snippet above.
• CORS issues: Serve audio from the same origin or add Access-Control-Allow-Origin: * header on the server or CDN.

Concrete Example

Below is a minimal sketch that demonstrates a working pattern. Replace assets/beat.mp3 with your own file.

let beat;

function preload() {
  beat = loadSound('assets/beat.mp3', () => console.log('Beat loaded'), err => console.error(err));
}

function setup() {
  createCanvas(400, 200);
  background(220);
  textAlign(CENTER, CENTER);
  text('Click to play', width/2, height/2);
}

function mousePressed() {
  let ctx = getAudioContext();
  if (ctx.state === 'suspended') ctx.resume();
  beat.play();
}

Escalation Criteria

1. If all diagnostic checks pass but audio still fails, verify the browser’s AudioContext state in DevTools: getAudioContext().state should be running after resume().
2. Check for Web Audio API errors in the console that mention AudioBufferSourceNode or decodeAudioData.
3. If the issue recurs across multiple browsers, suspect a server‑side MIME or CORS misconfiguration; contact the hosting provider or adjust server settings.
4. For persistent failures on a specific platform (e.g., Safari on iOS), consult the platform’s audio documentation and consider using p5.sound version 1.4.0 or later, which includes workarounds for known Safari bugs.

Limitations & Practical Checks

• Autoplay policies evolve; always test on the latest stable browser releases.
• Audio format support varies: MP3 is widely supported; OGG is not in Safari.
• p5.sound requires p5.js ≥1.4.0. Verify the script tag points to the correct version.
• To confirm the audio file is served correctly, use fetch('assets/beat.mp3').then(r => console.log(r.headers.get('Content-Type'))) in the console.

Practical Verification

After applying the fixes, perform the following steps:

1. Open the sketch in Chrome, Firefox, and Safari.
2. Click the canvas once; the console should show Beat loaded and no error.
3. Audio should play immediately.
4. Reload the page and repeat the click; the AudioContext should remain running and no autoplay error should appear.