@awesome-web-projects/music-player

Framework-agnostic audio player Web Components with multiple skins. Drop-in custom elements with Shadow DOM encapsulation — works in any framework or plain HTML. Powered by @awesome-web-projects/audio-engine.

Features

• 5 player skins: Circular, Minimal, Waveform, Vinyl, and Glass
• Standard Web Components (customElements.define) — no framework lock-in
• Shadow DOM for full style encapsulation
• Canvas-based audio visualizers (circular, waveform, glass)
• Streaming audio loading via Web Workers
• Partial loading — starts playing in seconds, preloads the full song in the background
• Keyboard shortcuts (Space, N, B)
• Configurable colors and volume
• Full TypeScript support with exported types

Installation

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

Usage

HTML

<script type="module">
  import '@awesome-web-projects/music-player';
</script>

<music-player-circular color="rgba(97, 218, 251, 0.8)"></music-player-circular>

<script>
  const player = document.querySelector('music-player-circular');
  player.tracks = [
    { name: 'Song One', artist: 'Artist A', url: '/songs/one.mp3' },
    { name: 'Song Two', artist: 'Artist B', url: '/songs/two.mp3' },
  ];
</script>

JavaScript / TypeScript

import { defineCircularPlayer, CircularPlayerElement } from '@awesome-web-projects/music-player';

// Elements are auto-registered on import, but you can also register individually:
// defineCircularPlayer();

const player = document.createElement('music-player-circular') as CircularPlayerElement;
player.tracks = [
  { name: 'Song One', artist: 'Artist A', url: '/songs/one.mp3' },
  { name: 'Song Two', artist: 'Artist B', url: '/songs/two.mp3' },
];
player.setAttribute('color', 'rgba(97, 218, 251, 0.8)');
document.body.appendChild(player);

Framework Integration

Works in React, Vue, Svelte, Angular, or any framework that supports custom elements:

// React example
function App() {
  const playerRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (playerRef.current) {
      (playerRef.current as any).tracks = [
        { name: 'Song', artist: 'Artist', url: '/song.mp3' },
      ];
    }
  }, []);

  return <music-player-minimal ref={playerRef} color="rgba(97, 218, 251, 0.8)" />;
}

Available Elements

| Element | Tag | Description | |---------|-----|-------------| | CircularPlayerElement | <music-player-circular> | Circular visualizer with frequency bars around a disc | | MinimalPlayerElement | <music-player-minimal> | Clean, compact player with progress bar | | WaveformPlayerElement | <music-player-waveform> | Waveform bar visualizer | | VinylPlayerElement | <music-player-vinyl> | Spinning vinyl disc animation | | GlassPlayerElement | <music-player-glass> | Frosted glass effect with frequency bars |

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | color | string | 'rgba(97, 218, 251, 0.8)' | Primary color for the player UI | | initial-volume | string | '0.5' | Initial volume (0-1) | | thread | 'main' \| 'worker' | 'worker' | Audio fetching strategy | | enable-keyboard | 'true' \| 'false' | 'true' | Enable keyboard shortcuts |

Properties

| Property | Type | Description | |----------|------|-------------| | tracks | Track[] | Array of tracks (set via JavaScript, not attribute) |

Track

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

Keyboard Shortcuts

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

Selective Registration

By default, all elements are registered on import. To register only specific elements:

import { defineCircularPlayer } from '@awesome-web-projects/music-player';

defineCircularPlayer(); // Only registers <music-player-circular>

Available registration functions: defineCircularPlayer, defineMinimalPlayer, defineWaveformPlayer, defineVinylPlayer, defineGlassPlayer, defineAllPlayers.

Related Packages

• @awesome-web-projects/audio-engine — The core audio engine this package is built on
• @awesome-web-projects/react-player — React components using the same engine

Development

npm install
npm run dev          # Start demo dev server
npm run build        # Build library
npm run build:demo   # Build demo page
npm run typecheck    # Type check

License

MIT