Web Components reference

@pulse-music/web-component registers three elements as soon as it is imported. Registration is idempotent, so importing the package from several bundles never throws.

A machine-readable Custom Elements Manifest (custom-elements.json) ships with the package for IDEs and doc tools.

• <pulse-player> — the inline player card
• <pulse-fab> — the floating mini player
• <pulse-track> — a declarative playlist entry
• Sessions · Events · Labels · Keyboard

<pulse-player>

<pulse-player variant="midnight" accent-color="#a78bfa" ambient-eq resizable></pulse-player>

The card fills the width of its container and adapts to it:

Give the element a width in flex/grid layouts (it is a size container, so it doesn’t size itself from its content).

Attributes and properties

Slots

Light-DOM <pulse-track> children are read as the playlist and are never rendered.

CSS parts

player, artwork, title, artist, controls, progress, time.

pulse-player::part(title) {
  font-family: 'Fraunces', serif;
  letter-spacing: 0;
}

CSS custom properties

Custom states

Style the host from the outside with :state():

pulse-player:state(playing) {
  outline: 1px solid var(--brand);
}
pulse-player:state(loading) {
  cursor: progress;
}
pulse-player:state(error) {
  opacity: 0.8;
}

<pulse-fab>

<pulse-fab placement="bottom-end" pulso></pulse-fab>

A floating disc bound to the same session. Tap to play or pause; drag it anywhere and it springs to the nearest screen edge, remembering the spot in localStorage. Long-press, right-click, the ⋯ badge or Shift+F10 open a menu with previous, next and close.

CSS: --pulse-accent, --pulse-fab-z (stacking order, default 1000). The disc respects env(safe-area-inset-*).

Choosing Close in the menu pauses playback and hides the FAB (with reveal="on-play") until music starts again.

<pulse-track>

Declares a playlist entry in markup. Changes to the children or their attributes update the playlist live.

<pulse-player>
  <pulse-track
    src="/a.mp3"
    title="Intro"
    artist="Me"
    album="Demo"
    cover="/a.jpg"
    cover-pos="50% 20%"
    cover-scale="1.1"
  ></pulse-track>
  <pulse-track src="/b.mp3" title="Outro"></pulse-track>
</pulse-player>

Sessions

All players with the same session (default: 'default') share one audio element and stay in sync. Give a player its own session for an independent stream — for example a podcast next to background music:

<pulse-player session="music"></pulse-player> <pulse-player session="podcast"></pulse-player>

To configure a session’s engine (options, CORS…), install your own before the players mount:

import { PulseEngine, setSharedEngine } from '@pulse-music/web-component'

setSharedEngine(new PulseEngine({ tracks, crossOrigin: 'anonymous', repeat: 'none' }), 'music')

Events

Both players dispatch these on the element itself. They don’t bubble, so a page with several players never receives duplicates.

For page-level logic, prefer subscribing to the engine directly — see the engine reference.

Labels

Every visible or spoken string can be replaced:

document.querySelector('pulse-player').labels = {
  play: 'Lecture',
  pause: 'Pause',
  previous: 'Piste précédente',
  next: 'Piste suivante',
  seek: 'Position',
  nowPlaying: 'En cours',
  mute: 'Couper le son',
  unmute: 'Réactiver le son',
  loading: 'Chargement…',
  error: 'Lecture impossible',
  empty: 'Aucune piste',
  resize: 'Redimensionner',
  options: 'Options du lecteur',
  close: 'Fermer le lecteur',
  player: 'Lecteur audio',
  timeText: '{current} sur {duration}',
}

The defaults are exported as DEFAULT_LABELS.

Keyboard

Shortcuts apply while focus is inside a player:

Variants

auto · transparent · solid · dark · light · sunset · midnight · aurora · vinyl · custom — see Theming.