useUserMedia

Installation

npm install @1hook/use-user-media

Usage

import { useUserMedia } from '@1hook/use-user-media'

Pass the media constraints to the hook.

const { stream, open, close, state, error } = useUserMedia({
  video: true,
})

The hook follows a simple state machine:

Initially starts in "closed" state with stream: null
Calling open() transitions to "loading" state while requesting device access
On successful device access, transitions to "open" state with stream: MediaStream
If an error occurs during loading, transitions to "error" state with the error details
Calling close() returns to "closed" state, stops the stream, and sets stream: null

This predictable state flow makes it easy to build UIs that respond appropriately to the media stream's status.

Example

Capture and display video from the device's camera.

import { useEffect, useRef } from 'react'
import { useUserMedia } from '@1hook/use-user-media'

export default function VideoCapture() {
  const { state, stream, open, close } = useUserMedia({
    video: true,
  })

  const ref = useRef<HTMLVideoElement | null>(null)

  // use the stream to reproduce the video
  useEffect(() => {
    if (!ref.current) return
    ref.current.srcObject = stream
  }, [stream])

  return (
    <div>
      <video ref={ref} autoPlay />

      <button onClick={state === 'closed' ? open : close}>
        {state === 'closed' ? 'Open' : 'Close'} Camera
      </button>
    </div>
  )
}

Parameters

UseUserMediaOptions

The options of the useUserMedia hook. See MDN docs for more details.

Prop	Type	Default
`video?`	`boolean \| MediaTrackConstraints`	-
`preferCurrentTab?`	`boolean`	-
`peerIdentity?`	`string`	-
`audio?`	`boolean \| MediaTrackConstraints`	-

UseUserMediaReturn

The return value of the useUserMedia hook.

Prop	Type	Default
`toggleVideo`	`() => void`	-
`toggleAudio`	`() => void`	-
`close`	`() => void`	-
`open`	`() => void`	-
`videoState`	`"none" \| "enabled" \| "disabled"`	-
`audioState`	`"none" \| "enabled" \| "disabled"`	-
`error`	`Error \| null`	-
`state`	`"closed" \| "error" \| "open" \| "loading"`	-
`stream`	`MediaStream \| null`	-