@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

Track

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

Keyboard Shortcuts

Development

# Install dependencies
npm install

# Start demo dev server
npm run dev

# Build library
npm run build

# Type check
npm run typecheck

License

MIT