Security News
npm Updates Search Experience with New Objective Sorting Options
npm has a revamped search experience with new, more transparent sorting options—Relevance, Downloads, Dependents, and Publish Date.
@vueuse/sound
Advanced tools
@vueuse/sound/nuxt
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.
Package can be added using yarn:
yarn add @vueuse/sound
Or, use NPM:
npm install @vueuse/sound
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>
This example is shown in the demo.
This example is shown in the demo.
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.
Consider the following snippet of code:
const playbackRate = ref(0.75)
const { play } = useSound('/path/to/sound', { playbackRate })
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.
The useSound
composable takes two arguments:
ComposableOptions
)It produces an array with two values:
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.
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 belowsprite
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.
play
functionWhen 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.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.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:
const spriteMap = {
laser: [0, 300],
explosion: [1000, 300],
meow: [2000, 75],
}
SpriteMap
is an object. The keys are the id
s for individual sounds. The value is a tuple (array of fixed length) with 2 items:
This visualization might make it clearer:
We can pass our SpriteMap as one of our ComposableOptions:
const { play } = useSound('/path/to/sprite.mp3', {
sprite: {
laser: [0, 300],
explosion: [1000, 300],
meow: [2000, 75],
},
})
To play a specific sprite, we'll pass its id
when calling the play
function:
<button
@click="play({id: 'laser'})"
>
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:
const { play } = useSound('/thing.mp3', {
onend: () => {
console.info('Sound ended!')
},
})
If you need more control, you should be able to use the sound
object directly, which is an instance of Howler.
For example: Howler exposes a fade
method, which lets you fade a sound in or out. You can call this method directly on the sound
object:
<template>
<button
@click={sound.fade(0, 1, 1000)}
>
Click to win
</button>
</template>
<script>
import { useSound } from '@vueuse/sound'
export default {
setup() {
const { play, sound } = useSound('/win-theme.mp3')
return {
sound
}
}
}
</script>
If you are using Vite, you should add the following to your defineConfig options in vite.config.js:
optimizeDeps: {
exclude: ['vue-demi']
}
If you use Nuxt 2, you must have @nuxt/bridge setup in your project.
Once you installed it, add @vueuse/sound/nuxt
dependency to your project.
Add @vueuse/sound/nuxt
to the modules
section of your nuxt.config
:
defineNuxtConfig({
modules: ['@vueuse/sound/nuxt']
})
Configure your sounds 🥁:
defineNuxtConfig({
sound: {
sounds: {
back: {
src: "/back.wav",
options: {
volume: 0.25
}
}
}
}
})
You can also automatically scan an generate typings for your sounds in public/sounds
directory by using scan feature:
defineNuxtConfig({
sound: {
sounds: {
scan: true
}
}
})
Then move your sounds into public/sounds
directory, and get autocompletion on useSound({url})
.
All the credit behind this idea goes to Josh W. Comeau.
The documentation of this package has only been updated for Vue Composition API instead of React Hooks.
If you like this package, consider following me on GitHub and on Twitter.
FAQs
🔊 A Vue composable for playing sound effects
We found that @vueuse/sound demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers 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.
Security News
npm has a revamped search experience with new, more transparent sorting options—Relevance, Downloads, Dependents, and Publish Date.
Security News
A supply chain attack has been detected in versions 1.95.6 and 1.95.7 of the popular @solana/web3.js library.
Research
Security News
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.