Events

py-player dispatches custom DOM events. All events bubble and are composed (they cross Shadow DOM boundaries).

Event Reference

Shared Events (all components)

Event	Detail	Description
py-play	—	Playback started
py-pause	—	Playback paused
py-ended	—	Media finished playing
py-time-update	{ currentTime: number, duration: number }	Fires during playback
py-track-change	{ track: Track, index: number }	Active track changed
py-error	{ code: string, format: string }	Playback error

Video-only Events

Event	Detail	Description
py-fullscreen	{ active: boolean }	Fullscreen state changed

Usage Examples

Basic event listeners

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

player.addEventListener('py-play', () => {
  console.log('Playback started')
})

player.addEventListener('py-pause', () => {
  console.log('Playback paused')
})

player.addEventListener('py-ended', () => {
  console.log('Track finished')
})

Time update

player.addEventListener('py-time-update', (e) => {
  const { currentTime, duration } = e.detail
  const percent = (currentTime / duration) * 100
  document.getElementById('my-bar').style.width = `${percent}%`
})

Track change

player.addEventListener('py-track-change', (e) => {
  const { track, index } = e.detail
  console.log(`Now playing: ${track.name} (track ${index + 1})`)
})

Error handling

player.addEventListener('py-error', (e) => {
  const { code, format } = e.detail
  console.error(`Playback error [${code}]: unsupported format ${format}`)
})

Fullscreen (video)

const video = document.querySelector('py-video')

video.addEventListener('py-fullscreen', (e) => {
  if (e.detail.active) {
    console.log('Entered fullscreen')
  } else {
    console.log('Exited fullscreen')
  }
})

Event Detail Types

interface PyTimeUpdateDetail {
  currentTime: number
  duration: number
}

interface PyTrackChangeDetail {
  track: Track
  index: number
}

interface PyErrorDetail {
  code: string
  format: string
}

interface PyFullscreenDetail {
  active: boolean
}