Playlist & Chapters

py-player supports two playlist formats: flat chapter markers within a single file, and multi-file playlists with per-file chapters.

Format 1: Flat Tracks (Single File)

Use tracks to mark chapters within one audio/video file. Prev/next seeks within the file.

<py-audio
  src="podcast.mp3"
  tracks='[
    {"name": "Intro",     "time": "0:00"},
    {"name": "Main",      "time": "2:30"},
    {"name": "Deep Dive", "time": "15:00"},
    {"name": "Outro",     "time": "28:00"}
  ]'
></py-audio>

Time format: mm:ss or hh:mm:ss.

Format 2: Multi-file Playlist

Include src in each track object to create a multi-file playlist. Chapters are nested under each file.

<py-audio tracks='[
  {
    "name": "Episode 1",
    "src": "ep1.mp3",
    "chapters": [
      {"name": "Intro",      "time": "0:00"},
      {"name": "Main topic", "time": "2:30"},
      {"name": "Q&A",        "time": "15:00"}
    ]
  },
  {
    "name": "Episode 2",
    "src": "ep2.mp3",
    "chapters": [
      {"name": "Opening",   "time": "0:00"},
      {"name": "Interview", "time": "1:45"}
    ]
  }
]'></py-audio>

Format detection

• Objects with src field → multi-file mode
• Objects with time field (no src) → flat/single-file mode

Multi-file navigation

• Prev/next navigates chapters within the current file
• At last chapter → next goes to first chapter of next file
• At first chapter → prev goes to last chapter of previous file
• Progress bar shows progress of the current file only

M3U Playlist

Load an external M3U or M3U8 playlist file:

<py-audio playlist="https://example.com/playlist.m3u"></py-audio>

Or via JavaScript:

const player = document.querySelector('py-audio')
player.loadPlaylist('https://example.com/playlist.m3u8')

Programmatic Track Control

Set tracks dynamically via JavaScript:

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

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

Multi-file format:

player.setTracks([
  {
    name: 'Episode 1',
    src: '/audio/ep1.mp3',
    chapters: [
      { name: 'Intro', time: '0:00' },
      { name: 'Main',  time: '3:00' },
    ],
  },
  {
    name: 'Episode 2',
    src: '/audio/ep2.mp3',
  },
])

Track Change Event

player.addEventListener('py-track-change', (e) => {
  console.log(e.detail.track)  // current track object
  console.log(e.detail.index)  // track index
})

Type Definitions

interface Chapter {
  name: string
  time: string  // "mm:ss" | "hh:mm:ss"
}

interface FileTrack {
  name: string
  src: string
  poster?: string
  chapters?: Chapter[]
}

interface FlatTrack {
  name: string
  time: string
}

type TracksInput = FileTrack[] | FlatTrack[]