use-media-controls

Two-way reactive controls for a <video> or <audio> element.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useMediaControls } from "@vizejs/composable/use-media-controls";

Try it

Build custom audio controls

Drive a native audio or video element through refs for play state, time, volume and speed.

Open the interactive example

What to observe: Play starts the audio and the time advances; Jump to 0.5 s seeks; Speed toggles between 1× and 2×.

Every control is a writable ref bound to the element. src accepts a URL, a list of sources or a getter, as here with an object URL.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { ref } from "vue";
import { useMediaControls } from "@vizejs/composable/use-media-controls";
import { useMounted } from "@vizejs/composable/use-mounted";
import { useObjectUrl } from "@vizejs/composable/use-object-url";

// A one-second silent WAV generated in the browser stands in for your audio file.
function silentWav(seconds: number, rate = 8000): Blob {
  const samples = seconds * rate;
  const view = new DataView(new ArrayBuffer(44 + samples));
  const text = (offset: number, value: string) =>
    [...value].forEach((char, index) => view.setUint8(offset + index, char.charCodeAt(0)));
  text(0, "RIFF");
  view.setUint32(4, 36 + samples, true);
  text(8, "WAVEfmt ");
  view.setUint32(16, 16, true);
  view.setUint16(20, 1, true);
  view.setUint16(22, 1, true);
  view.setUint32(24, rate, true);
  view.setUint32(28, rate, true);
  view.setUint16(32, 1, true);
  view.setUint16(34, 8, true);
  text(36, "data");
  view.setUint32(40, samples, true);
  for (let index = 0; index < samples; index += 1) view.setUint8(44 + index, 128);
  return new Blob([view.buffer], { type: "audio/wav" });
}

const audio = ref<HTMLAudioElement | null>(null);
// The generated file only exists in the browser, so create the element after hydration.
const mounted = useMounted();
const captions = `data:text/vtt,${encodeURIComponent("WEBVTT\n\n00:00.000 --> 00:01.000\n(silence)\n")}`;
const source = useObjectUrl(silentWav(1));
const { playing, currentTime, duration, muted, rate } = useMediaControls(audio, {
  src: () => source.value ?? "",
});
</script>

<template>
  <div class="composable-example">
    <p>Build custom audio controls on top of a native media element.</p>
    <audio v-if="mounted" ref="audio" preload="metadata">
      <track kind="captions" srclang="en" label="English" :src="captions" />
    </audio>
    <div class="example-actions">
      <button type="button" @click="() => (playing = !playing)">
        {{ playing ? "Pause" : "Play" }}
      </button>
      <button type="button" @click="() => (muted = !muted)">{{ muted ? "Unmute" : "Mute" }}</button>
      <button type="button" @click="() => (rate = rate === 1 ? 2 : 1)">Speed {{ rate }}×</button>
      <button type="button" @click="() => (currentTime = 0.5)">Jump to 0.5 s</button>
    </div>
    <output aria-live="off">{{ currentTime.toFixed(1) }} / {{ duration.toFixed(1) }} s</output>
  </div>
</template>

Runtime contract

API

useMediaControls

Two-way reactive controls for a <video> or <audio> element. playing, currentTime, volume, muted, and rate mirror the element and are writable: assigning them drives the element, while element events update them without echoing the change back. The element is the source of truth whenever a new target attaches. Read-only state covers duration, buffering, seeking, waiting, stalls, text tracks, and picture-in-picture. A rejected play() (blocked autoplay) resets playing and is exposed through error. Listeners are removed when the target changes and when the owning reactive scope stops. Server rendering: the template ref is empty, so every value keeps its neutral default (paused, time 0, volume 1) and nothing is touched.

function useMediaControls( target: MaybeRefOrGetter<MediaElementLike | null | undefined>, options: UseMediaControlsOptions = {}, ): MediaControls

const video = useTemplateRef<HTMLVideoElement>("video");
const { playing, currentTime, duration } = useMediaControls(video, {
  src: [{ src: "/clip.webm", type: "video/webm" }, { src: "/clip.mp4", type: "video/mp4" }],
});

Types

TimeRangesLike

Minimal TimeRanges.

TextTrackLike

Minimal TextTrack.

TextTrackListLike

Minimal TextTrackList.

MediaElementLike

Minimal HTMLMediaElement (<video> or <audio>).

PictureInPictureDocumentLike

Document capabilities used for picture-in-picture.

MediaSourceCandidate

One candidate media source.

MediaTextTrack

Summary of one text track.

UseMediaControlsOptions

Options for useMediaControls.

MediaControls

Reactive state and actions returned by useMediaControls.