# useUserMedia

Opens the camera and/or microphone with `getUserMedia`, and stops every track on unmount, when disabled, or when the constraints change, so the camera light turns off.

Enabling it makes the browser ask for permission the first time. Returns `{ stream: null, loading: false }` on the server, during hydration, and while disabled. Constraints are compared by value, so an inline object is fine.

## Import

```ts
import { useUserMedia } from '@vincent.ri/react-tils'
// or only this hook
import { useUserMedia } from '@vincent.ri/react-tils/useUserMedia'
```

## Usage

```ts
const { stream, error } = useUserMedia({ video: { facingMode: 'environment' } })
const videoRef = useCallback(
  (video: HTMLVideoElement | null) => {
    if (video) video.srcObject = stream
  },
  [stream],
)
if (error) return <p>Camera unavailable: {error.message}</p>
return <video ref={videoRef} autoPlay playsInline muted />
```

## When to use it

A video call preview, scanning a QR code, recording audio, or taking a profile photo.

## When not to

A file input is enough (`<input type="file" accept="image/*" capture>` opens the camera on phones with no permission prompt). To check the permission first, use `usePermission('camera')`.

## API

```ts
function useUserMedia(constraints: MediaStreamConstraints, options?: {
  enabled?: boolean;
}): UserMediaState
```

| Parameter | Description |
| --- | --- |
| `constraints` | `getUserMedia` constraints, e.g. `{ video: true, audio: false }`. |
| `options` | `enabled`: request while `true`. Default `true`. |

### Types

```ts
export type UserMediaState = {
  /** The live stream, or `null` while disabled, loading, or after an error. */
  stream: MediaStream | null;
  /** `NotAllowedError` (denied), `NotFoundError` (no device), etc., or an `Error` if unsupported. */
  error: Error | null;
  /** `true` while enabled and waiting for the stream or an error. */
  loading: boolean;
};
```

## Browser support

Works in all modern browsers.

- Needs a secure page (HTTPS or localhost).

---

313 B minified and brotlied
Source: https://github.com/vincentri/react-tils/blob/main/src/useUserMedia.ts
Docs page: https://vincentri.github.io/react-tils/hooks/useUserMedia/
Previous: [useWakeLock](https://vincentri.github.io/react-tils/hooks/useWakeLock.md)
Next: [useMediaRecorder](https://vincentri.github.io/react-tils/hooks/useMediaRecorder.md)