Source Adapters
The source parameter controls how the player resolves its audio URL. When omitted, the source type is auto-detected from the src URL.
Local (default)
Plays the URL as-is. Use for direct audio file links or local Hugo resources.
AzuraCast
Fetches the AzuraCast nowplaying API to discover the stream URL and enriches the player with current song metadata.
Requires the data-azuracast-api-url attribute:
If src is provided alongside source="azuracast", it’s used directly without fetching the API.
Auto-detection: triggered when the URL contains azuracast or .stream..
iVoox
Fetches the iVoox episode page and extracts the audio URL from:
og:audiometa propertydata-audio-urlattribute<audio><source>element
On fetch failure, falls back to the src URL as-is.
Auto-detection: triggered when the URL contains ivoox.com.
JavaScript Events API
The component emits custom events that bubble through the DOM. Listen on any <podcast-player> or <podcast-footer> element:
Event Reference
| Event | Fired on | Detail payload |
|---|---|---|
player-state | play, pause, seek | { paused, src, currentTime, duration } |
podcast-play | play (compat) | { src, title, url } |
podcast-pause | pause | { src } |
podcast-close | footer close button | { src } |
podcast-seek | seek on any player | { src, currentTime } |
sessionStorage Persistence
State is saved per-source in sessionStorage using the key format:
This means multiple players on the same page use separate keys and don’t interfere with each other.
Cross-Page Behaviour
- Navigating away pauses inline audio (saves position)
- Returning to a page does not autoplay: the player restores in paused state
- The footer player persists across all pages without interruption
Keyboard Shortcuts
| Key | Action |
|---|---|
Space | Toggle play/pause |
Left Arrow | Skip back 15 seconds |
Right Arrow | Skip forward 15 seconds |
M | Toggle mute |
Works on both inline and footer players when the player is focused.
Media Session API
Wavecast integrates with the Media Session API, which means:
- Play/pause controls appear on OS lock screens and notification centres
- Track title and cover art are displayed in system media controls
- Hardware media keys (headphones, keyboard) control playback
This is automatic: no configuration needed.