@awesome-web-projects/react-player

A React audio player component with circular frequency visualization powered by the Web Audio API and Canvas.

Listed on Awesome Audio Visualization. Layout inspired by Alex Permyakov's CodePen.

Features

• Circular audio frequency visualizer rendered on Canvas
• Streaming audio loading via Web Workers for smooth playback
• Partial loading — starts playing in seconds, preloads the full song in the background
• Keyboard shortcuts (Space, N, B)
• Configurable colors, volume, and visualization
• Zero runtime dependencies (besides React and Lucide icons)
• Full TypeScript support with exported types
• CSS Modules for style isolation

Installation

npm install @awesome-web-projects/react-player

Usage

import { AudioPlayer } from '@awesome-web-projects/react-player';
import '@awesome-web-projects/react-player/styles.css';

function App() {
  return (
    <AudioPlayer
      tracks={[
        { name: 'My Song', artist: 'Artist', url: '/song.mp3' },
        { name: 'Another', artist: 'Band', url: '/another.mp3' },
      ]}
      initialVolume={0.5}
      enableKeyboard
      enableVisualization
      visualizerColor="rgba(97, 218, 251, 0.8)"
      onTrackChange={(track, index) => console.log('Now playing:', track.name)}
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | tracks | Track[] | required | Array of tracks to play | | thread | 'main' \| 'worker' | 'worker' | Audio fetching strategy | | initialVolume | number | 0.5 | Initial volume (0-1) | | enableKeyboard | boolean | true | Enable keyboard shortcuts | | enableVisualization | boolean | true | Enable canvas visualizer | | visualizerColor | string | 'rgba(97, 218, 251, 0.8)' | Primary color for the visualizer | | className | string | — | Additional CSS class | | onTrackChange | (track, index) => void | — | Called when track changes | | onPlayStateChange | (playing) => void | — | Called on play/pause | | onTimeUpdate | (time, duration) => void | — | Called as playback progresses |

Track

interface Track {
  name: string;
  artist: string;
  url: string;
}

Keyboard Shortcuts

| Key | Action | |-----|--------| | Space | Play / Pause | | N | Next track | | B | Previous track |

Development

# Install dependencies
npm install

# Start demo dev server
npm run dev

# Build library
npm run build

# Type check
npm run typecheck

License

MIT