use-user-media

Manage the lifecycle of a media stream from any asynchronous source.

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 { useMediaStream, useUserMedia } from "@vizejs/composable/use-user-media";

Try it

Preview the camera

Start the camera on request and show its stream before a call.

Open the interactive example

What to observe: Turn on camera asks for permission and shows the preview; Turn off camera stops every track.

Pass constraints for resolution or devices; devices lists the available inputs. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

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 { computed, watchEffect, useTemplateRef } from "vue";
import { useMounted } from "@vizejs/composable/use-mounted";
import { useUserMedia } from "@vizejs/composable/use-user-media";

const mounted = useMounted();
const camera = useTemplateRef<HTMLVideoElement>("camera");
const { supported, stream, status, start, stop } = useUserMedia({ constraints: { video: true } });
const live = computed(() => stream.value !== undefined);
watchEffect(() => {
  if (camera.value) camera.value.srcObject = (stream.value as MediaStream | undefined) ?? null;
});
</script>

<template>
  <div class="composable-example">
    <p>Show a camera preview before a video call starts.</p>
    <div class="example-actions">
      <button type="button" :disabled="!mounted || !supported || live" @click="() => start()">
        Turn on camera
      </button>
      <button type="button" :disabled="!live" @click="() => stop()">Turn off camera</button>
    </div>
    <video ref="camera" autoplay muted playsinline aria-label="Camera preview"></video>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : supported
          ? `Camera: ${status}`
          : "Camera access is not available in this browser."
    }}</output>
  </div>
</template>

Runtime contract

API

useMediaStream

Manage the lifecycle of a media stream from any asynchronous source. This is the engine behind useUserMedia and useDisplayMedia, and can wrap any other stream producer (canvas capture, WebRTC). Acquisition failures are classified into MediaStreamErrorCodes; the stream returns to "idle" once all of its tracks ended (device unplugged, the user stopped screen sharing). Latest-wins: a stream that resolves after a newer request or a stop is stopped immediately. All tracks are stopped when the owning reactive scope stops. Server rendering: without a browser window a missing source keeps the status "idle" (no error), so server markup matches the first client render.

function useMediaStream<Constraints>( options: UseMediaStreamOptions<Constraints>, ): MediaStreamControls

const canvasStream = useMediaStream({
  source: { request: async (fps: number) => canvas.captureStream(fps) },
  constraints: 30,
});

useUserMedia

Access the camera and microphone with getUserMedia. Built on useMediaStream: reactive constraints (restarting an active stream when they change), enabled activation, classified failures such as "permission-denied", and latest-wins requests. With listDevices, devices follows devicechange. Tracks and listeners are released when the owning reactive scope stops. Server rendering: no device is touched; status is "idle", stream is undefined, and supported is false.

function useUserMedia(options: UseUserMediaOptions = {}): UserMediaControls

const camera = useUserMedia({ constraints: { video: true, audio: false } });
await camera.start();
video.srcObject = camera.stream.value;

Types

MediaStreamTrackLike

Minimal MediaStreamTrack.

MediaStreamLike

Minimal MediaStream.

MediaStreamSource

Anything that can asynchronously produce a media stream.

MediaStreamFailure

Stream acquisition failure.

UseMediaStreamOptions

Options for useMediaStream.

MediaStreamControls

Reactive state and actions of a managed media stream.

MediaDeviceInfoLike

Minimal MediaDeviceInfo.

UserMediaHost

Minimal MediaDevices consumed by useUserMedia.

UseUserMediaOptions

Options for useUserMedia.

UserMediaControls

Reactive state and actions returned by useUserMedia.