Skip to content

Player

Video, audio and embeds, a persistent audio player across pages, and an inline audio button.

<p class="cap-muted">No request goes to the service until the reader asks. Without script the link opens the service; with script (Prelum's <code>render/enhance</code> in a post, the React wrapper on a page) the player takes its place.</p>
<div class="player-sample-column">
  <figure class="cap-player" data-kind="embed" data-service="youtube" id="embed-poster"><a class="cap-player-facade" href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" data-embed-src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?autoplay=1" data-embed-title="A keynote on publishing with Prelum"><img class="cap-player-poster" src="./specimen/poster.svg" width="1280" height="720" alt="" loading="lazy" decoding="async"><span class="cap-player-play" aria-hidden="true"></span><span class="cap-player-label">Watch on YouTube: A keynote on publishing with Prelum</span></a><figcaption>The talk, 38 minutes.</figcaption></figure>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/player.css";
import { enhance } from "capsomer/behavior/player";

enhance();

Usage

<figure class="cap-player" data-kind="embed" data-service="youtube">
  <a class="cap-player-facade" href="https://www.youtube.com/watch?v=ID"
     data-embed-src="https://www.youtube-nocookie.com/embed/ID?autoplay=1" data-embed-title="The title">
    <img class="cap-player-poster" src="/media/poster.jpg?w=704" srcset="…" sizes="…" width="704" height="396" alt="" loading="lazy" decoding="async">
    <span class="cap-player-play" aria-hidden="true"></span>
    <span class="cap-player-label">Watch on YouTube: The title</span>
  </a>
  <figcaption>…</figcaption>
</figure>

<figure class="cap-player" data-kind="video">
  <video src="/media/demo.mp4" poster="/media/demo-poster.jpg?w=1408" width="1280" height="720" controls preload="none" loading="lazy" playsinline aria-label="The title">
    <track kind="captions" src="/media/demo.vtt" srclang="en" label="English" default>
  </video>
  <p class="cap-player-transcript"><a href="/writing/demo-transcript">Transcript: The title</a></p>
  <figcaption>…</figcaption>
</figure>

<figure class="cap-player" data-kind="audio">
  <audio src="/media/talk.mp3" controls preload="none" loading="lazy" aria-label="The title"></audio>
  <p class="cap-player-transcript"><a href="/writing/talk-transcript">Transcript: The title</a></p>
</figure>
import { Audio, Embed, Video } from "capsomer/react/player";

<Embed service="youtube" href={url} player={noCookieUrl} title="The title" action="Watch on YouTube" poster={pictureProps(attrs, { alt: "" }).img} />
import { PlayerDock, PlayerProvider, PlayerSurface, PlayerTranscript, ChapterList } from "capsomer/react/player";

<PlayerProvider storagePrefix="example-" artist="Example Show" artwork={[{ src: "/icon-512.png", sizes: "512x512", type: "image/png" }]} noun="episode">
  <Outlet />
  <PlayerDock renderLink={routerRenderLink} />
</PlayerProvider>
import { PlayerProvider, usePlayer } from "capsomer/react/player-context";
const PlayerDock = lazy(() => import("capsomer/react/player").then(({ PlayerDock }) => ({ default: PlayerDock })));
function Dock() {
  if (!usePlayer().current) return null;
  return <Suspense fallback={null}><PlayerDock renderLink={routerRenderLink} /></Suspense>;
}

const track = { id: 12, title: "Getting started", src: "/media/ep12.mp3", album: "Episode 12", chapters, href: "/getting-started", transcript: "/getting-started#transcript", duration: 1834 };
<PlayerSurface track={track} peaks={peaks} transcriptHref="#transcript" />
<ChapterList track={track} />
<PlayerTranscript cues={cues} track={track} shareUrl={(t) => `https://example.com/getting-started?t=${t}`} attribution={(title, url) => `From "${title}" on Example Show: ${url}`} />
<span class="cap-player-clip" data-cap="player" data-kind="clip">
  <a class="cap-player-clip-link" href="/media/capsomer.mp3" aria-label="Hear how Capsomer is pronounced"><svg aria-hidden="true">…</svg></a>
  <button type="button" class="cap-player-clip-button" data-src="/media/capsomer.mp3" aria-label="Hear how Capsomer is pronounced" aria-pressed="false" hidden><svg aria-hidden="true">…</svg></button>
</span>
import { enhance } from "capsomer/behavior/player";
enhance();

Examples

An embed with no poster, and a song

<div class="player-sample-column">
  <figure class="cap-player" data-kind="embed" data-service="vimeo" id="embed-plain"><a class="cap-player-facade" href="https://vimeo.com/123456789" data-embed-src="https://player.vimeo.com/video/123456789?dnt=1&amp;autoplay=1" data-embed-title="Setting up a new site in ten minutes"><span class="cap-player-play" aria-hidden="true"></span><span class="cap-player-label">Watch on Vimeo: Setting up a new site in ten minutes</span></a></figure>
  <figure class="cap-player" data-kind="embed" data-service="spotify" id="embed-audio"><a class="cap-player-facade" href="https://open.spotify.com/episode/0123456789abcdefghijkl" data-embed-src="https://open.spotify.com/embed/episode/0123456789abcdefghijkl" data-embed-title="Episode 12: shared site code"><span class="cap-player-play" aria-hidden="true"></span><span class="cap-player-label">Listen on Spotify: Episode 12: shared site code</span></a></figure>
</div>

The React wrapper: a click puts the player in place

<div class="player-sample-column" data-mount="embed"></div>

Video and audio

<p class="cap-muted">The native players at the column's width. The video holds its shape from its width and height, shows the site's poster, and downloads nothing before play; the audio's transcript is one link away.</p>
<div class="player-sample-column">
  <figure class="cap-player" data-kind="video" id="video"><video src="/media/sample-demo.mp4" poster="./specimen/poster.svg" width="1280" height="720" controls preload="none" loading="lazy" playsinline aria-label="A short demo"><track kind="captions" src="/media/sample-demo.vtt" srclang="en" label="English" default></video><p class="cap-player-transcript"><a href="/writing/demo-transcript">Transcript: A short demo</a></p><figcaption>What the demo shows.</figcaption></figure>
  <figure class="cap-player" data-kind="audio" id="audio"><audio src="/media/sample-talk.mp3" controls preload="none" loading="lazy" aria-label="A talk on shared site code"></audio><p class="cap-player-transcript"><a href="/writing/talk-transcript">Transcript: A talk on shared site code</a></p></figure>
</div>

A surface with no stored peaks: the stand-in shape, labeled a preview

<div class="player-sample-column" data-mount="standin"></div>

The editor's still waveform, with chapter markers, and before there are peaks

<div class="player-sample-column" data-mount="preview"></div>

The inline audio button: a short clip inside running text

<p class="cap-muted">With no script it is a link to the clip; with it, a button that plays in place and shows that it is playing. A clip that cannot load brings the link back.</p>
<div class="player-sample-column">
  <p id="clip-sample">Capsomer <span class="player-sample-ipa">/ˈkap.sə.mər/</span> <span class="cap-player-clip" data-cap="player" data-kind="clip"><a class="cap-player-clip-link" href="./specimen/tone.ts" aria-label="Hear how Capsomer is pronounced"><svg class="cap-player-clip-icon" viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false"><path d="M4 9.5h3.5L12 5.5v13l-4.5-4H4z" fill="currentColor"/><path class="cap-player-clip-wave" d="M15 9.2a4 4 0 0 1 0 5.6" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/><path class="cap-player-clip-wave" data-wave="2" d="M17.6 6.6a7.6 7.6 0 0 1 0 10.8" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/></svg></a><button type="button" class="cap-player-clip-button" data-src="./specimen/tone.ts" aria-label="Hear how Capsomer is pronounced" aria-pressed="false" hidden><svg class="cap-player-clip-icon" viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false"><path d="M4 9.5h3.5L12 5.5v13l-4.5-4H4z" fill="currentColor"/><path class="cap-player-clip-wave" d="M15 9.2a4 4 0 0 1 0 5.6" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/><path class="cap-player-clip-wave" data-wave="2" d="M17.6 6.6a7.6 7.6 0 0 1 0 10.8" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/></svg></button></span> is the family's design system.</p>
  <p>Playing, forced for the specimen: <span class="cap-player-clip"><button type="button" class="cap-player-clip-button" aria-label="Hear the sample clip" aria-pressed="true" id="clip-playing"><svg class="cap-player-clip-icon" viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false"><path d="M4 9.5h3.5L12 5.5v13l-4.5-4H4z" fill="currentColor"/><path class="cap-player-clip-wave" d="M15 9.2a4 4 0 0 1 0 5.6" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/><path class="cap-player-clip-wave" data-wave="2" d="M17.6 6.6a7.6 7.6 0 0 1 0 10.8" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/></svg></button></span></p>
</div>

The dock: a track loaded and paused, the settings inline; narrower than 48rem, behind More

<div data-mount="dock"></div>

The dock on a phone: More opens the bottom sheet with speed, sleep, chapters and the transcript

<div data-mount="dock"></div>

A track's page: the surface (waveform, scrubber with chapter ticks, transport, settings), key moments, chapters, hosts and the synced transcript; the dock steps aside while the surface is on screen

<div data-mount="surface"></div>

API reference

Video

PropTypeRequiredDoes
srcstringYes
titlestringYesThe video's accessible name.
posterstringYesThe site's own still, shown before play: with it the page downloads none of the video until asked.
widthnumberYesThe video's own size, so the box holds its shape before the first frame.
heightnumberYes
captions{ src: string; lang?: string; label?: string }Captions (WCAG 1.2.2). Leave out only for a video with no speech or sound that carries meaning.
transcriptstringA transcript, or a text alternative with what the picture shows (WCAG 1.2.3).
captionReactNode
loading"lazy" | "eager""lazy" (the default): the poster and the video wait until the player nears the screen (loading="lazy", Chromium; other browsers fetch the poster at once, as before). "eager" for a video at the top of a page, so its poster is not held back (Modern Web Guidance, lazy-load-video-and-audio).

Audio

PropTypeRequiredDoes
srcstringYes
titlestringYes
transcriptstringYesRequired: a recording of speech needs its words in text (WCAG 1.2.1).
captionReactNode
loading"lazy" | "eager"As for Video: "lazy" (the default) waits until the player nears the screen.

Embed

PropTypeRequiredDoes
servicestringYesThe service's name in the markup ("youtube", "vimeo", "spotify", "soundcloud").
hrefstringYesThe page on the service: where the link goes with no script.
playerstringYesThe player address the iframe loads after the click (the no-cookie host for YouTube).
titlestringYesWhat it shows; it names the player's iframe.
actionstringYesThe service's verb and name: "Watch on YouTube", "Listen on Spotify".
posterPosterPropsThe site's own poster, from its library. Never the service's thumbnail, which would call the service.
captionReactNode

Functions

FunctionSignatureDoes
resumePoint(saved: number, duration: number): number | nullA saved position is used only when it is past the start and short of the last five seconds.
playerStorage(prefix?: string): PlayerStorage
formatRate(r: number): string"1.0x", "1.25x".
sleepLabel(mode: SleepMode | null, noun?: string): stringThe sleep timer in words: "off", "end of episode", "15 minutes".
activeChapterIndex(chapters: readonly { start: number; }[], t: number): numberThe chapter playing at t, or -1. Chapters are sorted by start.
mediaSession(): MediaSession | null--------------------------------------------------------------------------------------- Media Session: the lock screen, a car and the media keys.
setPositionState(audio: HTMLMediaElement | null): voidPushes the element's position to the lock screen. A no-op without Media Session, before the duration is known, or on a value the browser refuses.
clearPositionState(): void
trackMetadata(track: PlayerTrack, defaults?: MetadataDefaults): MediaMetadataInit & { chapterInfo?: { title: string; startTime: number; }[] | undefined; }The metadata for a track: its own artist, album and artwork or the site's, and its chapters as chapterInfo (Media Session's chapter list, where the browser has it).
setSessionHandlers(handlers: SessionHandlers): () => voidSets every action handler; returns a function that clears them, so a stale one never fires.
loadTrack(audio: HTMLAudioElement, track: { id: string | number; src: string; }, storage: PlayerStorage): voidPoints the element at a track, resuming where the reader left off once its metadata is in, as the provider would. Nothing happens when it already has that source.
startTrack(audio: HTMLAudioElement, track: { id: string | number; src: string; }, storage: PlayerStorage): booleanPlays a track inside the press with the remembered rate, volume and mute, and marks the element for the provider. Pressing the same playing track again pauses it. Returns whether the press still needs the app (false once it paused).
computePeaks(channels: Float32Array<ArrayBufferLike>[], n?: number): number[]Peaks from decoded PCM (one Float32Array per channel): the peak of each slice of a mono mixdown, scaled so the loudest is 100. No decoding here, so a Node script and a browser both use it.
decodePeaks(source: ArrayBuffer, n?: number): Promise<{ peaks: number[]; duration: number; } | null>Decodes an audio file in the browser and returns its peaks and exact duration, or null where the browser cannot decode it. Heavy and one-shot: for an editor at upload, never a reader's page.
probeDuration(file: Blob): Promise<number | null>A file's duration in whole seconds from its metadata alone, or null.
normalizePeaks(peaks: readonly number[] | null | undefined, bars?: number): number[] | nullbars heights from 0 to 1 (at least 0.04 so a quiet bar still shows), or null with no peaks.
syntheticPeaks(bars?: number): number[]A calm shape for a track with no stored peaks yet: two sines, never flat, never like real data.
playheadCue(cues: readonly { start: number; }[], t: number): number | nullThe start of the last cue at or before t, or null: the active cue where the browser has no VTTCue to follow.
wireClip(root: HTMLElement): () => void--------------------------------------------------------------------------------------- The inline audio button: a small play button inside running text that plays a short clip (a pronunciation). The server writes a plain link to the clip, which works with no script; this shows the button in its place, which plays in place on a press (a native button: click, Enter, Space). Nothing is fetched before the first press. aria-pressed carries the playing state; a second press stops it. A clip that cannot load or play brings the link back.
enhance(root?: ParentNode): () => voidEvery inline audio button under root ([data-cap="player"][data-kind="clip"]). Idempotent.
clampRate(r: number): number
clampVolume(v: number): number
formatTime(seconds?: number | null | undefined): string--------------------------------------------------------------------------------------- Time and labels. "1:02:03" or "4:05".
spokenTime(seconds?: number | null | undefined): string"3 minutes, 12 seconds", for aria-valuetext.

