rehawk
TypeScript icon, indicating that this package has built-in type declarations

0.2.6 • Public • Published

Rehawk

Actions Status LICENSE MIT npm version

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:

  1. git clone the repository
  2. cd rehawk/example
  3. yarn install
  4. 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.

Readme

Keywords

none

Package Sidebar

Install

npm i rehawk

Weekly Downloads

1

Version

0.2.6

License

MIT

Unpacked Size

135 kB

Total Files

22

Last publish

Collaborators

  • leonardomso