Rehawk
Work with audio in React it's painful sometimes, that's why this library was created. Especially in React, there are not too many good libraries out there to work with audio.
Rehawk is a powerful and lightweight library that aims to make things easier for you to start to work with audio. Using the Audio API, a custom React Hook powered by an XState finite state machine, it brings a lot of functionalities and methods for you to start faster your development, without having to waste time implementing anything.
Feel free to submit a PR.
Install
yarn add rehawk
Usage
All you need to do is import the RehawkProvider
context and the useRehawk
hook. Context was the best choice here because sometimes we might want to use different properties of our custom hook in different components in our React tree.
The following is a very basic usage example of Rehawk. If you want the most complete example of Rehawk working, click here.
import React from 'react';
import { RehawkProvider, useRehawk } from 'rehawk';
const src =
'https://storage.googleapis.com/media-session/elephants-dream/the-wires.mp3';
const Player = () => {
const {
ready,
loading,
error,
playing,
paused,
stopped,
onPlay,
onPause,
} = useRehawk({
src,
autoplay: false,
});
return (
<div>
<p>Ready: {ready ? 'true' : 'false'}</p>
<p>Loading: {loading ? 'true' : 'false'}</p>
<p>Error: {error}</p>
<p>Playing: {playing ? 'true' : 'false'}</p>
<p>Paused: {paused ? 'true' : 'false'}</p>
<p>Stopped: {stopped ? 'true' : 'false'}</p>
<button onClick={onPlay}>Play</button>
<button onClick={onPause}>Pause</button>
</div>
);
};
const App = () => {
return (
<RehawkProvider>
<Player />
</RehawkProvider>
);
};
API
Props
Name | Type | Required |
---|---|---|
src |
string | string[] |
false |
preload |
boolean |
false |
autoplay |
boolean |
false |
volume |
number (0.0 to 1.0) |
false |
muted |
boolean |
false |
loop |
boolean |
false |
rate |
number (0.25 to 5.0, with 1.0 being normal speed) |
false |
onLoading |
Callback function will run when 'loading' is true |
false |
onReady |
Callback function will run when 'ready' is true |
false |
onError |
Callback function will run when there's an error |
false |
onPlaying |
Callback function will run when 'playing' is true |
false |
onPaused |
Callback function will run when 'paused' is true |
false |
onStopped |
Callback function will run when 'stopped' is true |
false |
onMuted |
Callback function will run when 'muted' is true |
false |
onLooped |
Callback function will run when 'loop' is true |
false |
onEnded |
Callback function will run when 'ended' is true |
false |
Returned values
Name | Type | Description |
---|---|---|
loading |
boolean |
Return true if the audio is been loaded.
|
ready |
boolean |
Return true if the audio is ready to be played.
|
error |
string | null |
Return a string if any error occurs, otherwise returns null.
|
playing |
boolean |
Return true if audio is been played.
|
paused |
boolean |
Return true if audio is paused.
|
stopped |
boolean |
Return true if audio is stopped.
|
duration |
number |
Return the duration of the actual audio, in case there's no audio it returns 0.
|
seek |
number |
Return the seek of the actual audio, in case there's no audio it returns 0.
|
volume |
number |
Return the volume of the actual audio, in case there's no audio it returns 0.
|
muted |
boolean |
Return true if the audio is muted.
|
rate |
number |
Return the rate of the audio, in case there's no audio it returns 0.
|
loop |
boolean |
Return true if the audio is set to loop forever.
|
ended |
boolean |
Return true if the audio is ended.
|
Returned methods
Name | Type | Description |
---|---|---|
load |
({
src?: string;
preload?: boolean;
autoplay?: boolean;
volume?: number;
muted?: boolean;
loop?: boolean;
rate?: number;
onLoading = () => {};
onReady = () => {};
onError = () => {};
onPlaying = () => {};
onPaused = () => {};
onStopped = () => {};
onMuted = () => {};
onLooped = () => {};
onEnded = () => {};
}) => void |
Method to load the audio in case you want it.
|
onToggle |
() => void |
Switch between playing and paused.
|
onPlay |
() => void |
Set playing to true.
|
onPause |
() => void |
Set paused to true.
|
onStop |
() => void |
Set stopped to true.
|
onMute |
() => void |
Set muted to the opposite actual value.
|
onLoop |
() => void |
Set loop to the opposite actual value.
|
onVolume |
(e: React.ChangeEvent) => void |
Change volume to a specific value (recommended to be used in a input element).
|
onRate |
(value: number) => void |
Change rate to a specific value.
|
onSeek |
(e: React.ChangeEvent) => void |
Change seek to a specific value (recommended to be used in a input element).
|
onForward |
(number) => void |
Forward the audio for the specified number.
|
onBackward |
(number) => void |
Backward the audio for the specified number.
|
Example
To run the example do the following steps:
-
git clone
the repository cd rehawk/example
yarn install
yarn start
Contributing
Your contributions are welcome! If you have any questions or want to start to contribute to this library in any form, please open an issue. Feel free to open PR.
If there are any questions about this library or about any other topic, please contact me on Twitter @leonardomso and I'll gladly answer it.