useSound - react-native-use-sound
π A React Native Hook for playing sounds π
react-native-use-sound is largely based on the work by @joshwcomeau use-sound
Installation
npm i react-native-sound
cd ios && pod install
Then, our Hook can be added:
npm install react-native-use-sound
Examples
Basic Example
import useSound from "react-native-use-sound";
import { Button } from "react-native";
const MusicButton = () => {
const coolMusic =
"http://commondatastorage.googleapis.com/codeskulptor-demos/DDR_assets/Kangaroo_MusiQue_-_The_Neverwritten_Role_Playing_Game.mp3";
const [play, pause, stop, data] = useSound(coolMusic);
const handlePlay = () => {
if (data.isPlaying) pause();
else play();
};
return (
<>
<Button
title={data.isPlaying ? "Pause" : "Play"}
onPress={handlePlay}
/>
<Button
title={"Stop"}
onPress={stop}
/>
</>
);
};
API Documentation
The useSound
hook takes two arguments:
- A URL to the sound that it will load
- A config object (
HookOptions
)
It produces an array with four values:
- A function you can call to play the sound
- A function you can call to pause the sound
- A function you can call to stop the sound
- An object with additional data and controls (
ExposedData
)
HookOptions
When calling useSound
, you can pass it a variety of options:
Name | Value |
---|---|
volume | number |
interrupt | boolean |
soundEnabled | boolean |
timeRate | number |
numberOfLoops | boolean |
-
volume
is a number from0
to1
, where1
is full volume and0
is comletely muted. -
interrupt
specifies whether or not the sound should be able to "overlap" if theplay
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 thePlayOptions
, see below -
timeRate
is the frequency (in milliseconds) at which thecurrentTime
value will be updated. Default is 1000, -
numberOfLoops
specifies the number of times you want the sound repeated. Note that you can use-1
to Loop indefinitely until stop() is called.
Data
The hook produces a tuple with 4 options, the play, pause, stop functions and an Data
object:
const [play, pause, stop, data] = useSound("/meow.mp3");
// ^ What we're talking about
Name | Value |
---|---|
sound | Sound |
seek | function ((sec: number) => void) |
isPlaying | boolean |
duration | number |
currrentTime | number |
loading | boolean |
-
sound
is an escape hatch. It grants you access to the underlyingSound
instance. -
seek
is a function you can use to seek to a position in the sound. -
isPlaying
lets you know whether this sound is currently playing or not. When the sound reaches the end, or it's interrupted withstop
orpaused
, this value will flip back tofalse
. You can use this to show some UI only while the sound is playing. -
duration
is the length of the sample, in milliseconds. -
currentTime
is the current time of the sample, in milliseconds. You can chose the rate at which this is updated by specifyingtimeRate
in the hook options (see above). -
loading
lets you know whether the current sample is loading.