py-player

Appearance

Audio Player ​

<py-audio> is the core audio player element with real-time frequency visualization and 7 layout presets.

Basic Usage ​

html
<py-audio
  src="https://example.com/audio.mp3"
  title="My Track"
  theme="auto"
></py-audio>

Layouts ​

Set the layout attribute to choose a structural preset. All layouts support all themes.

Normal (default) ​

Full-featured: title bar, now playing, visualizer, progress, controls, playlist.

html
<py-audio src="audio.mp3" layout="normal" title="Full Player"></py-audio>

Minimal ​

Track name + progress bar + play/prev/next. No playlist, no visualizer, no title bar.

html
<py-audio src="audio.mp3" layout="minimal"></py-audio>

Album Art ​

Large artwork area (uses poster attribute or gradient placeholder), visualizer overlay, controls below.

html
<py-audio
  src="audio.mp3"
  layout="album-art"
  poster="https://example.com/cover.jpg"
  artist="Artist Name"
  title="Track Title"
></py-audio>

Compact ​

Single horizontal pill-shaped bar: play button, track name, progress, next. Suitable for sticky footer.

html
<py-audio src="audio.mp3" layout="compact" title="Now Playing"></py-audio>

Podcast ​

Podcast-optimized: episode thumbnail, skip -15s/+30s buttons, speed selector (0.5x–2x), chapter list.

html
<py-audio
  src="podcast.mp3"
  layout="podcast"
  title="Tech Talk EP 42"
  poster="https://example.com/episode-art.jpg"
  skip-back="15"
  skip-forward="30"
  tracks='[
    {"name": "Intro",    "time": "0:00"},
    {"name": "Topic 1",  "time": "2:30"},
    {"name": "Topic 2",  "time": "15:00"},
    {"name": "Outro",    "time": "28:00"}
  ]'
></py-audio>

Visualizer ​

Full-width frequency bars as hero element. Track info overlaid on top. Slim controls bar at bottom.

html
<py-audio
  src="music.mp3"
  layout="visualizer"
  theme="midnight"
  accent="#ff6b6b"
  artist="Artist Name"
></py-audio>

Playlist-first ​

Playlist dominates the view with rich track info. Compact player controls docked at bottom.

html
<py-audio
  src="playlist.mp3"
  layout="playlist-first"
  theme="auto"
  tracks='[
    {"name": "Morning Light", "time": "0:00"},
    {"name": "Sunset Drive",  "time": "3:30"},
    {"name": "Ocean Waves",   "time": "7:00"}
  ]'
></py-audio>

Visualization ​

The Normal and Visualizer layouts display real-time frequency bars powered by the Web Audio API (36 bars, fftSize 128). Visualization starts on first play.

Show Playlist ​

The minimal and album-art layouts hide the playlist by default. Add show-playlist to display it:

html
<py-audio
  src="audio.mp3"
  layout="minimal"
  show-playlist
  tracks='[
    {"name": "Track 1", "time": "0:00"},
    {"name": "Track 2", "time": "3:30"}
  ]'
></py-audio>

Works with minimal and album-art. Other layouts (normal, podcast, playlist-first) always show the playlist.

File Upload ​

Enable local file upload with the allow-upload attribute:

html
<py-audio
  allow-upload
  theme="dark"
  title="Upload & Play"
></py-audio>

Users can click the upload area to select audio files. Supports any audio/* format the browser can decode.

JavaScript API ​

js
const player = document.querySelector('py-audio')

player.play()
player.pause()

player.setTracks([
  { name: 'Chapter 1', time: '0:00' },
  { name: 'Chapter 2', time: '5:00' },
])

console.log(player.currentTime)
console.log(player.duration)
console.log(player.paused)

player.currentTime = 30

player.addEventListener('py-play', () => console.log('playing'))
player.addEventListener('py-track-change', (e) => console.log(e.detail))