howler.js Audio Library

Common errors

• Uncaught (in promise) DOMException: play() failed because the user didn't interact with the document first.

  cause Browser autoplay policies prevent audio from playing until a user gesture (click, keydown, etc.).
  fix Call `sound.play()` only within an event listener for a user interaction. `howler.js` attempts to unlock audio on first input, but direct calls outside user events will fail.

• Howl is not defined

  cause The `Howl` class was not correctly imported or loaded into the scope.
  fix For ES Modules, use `import { Howl, Howler } from 'howler';`. For CommonJS, use `const { Howl, Howler } = require('howler');`. If using a script tag, ensure `howler.js` is loaded before your script and that `Howl` is accessed globally.

• Sound not looping correctly in Firefox.

  cause Browser-specific timing or decoding issues for looping audio files in certain Firefox versions.
  fix Update `howler.js` to version 2.2.2 or newer, which includes specific fixes for looping sounds in recent Firefox desktop versions.

• Audio file with authentication headers fails to load or plays with a network error.

  cause The Web Audio API's underlying XHR requests do not automatically send custom headers or `withCredentials` to the server for protected assets.
  fix When creating a new `Howl` instance for such files, set the `xhr` option with the appropriate `headers` or `withCredentials: true` property. This feature is available since `howler.js` v2.2.0.

Warnings

• breaking Browser autoplay policies now universally require user interaction before audio can play. The `mobileAutoEnable` option was renamed to reflect this broader impact.
  Fix: Ensure `Howl.play()` calls are triggered by a user gesture (e.g., click, keydown). Howler.js attempts to auto-unlock on the first user input, but explicit user interaction remains critical for reliable playback initiation.
• gotcha Earlier versions might encounter issues with multiple HTML5 Audio elements failing to play after the first one, due to browser limitations and resource handling.
  Fix: Upgrade to v2.1.0 or newer. This version introduced a global pool of HTML5 Audio nodes, which are unlocked on first user input, significantly improving reliability for subsequent HTML5 audio plays.
• gotcha When fetching audio files for the Web Audio API (default), custom HTTP headers (e.g., for authentication) or `withCredentials` settings are not automatically applied to XHR requests.
  Fix: For `Howl` instances requiring custom XHR settings, utilize the `xhr` property in the options object. This property, added in v2.2.0, allows specifying custom `headers`, `withCredentials`, and HTTP `method` for the request.
• gotcha Specific browser versions (e.g., Safari 14, recent Firefox, Chrome for iOS) have had unique quirks affecting audio playback, such as WAV detection, looping behavior, or critical errors.
  Fix: Regularly update `howler.js` to the latest version (currently 2.2.4). The library actively addresses these browser-specific issues, providing fixes for improved cross-browser compatibility and stability.

Install

• npm install howler npm
• yarn add howler yarn
• pnpm add howler pnpm

Imports

• Howl
  wrong:

  const Howl = require('howler');

  correct:

  import { Howl } from 'howler';

  Howl is the primary class for creating and managing individual audio instances. The 'require' syntax is for CommonJS environments.
• Howler
  wrong:

  const Howler = require('howler');

  correct:

  import { Howler } from 'howler';

  Howler is the global object for controlling all sounds and setting global preferences (e.g., global volume, mute). The 'require' syntax is for CommonJS environments.
• Browser Global
  wrong:

  import { Howl } from 'howler';

  correct:

  <!-- Add <script src="howler.js"></script> in HTML -->
  <script>
    const sound = new Howl({ src: ['sound.mp3'] });
  </script>

  When included directly via a script tag in the browser, `Howl` and `Howler` are available as global variables, making explicit imports unnecessary but potentially conflicting with module bundlers.

Quickstart

Initializes and plays background music and a sound effect, demonstrating global mute/unmute functionality and basic playback options.

import { Howl, Howler } from 'howler';

// Initialize a Howl instance for a background music loop
const bgMusic = new Howl({
  src: ['/assets/music.mp3', '/assets/music.webm'],
  loop: true,
  volume: 0.5
});

// Initialize a Howl for a sound effect
const sfx = new Howl({
  src: ['/assets/blip.mp3', '/assets/blip.wav'],
  volume: 0.8
});

// Global settings: mute all sounds and then unmute after a delay
Howler.mute(true);
console.log('All audio is muted globally.');

setTimeout(() => {
  Howler.mute(false);
  console.log('All audio is unmuted. Playing background music and sound effect.');
  bgMusic.play(); // Play background music
  sfx.play();     // Play a sound effect
}, 3000);

// You can also stop all sounds globally if needed
// Howler.stop();