Audio Player

A feature-rich audio player component with waveform visualization, playback controls, and seeking capabilities.

Installation


pnpm dlx bna-ui add audio-player

Usage

import { AudioPlayer } from '@/components/ui/audio-player';

Basic Usage

function MyComponent() {
  return (
    <AudioPlayer
      source={{ uri: 'https://example.com/audio.mp3' }}
      showControls={true}
      showWaveform={true}
      showTimer={true}
      autoPlay={false}
    />
  );
}

With Local File

<AudioPlayer
  source={require('./assets/audio/sample.mp3')}
  showControls={true}
  showWaveform={true}
  showTimer={true}
  showProgressBar={true}
  onPlaybackStatusUpdate={(status) => {
    console.log('Playback status:', status);
  }}
/>

Minimal Player

<AudioPlayer
  source={{ uri: 'https://example.com/audio.mp3' }}
  showControls={true}
  showWaveform={false}
  showTimer={false}
  showProgressBar={true}
/>

Examples

Default

Minimal

Waveform Only

Custom Styling

Auto Play

Progress Bar Only

Audio player Music

API Reference

AudioPlayer

The main AudioPlayer component.

Prop	Type	Default	Description
`source`	`AudioSource`	-	The audio source to play (URI or local file).
`style`	`ViewStyle`	-	Additional styles for the player container.
`showControls`	`boolean`	`true`	Whether to show playback controls.
`showWaveform`	`boolean`	`true`	Whether to show the waveform visualization.
`showTimer`	`boolean`	`true`	Whether to show the current time and duration.
`showProgressBar`	`boolean`	`true`	Whether to show the progress bar.
`autoPlay`	`boolean`	`false`	Whether to start playing automatically when loaded.
`onPlaybackStatusUpdate`	`(status: any) => void`	-	Callback fired when playback status changes.

AudioSource

The audio source configuration.

type AudioSource =
  | {
      uri: string;
    }
  | number; // For local files using require()

Playback Status

The status object passed to onPlaybackStatusUpdate:

type PlaybackStatus = {
  isLoaded: boolean;
  playing: boolean;
  duration: number;
  position: number;
};

Features

Waveform Visualization

The audio player includes an interactive waveform that:

Shows audio amplitude visualization with 60 bars
Displays playback progress with visual feedback
Supports seeking by tapping/clicking on the waveform
Animates smoothly during playback
Uses theme colors for active/inactive states

Playback Controls

Standard playback controls include:

Play/Pause: Toggle audio playback
Back 5 seconds: Skip backward 5 seconds
Restart: Return to the beginning of the track

Interactive Progress Bar

An alternative to waveform seeking:

Shows current playback position
Allows seeking by dragging or tapping
Smooth visual feedback during interaction
Respects theme colors

Timer Display

Shows current position and total duration:

Format: MM:SS / MM:SS
Updates in real-time during playback
Uses muted text color from theme

Platform Support

The AudioPlayer works across all platforms supported by Expo:

iOS: Native audio playback with hardware control integration
Android: Optimized audio engine with proper lifecycle management
Web: HTML5 audio with fallback support

Accessibility

The AudioPlayer component follows accessibility best practices:

Screen reader announcements for control actions
Proper button labeling and roles
Keyboard navigation support (web)
Respects system accessibility settings
High contrast support for visually impaired users

Performance

The component is optimized for performance:

Efficient waveform rendering with limited update frequency
Smooth animations using native drivers where possible
Memory-efficient audio loading and cleanup
Minimal re-renders during playback

Theming

The AudioPlayer automatically adapts to your app's theme:

Uses theme colors for backgrounds, text, and accents
Supports both light and dark modes
Destructive color for the main play button
Muted colors for inactive states
Customizable through theme configuration

Advanced Usage

Custom Playback Status Handling

<AudioPlayer
  source={{ uri: 'https://example.com/podcast.mp3' }}
  onPlaybackStatusUpdate={(status) => {
    if (status.isLoaded && status.playing) {
      // Track listening analytics
      analytics.track('audio_playing', {
        position: status.position,
        duration: status.duration,
      });
    }
  }}
/>

Responsive Design

<AudioPlayer
  source={{ uri: 'https://example.com/music.mp3' }}
  style={{
    maxWidth: 400,
    alignSelf: 'center',
  }}
  showWaveform={Platform.OS !== 'web'} // Hide on web for better performance
/>

Troubleshooting

Audio Not Loading

Ensure the audio source URL is accessible
Check network connectivity
Verify audio format is supported (MP3, AAC, WAV)
Check for CORS issues on web platform

Performance Issues

Reduce waveform bar count for lower-end devices
Disable animations on older devices
Use lower quality audio files for better loading times

Seeking Issues

Ensure audio file supports seeking (not all streaming formats do)
Check if the audio source provides duration metadata
Verify the audio file is not corrupted

Alert Audio Recorder