Howl

Added in 6.5.0

Howl from soundhub/howler has the constructor and the methods of the Howler.js class of the same name. Each Howl is one sound in the shared hub that Howler.hub hands out. See Migrating from Howler.js for the overview.

import { Howl } from 'soundhub/howler';

const sound = new Howl(options: HowlOptions);

HowlOptions

Option	Type	Default	Description
src	string | string[]	required	The url, or a list the browser picks the first playable format from.
volume	number	1	Volume from 0 to 1.
loop	boolean	false	Start over at the end.
rate	number	1	Playback rate.
mute	boolean	false	Start muted.
sprite	Record<string, [offset, duration, loop?]>	none	Named ranges, in milliseconds. The third value makes one sprite loop.
autoplay	boolean	false	Play as soon as the file has loaded.
preload	boolean | 'metadata'	true	false waits for load(). 'metadata' counts as true.
html5	boolean	false	Stream the file with loadStream, for long files. One voice at a time, no sprites.
onload ... onunlock	functions	none	The callbacks, see Events.

Voice ids

play() returns a number, the voice id, as in Howler. Every call makes a new voice, so the same Howl can play over itself. Pass the id as the last argument to reach one voice, or leave it out to reach every voice of the Howl.

const laser = new Howl({ src: '/audio/laser.mp3' });

const a = laser.play();
const b = laser.play();

laser.volume(0.3, a); // only the first
laser.stop();         // both

play() returns the id before the file has loaded as well. The voice starts once the file is in.

Methods

Playback

Method	Returns	What it does
play(sprite?: string | number)	number	Play the whole file, a sprite by name, or resume a paused voice by its id.
pause(id?)	this	Pause one voice or all of them.
stop(id?)	this	Stop one voice or all of them.
playing(id?)	boolean	Whether that voice, or any voice, plays.
duration(id?)	number	Seconds. For a sprite voice the sprite's length, otherwise the file's. 0 before the file has loaded.
seek() / seek(id)	number	The position in seconds, of that voice or the first one.
seek(seconds, id?)	this	Jump to a position in seconds.

Properties

Each of these is a getter without a value and a setter with one.

Method	Unit	What it does
volume(volume?, id?)	0 to 1	Volume of one voice, or of the Howl and every voice.
fade(from, to, duration, id?)	0 to 1, milliseconds	Fade between two volumes. onfade fires at the end.
mute(muted?, id?)	boolean	Mute or unmute.
rate(rate?, id?)	factor	Playback rate.
loop(loop?, id?)	boolean	Loop or not.
stereo(pan?, id?)	-1 to 1	Stereo pan, left to right.
pos(x, y, z, id?)	units in the scene	Place the voice in 3D. It switches that voice to spatial panning.

volume, fade, mute, rate and loop without an id also set the value for voices that start later. With an id they only reach that voice. stereo and pos only reach voices that have started.

Loading

Method	Returns	What it does
load()	this	Start loading. Only needed with preload: false.
state()	'unloaded' | 'loading' | 'loaded'	Where loading stands.
unload()	null	Stop every voice, remove the listeners and unload the sound from the hub.

soundhubId

howl.soundhubId is a read-only string, the id of this Howl in the shared hub, such as 'howl1'. Use it with Howler.hub for anything Howler has no method for.

Events

Listen with the on* options, or with on, once and off:

sound.on('end', (id) => console.log('voice finished', id));
sound.once('load', () => sound.play());
sound.off('end');        // every end listener
sound.off();             // every listener
sound.on('end', fn, id); // only for one voice

Event	Fires when	Arguments
load	the file has loaded	none
loaderror	loading failed	null, the error
playerror	a voice could not start	voice id, the error
play	a voice starts or resumes	voice id
end	a voice reaches its end, or finishes one pass of a loop	voice id
pause	a voice pauses	voice id
stop	a voice stops	voice id
mute	mute() sets a value	voice id
volume	volume() sets a value	voice id
rate	rate() sets a value	voice id
seek	seek() jumps	voice id
fade	a fade() has run its duration	voice id
unlock	the browser has released audio after the first touch	none

Example

import { Howl } from 'soundhub/howler';

const sfx = new Howl({
  src: ['/audio/sfx.webm', '/audio/sfx.mp3'],
  sprite: {
    laser: [0, 400],
    coin: [500, 300],
    engine: [1000, 2000, true], // loops
  },
  volume: 0.8,
  onload: () => console.log('ready'),
});

const engine = sfx.play('engine');
sfx.rate(1.2, engine);
sfx.fade(0.8, 0, 1000, engine); // one second

sfx.play('coin');

Good to know

• A listener error is caught and logged, so the other listeners still run.
• Setting volume, rate or mute for one voice before its file has loaded does not stick. Set them without an id, or after onplay.
• mute, volume, rate and seek fire their event right away, in the same call.

See also

• Howler: the global object.
• Migrating from Howler.js: what is covered and what is not.