useLocalMedia

The useLocalMedia hook enables preview and selection of local devices (camera & microphone) prior to establishing a connection within a Whereby room. Use this hook to build rich pre-call and waiting room experiences, allowing end users to confirm their device selection up-front. This hook works seamlessly with the useRoomConnection hook.

useLocalMedia(mediaStreamConstraints: MediaStreamConstraints): Object | null

Parameters

Parameter	Required	Type	Description
mediaStreamConstraints	✅	MediaStreamConstraints	Options to use for initializing local media

Return type

The hook returns a LocalMediaReference object with the following properties.

Property	Type	Description
state	LocalMediaState	Object representing the state of local media
actions	LocalMediaActions	Object representing the available actions on local media

state

The state of local media

Property	Type	Description
currentCameraDeviceId	string | undefined	The Id of the current camera device
currentMicrophoneDeviceId	string | undefined	The id of the current microphone device
cameraDeviceError	unknown
cameraDevices	MediaDeviceInfo[]	List of the available camera devices
isSettingCameraDevice	boolean
isSettingMicrophoneDevice	boolean
isStarting	boolean
localStream	MediaStream| undefined	The stream of local media (camera & microphone)
lowDataMode	boolean	State of low data mode
microphoneDeviceError	unknown
microphoneDevices	MediaDeviceInfo[]	List of the available microphone devices
speakerDevices	MediaDeviceInfo[]	List of the available speaker devices
startError	unknown

actions

The actions property contains a map of functions which can be invoked to perform an action on local media. All these functions are sync and return void, and you should rely on the state to render the effect of their invocation.

Name	Parameters	Description
setCameraDevice	(deviceId: string) => void	Change the current camera device
setMicrophoneDevice	(deviceId: string) => void	Change the current microphone device
setSpeakerDevice	(deviceId: string) => void	Change the current speaker device
toggleCameraEnabled	(enabled?: boolean) => void	Change the state of your camera. Omitting the enabled parameter toggles the current value
toggleMicrophoneEnabled	(enabled?: boolean) => void	Change the state of your microphone. Omitting the enabled parameter toggles the current value
toggleLowDataModeEnabled	(enabled?: boolean) => void	Change the state of low data mode. Omitting the enabled parameter toggles the current value

Usage

import { useLocalMedia, VideoView } from "@whereby.com/browser-sdk/react";

function MyPreCallUX() {
    const localMedia = useLocalMedia({ audio: false, video: true });

    const { currentCameraDeviceId, cameraDevices, localStream } = localMedia.state;
    const { setCameraDevice, toggleCameraEnabled } = localMedia.actions;

    return <div className="preCallView">
        { /* Render any UI, making use of state */ }
        { cameraDevices.map((d) => (
            <p
                key={d.deviceId}
                onClick={() => {
                    if (d.deviceId !== currentCameraDeviceId) {
                        setCameraDevice(d.deviceId);
                    }
                }}
            >
                {d.label}
            </p>
        )) }
        <VideoView muted stream={localStream} />
    </div>;
}