useUserMedia

sensors

Installation

npx usehooks-cli@latest add use-user-media

Description

A React hook for accessing user media devices (camera and microphone) using the getUserMedia API. Provides comprehensive error handling and stream management.

Parameters

Name	Type	Default	Description
initialConstraints?	UseUserMediaConstraints	-	Initial media constraints for video and audio

Parameter Properties

initialConstraints properties:

Name	Type	Description
video?	boolean \| MediaTrackConstraints	Video constraints or boolean to enable/disable video
audio?	boolean \| MediaTrackConstraints	Audio constraints or boolean to enable/disable audio

Return Type

UseUserMediaReturn

Property	Type	Description
stream	MediaStream \| null	Current media stream from user devices
error	string \| null	Error message if media access failed
isLoading	boolean	Whether currently requesting media access
isSupported	boolean	Whether getUserMedia is supported in the browser
startCapture	(constraints?: UseUserMediaConstraints) => Promise<void>	Function to start media capture with optional constraints
stopCapture	() => void	Function to stop media capture and release devices

Examples

Video chat component

Basic video chat setup with camera and microphone

import { useUserMedia } from '@usehooks.io/use-user-media';
import { useRef, useEffect } from 'react';

function VideoChat() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const {
    stream,
    error,
    isLoading,
    isSupported,
    startCapture,
    stopCapture
  } = useUserMedia({ video: true, audio: true });

  useEffect(() => {
    if (videoRef.current && stream) {
      videoRef.current.srcObject = stream;
    }
  }, [stream]);

  if (!isSupported) {
    return <div>getUserMedia not supported</div>;
  }

  return (
    <div>
      <video ref={videoRef} autoPlay muted />
      
      {error && <p style={{ color: 'red' }}>Error: {error}</p>}
      
      <button onClick={() => startCapture()} disabled={isLoading}>
        {isLoading ? 'Starting...' : 'Start Camera'}
      </button>
      
      <button onClick={stopCapture}>
        Stop Camera
      </button>
    </div>
  );
}

Dependencies

react

Notes

•Automatically stops previous streams when starting new capture
•Provides detailed error messages for different failure scenarios
•Requires HTTPS in production for security reasons
•Automatically cleans up streams on component unmount
•Supports both boolean and detailed MediaTrackConstraints

Implementation

'use client';

import { useState, useCallback, useRef, useEffect } from "react";

interface UseUserMediaConstraints {
  video?: boolean | MediaTrackConstraints;
  audio?: boolean | MediaTrackConstraints;
}

interface UseUserMediaReturn {
  stream: MediaStream | null;
  error: string | null;
  isLoading: boolean;
  isSupported: boolean;
  startCapture: (constraints?: UseUserMediaConstraints) => Promise<void>;
  stopCapture: () => void;
}

const DEFAULT_CONSTRAINTS: UseUserMediaConstraints = {
  video: true,
  audio: true,
};

export const useUserMedia = (
  initialConstraints: UseUserMediaConstraints = DEFAULT_CONSTRAINTS
): UseUserMediaReturn => {
  const [stream, setStream] = useState<MediaStream | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(false);
  const streamRef = useRef<MediaStream | null>(null);

  const isSupported =
    typeof navigator !== "undefined" &&
    "mediaDevices" in navigator &&
    "getUserMedia" in navigator.mediaDevices;

  const stopCapture = useCallback(() => {
    if (streamRef.current) {
      streamRef.current.getTracks().forEach((track) => {
        track.stop();
      });
      streamRef.current = null;
      setStream(null);
    }
    setError(null);
  }, []);

  const startCapture = useCallback(
    async (constraints: UseUserMediaConstraints = initialConstraints) => {
      if (!isSupported) {
        setError("getUserMedia is not supported in this browser");
        return;
      }

      // Stop any existing stream
      stopCapture();

      setIsLoading(true);
      setError(null);

      try {
        const mediaStream =
          await navigator.mediaDevices.getUserMedia(constraints);
        streamRef.current = mediaStream;
        setStream(mediaStream);
      } catch (err) {
        let errorMessage = "Failed to access media devices";

        if (err instanceof Error) {
          switch (err.name) {
            case "NotAllowedError":
              errorMessage =
                "Permission denied. Please allow camera/microphone access.";
              break;
            case "NotFoundError":
              errorMessage = "No camera or microphone found.";
              break;
            case "NotReadableError":
              errorMessage = "Camera or microphone is already in use.";
              break;
            case "OverconstrainedError":
              errorMessage =
                "Camera or microphone constraints cannot be satisfied.";
              break;
            case "SecurityError":
              errorMessage = "Security error. Make sure you're using HTTPS.";
              break;
            case "AbortError":
              errorMessage = "Media access was aborted.";
              break;
            default:
              errorMessage = err.message || errorMessage;
          }
        }

        setError(errorMessage);
      } finally {
        setIsLoading(false);
      }
    },
    [isSupported, initialConstraints, stopCapture]
  );

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      stopCapture();
    };
  }, [stopCapture]);

  return {
    stream,
    error,
    isLoading,
    isSupported,
    startCapture,
    stopCapture,
  };
};

export default useUserMedia;

useNetworkInformation

CLI Docs All Hooks

useVibration