Media Player Controls

InstallCopy Anchor Link

pnpm exec vegastack-design verify media-player-controls

pnpm dlx shadcn@4.21.0 add @vegastack/media-player-controls

UsageCopy Anchor Link

MediaPlayerControls is the transport that AudioPlayer and VideoPlayer both compose. Install it directly only when the player around it is yours — otherwise reach for one of those two.

import { useRef } from "react";
import { MediaPlayerControls } from "@/components/ui/media-player-controls";

const mediaRef = useRef<HTMLMediaElement>(null);

<audio ref={mediaRef} src="/media/demo.mp3" aria-label="Demo audio" />
<MediaPlayerControls mediaRef={mediaRef} label="Demo audio" />;

Two visual treatments. variant="default" is the bordered audio card. variant="overlay" is chrome drawn over video: it paints on the theme-invariant --media-scrim / --media-scrim-strong / --media-foreground tokens, so the controls read dark-scrim + light-ink in both themes rather than inverting in dark.

ExamplesCopy Anchor Link

DefaultCopy Anchor Link

Wide players lay the transport out on a single line: play/pause, rewind and forward, the elapsed·duration readout, the seek rail, mute + volume, and the tappable speed pill.

NarrowCopy Anchor Link

Below the @sm container width the transport reflows to two lines — seek and timers on top, a centred transport below with the transcript and volume controls on the leading edge. It is a container query, so a narrow sidebar gets the mobile layout on a wide viewport.

API ReferenceCopy Anchor Link

useMediaShortcutsCopy Anchor Link

The single keyboard map, exported so a custom media surface binds the same keys the controls do. runShortcut(key, scope) returns whether a shortcut ran, so the caller decides whether to preventDefault().

Scope is what keeps a shortcut from stealing a key from the control the user is on. surface — the player frame, or the document while the frame owns keyboard attention — claims the whole map. controls — inside the transport, where a focused button already owns Space and a focused seek rail already owns the arrows — claims only the letter shortcuts.

AccessibilityCopy Anchor Link

* The volume rail is a native range in writing-mode: vertical-lr, so which arrow walks which way is the platform's call rather than this component's; the suite drives it through the native setter for that reason.

• The group is labelled from label and is not itself a tab stop — every control inside it is focusable, so a stop on the wrapper only added an empty one.
• Focus is the centralized 2px :focus-visible outline. Over video it is pulled inside (-outline-offset-2) because the frame clips it; the width, colour and token are unchanged.
• Icon-only controls are Button size="icon", and every one of them names itself with an explicit aria-label — icon-button's compile-time guarantee went with it in Batch 7a, so the names are asserted in media-player-controls.test.tsx instead.
• The seek thumb is hidden at rest only where a pointer can hover. On a touch device it stays visible, because there is no hover to reveal it with.
• qualityOptions / defaultQuality / onQualityChange reach the settings menu, which only the overlay variant renders; in the default variant they are accepted and unused.
• Tooltips name the keyboard shortcut alongside the action, and they appear in fullscreen. The browser paints only the subtree passed to requestFullscreen(), so a portal to <body> would be invisible there; decision OVL-14 gives TooltipContent and DropdownMenuContent a container pass-through, and the transport hands them document.fullscreenElement for exactly as long as it contains them. There is no prop to wire: a page that fullscreens something else is untouched, and outside fullscreen both popups keep upstream's <body> default. The volume panel is inline and never depended on it.

Do / Don'tCopy Anchor Link