useMediaControls
Reactive media controls for both audio and video elements
Demo
00:00
00:00 / 14:48
Off
English
French
Enter Picture in Picture
Loop
2x
1x
currentTime: 0
duration: 888.035
waiting: false
seeking: false
ended: false
stalled: false
buffered: []
playing: false
rate: 1
volume: 1
muted: false
tracks:
- id: 0
label: English
kind: subtitles
language: en
mode: showing
activeCues: []
cues: []
- id: 1
label: French
kind: subtitles
language: fr
mode: disabled
activeCues: null
cues: null
selectedTrack: 0
supportsPictureInPicture: true
isPictureInPicture: false
Usage
Basic Usage
vue
<script setup lang="ts">
import { useMediaControls } from '@vueuse/core'
import { onMounted, useTemplateRef } from 'vue'
const video = useTemplateRef('video')
const { playing, currentTime, duration, volume } = useMediaControls(video, {
src: 'video.mp4',
})
// Change initial media properties
onMounted(() => {
volume.value = 0.5
currentTime.value = 60
})
</script>
<template>
<video ref="video" />
<button @click="playing = !playing">
Play / Pause
</button>
<span>{{ currentTime }} / {{ duration }}</span>
</template>Providing Captions, Subtitles, etc...
You can provide captions, subtitles, etc in the tracks options of the useMediaControls function. The function will return an array of tracks along with two functions for controlling them, enableTrack, disableTrack, and selectedTrack. Using these you can manage the currently selected track. selectedTrack will be -1 if there is no selected track.
vue
<script setup lang="ts">
import { useMediaControls } from '@vueuse/core'
import { useTemplateRef } from 'vue'
const video = useTemplateRef('video')
const {
tracks,
enableTrack
} = useMediaControls(video, {
src: 'video.mp4',
tracks: [
{
default: true,
src: './subtitles.vtt',
kind: 'subtitles',
label: 'English',
srcLang: 'en',
},
]
})
</script>
<template>
<video ref="video" />
<button v-for="track in tracks" :key="track.id" @click="enableTrack(track)">
{{ track.label }}
</button>
</template>Type Declarations
Show Type Declarations
ts
/**
* Many of the jsdoc definitions here are modified version of the
* documentation from MDN(https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement)
*/
export interface UseMediaSource {
/**
* The source url for the media
*/
src: string
/**
* The media codec type
*/
type?: string
/**
* Specifies the media query for the resource's intended media.
*/
media?: string
}
export interface UseMediaTextTrackSource {
/**
* Indicates that the track should be enabled unless the user's preferences indicate
* that another track is more appropriate
*/
default?: boolean
/**
* How the text track is meant to be used. If omitted the default kind is subtitles.
*/
kind: TextTrackKind
/**
* A user-readable title of the text track which is used by the browser
* when listing available text tracks.
*/
label: string
/**
* Address of the track (.vtt file). Must be a valid URL. This attribute
* must be specified and its URL value must have the same origin as the document
*/
src: string
/**
* Language of the track text data. It must be a valid BCP 47 language tag.
* If the kind attribute is set to subtitles, then srclang must be defined.
*/
srcLang: string
}
interface UseMediaControlsOptions extends ConfigurableDocument {
/**
* The source for the media, may either be a string, a `UseMediaSource` object, or a list
* of `UseMediaSource` objects.
*/
src?: MaybeRefOrGetter<string | UseMediaSource | UseMediaSource[]>
/**
* A list of text tracks for the media
*/
tracks?: MaybeRefOrGetter<UseMediaTextTrackSource[]>
}
export interface UseMediaTextTrack {
/**
* The index of the text track
*/
id: number
/**
* The text track label
*/
label: string
/**
* Language of the track text data. It must be a valid BCP 47 language tag.
* If the kind attribute is set to subtitles, then srclang must be defined.
*/
language: string
/**
* Specifies the display mode of the text track, either `disabled`,
* `hidden`, or `showing`
*/
mode: TextTrackMode
/**
* How the text track is meant to be used. If omitted the default kind is subtitles.
*/
kind: TextTrackKind
/**
* Indicates the track's in-band metadata track dispatch type.
*/
inBandMetadataTrackDispatchType: string
/**
* A list of text track cues
*/
cues: TextTrackCueList | null
/**
* A list of active text track cues
*/
activeCues: TextTrackCueList | null
}
export declare function useMediaControls(
target: MaybeRef<HTMLMediaElement | null | undefined>,
options?: UseMediaControlsOptions,
): {
currentTime: ShallowRef<number, number>
duration: ShallowRef<number, number>
waiting: ShallowRef<boolean, boolean>
seeking: ShallowRef<boolean, boolean>
ended: ShallowRef<boolean, boolean>
stalled: ShallowRef<boolean, boolean>
buffered: Ref<[number, number][], [number, number][]>
playing: ShallowRef<boolean, boolean>
rate: ShallowRef<number, number>
volume: ShallowRef<number, number>
muted: ShallowRef<boolean, boolean>
tracks: Ref<
{
id: number
label: string
language: string
mode: TextTrackMode
kind: TextTrackKind
inBandMetadataTrackDispatchType: string
cues: {
[x: number]: {
endTime: number
id: string
onenter: ((this: TextTrackCue, ev: Event) => any) | null
onexit: ((this: TextTrackCue, ev: Event) => any) | null
pauseOnExit: boolean
startTime: number
readonly track: {
readonly activeCues: /*elided*/ any | null
readonly cues: /*elided*/ any | null
readonly id: string
readonly inBandMetadataTrackDispatchType: string
readonly kind: TextTrackKind
readonly label: string
readonly language: string
mode: TextTrackMode
oncuechange: ((this: TextTrack, ev: Event) => any) | null
addCue: (cue: TextTrackCue) => void
removeCue: (cue: TextTrackCue) => void
addEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
} | null
addEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
}
readonly length: number
getCueById: (id: string) => TextTrackCue | null
[Symbol.iterator]: () => ArrayIterator<TextTrackCue>
} | null
activeCues: {
[x: number]: {
endTime: number
id: string
onenter: ((this: TextTrackCue, ev: Event) => any) | null
onexit: ((this: TextTrackCue, ev: Event) => any) | null
pauseOnExit: boolean
startTime: number
readonly track: {
readonly activeCues: /*elided*/ any | null
readonly cues: /*elided*/ any | null
readonly id: string
readonly inBandMetadataTrackDispatchType: string
readonly kind: TextTrackKind
readonly label: string
readonly language: string
mode: TextTrackMode
oncuechange: ((this: TextTrack, ev: Event) => any) | null
addCue: (cue: TextTrackCue) => void
removeCue: (cue: TextTrackCue) => void
addEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
} | null
addEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
}
readonly length: number
getCueById: (id: string) => TextTrackCue | null
[Symbol.iterator]: () => ArrayIterator<TextTrackCue>
} | null
}[],
| UseMediaTextTrack[]
| {
id: number
label: string
language: string
mode: TextTrackMode
kind: TextTrackKind
inBandMetadataTrackDispatchType: string
cues: {
[x: number]: {
endTime: number
id: string
onenter: ((this: TextTrackCue, ev: Event) => any) | null
onexit: ((this: TextTrackCue, ev: Event) => any) | null
pauseOnExit: boolean
startTime: number
readonly track: {
readonly activeCues: /*elided*/ any | null
readonly cues: /*elided*/ any | null
readonly id: string
readonly inBandMetadataTrackDispatchType: string
readonly kind: TextTrackKind
readonly label: string
readonly language: string
mode: TextTrackMode
oncuechange: ((this: TextTrack, ev: Event) => any) | null
addCue: (cue: TextTrackCue) => void
removeCue: (cue: TextTrackCue) => void
addEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
} | null
addEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
}
readonly length: number
getCueById: (id: string) => TextTrackCue | null
[Symbol.iterator]: () => ArrayIterator<TextTrackCue>
} | null
activeCues: {
[x: number]: {
endTime: number
id: string
onenter: ((this: TextTrackCue, ev: Event) => any) | null
onexit: ((this: TextTrackCue, ev: Event) => any) | null
pauseOnExit: boolean
startTime: number
readonly track: {
readonly activeCues: /*elided*/ any | null
readonly cues: /*elided*/ any | null
readonly id: string
readonly inBandMetadataTrackDispatchType: string
readonly kind: TextTrackKind
readonly label: string
readonly language: string
mode: TextTrackMode
oncuechange: ((this: TextTrack, ev: Event) => any) | null
addCue: (cue: TextTrackCue) => void
removeCue: (cue: TextTrackCue) => void
addEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
} | null
addEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
}
readonly length: number
getCueById: (id: string) => TextTrackCue | null
[Symbol.iterator]: () => ArrayIterator<TextTrackCue>
} | null
}[]
>
selectedTrack: ShallowRef<number, number>
enableTrack: (
track: number | UseMediaTextTrack,
disableTracks?: boolean,
) => void
disableTrack: (track?: number | UseMediaTextTrack) => void
supportsPictureInPicture: boolean | undefined
togglePictureInPicture: () => Promise<unknown>
isPictureInPicture: ShallowRef<boolean, boolean>
onSourceError: EventHookOn<Event>
onPlaybackError: EventHookOn<Event>
}
export type UseMediaControlsReturn = ReturnType<typeof useMediaControls>Source
Contributors
Anthony Fu
Alex Kozack
Anthony Fu
Fernando Fernández
wheat
IlyaL
Justin Halsall
webfansplz
IlyaL
Robin
Andrew
aaron lejeune
Darren
huiliangShen
丶远方
Bryce
CommanderRoot
jelf
rimday
ShinigamiChangelog
v12.8.0 on v12.5.0 on v12.4.0 on v12.3.0 on 59f75 - feat(toValue): deprecate toValue from @vueuse/shared in favor of Vue's nativev12.1.0 on v11.2.0 on v10.10.0 on v10.2.0 on v10.1.0 on cb644 - refactor!: remove isFunction and isString utils4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter0a72b - feat(toValue): rename resolveUnref to toValue