useMediaDevices

Overview

The useMediaDevices hook simplifies access to media input devices like microphones and cameras, managing permissions and providing a way to retrieve available devices based on the specified types.

Importing

To use the useMediaDevices hook, import it:

import { useMediaDevices } from './path/to/useMediaDevices'

Hook Signature

useMediaDevices(
  ...xs: MediaDeviceKind[]
): [() => Promise<DeviceOptions | undefined>]

Parameters

• ...xs: A list of media device kinds to check for. Valid values:
  • 'microphone': To check for audio input devices.
  • 'camera': To check for video input devices.

Returns

An array with a single function:

1. A callback function that, when called, checks permissions and retrieves available devices for the specified media kinds.

---

Supporting Types

MediaDeviceKind

type MediaDeviceKind = 'microphone' | 'camera';

Represents the types of media devices that can be checked.

MediaDeviceInfoMediaDeviceSelection

type MediaDeviceInfoMediaDeviceSelection = {
  deviceId: string;
  label: string;
  device: MediaDeviceInfo;
};

Describes a media device, including its deviceId, label, and raw MediaDeviceInfo object.

DeviceOptions

type DeviceOptions = {
  audio: MediaDeviceInfoMediaDeviceSelection[];
  video: MediaDeviceInfoMediaDeviceSelection[];
};

Represents the available media devices separated into audio and video categories.

---

How It Works

1. Permissions Check:
   • Uses the navigator.permissions.query API to check for microphone and camera permissions.
2. Media Stream:
   • Temporarily acquires a media stream using navigator.mediaDevices.getUserMedia to ensure devices are available.
3. Device Enumeration:
   • Retrieves a list of available media devices with navigator.mediaDevices.enumerateDevices.
4. Cleanup:
   • Stops media tracks to avoid resource locking.

---

Example Usage

Basic Example

import React from 'react';
import { useMediaDevices } from './path/to/useMediaDevices';

const MediaDeviceComponent: React.FC = () => {
  const [getDevices] = useMediaDevices('microphone', 'camera');
  const [devices, setDevices] = React.useState<DeviceOptions | undefined>(undefined);

  const fetchDevices = async () => {
    const result = await getDevices();
    setDevices(result);
  };

  return (
    <div>
      <h1>Media Devices</h1>
      <button onClick={fetchDevices}>Get Devices</button>
      {devices && (
        <div>
          <h2>Audio Devices</h2>
          <ul>
            {devices.audio.map((device) => (
              <li key={device.deviceId}>{device.label || 'Unnamed Audio Device'}</li>
            ))}
          </ul>
          <h2>Video Devices</h2>
          <ul>
            {devices.video.map((device) => (
              <li key={device.deviceId}>{device.label || 'Unnamed Video Device'}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
};

export default MediaDeviceComponent;

Explanation

1. Media Device Check: The getDevices function is called to retrieve audio and video devices.
2. State Update: The results are stored in devices and displayed in lists for audio and video devices.
3. Dynamic Rendering: The UI updates based on the availability of media devices.

---

Best Practices

• Handle Permissions Gracefully: Check for denied permissions and inform users if access is not granted.
• Device Refresh: Provide a way to refresh the list of devices as they may change dynamically (e.g., USB device plugged in).
• Error Handling: Use try-catch to manage potential errors when accessing media devices.

---

Notes

• The checkPermissions helper function is used internally to validate permissions and gather devices.
• Media tracks are stopped after use to prevent resource locking.

---

Contributing

If you encounter issues or have suggestions for improving the useMediaDevices hook, feel free to contribute or report an issue on the repository.