Everything you need to ship a polished media player

Documentation that focuses on what the package actually does.

This package is more than a wrapper around a media element. It gives you playlist-aware video, preview clips, subtitle tracks, poster generation, waveform audio, downloads, shortcuts, and sensible loading behaviour.

Quick install

npm install react-video-audio-player

At a glance

The docs are centered around the behaviors that help the player stand out in real applications.

Video player

Multiple sources, playlist timelines, captions, previews, fullscreen, PiP, and custom control visibility.

Audio player

Waveform playback, peaks loading, keyboard shortcuts, volume, speed, and graceful fallback rendering.

Playlist support

Treat multiple clips like one continuous experience with total duration and seek mapping.

Preview mode

Expose clip-only or random previews for sampling, teasers, and gated playback flows.

Poster generation

Generate posters from any chosen timestamp to make embeds, demos, and listings feel finished.

Safer defaults

Lazy load when visible and cap autoplay for oversized media so behaviour stays predictable.

Video Player Props

Core configuration for video playback, source handling, and media-specific interactions.

1import { VideoPlayerProps, VideoPreviewOptions, PlaylistItem, PlaylistConfig, preload, VideoControlOptionsToRemove, VideoMimeType, sources } from "react-video-audio-player";

Video Player Properties
Prop	Type	Default	Description
`src`	`string`	`""`	The URL of the video to embed. This is optional; you may instead use the sources property to specify one or more source elements for the video.
`sources`	`Array<{ src: string; type: string }>`	`[]`	An array of objects containing the URL and type of the video to embed. This is optional; you may instead use the src property to specify the URL of the video.
`accentColor`	`string`	`"#60a5fa"`	The accent color to use for the player controls
`tracks`	`Array<{ src: string; kind: string; label: string; srclang: string; default?: boolean }>`	`[]`	An array of objects containing the URL, kind, label, and srclang of the tracks to embed.
`poster`	`string`	`""`	A URL for an image to be shown while the video is downloading. If this attribute isn't specified, nothing is displayed until the first frame is available, then the first frame is shown as the poster frame.
`generatePosterAt`	`number`	`undefined`	A number representing the time in seconds to generate a poster for the video. If not provided, a poster will be generated at half the video duration.
`preload`	`"auto" \| "metadata" \| "none" \| ""`	`"metadata"`	This enumerated attribute is intended to provide a hint to the video player about what the author thinks will lead to the best user experience regarding what content is loaded before the video is played. It may have one of the following values: - none: Indicates that the video should not be preloaded. - metadata: Indicates that only video metadata (e.g. length) is fetched. - auto: Indicates that the whole video file can be downloaded, even if the user is not expected to use it. - empty string: A synonym of the auto value. The spec advises it to be set to metadata but if the video is streamed, auto is a better choice.
`controls`	`boolean`	`true`	If this attribute is present, the video player will offer controls to allow the user to control video playback, including volume, duration, seeking, pause/resume playback, picture in picture (if supported), playback rate, skip forward, skip backward and fullscreen toggle.
`autoPlay`	`boolean`	`false`	A Boolean attribute; if specified, the video automatically begins to play back as soon as it can without stopping to finish loading the data.
`loop`	`boolean`	`false`	A Boolean attribute; if specified, the video player will automatically seek back to the start upon reaching the end of the video.
`maxAutoPlayDuration`	`number`	`undefined`	Optional guard in seconds. If set, autoplay is blocked for videos longer than this duration.
`muted`	`boolean`	`false`	A Boolean attribute that indicates the default audio mute setting contained in the video. If set, the audio will be initially silenced. Its default value is false, meaning the audio will be played when the video is played.
`playsInline`	`boolean`	`true`	A Boolean attribute indicating that the video is to be played "inline", that is, within the element's playback area. Note that the absence of this attribute does not imply that the video will always be played in fullscreen.
`defaultPlaybackRate`	`number`	`undefined`	A number indicating the default playback speed of the video when loaded. The default value is 1.0, which indicates normal speed. The value must be between 0.0625 and 16.0.
`defaultVolume`	`number`	`1`	A number indicating the default volume of the video when loaded. The default value is 1.0, which indicates normal volume. The value must be between 0 and 1.
`preview`	`{ mode?: 'clip' \| 'random'; duration?: number; start?: number; loop?: boolean }`	`undefined`	Configures clip or random preview playback. When enabled, the player can start at a chosen second or a random segment and stop after the configured duration. - mode: "clip" to preview a specific segment, or "random" to preview a random segment on each load. - duration: Duration of the preview in seconds. - start: Start time of the preview in seconds. Only used in "clip" mode. Ignored in "random" mode where the start time is randomized on each load. - loop: Whether to loop the preview.
`playlist`	`{ items: Array<{ src: string; duration: string; start?: number; end?: number }>; loop?: boolean }`	`undefined`	Configure a playlist to play multiple videos in sequence. - items: Array of video items with src URL, duration, and optional start time, and end time. - loop: Loop back to first item when reaching the end (default: false). Use start/end times for same-source clips to create gapless playback of segments from the same video file.
`seekTo`	`number`	`0`	A number representing the time in seconds to seek to in the video when it has loaded
`controlsToExclude`	`Array<typeof VideoControlOptionsToRemove>`	`[]`	An array of controls to remove from the video player. The following controls can be removed: - center-playPause-button: Center play/pause button - bottom-playPause-button: Bottom play/pause button - skip-forward-backward: Skip forward and backward buttons - progress: Progress bar - current-time: Current time display - duration: Duration display - volume: Volume control - mute: Mute button - fullscreen: Fullscreen button - playbackRate: Playback rate control - pip: Picture-in-picture button
`width`	`string \| number`	`"100%"`	A string or number representing the width of the video player.
`height`	`string \| number`	`"100%"`	A string or number representing the height of the video player. minHeight: 180px
`className`	`string`	`""`	Additional class names for the video player
`style`	`CSSProperties`	`{}`	Additional styles for the video player
`customErrorMessage`	`string`	`"An error occurred while trying to play the video."`	Custom error message to display when video fails to load
`disableDoubleClick`	`boolean`	`false`	If true, disables double-click functionality for play/pause or fullscreen.
`doubleClickToFullscreen`	`boolean`	`false`	If true, double-clicking the video toggles fullscreen mode.
`showDownloadButton`	`boolean`	`false`	If true, shows a download button for the video.
`disableShortcuts`	`boolean`	`false`	If true, disables keyboard shortcuts for video controls.
`onProgress`	`(currentTime: number, duration: number) => void`	`undefined`	Callback during video playback progress
`onSeeking`	`(time: number) => void`	`undefined`	Callback when the video when the user starts seeking
`onSeeked`	`(time: number) => void`	`undefined`	Callback when the video after the user finishes seeking
`onPlay`	`() => void`	`undefined`	Callback when the video starts playing
`onPause`	`() => void`	`undefined`	Callback when the video is paused
`onEnded`	`() => void`	`undefined`	Callback when the video ends
`onVolumeChange`	`(volume: number) => void`	`undefined`	Callback when the volume is changed
`onPlaybackRateChange`	`(rate: number) => void`	`undefined`	Callback when the playback rate is changed
`onMuteChange`	`(isMuted: boolean) => void`	`undefined`	Callback when the mute state is changed
`onFullscreenChange`	`(isFullscreen: boolean) => void`	`undefined`	Callback when the fullscreen state is changed
`onPictureInPictureChange`	`(isPictureInPicture: boolean) => void`	`undefined`	Callback when the picture-in-picture state is changed
`onDownloadStart`	`() => void`	`undefined`	Callback when video download starts
`onDownloadEnd`	`(success: boolean) => void`	`undefined`	Callback when video download ends, with success status
`onError`	`() => void`	`undefined`	Callback when there is an error
`onReady`	`() => void`	`undefined`	Callback when the video is ready
`onDuration`	`(duration: number) => void`	`undefined`	Callback with video duration
`getVideoRef`	`(ref: HTMLVideoElement \| null) => void`	`undefined`	Get video element reference to access video properties and methods. Learn more about the HTMLMediaElement interface.

Example Usage

1import { VideoPlayer } from 'react-video-audio-player';
2
3function App() {
4  return (
5    <VideoPlayer
6      src="video.mp4"
7      controls
8      autoPlay={false}
9      loop={false}
10      muted={false}
11      width="100%"
12      height="auto"
13      accentColor="#60a5fa"
14      maxAutoPlayDuration={60}
15      preview={{ mode: 'clip', start: 15, duration: 12, loop: false }}
16    />
17  );
18}

Multiple Videos Playlist

1import { VideoPlayer } from 'react-video-audio-player';
2
3function App() {
4  const playlist = {
5    items: [
6      { src: 'video1.mp4', duration: 45},
7      { src: 'video2.mp4', duration: 120 },
8      { src: 'video3.mp4', duration: 90 },
9    ],
10    loop: false,
11  };
12
13  return <VideoPlayer playlist={playlist} controls />;
14}

Keyboard Shortcuts

Space - Play/Pause
M - Mute/Unmute
F - Toggle Fullscreen
P - Picture-in-Picture
← - Seek -10s
→ - Seek +10s
↑ - Volume Up
↓ - Volume Down
S - Change Speed