Media players

Updated: August 31, 2026

Media decides what to render by looking at the file extension, and hands video off to a player. MediaVideoPlayer and MediaAudioPlayer are those players, and you can reach for either directly. You need them directly in two situations: when the source has no usable extension — a blob: URL from MediaRecorder, a signed URL with the type in a query string — so Media cannot sniff it; and when the media is the component, as in an audio player that has no visual counterpart at all.

Importing

Both live on the ./components/* subpath rather than the root barrel, so they are not pulled into every bundle that imports something from Once UI.

Import

import { MediaAudioPlayer } from "@once-ui-system/core/components/MediaAudioPlayer";
import { MediaVideoPlayer } from "@once-ui-system/core/components/MediaVideoPlayer";

MediaVideoPlayer

A video surface with play/pause, a scrubbable progress bar and elapsed time. It is the right component for an extension-less source:

Recorder output

const [url, setUrl] = useState<string>();

// MediaRecorder output has no extension, so Media cannot sniff it.
recorder.ondataavailable = (event) => {
setUrl(URL.createObjectURL(event.data));
};

{url && <MediaVideoPlayer src={url} objectFit="contain" />}

MediaVideoPlayer	Type	Default
src Video source. Required.	string	—
autoplay Start playing as soon as the video can play.	boolean	false
loop Restart when playback reaches the end.	boolean	false
muted Start muted. Autoplay is blocked with sound in most browsers.	boolean	true
objectFit How the frame fits its box.	CSSProperties["objectFit"]	"cover"
className	string	—

MediaAudioPlayer

Play/pause, a scrubbable progress bar and elapsed/total time, laid out as a row rather than a surface. It takes every Column prop, so it sits in a layout like any other block.

Audio player

<MediaAudioPlayer
src="/audio/chapter-one.mp3"
label="Chapter one"
border="neutral-alpha-weak"
radius="m"
padding="12"
/>

Synchronising with playback

onTimeUpdate fires on every timeupdate with the position in seconds. The player owns playback; the caller owns what that position means — highlighting the paragraph being narrated, advancing a transcript, moving a chapter marker.

Narration sync

const [time, setTime] = useState(0);
const current = chapters.findLast((chapter) => chapter.start <= time);

<MediaAudioPlayer src={audio} onTimeUpdate={setTime} />
<Text onBackground={current ? "neutral-strong" : "neutral-weak"}>
{current?.title ?? "Not started"}
</Text>

MediaAudioPlayer	Type	Default
src Audio source. Required.	string	—
autoplay Start playing as soon as the audio can play.	boolean	false
loop Restart when playback reaches the end.	boolean	false
label Accessible name for the player group.	string	"Audio player"
onTimeUpdate Fires on every timeupdate with the position in seconds.	(currentTime: number) => void	—
onPlayingChange Fires when playback starts or stops.	(playing: boolean) => void	—
…and every FlexProps prop	inherited	—

ComponentsMasonryGrid

ComponentsModal

Edit this page on GitHub

Built with curiosity by Lorant One and the Design Engineers Club