React component for wavesurfer.js

[katspaugh]

I've just published a new package – @wavesurfer/react – a React component for wavesurfer.js.

It makes it easy to use wavesurfer from React. All of the familiar wavesurfer options become React props. You can subscribe to various wavesurfer events also via props. Just prepend an event name with on, e.g. ready -> onReady.

Please let me know if you have any feedback, suggestions for improvements are welcome!

I've also created a new NPM organization @wavesurfer where all future official packages will reside, and this React wrapper is the first one.

Usage

yarn add @wavesurfer/react

import WavesurferPlayer from '@wavesurfer/react'

const App = () => {
  const [wavesurfer, setWavesurfer] = useState(null)
  const [isPlaying, setIsPlaying] = useState(false)

  const onReady = (ws) => {
    setWavesurfer(ws)
    setIsPlaying(false)
  }

  const onPlayPause = () => {
    wavesurfer && wavesurfer.playPause()
  }

  return (
    <>
      <WavesurferPlayer
        height={100}
        waveColor="violet"
        url="/my-server/audio.wav"
        onReady={onReady}
        onPlay={() => setIsPlaying(true)}
        onPause={() => setIsPlaying(false)}
      />

      <button onClick={onPlayPause}>
        {isPlaying ? 'Pause' : 'Play'}
      </button>
    </>
  )
}

Links & docs

GitHub: https://github.com/katspaugh/wavesurfer-react
NPM: https://www.npmjs.com/package/@wavesurfer/react

[ChristopherTrimboli]

O M G... huge!

my only advice here would be to maybe also create a useWaveSurfer() hook that exposes the API instead of needing to make own useStates...

example:

const { play, stop, isLoading, isPlaying } = useWaveSurfer({
 src: "xyz",
 element: "#wavesurfer-id",
 ... etc
});

[andreamazzitelli]

Extremely useful!! Both the component and the hook work great!
I'd like to suggest an extension to the hook that would allow direct subscription to events without relying on props.

[katspaugh]

What do you mean, @andreamazzitelli?

[andreamazzitelli]

For example: I want to subscribe to the event "decode". The I only way to do it, at least to my understanding, is to use the WavesurferPlayer component passing a prop called onDecode. Instead it would be nice to be able to achieve the same result (i.e. subscribe to an event) also with the hook.

This could be done by passing and additional object to useWavesurfer like

const {wavesurfer, isready, isPlaying, currentTime} = useWavesurfer(options, {
"decode": functionDecode,
"interaction": functionInteraction
})

where functionDecode and functionInteraction are the functions to execute on "decode" and on "interaction".
I don't know if it is feasible and if it makes sense to do it this way 😅.

[katspaugh]

I see. I think this is a bit impractical in React as you also want to unsubscribe when your component unmounts. I recommend doing it this way:

const { wavesurfer } = useWavesurfer(options)

useEffect(() => {
  if (!wavesurfer) return
  const unsubscribe = wavesurfer.on('decode', () => { ... })
  return unsubscribe
}, [wavesurfer])

With the decode event specifically, since it's almost equal to the ready event, you could also trigger an effect like this:

const { wavesurfer, isReady } = useWavesurfer(options)

useEffect(() => {
  if (isReady) {
    // do something
  }
}, [isReady])

[andreamazzitelli]

I understand, I'm still unfamiliar with React so the unsubscribe when unmount part completely slipped my mind. I will surely try your suggestion.
Thanks for the quick replies and keep on with the great work!

[clbrec]

Thanks for your work @katspaugh. Do you have any hints on how to use a bit more 'advanced' features of your library like regions? Currently struggling to get this properly implemented with react, since I haven't found a way how to get the region instance.

Edit: Actually wasn't that complicated, can get the plugin reference like this:

    const regionsPlugin = useMemo(() => RegionsPlugin.create(), []);
    const plugins = useMemo(() => [regionsPlugin], [regionsPlugin]);
    const containerRef = useRef<HTMLDivElement>(null);

    const { wavesurfer, isPlaying } = useWavesurfer({
      container: containerRef,
      height: 64,
      url: url,
      peaks: peaks,
      duration: duration,
      plugins: plugins,
    });

Then simply add a region like:

      regionsPlugin.addRegion({
        content: `TestRegion`,
        start: wavesurfer.getCurrentTime(),
        end: wavesurfer.getCurrentTime() + 30,
      });

Alternatively can add the return value of addRegion to state if you need a reference for removal or w/e.

[clbrec]

@katspaugh I encountered something today where I'm not quite sure whether its a bug or me being dumb. When using useWavesurfer hook with zoom functionalities as follows.

interface TestProps {
  url: string;
}

export const TestComponent = ({ url }: TestProps) => {
  const containerRef = useRef<HTMLDivElement>(null);

  const { wavesurfer, isPlaying } = useWavesurfer({
    container: containerRef,
    url: url,
    interact: true,
    normalize: true,
    mediaControls: true,
  });

  const onZoomChange = useCallback(
    (_: Event, newValue: number | number[]) => {
      if (!wavesurfer) return;
      wavesurfer.zoom(newValue as number);
    },
    [wavesurfer]
  );

  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        width: "100%",
        height: "100%",
      }}
    >
      <div ref={containerRef} className="Container" />
      <div style={{ width: "300px", padding: "16px" }}>
        <Slider onChange={onZoomChange} min={0} max={150} />
      </div>
    </div>
  );
};

The resulting HTML looks like:

When I zoom in a bit:

So overflow changes from hidden to auto which is as expected to show scrollbar and width changes from 100% to whatever.

However, lets say I have a somewhat responsive UI so I'm not setting a fixed width when initializing wavesurfer or the div which gets the containerRef. I don't want the container to resize when zooming, i.e. it should stay at 100%, without the canvas breaking out of its bounds.

Setting it like

div ref={containerRef} className="Container" style={{overflow: 'hidden'}} />

doesn't do anything, since there's an additional wrapper div being rendered as a child of my container. Setting overflow: hidden on that child div directly via. devtools works.

Any hints on how to solve this? Doesn't seem like there's an easy way to target that container div, as it doesn't exist when my component first renders.

[katspaugh]

Not sure what you mean tbh. Wavesurfer already fills 100% of the parent width by default, and it won't overflow the parent because wavesurfer's own container scrolls when the canvas zooms. You can see it being responsive on https://wavesurfer.xyz/examples/?zoom.js when resizing the page.

[clbrec]

Saw that example. It's probably on my end then, sorry for that. Was just a bit confused, since setting the overflow to hidden on the outer-most div (coming from wavesurfer) seems to fix it for me. Guess I got some digging to do.

Thanks for the quick reply regardless.

[katspaugh]

Perhaps you could replicate your setup in an isolated example based off of the zoom.js example. Including the CSS/flexbox containers from your app. And see if you can reproduce it there.