useMediaControls

v0.0.14testeddemo

Reactive controls and state for an <audio>/<video> element: play/pause, seeking, duration, buffered ranges, volume, mute, rate, text tracks, and Picture-in-Picture. Source and track injection are handled for you, and all DOM listeners attach passively with automatic cleanup. SSR-safe.

Source Tests

Examples

const video = useTemplateRef<HTMLVideoElement>('video');
const { playing, currentTime, duration, volume } = useMediaControls(video, {
  src: 'https://example.com/clip.mp4',
});
playing.value = true; // start playback

const { tracks, enableTrack, togglePictureInPicture } = useMediaControls(video, {
  src: 'video.mp4',
  tracks: [{ default: true, src: 'en.vtt', srcLang: 'en', label: 'English', kind: 'subtitles' }],
});

Demo

Loading demo…

Signature

export function useMediaControls(
  target: MaybeComputedElementRef<HTMLMediaElement | null | undefined>,
  options: UseMediaControlsOptions ={ ... }

Parameters

Parameter	Type	Default	Description
`target`	`MaybeComputedElementRef<HTMLMediaElement \| null \| undefined>`	—	The media element (reactive ref, getter, or component instance)
`options`?	`UseMediaControlsOptions`	`{}`	Source/track configuration and a custom `document`

Returns

UseMediaControlsReturnReactive media state plus track and Picture-in-Picture controls

Property	Type	Default	Description
`currentTime`	`ShallowRef<number>`	—	Current playback position in seconds. Writing seeks the media.
`duration`	`ShallowRef<number>`	—	Total media duration in seconds (read-only mirror)
`waiting`	`ShallowRef<boolean>`	—	Whether the media is buffering and waiting for more data
`seeking`	`ShallowRef<boolean>`	—	Whether a seek operation is in progress
`ended`	`ShallowRef<boolean>`	—	Whether playback has reached the end of the media
`stalled`	`ShallowRef<boolean>`	—	Whether the browser is trying to fetch data but it is not forthcoming
`buffered`	`ShallowRef<Array<[number, number]>>`	—	Buffered time ranges as `[start, end]` second pairs
`playing`	`ShallowRef<boolean>`	—	Whether the media is currently playing. Writing toggles play/pause.
`rate`	`ShallowRef<number>`	—	Playback rate (`1` is normal speed). Writing sets `playbackRate`.
`playbackRate`	`ShallowRef<number>`	—	Alias of `rate` for API parity. Writing sets `playbackRate`.
`volume`	`ShallowRef<number>`	—	Audio volume in the range `[0, 1]`. Writing sets the element volume.
`muted`	`ShallowRef<boolean>`	—	Whether the media is muted. Writing mutes/unmutes the element.
`tracks`	`ShallowRef<UseMediaTextTrack[]>`	—	Reactive snapshot of the element's text tracks
`selectedTrack`	`ShallowRef<number>`	—	The id of the currently selected (`showing`) track, or `-1` when none
`enableTrack`	`(track: number \| UseMediaTextTrack, disableTracks?: boolean) => void`	—	Enable a track (set to `showing`), optionally disabling all others first.
`disableTrack`	`(track?: number \| UseMediaTextTrack) => void`	—	Disable a track. With no argument, disables every track.
`supportsPictureInPicture`	`boolean`	—	Whether the Picture-in-Picture API is available
`togglePictureInPicture`	`() => Promise<PictureInPictureWindow \| void>`	—	Toggle Picture-in-Picture for a `<video>` element
`isPictureInPicture`	`ShallowRef<boolean>`	—	Whether the element is currently in Picture-in-Picture mode
`onSourceError`	`MediaEventHookOn<Event>`	—	Register a callback fired when a `<source>` element errors
`onPlaybackError`	`MediaEventHookOn<unknown>`	—	Register a callback fired when playback errors (e.g. `play()` rejects)

Related Types

UseMediaSource

A media <source> descriptor injected as a child <source> element. Many of these definitions mirror MDN's HTMLMediaElement documentation.

interface UseMediaSource

Property	Type	Default	Description
`src`	`string`	—	The source url for the media
`type`?	`string`	—	The media codec type
`media`?	`string`	—	Media query for the resource's intended media

UseMediaTextTrackSource

A text track <track> descriptor injected as a child <track> element.

interface UseMediaTextTrackSource

Property	Type	Default	Description
`default`?	`boolean`	—	Mark the track as enabled unless the user's preferences indicate another is preferred
`kind`	`TextTrackKind`	—	How the text track is meant to be used. Defaults to `subtitles` when omitted.
`label`	`string`	—	A user-readable title used by the browser when listing tracks
`src`	`string`	—	Address of the track (`.vtt` file). Must be same-origin as the document.
`srcLang`	`string`	—	Language of the track text data. A valid BCP 47 language tag.

UseMediaTextTrack

A reactive snapshot of a single TextTrack.

interface UseMediaTextTrack

Property	Type	Default	Description
`id`	`number`	—	The index of the text track within the element's `textTracks`
`label`	`string`	—	The text track label
`language`	`string`	—	Language of the track text data (BCP 47)
`mode`	`TextTrackMode`	—	The display mode of the text track: `disabled`, `hidden`, or `showing`
`kind`	`TextTrackKind`	—	How the text track is meant to be used
`inBandMetadataTrackDispatchType`	`string`	—	The track's in-band metadata track dispatch type
`cues`	`TextTrackCueList \| null`	—	A list of text track cues
`activeCues`	`TextTrackCueList \| null`	—	A list of active text track cues

MediaEventHookOn

Subscribe to a media event hook; returns an unsubscribe handle. Backed by the shared createEventHook, so the off handle is callable (and exposes an .off method) and listeners are auto-removed on scope dispose.

export type MediaEventHookOn<T = void> = EventHookOn<T>;