CSS variables

VariableDefault
--cap-player-at0%
--cap-player-btnmax(var(--control), var(--target))
--cap-player-btn-lgcalc(var(--cap-player-btn, max(var(--control), var(--target))) + var(--space-3))
--cap-player-dock-h0px
--cap-player-facevar(--ui)
--cap-player-meta-facevar(--mono)

Parts and data attributes

ClassIs
.cap-playerthe root
.cap-player-ata part
.cap-player-btna part
.cap-player-chaptera part
.cap-player-chapter-nowa part
.cap-player-chapter-titlea part
.cap-player-chaptersa part
.cap-player-choicesa part
.cap-player-clipa part
.cap-player-clip-buttona part
.cap-player-clip-linka part
.cap-player-clip-wavea part
.cap-player-cuea part
.cap-player-docka part
.cap-player-dock-innera part
.cap-player-dock-rowa part
.cap-player-facadea part
.cap-player-finea part
.cap-player-hosta part
.cap-player-host-namea part
.cap-player-host-texta part
.cap-player-hostsa part
.cap-player-icona part
.cap-player-jumpa part
.cap-player-labela part
.cap-player-legenda part
.cap-player-list-headinga part
.cap-player-marka part
.cap-player-menua part
.cap-player-metaa part
.cap-player-meta-texta part
.cap-player-momenta part
.cap-player-momentsa part
.cap-player-morea part
.cap-player-nowa part
.cap-player-optionsa part
.cap-player-paraa part
.cap-player-para-chaptera part
.cap-player-para-texta part
.cap-player-playa part
.cap-player-postera part
.cap-player-ratea part
.cap-player-readalonga part
.cap-player-saida part
.cap-player-scrubbera part
.cap-player-seeka part
.cap-player-settingsa part
.cap-player-sheeta part
.cap-player-speakera part
.cap-player-spina part
.cap-player-surfacea part
.cap-player-surface-rowa part
.cap-player-surface-settingsa part
.cap-player-ticksa part
.cap-player-timea part
.cap-player-titlea part
.cap-player-tracka part
.cap-player-transcripta part
.cap-player-transcript-bara part
.cap-player-transcript-boxa part
.cap-player-transcript-linka part
.cap-player-transcript-rawa part
.cap-player-transporta part
.cap-player-volumea part
.cap-player-volume-rowa part
.cap-player-wavea part
.cap-player-wave-bara part
.cap-player-wave-barsa part
.cap-player-wave-boxa part
.cap-player-wave-emptya part
.cap-player-wave-markera part
.cap-player-wave-notea part
.cap-player-wave-previewa part
.cap-player-wave-regiona part
.cap-player-wave-tipa part
AttributeValues
data-activepresent or absent
data-hiddenpresent or absent
data-kindsound
data-layoutgrid
data-partclose next play setting skip
data-servicesoundcloud spotify
data-sizelg sm
data-stateleading played playing region
data-tonecrit
data-wave2
StateRead from
:disabledthe platform
:hoverthe platform
[aria-current="true"]an attribute
[aria-pressed="true"]an attribute
[hidden]an attribute

