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();import "capsomer/tokens.css";
import "capsomer/player.css";
import { Video, Audio, Embed } from "capsomer/react/player";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&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
| Prop | Type | Required | Does |
|---|---|---|---|
src | string | Yes | |
title | string | Yes | The video's accessible name. |
poster | string | Yes | The site's own still, shown before play: with it the page downloads none of the video until asked. |
width | number | Yes | The video's own size, so the box holds its shape before the first frame. |
height | number | Yes | |
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. | |
transcript | string | A transcript, or a text alternative with what the picture shows (WCAG 1.2.3). | |
caption | ReactNode | ||
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
| Prop | Type | Required | Does |
|---|---|---|---|
src | string | Yes | |
title | string | Yes | |
transcript | string | Yes | Required: a recording of speech needs its words in text (WCAG 1.2.1). |
caption | ReactNode | ||
loading | "lazy" | "eager" | As for Video: "lazy" (the default) waits until the player nears the screen. |
Embed
| Prop | Type | Required | Does |
|---|---|---|---|
service | string | Yes | The service's name in the markup ("youtube", "vimeo", "spotify", "soundcloud"). |
href | string | Yes | The page on the service: where the link goes with no script. |
player | string | Yes | The player address the iframe loads after the click (the no-cookie host for YouTube). |
title | string | Yes | What it shows; it names the player's iframe. |
action | string | Yes | The service's verb and name: "Watch on YouTube", "Listen on Spotify". |
poster | PosterProps | The site's own poster, from its library. Never the service's thumbnail, which would call the service. | |
caption | ReactNode |
Functions
| Function | Signature | Does |
|---|---|---|
resumePoint | (saved: number, duration: number): number | null | A 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): string | The sleep timer in words: "off", "end of episode", "15 minutes". |
activeChapterIndex | (chapters: readonly { start: number; }[], t: number): number | The 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): void | Pushes 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): () => void | Sets 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): void | Points 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): boolean | Plays 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[] | null | bars 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 | null | The 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): () => void | Every 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
| Variable | Default |
|---|---|
--cap-player-at | 0% |
--cap-player-btn | max(var(--control), var(--target)) |
--cap-player-btn-lg | calc(var(--cap-player-btn, max(var(--control), var(--target))) + var(--space-3)) |
--cap-player-dock-h | 0px |
--cap-player-face | var(--ui) |
--cap-player-meta-face | var(--mono) |
Parts and data attributes
| Class | Is |
|---|---|
.cap-player | the root |
.cap-player-at | a part |
.cap-player-btn | a part |
.cap-player-chapter | a part |
.cap-player-chapter-now | a part |
.cap-player-chapter-title | a part |
.cap-player-chapters | a part |
.cap-player-choices | a part |
.cap-player-clip | a part |
.cap-player-clip-button | a part |
.cap-player-clip-link | a part |
.cap-player-clip-wave | a part |
.cap-player-cue | a part |
.cap-player-dock | a part |
.cap-player-dock-inner | a part |
.cap-player-dock-row | a part |
.cap-player-facade | a part |
.cap-player-fine | a part |
.cap-player-host | a part |
.cap-player-host-name | a part |
.cap-player-host-text | a part |
.cap-player-hosts | a part |
.cap-player-icon | a part |
.cap-player-jump | a part |
.cap-player-label | a part |
.cap-player-legend | a part |
.cap-player-list-heading | a part |
.cap-player-mark | a part |
.cap-player-menu | a part |
.cap-player-meta | a part |
.cap-player-meta-text | a part |
.cap-player-moment | a part |
.cap-player-moments | a part |
.cap-player-more | a part |
.cap-player-now | a part |
.cap-player-options | a part |
.cap-player-para | a part |
.cap-player-para-chapter | a part |
.cap-player-para-text | a part |
.cap-player-play | a part |
.cap-player-poster | a part |
.cap-player-rate | a part |
.cap-player-readalong | a part |
.cap-player-said | a part |
.cap-player-scrubber | a part |
.cap-player-seek | a part |
.cap-player-settings | a part |
.cap-player-sheet | a part |
.cap-player-speaker | a part |
.cap-player-spin | a part |
.cap-player-surface | a part |
.cap-player-surface-row | a part |
.cap-player-surface-settings | a part |
.cap-player-ticks | a part |
.cap-player-time | a part |
.cap-player-title | a part |
.cap-player-track | a part |
.cap-player-transcript | a part |
.cap-player-transcript-bar | a part |
.cap-player-transcript-box | a part |
.cap-player-transcript-link | a part |
.cap-player-transcript-raw | a part |
.cap-player-transport | a part |
.cap-player-volume | a part |
.cap-player-volume-row | a part |
.cap-player-wave | a part |
.cap-player-wave-bar | a part |
.cap-player-wave-bars | a part |
.cap-player-wave-box | a part |
.cap-player-wave-empty | a part |
.cap-player-wave-marker | a part |
.cap-player-wave-note | a part |
.cap-player-wave-preview | a part |
.cap-player-wave-region | a part |
.cap-player-wave-tip | a part |
| Attribute | Values |
|---|---|
data-active | present or absent |
data-hidden | present or absent |
data-kind | sound |
data-layout | grid |
data-part | close next play setting skip |
data-service | soundcloud spotify |
data-size | lg sm |
data-state | leading played playing region |
data-tone | crit |
data-wave | 2 |
| State | Read from |
|---|---|
:disabled | the platform |
:hover | the platform |
[aria-current="true"] | an attribute |
[aria-pressed="true"] | an attribute |
[hidden] | an attribute |
Accessibility
| Key | Does |
|---|---|
| Tab | Reaches the embed, the player's own controls and the transcript link |
| Enter on an embed | Puts the player in its place and moves focus into it |
| Key | Does |
|---|---|
| Tab | Reaches each control in order; the dock's controls are skipped while it is hidden |
| Enter or Space on a control | Plays or pauses, skips, opens a setting, presses a chapter, a key moment or a transcript line |
| Arrow keys on the scrubber | Back or forward 5 seconds; with Shift, 15 |
| Page Up, Page Down on the scrubber | Forward or back a minute |
| Home, End on the scrubber | To the start, to the end |
| Arrow keys in a setting | Choose the speed or the sleep timer (radios), move through a menu |
| Esc | Closes a popover, a menu or the sheet; focus returns to its button |
| Enter or Space on the inline audio button | Plays 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'sPlayTrackButtonnames the track and does carryaria-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 carriesaria-pressed.