1---
2category: Browser
3---
4 
5# useMediaControls
6 
7Reactive media controls for both `audio` and `video` elements
8 
9## Usage
10 
11### Basic Usage
12 
13```vue
14<script setup lang="ts">
15import { useMediaControls } from '@vueuse/core'
16import { onMounted, useTemplateRef } from 'vue'
17 
18const video = useTemplateRef('video')
19const { playing, currentTime, duration, volume } = useMediaControls(video, {
20  src: 'video.mp4',
21})
22 
23// Change initial media properties
24onMounted(() => {
25  volume.value = 0.5
26  currentTime.value = 60
27})
28</script>
29 
30<template>
31  <video ref="video" />
32  <button @click="playing = !playing">
33    Play / Pause
34  </button>
35  <span>{{ currentTime }} / {{ duration }}</span>
36</template>
37```
38 
39### Providing Captions, Subtitles, etc...
40 
41You can provide captions, subtitles, etc in the `tracks` options of the
42`useMediaControls` function. The function will return an array of tracks
43along with two functions for controlling them, `enableTrack`, `disableTrack`, and `selectedTrack`.
44Using these you can manage the currently selected track. `selectedTrack` will
45be `-1` if there is no selected track.
46 
47```vue
48<script setup lang="ts">
49import { useMediaControls } from '@vueuse/core'
50import { useTemplateRef } from 'vue'
51 
52const video = useTemplateRef('video')
53const {
54  tracks,
55  enableTrack
56} = useMediaControls(video, {
57  src: 'video.mp4',
58  tracks: [
59    {
60      default: true,
61      src: './subtitles.vtt',
62      kind: 'subtitles',
63      label: 'English',
64      srcLang: 'en',
65    },
66  ]
67})
68</script>
69 
70<template>
71  <video ref="video" />
72  <button v-for="track in tracks" :key="track.id" @click="enableTrack(track)">
73    {{ track.label }}
74  </button>
75</template>
76```
77 
78## Type Declarations
79 
80```ts
81/**
82 * Many of the jsdoc definitions here are modified version of the
83 * documentation from MDN(https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement)
84 */
85export interface UseMediaSource {
86  /**
87   * The source url for the media
88   */
89  src: string
90  /**
91   * The media codec type
92   */
93  type?: string
94  /**
95   * Specifies the media query for the resource's intended media.
96   */
97  media?: string
98}
99export interface UseMediaTextTrackSource {
100  /**
101   * Indicates that the track should be enabled unless the user's preferences indicate
102   * that another track is more appropriate
103   */
104  default?: boolean
105  /**
106   * How the text track is meant to be used. If omitted the default kind is subtitles.
107   */
108  kind: TextTrackKind
109  /**
110   * A user-readable title of the text track which is used by the browser
111   * when listing available text tracks.
112   */
113  label: string
114  /**
115   * Address of the track (.vtt file). Must be a valid URL. This attribute
116   * must be specified and its URL value must have the same origin as the document
117   */
118  src: string
119  /**
120   * Language of the track text data. It must be a valid BCP 47 language tag.
121   * If the kind attribute is set to subtitles, then srclang must be defined.
122   */
123  srcLang: string
124}
125interface UseMediaControlsOptions extends ConfigurableDocument {
126  /**
127   * The source for the media, may either be a string, a `UseMediaSource` object, or a list
128   * of `UseMediaSource` objects.
129   */
130  src?: MaybeRefOrGetter<string | UseMediaSource | UseMediaSource[]>
131  /**
132   * A list of text tracks for the media
133   */
134  tracks?: MaybeRefOrGetter<UseMediaTextTrackSource[]>
135}
136export interface UseMediaTextTrack {
137  /**
138   * The index of the text track
139   */
140  id: number
141  /**
142   * The text track label
143   */
144  label: string
145  /**
146   * Language of the track text data. It must be a valid BCP 47 language tag.
147   * If the kind attribute is set to subtitles, then srclang must be defined.
148   */
149  language: string
150  /**
151   * Specifies the display mode of the text track, either `disabled`,
152   * `hidden`, or `showing`
153   */
154  mode: TextTrackMode
155  /**
156   * How the text track is meant to be used. If omitted the default kind is subtitles.
157   */
158  kind: TextTrackKind
159  /**
160   * Indicates the track's in-band metadata track dispatch type.
161   */
162  inBandMetadataTrackDispatchType: string
163  /**
164   * A list of text track cues
165   */
166  cues: TextTrackCueList | null
167  /**
168   * A list of active text track cues
169   */
170  activeCues: TextTrackCueList | null
171}
172export interface UseMediaControlsReturn {
173  currentTime: ShallowRef<number>
174  duration: ShallowRef<number>
175  waiting: ShallowRef<boolean>
176  seeking: ShallowRef<boolean>
177  ended: ShallowRef<boolean>
178  stalled: ShallowRef<boolean>
179  buffered: Ref<[number, number][]>
180  playing: ShallowRef<boolean>
181  rate: ShallowRef<number>
182  volume: ShallowRef<number>
183  muted: ShallowRef<boolean>
184  tracks: Ref<UseMediaTextTrack[]>
185  selectedTrack: ShallowRef<number>
186  enableTrack: (
187    track: number | UseMediaTextTrack,
188    disableTracks?: boolean,
189  ) => void
190  disableTrack: (track?: number | UseMediaTextTrack) => void
191  supportsPictureInPicture: boolean
192  togglePictureInPicture: () => Promise<PictureInPictureWindow | void>
193  isPictureInPicture: ShallowRef<boolean>
194  onSourceError: EventHookOn<Event>
195  onPlaybackError: EventHookOn<Event>
196}
197export declare function useMediaControls(
198  target: MaybeRef<HTMLMediaElement | null | undefined>,
199  options?: UseMediaControlsOptions,
200): UseMediaControlsReturn
201```
202