useUserMedia

Reactive wrapper around the MediaDevices.getUserMedia() API. Provides start/stop/restart controls and exposes the media stream as an observable.

Demo

User Media

Not Supported

Access the camera via getUserMedia. Click Start to begin streaming.

No stream

StartStop

Usage

Hook

import { useUserMedia } from "@usels/web";

function CameraFeed() {
  const { isSupported$, stream$, enabled$, start, stop } = useUserMedia({
    constraints: { audio: false, video: true },
  });

  return (
    <div>
      <p>Supported: {isSupported$.get() ? "Yes" : "No"}</p>
      <p>Streaming: {enabled$.get() ? "Yes" : "No"}</p>
      <button onClick={() => start()}>Start</button>
      <button onClick={() => stop()}>Stop</button>
    </div>
  );
}

Scope

import { createUserMedia } from "@usels/web";

function CameraFeed() {
  "use scope";
  const { isSupported$, stream$, enabled$, start, stop } = createUserMedia({
    constraints: { audio: false, video: true },
  });

  return (
    <div>
      <p>Supported: {isSupported$.get() ? "Yes" : "No"}</p>
      <p>Streaming: {enabled$.get() ? "Yes" : "No"}</p>
      <button onClick={() => start()}>Start</button>
      <button onClick={() => stop()}>Stop</button>
    </div>
  );
}

Auto-start on mount

// @noErrors
import { useUserMedia } from "@usels/web";

function AutoCamera() {
  const { stream$, stop } = useUserMedia({
    constraints: { audio: false, video: true },
    immediate: true,
  });

  // Stream starts automatically on mount
  // Stops automatically on unmount
  return <button onClick={() => stop()}>Stop</button>;
}

Audio-only capture

// @noErrors
import { useUserMedia } from "@usels/web";

function Microphone() {
  const { stream$, start, stop, enabled$ } = useUserMedia({
    constraints: { audio: true, video: false },
  });

  return (
    <button onClick={() => (enabled$.get() ? stop() : start())}>
      {enabled$.get() ? "Stop Recording" : "Start Recording"}
    </button>
  );
}

Reactive options

Options can be passed as plain values, per-field Observables, or a single Observable<UseUserMediaOptions>. constraints are read at each start() / restart() call.

import { observable } from "@usels/core";
import { useUserMedia } from "@usels/web";

const constraints$ = observable<MediaStreamConstraints>({ audio: false, video: true });

const { start, restart } = useUserMedia({ constraints: constraints$ });

// Later: switch to audio+video reactively
constraints$.set({ audio: true, video: true });
restart(); // uses updated constraints

Notes

options is DeepMaybeObservable. Each option field can be a plain value or an Observable. constraints are read at each start() / restart() call time. immediate is read at mount-time.

Type

Parameters

Parameter	Type	Description
options	UseUserMediaOptions (optional)	-

UseUserMediaOptions

Option	Type	Default	Description
constraints	MediaStreamConstraints	-	Media constraints for getUserMedia. Default: { audio: false, video: true }
immediate	boolean	-	Auto-start stream on mount. Default: false

Returns

UseUserMediaReturn

Name	Type	Description
stream$	ReadonlyObservable<OpaqueObject<MediaStream> | null>	Current media stream
enabled$	ReadonlyObservable<boolean>	Whether stream is currently active
start	() => Promise<MediaStream>	Start the media stream. Throws if getUserMedia fails.
stop	() => void	Stop the media stream
restart	() => Promise<MediaStream>	Restart the media stream. Throws if getUserMedia fails.
isSupported$	ReadonlyObservable<boolean>	-

Source

View on GitHub