Media Element Playout

When to Use Media Element Playout

Choose MediaElementPlaylistProvider over WaveformPlaylistProvider when you need:

• Large audio files - streams audio without downloading the entire file first
• Pre-computed peaks - use audiowaveform to generate peaks server-side
• Playback rate control - 0.5x to 2.0x speed with pitch preservation
• Single-track playback - simpler API, smaller bundle

Use WaveformPlaylistProvider (Tone.js) when you need:

• Multi-track mixing - multiple tracks playing in sync
• Audio effects - reverb, delay, EQ, etc.
• Precise timing - sample-accurate scheduling
• Recording - capture audio input

Basic Usage

import {
  MediaElementPlaylistProvider,
  useMediaElementAnimation,
  useMediaElementControls,
  MediaElementWaveform,
  loadWaveformData,
} from '@waveform-playlist/browser';

function MyPlayer() {
  const [waveformData, setWaveformData] = useState(null);

  useEffect(() => {
    loadWaveformData('/peaks/audio.dat').then(setWaveformData);
  }, []);

  if (!waveformData) return <div>Loading...</div>;

  return (
    <MediaElementPlaylistProvider
      track={{
        source: '/audio/track.mp3',
        waveformData,
        name: 'My Track',
      }}
      samplesPerPixel={512}
      waveHeight={100}
    >
      <PlaybackControls />
      <MediaElementWaveform />
    </MediaElementPlaylistProvider>
  );
}

function PlaybackControls() {
  const { isPlaying, currentTime } = useMediaElementAnimation();
  const { play, pause, setPlaybackRate } = useMediaElementControls();

  return (
    <div>
      <button onClick={() => play()} disabled={isPlaying}>Play</button>
      <button onClick={() => pause()} disabled={!isPlaying}>Pause</button>
      <button onClick={() => setPlaybackRate(0.5)}>0.5x</button>
      <button onClick={() => setPlaybackRate(1)}>1x</button>
      <button onClick={() => setPlaybackRate(2)}>2x</button>
    </div>
  );
}