# howler.js — Cross-Browser Audio Library for the Web

> A JavaScript audio library that provides a simple, consistent API for playing sound in any browser using the Web Audio API with HTML5 Audio fallback.

## Install

Save in your project root:

# howler.js — Cross-Browser Audio Library for the Web

## Quick Use
```bash
npm install howler
```
```js
import { Howl } from 'howler';

const sound = new Howl({
  src: ['sound.webm', 'sound.mp3'],
  volume: 0.8,
  loop: false
});
sound.play();
```

## Introduction
howler.js is an audio library that abstracts away browser inconsistencies in audio playback. It uses the Web Audio API for modern browsers and falls back to HTML5 Audio where needed, providing a single unified API for loading, playing, and controlling sounds across all platforms.

## What howler.js Does
- Plays audio reliably across all major browsers and mobile platforms
- Manages an internal audio sprite system for combining multiple sounds into one file
- Controls volume, playback rate, stereo panning, and spatial 3D positioning
- Handles audio format detection and automatic codec selection
- Pools and caches audio buffers for efficient memory usage

## Architecture Overview
howler.js provides two constructors: `Howl` for individual sounds and `Howler` for global audio settings. Under the hood, a core module manages the Web Audio API context, gain nodes, and buffer cache. When Web Audio is unavailable, a fallback module transparently switches to HTML5 Audio elements. Audio sprites are decoded from a single loaded buffer and played by seeking to the correct offset.

## Self-Hosting & Configuration
- Install via npm or include the minified script from a CDN (7KB gzipped)
- Create a `Howl` instance with `src` pointing to one or more audio files in preferred codec order
- Define audio sprites with a `sprite` map of `[offset, duration]` pairs in milliseconds
- Configure global settings via `Howler.volume()`, `Howler.mute()`, and `Howler.unload()`
- Enable spatial audio by setting `Howl` options `pannerAttr`, `pos`, and `orientation`

## Key Features
- Zero dependencies and 7KB gzipped for the core library
- Audio sprite support for combining many short sounds into one HTTP request
- Spatial audio with 3D positioning via the Web Audio panner node
- Automatic codec detection picks the best format from the `src` array
- Event callbacks for `load`, `play`, `end`, `pause`, `stop`, `fade`, and `loaderror`

## Comparison with Similar Tools
- **Tone.js** — Full audio synthesis and effects framework; howler.js is simpler for playback-only use cases
- **Pizzicato.js** — Focus on audio effects and filters; howler.js emphasizes cross-browser reliability
- **SoundJS** — Part of CreateJS suite; howler.js is standalone and lighter weight
- **HTML5 Audio element** — Native but inconsistent across browsers; howler.js normalizes the differences
- **Web Audio API direct** — Maximum control but verbose; howler.js provides a friendlier abstraction

## FAQ
**Q: Which audio formats should I provide?**
A: Include WebM or OGG for modern browsers and MP3 as a fallback. List the preferred format first in the `src` array.

**Q: Does howler.js work on mobile browsers?**
A: Yes. It handles mobile autoplay restrictions by unlocking the audio context on the first user interaction.

**Q: Can I use audio sprites for a game?**
A: Yes. Define a sprite map in the `Howl` config and call `sound.play('spriteName')` to play individual clips from a single file.

**Q: How do I fade audio in or out?**
A: Use `sound.fade(fromVolume, toVolume, durationMs)` to smoothly transition between volume levels.

## Sources
- https://github.com/goldfire/howler.js
- https://howlerjs.com/


---
Source: https://tokrepo.com/en/workflows/asset-d9fc60d5
Author: AI Open Source