react-native-waveform-player

Native voice-note player for React Native. Play any local or remote audio file and render its waveform natively: Swift on iOS, Kotlin on Android, Fabric (New Architecture) only. Works in bare React Native and in Expo development builds (not Expo Go).

Documentation · Quick start · API reference · Tiếng Việt · 简体中文

Features

• Play, pause, scrub and cycle speed, all drawn in native code with no JavaScript in the hot path.
• Rounded-bar waveform decoded on the device, with a playhead that fills the current bar up to the exact pixel.
• Press-and-drag scrubbing with no activation delay, even inside a ScrollView.
• Configurable bar size, gap, radius and count, colors, time label (count-up or count-down) and a tap-to-cycle speed pill. Every part can be hidden.
• Pre-computed samples when you already have peaks data.
• Controlled (playing, speed) and uncontrolled modes, plus play(), pause(), toggle(), seekTo() and setSpeed() on a ref.
• Opt-in background playback with playInBackground.
• Events: onLoad, onLoadError, onPlayerStateChange, onTimeUpdate, onSeek, onEnd.

Try the styling options in the browser playground. To record voice notes, see the sister library react-native-waveform-recorder.

Installation

npm install react-native-waveform-player
# or
yarn add react-native-waveform-player

# iOS
cd ios && pod install

Expo: npx expo install react-native-waveform-player, then npx expo prebuild and run a development build. Requirements and the background playback setup are in the installation guide.

Quick start

import { AudioWaveformView } from 'react-native-waveform-player';

export function VoiceNote() {
  return (
    <AudioWaveformView
      source={{ uri: 'https://example.com/voice-note.m4a' }}
      style={{ height: 56 }}
      onEnd={() => console.log('finished')}
    />
  );
}

The view has no intrinsic size, so always give it a height.

Documentation

Everything else lives on the documentation site: https://maitrungduc1410.github.io/react-native-waveform-player/

• Props with their defaults
• Events and ref methods
• Styling and speed and playback, including controlled mode
• Background playback
• Platform notes and troubleshooting

The site is built from docs/ with VitePress, and the API reference is generated from the TSDoc comments in src/ with TypeDoc. Run yarn docs:dev to preview it locally.

Architecture

• ARCHITECTURE.md: codegen pipeline, the audio engine, decoder and bars view, the loading sequence and where state lives.
• LESSONS_LEARNED.md: bugs we hit and what we would do differently.

Contributing

• Development workflow
• Sending a pull request
• Agent / contributor guide
• Code of conduct

License

MIT

---

Made with create-react-native-library