0
# Howler.js
1

2
Howler.js is a comprehensive JavaScript audio library for modern web applications that provides a unified API for working with audio across different platforms. It automatically chooses between Web Audio API and HTML5 Audio and gracefully handles browser compatibility, mobile device limitations, and audio format support.
3

4
## Package Information
5

6
- **Package Name**: howler
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install howler`
10

11
## Core Imports
12

13
```javascript
14
import { Howl, Howler } from "howler";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Howl, Howler } = require("howler");
21
```
22

23
Browser (via CDN):
24

25
```html
26
<script src="https://cdn.jsdelivr.net/npm/howler@2.2.4/dist/howler.min.js"></script>
27
```
28

29
## Basic Usage
30

31
```javascript
32
import { Howl, Howler } from "howler";
33

34
// Create and play a sound
35
const sound = new Howl({
36
  src: ['path/to/audio.mp3', 'path/to/audio.ogg'],
37
  volume: 0.5,
38
  loop: true,
39
  onload: function() {
40
    console.log('Sound loaded successfully');
41
  }
42
});
43

44
// Play the sound
45
const id = sound.play();
46

47
// Control playback
48
sound.pause(id);
49
sound.stop(id);
50

51
// Global controls
52
Howler.volume(0.8); // Set global volume
53
Howler.mute(true);  // Mute all sounds
54
```
55

56
## Architecture
57

58
Howler.js is built around several key components:
59

60
- **Global Controller (Howler)**: Singleton instance managing global audio settings, codec detection, and audio context management
61
- **Sound Groups (Howl)**: Class representing a collection of related sounds with shared settings and audio source files
62
- **Individual Sounds (Sound)**: Internal instances representing individual playback instances within a Howl group
63
- **Audio Technology Abstraction**: Automatic selection between Web Audio API and HTML5 Audio based on browser capabilities
64
- **Mobile Audio Unlocking**: Automatic handling of mobile browser audio restrictions
65
- **Audio Sprites**: Support for playing segments of larger audio files for efficient resource usage
66

67
## Capabilities
68

69
### Global Audio Control
70

71
Centralized management of audio system settings, global volume control, codec detection, and audio context lifecycle.
72

73
```javascript { .api }
74
const Howler: {
75
  volume(vol?: number): Howler | number;
76
  mute(muted: boolean): Howler;
77
  stop(): Howler;
78
  unload(): Howler;
79
  codecs(ext: string): boolean;
80
};
81
```
82

83
[Global Audio Control](./global-audio.md)
84

85
### Sound Loading and Playback
86

87
Core functionality for loading audio files, creating sound instances, and controlling playback with support for multiple audio formats and automatic fallbacks.
88

89
```javascript { .api }
90
class Howl {
91
  constructor(options: HowlOptions);
92
  load(): Howl;
93
  play(sprite?: string): number;
94
  pause(id?: number): Howl;
95
  stop(id?: number): Howl;
96
  volume(vol?: number, id?: number): Howl | number;
97
  mute(muted?: boolean, id?: number): Howl | boolean;
98
  fade(from: number, to: number, len: number, id?: number): Howl;
99
  rate(rate?: number, id?: number): Howl | number;
100
  seek(seek?: number, id?: number): Howl | number;
101
  loop(loop?: boolean, id?: number): Howl | boolean;
102
  playing(id?: number): boolean;
103
  duration(id?: number): number;
104
  state(): string;
105
  unload(): Howl;
106
  on(event: string, fn: Function, id?: number): Howl;
107
  off(event?: string, fn?: Function, id?: number): Howl;
108
  once(event: string, fn: Function, id?: number): Howl;
109
}
110

111
interface HowlOptions {
112
  src: string | string[];
113
  volume?: number;
114
  html5?: boolean;
115
  loop?: boolean;
116
  preload?: boolean | 'metadata';
117
  autoplay?: boolean;
118
  mute?: boolean;
119
  sprite?: AudioSprite;
120
  rate?: number;
121
  pool?: number;
122
  format?: string | string[];
123
  xhr?: XHROptions;
124
  onend?: () => void;
125
  onfade?: () => void;
126
  onload?: () => void;
127
  onloaderror?: (id: number, error: any) => void;
128
  onplayerror?: (id: number, error: any) => void;
129
  onpause?: () => void;
130
  onplay?: () => void;
131
  onstop?: () => void;
132
  onmute?: () => void;
133
  onvolume?: () => void;
134
  onrate?: () => void;
135
  onseek?: () => void;
136
  onunlock?: () => void;
137
}
138
```
139

140
[Sound Loading and Playback](./sound-playback.md)
141

142
### Spatial Audio
143

144
3D positional audio and stereo panning capabilities for creating immersive audio experiences with spatial positioning, orientation, and realistic audio attenuation.
145

146
```javascript { .api }
147
// Global spatial audio methods
148
Howler.stereo(pan: number): Howler;
149
Howler.pos(x: number, y?: number, z?: number): Howler | number[];
150
Howler.orientation(x: number, y: number, z: number, xUp: number, yUp: number, zUp: number): Howler | number[];
151

152
// Per-sound spatial audio methods  
153
Howl.prototype.stereo(pan: number, id?: number): Howl | number;
154
Howl.prototype.pos(x: number, y?: number, z?: number, id?: number): Howl | number[];
155
Howl.prototype.orientation(x: number, y: number, z: number, id?: number): Howl | number[];
156
Howl.prototype.pannerAttr(o?: PannerAttributes, id?: number): Howl | PannerAttributes;
157

158
interface PannerAttributes {
159
  coneInnerAngle?: number;
160
  coneOuterAngle?: number;
161
  coneOuterGain?: number;
162
  distanceModel?: 'inverse' | 'linear' | 'exponential';
163
  maxDistance?: number;
164
  panningModel?: 'equalpower' | 'HRTF';
165
  refDistance?: number;
166
  rolloffFactor?: number;
167
}
168
```
169

170
[Spatial Audio](./spatial-audio.md)
171

172
## Types
173

174
```javascript { .api }
175
interface AudioSprite {
176
  [key: string]: [number, number] | [number, number, boolean];
177
}
178

179
interface XHROptions {
180
  method?: string;
181
  headers?: { [key: string]: string };
182
  withCredentials?: boolean;
183
}
184

185
type HowlEvent = 'load' | 'loaderror' | 'play' | 'end' | 'pause' | 'stop' | 'mute' | 'volume' | 'rate' | 'seek' | 'fade' | 'playerror' | 'unlock';
186

187
type LoadState = 'unloaded' | 'loading' | 'loaded';
188

189
type AudioContext = AudioContext | webkitAudioContext;
190
```