Plugins

Overview

waves-cn is fully compatible with every official wavesurfer.js plugin. There are two injection patterns depending on when the plugin needs to be registered:

Pattern	When to use
`plugins` prop / option	Plugin must exist at instance creation time (e.g. `ZoomPlugin`, `TimelinePlugin`, `SpectrogramPlugin`)
`onReady` / `useEffect`	Plugin requires the instance to already exist (e.g. `RecordPlugin`)

Pattern 1 — `plugins` prop (at creation time)

Pass a memoized array to the plugins prop. The player and hook use array reference equality to decide whether to recreate the instance — a new array on every render will destroy and recreate the waveform on every render.

The instances you pass are templates. wavesurfer.js destroys plugins together with the instance, so waves-cn clones each template every time it (re)creates the instance. Put plugin option props in the useMemo deps to have option changes applied, and look the live plugin up after ready with ws.getActivePlugins() rather than holding on to the template.

With `WavesurferPlayer`

import { useMemo } from "react"
import WavesurferPlayer from "@/lib/wave-cn"
import ZoomPlugin from "wavesurfer.js/dist/plugins/zoom.esm.js"
import TimelinePlugin from "wavesurfer.js/dist/plugins/timeline.esm.js"

export function MyPlayer() {
  // ✅ Memoized — stable reference across renders
  const plugins = useMemo(() => [
    ZoomPlugin.create({ scale: 0.5, maxZoom: 1000 }),
    TimelinePlugin.create(),
  ], [])

  return <WavesurferPlayer url="/coastline.mp3" plugins={plugins} />
}

With `useWavesurfer`

import { useRef, useMemo } from "react"
import { useWavesurfer } from "@/lib/wave-cn"
import ZoomPlugin from "wavesurfer.js/dist/plugins/zoom.esm.js"

export function MyPlayer() {
  const containerRef = useRef<HTMLDivElement | null>(null)

  const plugins = useMemo(() => [ZoomPlugin.create({ scale: 0.5 })], [])

  const { wavesurfer, isReady } = useWavesurfer({
    container: containerRef,
    url: "/coastline.mp3",
    plugins,
  })

  return <div ref={containerRef} />
}

Never do this:

// ❌ New array every render → instance recreated every render
useWavesurfer({ plugins: [ZoomPlugin.create()] })

Pattern 2 — `onReady` / `useEffect` (after creation)

Some plugins like RecordPlugin need to be registered after the instance is ready. Use onReady with WavesurferPlayer, or useEffect on wavesurfer with the hook.

With `WavesurferPlayer`

import WavesurferPlayer from "@/lib/wave-cn"
import RecordPlugin from "wavesurfer.js/dist/plugins/record.esm.js"

<WavesurferPlayer
  onReady={(ws) => {
    ws.registerPlugin(
      RecordPlugin.create({ scrollingWaveform: true })
    )
  }}
/>

With `useWavesurfer`

import { useRef, useEffect } from "react"
import { useWavesurfer } from "@/lib/wave-cn"
import RecordPlugin from "wavesurfer.js/dist/plugins/record.esm.js"

export function MyRecorder() {
  const containerRef = useRef<HTMLDivElement | null>(null)
  const { wavesurfer } = useWavesurfer({ container: containerRef })

  useEffect(() => {
    if (!wavesurfer) return
    const record = wavesurfer.registerPlugin(
      RecordPlugin.create({ scrollingWaveform: true })
    )
    return () => {
      record.stopMic()
      record.destroy()
    }
  }, [wavesurfer])

  return <div ref={containerRef} />
}

Subscribing to plugin events

Plugin events are accessed imperatively via wavesurfer.on() or through the plugin instance itself. Subscribe inside a useEffect so the listener is removed when the instance is recreated. With WavesurferPlayer, grab the instance in onReady, store it in state, and subscribe in an effect:

const [ws, setWs] = useState<WaveSurfer | null>(null)

useEffect(() => {
  if (!ws) return
  return ws.on("zoom", (minPxPerSec) => {
    console.log("zoom level:", minPxPerSec)
  })
}, [ws])

<WavesurferPlayer
  url="/coastline.mp3"
  plugins={plugins}
  onReady={(instance) => setWs(instance)}
  onDestroy={() => setWs(null)}
/>

Or with the hook:

useEffect(() => {
  if (!wavesurfer) return
  return wavesurfer.on("zoom", (minPxPerSec) => {
    setZoom(Math.round(minPxPerSec))
  })
}, [wavesurfer])

wavesurfer.on() returns an unsubscribe function — return it from useEffect for automatic cleanup.

Available plugins

All official wavesurfer.js plugins work with waves-cn:

Plugin	Import
`ZoomPlugin`	`wavesurfer.js/dist/plugins/zoom.esm.js`
`TimelinePlugin`	`wavesurfer.js/dist/plugins/timeline.esm.js`
`RecordPlugin`	`wavesurfer.js/dist/plugins/record.esm.js`
`SpectrogramPlugin`	`wavesurfer.js/dist/plugins/spectrogram.esm.js`
`MinimapPlugin`	`wavesurfer.js/dist/plugins/minimap.esm.js`
`RegionsPlugin`	`wavesurfer.js/dist/plugins/regions.esm.js`
`HoverPlugin`	`wavesurfer.js/dist/plugins/hover.esm.js`
`EnvelopePlugin`	`wavesurfer.js/dist/plugins/envelope.esm.js`

See the full list at wavesurfer.xyz/plugins.

Plugins

On this page