Video Player

Install

pnpm exec vegastack-design verify video-player

pnpm dlx shadcn@4.21.0 add @vegastack/video-player

Usage

import { VideoPlayer } from "@/components/ui/video-player";

<VideoPlayer
  src="/media/demo.mp4"
  poster="/media/demo-poster.webp"
  label="Product demo video"
/>;

Examples

Basic

The video surface owns a hover-revealed overlay transport: a thin media progress rail that expands smoothly on hover or focus, then play/pause, time, volume, settings, and fullscreen in the lower row. poster shows in the frame until playback starts — store one at upload with probeVideo from the media-probe lib — and the player never autoplays. Settings holds playback speed; a Quality entry appears only when you pass qualityOptions (and switch renditions in onQualityChange), since a single stored file has one. The docs preview uses a 90-second local MP4 fixture, so it can play without network access.

With copy

Use title and description when a video needs a visible name or supporting context.

One at a time

Starting the video pauses any other DS player that is playing — an AudioPlayer, the global player, the FileViewer stage — and starting one of them pauses the video. Nothing resumes by itself. exclusive={false} opts it out both ways.

Aspect ratio

aspectRatio="video" reserves a 16:9 frame. Use square for square media or auto when the video element should keep its intrinsic height.

Can't play

A browser cannot play every video: an HEVC .mov in Chrome or Firefox, an .mkv, an .avi. On a media error the frame shows "Can’t play this video here" (loadErrorLabel) with a Download button to downloadHref, and the transport — which would do nothing — goes away. Without downloadHref the message shows alone.

Expired URLs

A signed URL expires; a video paused past its lifetime fails on the next seek. Pass onSourceExpired and, on the first media error, the player calls it once, loads the URL it resolves and resumes at the same position — playing, if it was. Returning the same URL (a route that re-signs on every request) reloads it. A second failure shows the "can't play" card. This is the same contract as AudioPlayer's onSourceExpired.

<VideoPlayer
  src={`/api/files/${file.id}`}
  poster={file.posterUrl}
  label={file.name}
  downloadHref={`/api/files/${file.id}?download`}
  onSourceExpired={async () => `/api/files/${file.id}`}
/>

Controls always visible

The overlay reveals on pointer or focus and fades a second after the pointer leaves. controlsVisible takes that out of the loop — true pins the chrome open, false keeps it closed. Use it for a kiosk or always-on player, and for a static fixture: the auto-reveal never fires without a pointer, so a screenshot or a contract check would otherwise capture a frame with no controls in it.

Playground

Every VideoPlayer prop, auto-generated from its TypeScript types.

API Reference

Accessibility

• Pass a descriptive label; it names the video element and prefixes every custom control.
• The named media progress rail composes Slider, so keyboard and screen-reader slider semantics stay intact while its video-specific hover treatment remains separate from the generic component.
• Icon-only transport buttons are Button size="icon", each carrying its own aria-label.
• Tooltips expose the primary keyboard shortcuts for pointer and keyboard users.
• The volume slider is exposed from the mute control and keeps slider keyboard semantics.
• Playback speed (and quality, when qualityOptions are passed) live in settings submenus with radio selection.
• A video that cannot play announces "Can’t play this video here" as an alert, and its Download button is a real link with the download attribute.
• Rewind and forward are keyboard shortcuts rather than visible buttons.
• The overlay controls appear on hover or focus and fade out after the pointer leaves the frame.
• The fullscreen action changes to an exit-fullscreen icon and accessible name while the frame owns document fullscreen. The transport's tooltips and its settings menu stay visible there: they portal into the fullscreen element rather than to <body>, which is decision OVL-14. See MediaPlayerControls § Accessibility.
• The native <video> element is the media engine and visual frame; browser-native controls are omitted so audio and video players share the same VegaStack transport.

Do / Don't