Audio Player

1// One per view. Decodes real peaks as soon as it has a source.2const player = new AudioPlayer({ mount: el, variant: 'full' })3player.load('/uploads/chapter-3.mp3')45// In a list. Two differences, both load-bearing:6//   lazyWaveform — the row costs nothing until the reader shows interest7//   label        — "Play Arthur", not the forty-fold "Play"8const row = new AudioPlayer({9  mount: cell,10  variant: 'compact',11  lazyWaveform: true,12  bars: 56,13  label: track.title,14})1516// attach() points it at a source WITHOUT fetching: the seeded shape and the17// duration you already have from the API are enough to render a real,18// scrubbable row before a byte is spent.19row.attach(track.src, { duration: track.duration_sec })2021// A list that re-renders must MOVE its players, not rebuild them. A dropped22// player keeps playing with nothing left to stop it, and still holds its slot23// in the exclusivity registry — so it silences whatever you start next.24if (players.has(id)) players.get(id).remount(cell)25else players.set(id, new AudioPlayer({ mount: cell, variant: 'compact' }))26for (const [id, p] of players) if (!visible.has(id)) { p.destroy(); players.delete(id) }

<!-- One clip on an otherwise plain page: use the native element. It brings
     keyboard control, the platform's own accessibility integration, and a
     download affordance you would otherwise have to build. -->
<figure>
  <audio controls preload="metadata" src="/uploads/chapter-3.mp3"></audio>
  <figcaption>
    Chapter 3 · 3 min 34 s ·
    <a href="/transcripts/chapter-3">Read the transcript</a>
  </figcaption>
</figure>

<!-- A themed player is the markup below. The waveform is a canvas because a
     list of forty is forty canvases rather than forty times seventy DOM nodes,
     and it is a slider because a canvas is otherwise a picture. -->
<div class="ds-audio ds-audio--row">
  <button class="ds-audio__play" type="button" aria-label="Play Arthur">…</button>

  <canvas
    class="ds-audio__wave"
    tabindex="0"
    role="slider"
    aria-label="Seek Arthur"
    aria-valuemin="0" aria-valuemax="100" aria-valuenow="0"
    aria-valuetext="0:00 of 0:26"
  ></canvas>

  <span class="ds-audio__time">0:26</span>
</div>

.ds-audio {
  display: flex;
  align-items: center;
  gap: var(--space-2);
  min-inline-size: 0;          /* or the waveform pushes the row wider than its cell */
  user-select: none;
}

/* The scarce thing in a list is vertical space, so the row variant is one line. */
.ds-audio--row .ds-audio__wave { block-size: 28px; }
.ds-audio--full .ds-audio__wave { block-size: 64px; }

.ds-audio__wave {
  flex: 1 1 auto;
  min-inline-size: 0;
  cursor: pointer;
  border-radius: var(--radius-sm);
}

/* A canvas is not focusable and has no value semantics. role="slider" plus a
   real focus ring is what makes it a control rather than a picture. */
.ds-audio__wave:focus-visible {
  outline: 2px solid var(--ds-focus-ring);
  outline-offset: 2px;
}

.ds-audio__play {
  display: grid;
  place-items: center;
  flex: 0 0 auto;
  inline-size: 28px;
  block-size: 28px;
  border-radius: var(--radius-full);
  background: var(--ds-accent);
  color: var(--ds-fg-on-accent);
}
.ds-audio--full .ds-audio__play { inline-size: 48px; block-size: 48px; }
.ds-audio__play:hover { background: var(--ds-accent-hover); }
.ds-audio__play:disabled { opacity: 0.4; }

/* Fixed width, tabular figures: the waveform must not resize as the clock
   counts, and the digits must not jitter. */
.ds-audio__time {
  flex: 0 0 auto;
  min-inline-size: 36px;
  text-align: end;
  font-size: 11px;
  font-variant-numeric: tabular-nums;
  color: var(--ds-fg-muted);
}

/* 28px is right for density and wrong for a thumb. The overlay makes the target
   44px without inflating the row. */
@media (pointer: coarse) {
  .ds-audio__play { position: relative; }
  .ds-audio__play::after {
    content: '';
    position: absolute;
    inset: 50% auto auto 50%;
    inline-size: 44px;
    block-size: 44px;
    translate: -50% -50%;
  }
}