---
category: Browser
---

# useMediaControls

Reactive media controls for both `audio` and `video` elements

## 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

```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>;
```