Product
Introducing Java Support in Socket
We're excited to announce that Socket now supports the Java programming language.
Howler.js is a JavaScript audio library for the modern web. It provides a simple API for playing and controlling audio files, supporting a wide range of audio formats and offering features like spatial audio, audio sprites, and more.
Basic Audio Playback
This feature allows you to play audio files with a simple API. You can specify the source of the audio file and control playback with methods like play, pause, and stop.
const sound = new Howl({
src: ['sound.mp3']
});
sound.play();
Audio Sprites
Audio sprites allow you to combine multiple audio files into a single file and play specific sections of it. This can be useful for reducing the number of HTTP requests and managing audio assets more efficiently.
const sound = new Howl({
src: ['soundsprite.mp3'],
sprite: {
blast: [0, 1000],
laser: [2000, 3000]
}
});
sound.play('blast');
Spatial Audio
Spatial audio allows you to position audio in 3D space, providing a more immersive experience. You can set the position of the sound source and control its volume and other properties.
const sound = new Howl({
src: ['sound.mp3'],
pos: [0, 0, -0.5],
volume: 1.0
});
sound.play();
Event Handling
Howler.js provides an event system that allows you to listen for various events such as load, play, pause, and stop. This can be useful for synchronizing audio with other parts of your application.
const sound = new Howl({
src: ['sound.mp3']
});
sound.on('load', function() {
console.log('Sound loaded!');
});
sound.play();
Tone.js is a framework for creating interactive music in the browser. It provides a wide range of features for audio synthesis, effects, and scheduling. Compared to Howler.js, Tone.js is more focused on music creation and manipulation, offering more advanced features for audio synthesis and effects.
Pizzicato.js is a library that aims to simplify the way you create and manipulate sounds with the Web Audio API. It provides a simple API for common audio tasks and includes features like effects and sound generation. While Howler.js is more focused on audio playback and control, Pizzicato.js offers more tools for sound creation and manipulation.
Wavesurfer.js is a customizable audio waveform visualization, built on top of the Web Audio API. It allows you to create interactive waveforms for audio files, providing features like regions, markers, and plugins. Compared to Howler.js, Wavesurfer.js is more focused on visualizing and interacting with audio waveforms.
howler.js is an audio library for the modern web. It defaults to Web Audio API and falls back to HTML5 Audio. This makes working with audio in JavaScript easy and reliable across all platforms.
Additional information, live demos and a user showcase are available at howlerjs.com.
Follow on Twitter for howler.js and development-related discussion: @GoldFireStudios.
Tested in the following browsers/versions:
Several options to get up and running:
git clone https://github.com/goldfire/howler.js.git
npm install howler
yarn add howler
bower install howler
cdnjs
jsDelivr
In the browser:
<script src="/path/to/howler.js"></script>
<script>
var sound = new Howl({
src: ['sound.webm', 'sound.mp3']
});
</script>
As a dependency:
import {Howl, Howler} from 'howler';
const {Howl, Howler} = require('howler');
Included distribution files:
howler.core
and howler.spatial
. It includes all functionality that howler comes with.howler.core
to operate as it is simply an add-on to the core.var sound = new Howl({
src: ['sound.mp3']
});
sound.play();
var sound = new Howl({
src: ['stream.mp3'],
html5: true
});
sound.play();
var sound = new Howl({
src: ['sound.webm', 'sound.mp3', 'sound.wav'],
autoplay: true,
loop: true,
volume: 0.5,
onend: function() {
console.log('Finished!');
}
});
var sound = new Howl({
src: ['sounds.webm', 'sounds.mp3'],
sprite: {
blast: [0, 3000],
laser: [4000, 1000],
winner: [6000, 5000]
}
});
// Shoot the laser!
sound.play('laser');
var sound = new Howl({
src: ['sound.webm', 'sound.mp3']
});
// Clear listener after first call.
sound.once('load', function(){
sound.play();
});
// Fires when the sound finishes playing.
sound.on('end', function(){
console.log('Finished!');
});
var sound = new Howl({
src: ['sound.webm', 'sound.mp3']
});
// Play returns a unique Sound ID that can be passed
// into any method on Howl to control that specific sound.
var id1 = sound.play();
var id2 = sound.play();
// Fade out the first sound and speed up the second.
sound.fade(1, 0, 1000, id1);
sound.rate(1.5, id2);
import {Howl, Howler} from 'howler';
// Setup the new Howl.
const sound = new Howl({
src: ['sound.webm', 'sound.mp3']
});
// Play the sound.
sound.play();
// Change global volume.
Howler.volume(0.5);
More in-depth examples (with accompanying live demos) can be found in the examples directory.
Array/String
[]
required
The sources to the track(s) to be loaded for the sound (URLs or base64 data URIs). These should be in order of preference, howler.js will automatically load the first one that is compatible with the current browser. If your files have no extensions, you will need to explicitly specify the extension using the format
property.
Number
1.0
The volume of the specific track, from 0.0
to 1.0
.
Boolean
false
Set to true
to force HTML5 Audio. This should be used for large audio files so that you don't have to wait for the full file to be downloaded and decoded before playing.
Boolean
false
Set to true
to automatically loop the sound forever.
Boolean|String
true
Automatically begin downloading the audio file when the Howl
is defined. If using HTML5 Audio, you can set this to 'metadata'
to only preload the file's metadata (to get its duration without download the entire file, for example).
Boolean
false
Set to true
to automatically start playback when sound is loaded.
Boolean
false
Set to true
to load the audio muted.
Object
{}
Define a sound sprite for the sound. The offset and duration are defined in milliseconds. A third (optional) parameter is available to set a sprite as looping. An easy way to generate compatible sound sprites is with audiosprite.
new Howl({
sprite: {
key1: [offset, duration, (loop)]
},
});
Number
1.0
The rate of playback. 0.5 to 4.0, with 1.0 being normal speed.
Number
5
The size of the inactive sounds pool. Once sounds are stopped or finish playing, they are marked as ended and ready for cleanup. We keep a pool of these to recycle for improved performance. Generally this doesn't need to be changed. It is important to keep in mind that when a sound is paused, it won't be removed from the pool and will still be considered active so that it can be resumed later.
Array
[]
howler.js automatically detects your file format from the extension, but you may also specify a format in situations where extraction won't work (such as with a SoundCloud stream).
Object
null
When using Web Audio, howler.js uses an XHR request to load the audio files. If you need to send custom headers, set the HTTP method or enable withCredentials
(see reference), include them with this parameter. Each is optional (method defaults to GET
, headers default to null
and withCredentials defaults to false
). For example:
// Using each of the properties.
new Howl({
xhr: {
method: 'POST',
headers: {
Authorization: 'Bearer:' + token,
},
withCredentials: true,
}
});
// Only changing the method.
new Howl({
xhr: {
method: 'POST',
}
});
Function
Fires when the sound is loaded.
Function
Fires when the sound is unable to load. The first parameter is the ID of the sound (if it exists) and the second is the error message/code.
The load error codes are defined in the spec:
Function
Fires when the sound is unable to play. The first parameter is the ID of the sound and the second is the error message/code.
Function
Fires when the sound begins playing. The first parameter is the ID of the sound.
Function
Fires when the sound finishes playing (if it is looping, it'll fire at the end of each loop). The first parameter is the ID of the sound.
Function
Fires when the sound has been paused. The first parameter is the ID of the sound.
Function
Fires when the sound has been stopped. The first parameter is the ID of the sound.
Function
Fires when the sound has been muted/unmuted. The first parameter is the ID of the sound.
Function
Fires when the sound's volume has changed. The first parameter is the ID of the sound.
Function
Fires when the sound's playback rate has changed. The first parameter is the ID of the sound.
Function
Fires when the sound has been seeked. The first parameter is the ID of the sound.
Function
Fires when the current sound finishes fading in/out. The first parameter is the ID of the sound.
Function
Fires when audio has been automatically unlocked through a touch/click event.
Begins playback of a sound. Returns the sound id to be used with other methods. Only method that can't be chained.
String/Number
optional
Takes one parameter that can either be a sprite or sound ID. If a sprite is passed, a new sound will play based on the sprite's definition. If a sound ID is passed, the previously played sound will be played (for example, after pausing it). However, if an ID of a sound that has been drained from the pool is passed, nothing will play.Pauses playback of sound or group, saving the seek
of playback.
Number
optional
The sound ID. If none is passed, all sounds in group are paused.Stops playback of sound, resetting seek
to 0
.
Number
optional
The sound ID. If none is passed, all sounds in group are stopped.Mutes the sound, but doesn't pause the playback.
Boolean
optional
True to mute and false to unmute.Number
optional
The sound ID. If none is passed, all sounds in group are stopped.Get/set volume of this sound or the group. This method optionally takes 0, 1 or 2 arguments.
Number
optional
Volume from 0.0
to 1.0
.Number
optional
The sound ID. If none is passed, all sounds in group have volume altered relative to their own volume.Fade a currently playing sound between two volumes. Fires the fade
event when complete.
Number
Volume to fade from (0.0
to 1.0
).Number
Volume to fade to (0.0
to 1.0
).Number
Time in milliseconds to fade.Number
optional
The sound ID. If none is passed, all sounds in group will fade.Get/set the rate of playback for a sound. This method optionally takes 0, 1 or 2 arguments.
Number
optional
The rate of playback. 0.5 to 4.0, with 1.0 being normal speed.Number
optional
The sound ID. If none is passed, playback rate of all sounds in group will change.Get/set the position of playback for a sound. This method optionally takes 0, 1 or 2 arguments.
Number
optional
The position to move current playback to (in seconds).Number
optional
The sound ID. If none is passed, the first sound will seek.Get/set whether to loop the sound or group. This method can optionally take 0, 1 or 2 arguments.
Boolean
optional
To loop or not to loop, that is the question.Number
optional
The sound ID. If none is passed, all sounds in group will have their loop
property updated.Check the load status of the Howl
, returns a unloaded
, loading
or loaded
.
Check if a sound is currently playing or not, returns a Boolean
. If no sound ID is passed, check if any sound in the Howl
group is playing.
Number
optional
The sound ID to check.Get the duration of the audio source (in seconds). Will return 0 until after the load
event fires.
Number
optional
The sound ID to check. Passing an ID will return the duration of the sprite being played on this instance; otherwise, the full source duration is returned.Listen for events. Multiple events can be added by calling this multiple times.
String
Name of event to fire/set (load
, loaderror
, playerror
, play
, end
, pause
, stop
, mute
, volume
, rate
, seek
, fade
, unlock
).Function
Define function to fire on event.Number
optional
Only listen to events for this sound id.Same as on
, but it removes itself after the callback is fired.
String
Name of event to fire/set (load
, loaderror
, playerror
, play
, end
, pause
, stop
, mute
, volume
, rate
, seek
, fade
, unlock
).Function
Define function to fire on event.Number
optional
Only listen to events for this sound id.Remove event listener that you've set. Call without parameters to remove all events.
String
Name of event (load
, loaderror
, playerror
, play
, end
, pause
, stop
, mute
, volume
, rate
, seek
, fade
, unlock
).Function
optional
The listener to remove. Omit this to remove all events of type.Number
optional
Only remove events for this sound id.This is called by default, but if you set preload
to false, you must call load
before you can play any sounds.
Unload and destroy a Howl object. This will immediately stop all sounds attached to this sound and remove it from the cache.
Boolean
true
if the Web Audio API is available.
Boolean
true
if no audio is available.
Boolean
true
Automatically attempts to enable audio on mobile (iOS, Android, etc) devices and desktop Chrome/Safari.
Number
10
Each HTML5 Audio object must be unlocked individually, so we keep a global pool of unlocked nodes to share between all Howl
instances. This pool gets created on the first user interaction and is set to the size of this property.
Boolean
true
Automatically suspends the Web Audio AudioContext after 30 seconds of inactivity to decrease processing and energy usage. Automatically resumes upon new playback. Set this property to false
to disable this behavior.
Boolean
Web Audio Only
Exposes the AudioContext
with Web Audio API.
Boolean
Web Audio Only
Exposes the master GainNode
with Web Audio API. This can be useful for writing plugins or advanced usage.
The following methods are used to modify all sounds globally, and are called from the Howler
object.
Mute or unmute all sounds.
Boolean
True to mute and false to unmute.Get/set the global volume for all sounds, relative to their own volume.
Number
optional
Volume from 0.0
to 1.0
.Stop all sounds and reset their seek position to the beginning.
Check supported audio codecs. Returns true
if the codec is supported in the current browser.
String
File extension. One of: "mp3", "mpeg", "opus", "ogg", "oga", "wav", "aac", "caf", "m4a", "m4b", "mp4", "weba", "webm", "dolby", "flac".Unload and destroy all currently loaded Howl objects. This will immediately stop all sounds and remove them from cache.
Array
[1, 0, 0]
Sets the direction the audio source is pointing in the 3D cartesian coordinate space. Depending on how directional the sound is, based on the cone
attributes, a sound pointing away from the listener can be quiet or silent.
Number
null
Sets the stereo panning value of the audio source for this sound or group. This makes it easy to setup left/right panning with a value of -1.0
being far left and a value of 1.0
being far right.
Array
null
Sets the 3D spatial position of the audio source for this sound or group relative to the global listener.
Object
Sets the panner node's attributes for a sound or group of sounds. See the pannerAttr
method for all available options.
Function
Fires when the current sound has the stereo panning changed. The first parameter is the ID of the sound.
Function
Fires when the current sound has the listener position changed. The first parameter is the ID of the sound.
Function
Fires when the current sound has the direction of the listener changed. The first parameter is the ID of the sound.
Get/set the stereo panning of the audio source for this sound or all in the group.
Number
A value of -1.0
is all the way left and 1.0
is all the way right.Number
optional
The sound ID. If none is passed, all in group will be updated.Get/set the 3D spatial position of the audio source for this sound or group relative to the global listener.
Number
The x-position of the audio source.Number
The y-position of the audio source.Number
The z-position of the audio source.Number
optional
The sound ID. If none is passed, all in group will be updated.Get/set the direction the audio source is pointing in the 3D cartesian coordinate space. Depending on how directional the sound is, based on the cone
attributes, a sound pointing away from the listener can be quiet or silent.
Number
The x-orientation of the source.Number
The y-orientation of the source.Number
The z-orientation of the source.Number
optional
The sound ID. If none is passed, all in group will be updated.Get/set the panner node's attributes for a sound or group of sounds.
Object
All values to update.
360
A parameter for directional audio sources, this is an angle, in degrees, inside of which there will be no volume reduction.360
A parameter for directional audio sources, this is an angle, in degrees, outside of which the volume will be reduced to a constant value of coneOuterGain
.0
A parameter for directional audio sources, this is the gain outside of the coneOuterAngle
. It is a linear value in the range [0, 1]
.inverse
Determines algorithm used to reduce volume as audio moves away from listener. Can be linear
, inverse
or exponential
. You can find the implementations of each in the spec.10000
The maximum distance between source and listener, after which the volume will not be reduced any further.1
A reference distance for reducing volume as source moves further from the listener. This is simply a variable of the distance model and has a different effect depending on which model is used and the scale of your coordinates. Generally, volume will be equal to 1 at this distance.1
How quickly the volume reduces as source moves from listener. This is simply a variable of the distance model and can be in the range of [0, 1]
with linear
and [0, ∞]
with inverse
and exponential
.HRTF
Determines which spatialization algorithm is used to position audio. Can be HRTF
or equalpower
.Number
optional
The sound ID. If none is passed, all in group will be updated.Helper method to update the stereo panning position of all current Howls
. Future Howls
will not use this value unless explicitly set.
Number
A value of -1.0 is all the way left and 1.0 is all the way right.Get/set the position of the listener in 3D cartesian space. Sounds using 3D position will be relative to the listener's position.
Number
The x-position of the listener.Number
The y-position of the listener.Number
The z-position of the listener.Get/set the direction the listener is pointing in the 3D cartesian space. A front and up vector must be provided. The front is the direction the face of the listener is pointing, and up is the direction the top of the listener is pointing. Thus, these values are expected to be at right angles from each other.
Number
The x-orientation of listener.Number
The y-orientation of listener.Number
The z-orientation of listener.Number
The x-orientation of the top of the listener.Number
The y-orientation of the top of the listener.Number
The z-orientation of the top of the listener.Each new Howl()
instance is also a group. You can play multiple sound instances from the Howl
and control them individually or as a group (note: each Howl
can only contain a single audio file). For example, the following plays two sounds from a sprite, changes their volume together and then pauses both of them at the same time.
var sound = new Howl({
src: ['sound.webm', 'sound.mp3'],
sprite: {
track01: [0, 20000],
track02: [21000, 41000]
}
});
// Play each of the track.s
sound.play('track01');
sound.play('track02');
// Change the volume of both tracks.
sound.volume(0.5);
// After a second, pause both sounds in the group.
setTimeout(function() {
sound.pause();
}, 1000);
By default, audio on mobile browsers and Chrome/Safari is locked until a sound is played within a user interaction, and then it plays normally the rest of the page session (Apple documentation). The default behavior of howler.js is to attempt to silently unlock audio playback by playing an empty buffer on the first touchend
event. This behavior can be disabled by calling:
Howler.autoUnlock = false;
If you try to play audio automatically on page load, you can listen to a playerror
event and then wait for the unlock
event to try and play the audio again:
var sound = new Howl({
src: ['sound.webm', 'sound.mp3'],
onplayerror: function() {
sound.once('unlock', function() {
sound.play();
});
}
});
sound.play();
Full support for playback of the Dolby Audio format (currently support in Edge and Safari) is included. However, you must specify that the file you are loading is dolby
since it is in a mp4
container.
var dolbySound = new Howl({
src: ['sound.mp4', 'sound.webm', 'sound.mp3'],
format: ['dolby', 'webm', 'mp3']
});
Howler.js provides audio support for the new Facebook Instant Games platform. If you encounter any issues while developing for Instant Games, open an issue with the tag [IG]
.
Howler.js supports a wide array of audio codecs that have varying browser support ("mp3", "opus", "ogg", "wav", "aac", "m4a", "m4b", "mp4", "webm", ...), but if you want full browser coverage you still need to use at least two of them. If your goal is to have the best balance of small filesize and high quality, based on extensive production testing, your best bet is to default to webm
and fallback to mp3
. webm
has nearly full browser coverage with a great combination of compression and quality. You'll need the mp3
fallback for Internet Explorer.
It is important to remember that howler.js selects the first compatible sound from your array of sources. So if you want webm
to be used before mp3
, you need to put the sources in that order.
If you want your webm
files to be seekable in Firefox, be sure to encode them with the cues element. One way to do this is by using the dash
flag in ffmpeg:
ffmpeg -i sound1.wav -dash 1 sound1.webm
Support the ongoing development of howler.js and get your logo on our README with a link to your site [become a sponsor]. You can also become a backer at a lower tier and get your name in the BACKERS list. All support is greatly appreciated!
Copyright (c) 2013-2021 James Simpson and GoldFire Studios, Inc.
Released under the MIT License.
FAQs
Javascript audio library for the modern web.
The npm package howler receives a total of 327,689 weekly downloads. As such, howler popularity was classified as popular.
We found that howler demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
We're excited to announce that Socket now supports the Java programming language.
Security News
Socket detected a malicious Python package impersonating a popular browser cookie library to steal passwords, screenshots, webcam images, and Discord tokens.
Security News
Deno 2.0 is now available with enhanced package management, full Node.js and npm compatibility, improved performance, and support for major JavaScript frameworks.