Indexed by TopGit from live GitHub metadata: vueuse/sound has 559 stars, written primarily in TypeScript. π A Vue composable for playing sound effects
Snapshot summary built from the project's own GitHub metadata β there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then β see the READ ME tab for the original README in full.
π Lets your website communicate using 2 human senses instead of 1
π₯ Built with Vue Composition API
β Supports Vue 2 & 3 using vue-demi
π Supports Nuxt 2 & 3 using @vueuse/sound/nuxt
β‘οΈ <1kb bytes (gzip) in your bundle! ~10kb loaded async.
β¨ Built with TypeScript
π£ Uses a powerful, battle-tested audio utility: Howler.js
If you want to take a quick look at the composable in effect, you should visit the π demo.
This package is a Vue version of the useSound React hook by joshwcomeau.
Installation
Package can be added using yarn:
yarn add @vueuse/sound
Or, use NPM:
npm install @vueuse/sound
Examples
Play a sound on click
This is the most basic example of how fast you can implement sounds in your app using @vueuse/sound.
<template>
<button @click="play">Play a sound</button>
</template>
<script>
import { useSound } from '@vueuse/sound'
import buttonSfx from '../assets/sounds/button.mp3'
export default {
setup() {
const { play } = useSound(buttonSfx)
return {
play,
}
},
}
</script>
Playing on hover
This example is shown in the demo.
Increase pitch on every click
This example is shown in the demo.
Usage Notes
No sounds immediately after load
For the user's sake, browsers don't allow websites to produce sound until the user has interacted with them (eg. by clicking on something). No sound will be produced until the user clicks, taps, or triggers something.
useSound takes advantage of this: because we know that sounds won't be needed immediately on-load, we can lazy-load a third-party dependency.
useSound will add about 1kb gzip to your bundle, and will asynchronously fetch an additional package after load, which clocks in around 9kb gzip.
If the user does happen to click with something that makes noise before this dependency has been loaded and fetched, it will be a no-op (everything will still work, but no sound effect will play). In my experience this is exceedingly rare.
playbackRate doesn't just serve as an initial value for the sound effect. If playbackRate changes, the sound will immediately begin playing at a new rate. This is true for all options passed to the useSound composable.
API Documentation
The useSound composable takes two arguments:
A URL to the sound that it wil load
A config object (ComposableOptions)
It produces an array with two values:
A function you can call to trigger the sound
An object with additional data and controls (ExposedData)
When calling the function to play the sound, you can pass it a set of options (PlayOptions).
Let's go through each of these in turn.
ComposableOptions
When calling useSound, you can pass it a variety of options:
Name
Value
volume
number
playbackRate
number
interrupt
boolean
soundEnabled
boolean
sprite
SpriteMap
[delegated]
β
volume is a number from 0 to 1, where 1 is full volume and 0 is comletely muted.
playbackRate is a number from 0.5 to 4. It can be used to slow down or speed up the sample. Like a turntable, changes to speed also affect pitch.
interrupt specifies whether or not the sound should be able to "overlap" if the play function is called again before the sound has ended.
soundEnabled allows you to pass a value (typically from context or redux or something) to mute all sounds. Note that this can be overridden in the PlayOptions, see below
sprite allows you to use a single useSound composable for multiple sound effects. See βSpritesβ below.
[delegated] refers to the fact that any additional argument you pass in ComposableOptions will be forwarded to the Howl constructor. See "Escape hatches" below for more information.
The play function
When calling the composable, you get back a play function as the first item in the tuple:
const { play } = useSound('/meow.mp3')
// ^ What we're talking about
You can call this function without any arguments when you want to trigger the sound. You can also call it with a PlayOptions object:
Name
Value
id
string
forceSoundEnabled
boolean
playbackRate
number
id is used for sprite identification. See βSpritesβ below.
forceSoundEnabled allows you to override the soundEnabled boolean passed to ComposableOptions. You generally never want to do this. The only exception I've found: triggering a sound on the "Mute" button.
playbackRate is another way you can set a new playback rate, same as in ComposableOptions. In general you should prefer to do it through ComposableOptions, this is an escape hatch.
ExposedData
The composable produces a tuple with 2 options, the play function and an ExposedData object:
const [play, exposedData] = useSound('/meow.mp3')
// ^ What we're talking about
Name
Value
stop
function ((id?: string) => void)
pause
function ((id?: string) => void)
isPlaying
boolean
duration
number (or null)
sound
Howl (or null)
stop is a function you can use to pre-emptively halt the sound.
pause is like stop, except it can be resumed from the same point. Unless you know you'll want to resume, you should use stop; pause hogs resources, since it expects to be resumed at some point.
isPlaying lets you know whether this sound is currently playing or not. When the sound reaches the end, or it's interrupted with stop or paused, this value will flip back to false. You can use this to show some UI only while the sound is playing.
duration is the length of the sample, in milliseconds. It will be null until the sample has been loaded. Note that for sprites, it's the length of the entire file.
sound is an escape hatch. It grants you access to the underlying Howl instance. See the Howler documentation to learn more about how to use it. Note that this will be null for the first few moments after the component mounts.
Advanced
Sprites
An audio sprite is a single audio file that holds multiple samples. Instead of loading many individual sounds, you can load a single file and slice it up into multiple sections which can be triggered independently.
There can be a performance benefit to this, since it's less parallel network requests, but it can also be worth doing this if a single component needs multiple samples. See the Drum Machine component for an example.
For sprites, we'll need to define a SpriteMap. It looks like this:
To play a specific sprite, we'll pass its id when calling the play function:
<button
@click="play({id: 'laser'})"
>
Escape hatches
Howler is a very powerful library, and we've only exposed a tiny slice of what it can do in useSound. We expose two escape hatches to give you more control.
First, any unrecognized option you pass to ComposableOptions will be delegated to Howl. You can see the full list of options in the Howler docs. Here's an example of how we can use onend to fire a function when our sound stops playing:
The most recent commit recorded on vueuse/sound was 1.9 years ago, based on the GitHub push timestamp. The repository has 30 forks β one of the better signals of community interest.
Is vueuse/sound open source?
Yes β vueuse/sound ships under the MIT license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/vueuse/sound.
What license does vueuse/sound use?
vueuse/sound is released under the MIT license. Always verify the LICENSE file directly on GitHub for the authoritative terms β license strings can be edited out of sync with a project's actual stance.
What topics is vueuse/sound associated with?
GitHub's repository topics for vueuse/sound: "audio", "composition-api", "hooks", "sound", "vue", "vue-composable", "vue3". TopGit's editorial category is Frontend.
Where can I see vueuse/sound in action?
The project maintains a homepage at https://sound.vueuse.org. The README tab on this page also usually contains screenshots and a quickstart.
Where do I read more about vueuse/sound?
This TopGit page is a snapshot β the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/vueuse/sound is the definitive source.
Read full README in the tab above.
Still deciding about sound?
One click hands the question to an AI along with this page β see what it says about sound.