Attributes

Shared Attributes

These attributes apply to <py-audio>, <py-video>, and <py-player>.

Attribute	Type	Default	Description
src	string	—	URL to the media file
title	string	—	Title displayed in the player
theme	string	"auto"	Color theme: auto light dark midnight nord sunset forest
accent	string	"#378ADD"	Accent color (any CSS color value)
tracks	string	—	JSON array of track/chapter objects
playlist	string	—	URL to an M3U or M3U8 playlist file
layout	string	"normal"	Layout preset: normal minimal album-art compact podcast visualizer playlist-first
allow-upload	boolean	—	Presence enables local file upload
strings	string	—	JSON object of UI string overrides

Layout-specific Attributes

Attribute	Type	Default	Layouts	Description
poster	string	—	album-art, podcast	Artwork/thumbnail image URL
artist	string	—	album-art, playlist-first	Artist name display
skip-back	number	15	podcast	Skip back seconds
skip-forward	number	30	podcast	Skip forward seconds

Video-specific Attributes

These attributes apply to <py-video> only.

Attribute	Type	Default	Description
poster	string	—	Thumbnail shown before playback
aspect-ratio	string	"16/9"	Video aspect ratio
autoplay	boolean	—	Start playing automatically
muted	boolean	—	Start muted (required for autoplay in most browsers)
loop	boolean	—	Loop playback

Smart Wrapper Attribute

Attribute	Type	Default	Description
type	string	—	Force "audio" or "video" — overrides auto-detection

Attribute Examples

<!-- Basic audio -->
<py-audio src="audio.mp3" title="My Podcast" theme="dark"></py-audio>

<!-- Full audio with tracks -->
<py-audio
  src="podcast.mp3"
  layout="podcast"
  theme="nord"
  accent="#5e81ac"
  title="Tech Talk"
  poster="episode.jpg"
  skip-back="15"
  skip-forward="30"
  tracks='[{"name":"Intro","time":"0:00"},{"name":"Main","time":"2:30"}]'
></py-audio>

<!-- Video with all options -->
<py-video
  src="video.mp4"
  poster="thumb.jpg"
  title="My Video"
  aspect-ratio="16/9"
  theme="midnight"
></py-video>

<!-- Smart wrapper with forced type -->
<py-player src="stream.m3u8" type="video"></py-player>

Track Format

Flat tracks (single file)

[
  { "name": "Intro",   "time": "0:00" },
  { "name": "Main",    "time": "2:30" },
  { "name": "Outro",   "time": "28:00" }
]

Multi-file playlist

[
  {
    "name": "Episode 1",
    "src": "ep1.mp3",
    "chapters": [
      { "name": "Intro", "time": "0:00" },
      { "name": "Main",  "time": "3:00" }
    ]
  },
  {
    "name": "Episode 2",
    "src": "ep2.mp3"
  }
]

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