Skip to main content

​
Overview

Playback control components provide pre-built buttons that integrate with WaveformPlaylistProvider context. All components are fully controlled via context and automatically reflect the current playback state. Package: @waveform-playlist/browser Requires: WaveformPlaylistProvider context

​
PlayButton

Starts audio playback from the current cursor position or plays the selection region.

​
Props

​
className
string
Additional CSS class name for styling.

​
Behavior

  • With selection (no loop): Plays the selection region only, then stops
  • Without selection or with loop enabled: Plays from current cursor position (Transport loop handles boundaries when enabled)
  • Disabled when: Already playing

​
Usage

import { WaveformPlaylistProvider, PlayButton } from '@waveform-playlist/browser';

function Player() {
  return (
    <WaveformPlaylistProvider tracks={tracks}>
      <PlayButton className="my-play-btn" />
    </WaveformPlaylistProvider>
  );
}

​
PauseButton

Pauses audio playback at the current position.

​
Props

​
className
string
Additional CSS class name for styling.

​
Behavior

  • Pauses playback and maintains cursor position
  • Disabled when: Not playing

​
Usage

import { PauseButton } from '@waveform-playlist/browser';

<PauseButton />

​
StopButton

Stops audio playback.

​
Props

​
className
string
Additional CSS class name for styling.

​
Behavior

  • Stops playback completely
  • Disabled when: Not playing

​
Usage

import { StopButton } from '@waveform-playlist/browser';

<StopButton />

​
RewindButton

Rewinds playback to the beginning (0:00).

​
Props

​
className
string
Additional CSS class name for styling.

​
Behavior

  • Sets cursor to 0:00
  • If currently playing, restarts playback from 0:00
  • Always enabled

​
Usage

import { RewindButton } from '@waveform-playlist/browser';

<RewindButton />

​
FastForwardButton

Fast forwards to the end of the audio.

​
Props

​
className
string
Additional CSS class name for styling.

​
Behavior

  • Sets cursor to end of duration
  • If currently playing, restarts playback from end position
  • Always enabled

​
Usage

import { FastForwardButton } from '@waveform-playlist/browser';

<FastForwardButton />

​
SkipBackwardButton

Skips backward by a specified number of seconds.

​
Props

​
skipAmount
number
default:"5"
Number of seconds to skip backward.
​
className
string
Additional CSS class name for styling.

​
Behavior

  • Moves cursor backward by skipAmount seconds (minimum 0:00)
  • If currently playing, restarts playback from new position
  • Always enabled

​
Usage

import { SkipBackwardButton } from '@waveform-playlist/browser';

{/* Skip back 5 seconds (default) */}
<SkipBackwardButton />

{/* Skip back 10 seconds */}
<SkipBackwardButton skipAmount={10} />

​
SkipForwardButton

Skips forward by a specified number of seconds.

​
Props

​
skipAmount
number
default:"5"
Number of seconds to skip forward.
​
className
string
Additional CSS class name for styling.

​
Behavior

  • Moves cursor forward by skipAmount seconds (maximum: duration)
  • If currently playing, restarts playback from new position
  • Always enabled

​
Usage

import { SkipForwardButton } from '@waveform-playlist/browser';

{/* Skip forward 5 seconds (default) */}
<SkipForwardButton />

{/* Skip forward 30 seconds */}
<SkipForwardButton skipAmount={30} />

​
LoopButton

Toggles loop mode on/off. When loop is enabled, playback repeats within the loop region boundaries.

​
Props

​
className
string
Additional CSS class name for styling.

​
Behavior

  • Toggles loop enabled state
  • When enabling loop without a valid loop region, creates a default loop region (first 10 seconds or 25% of duration, whichever is smaller)
  • Button text changes to “Loop On” or “Loop Off” based on state
  • Always enabled

​
Usage

import { LoopButton } from '@waveform-playlist/browser';

<LoopButton />

​
SetLoopRegionButton

Sets or clears the loop region based on the current selection.

​
Props

​
className
string
Additional CSS class name for styling.

​
Behavior

  • If loop region exists: Clears it (button shows “Clear Loop”)
  • If valid selection exists: Sets loop region from selection (button shows “Set Loop”)
  • Disabled when: No valid selection and no existing loop region
  • Button title provides contextual help text

​
Usage

import { SetLoopRegionButton } from '@waveform-playlist/browser';

<SetLoopRegionButton />

​
AudioPosition

Displays the current audio playback position as formatted text. Package: @waveform-playlist/ui-components

​
Props

​
formattedTime
string
required
The formatted time string to display (e.g., “00:05”, “1:23.456”).
​
className
string
Additional CSS class name for styling.

​
Usage

This component is typically used with the useTimeFormat hook to format the current time: 
import { usePlaybackAnimation } from '@waveform-playlist/browser';
import { useTimeFormat } from '@waveform-playlist/browser';
import { AudioPosition } from '@waveform-playlist/ui-components';

function TimeDisplay() {
  const { currentTimeRef } = usePlaybackAnimation();
  const { formatTime } = useTimeFormat();
  const [time, setTime] = useState(0);
  
  // Update time display during playback
  useEffect(() => {
    const interval = setInterval(() => {
      setTime(currentTimeRef.current ?? 0);
    }, 100);
    return () => clearInterval(interval);
  }, []);
  
  return <AudioPosition formattedTime={formatTime(time)} />;
}

​
Complete Example

import { 
  WaveformPlaylistProvider, 
  PlayButton, 
  PauseButton, 
  StopButton,
  RewindButton,
  FastForwardButton,
  SkipBackwardButton,
  SkipForwardButton,
  LoopButton,
  SetLoopRegionButton
} from '@waveform-playlist/browser';

function PlaybackControls() {
  return (
    <WaveformPlaylistProvider tracks={tracks}>
      <div className="controls">
        <RewindButton />
        <SkipBackwardButton skipAmount={10} />
        <PlayButton />
        <PauseButton />
        <StopButton />
        <SkipForwardButton skipAmount={10} />
        <FastForwardButton />
        <LoopButton />
        <SetLoopRegionButton />
      </div>
    </WaveformPlaylistProvider>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us