Accessibility

KeyDoes
TabReaches the embed, the player's own controls and the transcript link
Enter on an embedPuts the player in its place and moves focus into it
KeyDoes
TabReaches each control in order; the dock's controls are skipped while it is hidden
Enter or Space on a controlPlays or pauses, skips, opens a setting, presses a chapter, a key moment or a transcript line
Arrow keys on the scrubberBack or forward 5 seconds; with Shift, 15
Page Up, Page Down on the scrubberForward or back a minute
Home, End on the scrubberTo the start, to the end
Arrow keys in a settingChoose the speed or the sleep timer (radios), move through a menu
EscCloses a popover, a menu or the sheet; focus returns to its button
Enter or Space on the inline audio buttonPlays the clip; again, stops it
  • The embed is a link named by the service and the title; the play button and the poster are decoration (aria-hidden, alt=""). The player's iframe is named by the title.
  • The video and audio are named by their title (aria-label); captions and transcripts are WCAG 1.2.1 to 1.2.3.
  • Nothing plays by itself; the service's autoplay starts only after the reader's own click.
  • Screen readers: no manual NVDA or VoiceOver run, by decision (2026-11-07); the automated browser checks and a front-end review stand in. Automated: see the site's Tests page.
  • Play and pause change the button's name ("Play", "Pause") and carry no aria-pressed (APG Button: one or the other). A listing's PlayTrackButton names the track and does carry aria-pressed, as germomics' did.
  • The scrubber is a native range with aria-valuetext ("1 minute 5 seconds of 2 minutes"); the waveform never is the only way to seek.
  • Speed and sleep are radios in a fieldset in the sheet and the speed popover (one tab stop, arrows choose); in the dock and on the surface, sleep and chapters are the shared menu's radio items.
  • The player's state is said politely ("Playing, Field notes", "Buffering", "Error loading audio") from one live region, outside the hidden dock.
  • The chapter playing, the key moment playing and the transcript line playing are aria-current, with an edge, weight or tint beside the color; forced colors keep a system color or an outline.
  • Volume is left out under a coarse pointer: phones have their own buttons and iOS ignores a page's volume (MDN, HTMLMediaElement.volume).
  • The inline audio button is named by its label ("Hear how Capsomer is pronounced") and carries aria-pressed.