{"id":11043,"library":"howler","title":"howler.js Audio Library","description":"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.","status":"active","version":"2.2.4","language":"javascript","source_language":"en","source_url":"git://github.com/goldfire/howler.js","tags":["javascript","howler","howler.js","audio","sound","web audio","webaudio","browser","html5"],"install":[{"cmd":"npm install howler","lang":"bash","label":"npm"},{"cmd":"yarn add howler","lang":"bash","label":"yarn"},{"cmd":"pnpm add howler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Howl is the primary class for creating and managing individual audio instances. The 'require' syntax is for CommonJS environments.","wrong":"const Howl = require('howler');","symbol":"Howl","correct":"import { Howl } from 'howler';"},{"note":"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.","wrong":"const Howler = require('howler');","symbol":"Howler","correct":"import { Howler } from 'howler';"},{"note":"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.","wrong":"import { Howl } from 'howler';","symbol":"Browser Global","correct":"<!-- Add <script src=\"howler.js\"></script> in HTML -->\n<script>\n  const sound = new Howl({ src: ['sound.mp3'] });\n</script>"}],"quickstart":{"code":"import { Howl, Howler } from 'howler';\n\n// Initialize a Howl instance for a background music loop\nconst bgMusic = new Howl({\n  src: ['/assets/music.mp3', '/assets/music.webm'],\n  loop: true,\n  volume: 0.5\n});\n\n// Initialize a Howl for a sound effect\nconst sfx = new Howl({\n  src: ['/assets/blip.mp3', '/assets/blip.wav'],\n  volume: 0.8\n});\n\n// Global settings: mute all sounds and then unmute after a delay\nHowler.mute(true);\nconsole.log('All audio is muted globally.');\n\nsetTimeout(() => {\n  Howler.mute(false);\n  console.log('All audio is unmuted. Playing background music and sound effect.');\n  bgMusic.play(); // Play background music\n  sfx.play();     // Play a sound effect\n}, 3000);\n\n// You can also stop all sounds globally if needed\n// Howler.stop();","lang":"javascript","description":"Initializes and plays background music and a sound effect, demonstrating global mute/unmute functionality and basic playback options."},"warnings":[{"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.","message":"Browser autoplay policies now universally require user interaction before audio can play. The `mobileAutoEnable` option was renamed to reflect this broader impact.","severity":"breaking","affected_versions":">=2.1.0"},{"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.","message":"Earlier versions might encounter issues with multiple HTML5 Audio elements failing to play after the first one, due to browser limitations and resource handling.","severity":"gotcha","affected_versions":"<2.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.2.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Browser autoplay policies prevent audio from playing until a user gesture (click, keydown, etc.).","error":"Uncaught (in promise) DOMException: play() failed because the user didn't interact with the document first."},{"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.","cause":"The `Howl` class was not correctly imported or loaded into the scope.","error":"Howl is not defined"},{"fix":"Update `howler.js` to version 2.2.2 or newer, which includes specific fixes for looping sounds in recent Firefox desktop versions.","cause":"Browser-specific timing or decoding issues for looping audio files in certain Firefox versions.","error":"Sound not looping correctly in Firefox."},{"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.","cause":"The Web Audio API's underlying XHR requests do not automatically send custom headers or `withCredentials` to the server for protected assets.","error":"Audio file with authentication headers fails to load or plays with a network error."}],"ecosystem":"npm"}