howler

library2.2.4jsnpmunverified

howler.js is a robust JavaScript audio library designed for modern web applications, abstracting away the complexities of the Web Audio API and falling back seamlessly to HTML5 Audio when necessary. Currently stable at version 2.2.4, it sees regular maintenance releases addressing browser-specific quirks and improving reliability, such as fixes for Opera versions 100+ and Chrome for iOS. Key differentiators include its single, intuitive API, comprehensive cross-browser compatibility across desktop and mobile, support for audio sprites, 3D spatial audio, and an automatic HTML5 audio node pooling system to overcome common browser autoplay restrictions. It's a dependency-free, lightweight solution, offering full control over playback features like fading, rate, seek, and volume, suitable for a wide range of audio needs from simple sound effects to complex interactive audio experiences. It prioritizes performance with automatic caching and is modular, weighing in at just 7kb gzipped.

http-networking web-framework

npm install howler

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HOWLER

howler

http-networkingjavascriptv2.2.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Howl

✓ import { Howl } from 'howler';

✗ const Howl = require('howler');

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

Howler

✓ import { Howler } from 'howler';

✗ const Howler = require('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

✓  <script> const sound = new Howl({ src: ['sound.mp3'] }); </script>

✗ import { Howl } from 'howler';

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.

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();

Debug

Known issues

breakingBrowser 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.

affects: >=2.1.0

gotchaEarlier 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.

affects: <2.1.0

gotchaWhen 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.

affects: <2.2.0

gotchaSpecific 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.

affects: <2.2.4

Errors

Common errors & fixes

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

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

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.

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.

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.

Upgrade

Version history

2.2.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

Resources

githubhttps://github.com/goldfire/howler.js ↗

packagehttps://www.npmjs.com/package/howler ↗

homepagehttps://howlerjs.com ↗