MediaPlayer

Plays a video or audio file with the HUD MediaControls instead of the browser's own controls. Through its ref, code (or a voice assistant) can play, pause, seek and change the volume.

import { MediaPlayer } from 'jarvis-react-ui';

Video

Pass the file as src. The video sits in a 16:9 frame as wide as its container, with a large play button until it starts. poster shows an image before playback, and captions adds a WebVTT captions track, which you should provide for spoken content.

import { MediaPlayer } from 'jarvis-react-ui';

export default function Video() {
    return (
        <MediaPlayer
            title="Flower · CC0"
            src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
        />
    );
}

Audio

kind="audio" renders a compact player: a WaveStrip that moves while playing, the title and the controls.

import { MediaPlayer } from 'jarvis-react-ui';

export default function Audio() {
    return (
        <MediaPlayer
            kind="audio"
            title="T-Rex roar · CC0"
            src="https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3"
            size="sm"
        />
    );
}

Control it from code

The ref is a MediaHandle with play(), pause(), seek(seconds), setVolume(0–1) and setMuted(boolean). YouTubePlayer has the same handle, so commands like "pause" or "skip 30 seconds" work the same for both.

import { useRef } from 'react';
import { Button, MediaPlayer } from 'jarvis-react-ui';
import type { MediaHandle } from 'jarvis-react-ui';

export default function Programmatic() {
    const player = useRef<MediaHandle>(null);

    return (
        <div className="flex flex-col gap-3">
            <div className="flex flex-wrap gap-2">
                <Button size="sm" onClick={() => void player.current?.play()}>
                    Play
                </Button>
                <Button size="sm" onClick={() => player.current?.pause()}>
                    Pause
                </Button>
                <Button size="sm" onClick={() => player.current?.seek(2)}>
                    Jump to 0:02
                </Button>
                <Button size="sm" onClick={() => player.current?.setVolume(0.2)}>
                    Volume 20 %
                </Button>
            </div>
            <MediaPlayer
                ref={player}
                src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
            />
        </div>
    );
}

Warning: Autoplay

Browsers only autoplay media without sound, or after the user interacted with the page. With autoPlay, also set defaultMuted if playback must start on its own.

Sound

The controls play hover_button, click, drag_start and drag_end through the nearest SfxProvider; the media itself plays through the normal browser audio. See Sound effects.

Accessibility

Uses the native <video> / <audio> element with a <track kind="captions"> for captions.
All controls are keyboard accessible, with the shortcuts of MediaControls (K, M, ←, →).
If the media fails to load, the controls are disabled and Media unavailable is shown.

API

Prop	Type	Default	Description
`src` (required)	`string`		URL of the video or audio file.
`autoPlay`	`boolean`	`false`	Starts playing on mount. Browsers allow it only muted or after a user gesture.
`captions`	`MediaCaptions`		Captions for a video; strongly recommended for spoken content.
`className`	`string`		Additional class names for the root element.
`defaultMuted`	`boolean`	`false`	Starts muted.
`defaultVolume`	`number`	`1`	Initial volume from 0 to 1.
`kind`	`'video' \| 'audio'`	`'video'`	`video` shows the picture in a 16:9 frame; `audio` shows a compact player.
`loop`	`boolean`	`false`	Starts again at the end.
`onEnded`	`(() => void)`		Called when playback reaches the end (not with `loop`).
`onError`	`(() => void)`		Called when the media cannot be loaded or played.
`poster`	`string`		Image shown before a video starts.
`size`	`'sm' \| 'md'`	`'md'`	Size of the controls.
`title`	`ReactNode`		Title shown in the player, e.g. the track or clip name.

Also accepts inherited props from RefAttributes (1), Attributes (1).

Type `MediaCaptions`

A captions track for a video, in WebVTT format.

Field	Type	Description
`label` (required)	`string`	Name shown in the browser's captions menu, e.g. `English`.
`src` (required)	`string`	URL of the `.vtt` file.
`srcLang` (required)	`string`	Language of the captions, e.g. `en`.