| description |
|---|
This guide will walk you through migrating from Twilio's Programmable Video platform to Whereby's Browser SDK. |
{% embed url="https://www.twilio.com/docs/video/javascript-getting-started#contents" %}
Whereby's Browser SDK is a suite of powerful integration options that allows developers to set up WebRTC-based video experiences in minutes! We offer a pre-built experience via our Web Component as well as a complete set of React Hooks, so there are options for teams of all sizes and capabilities.
This guide will mainly focus on our React library as this offers developers complete control over the video experience, and closely replicates the features that were offered in Programmable Video. If you're looking for a solution that can be quickly implemented check out our Twilio JS SDK Quick Migration guide.
Whereby and Twilio both have methods to manage connections to the room, control local media, and handle events within the room. The easiest place to start your migration is to swap these methods within your application.
Whereby and Twilio have structured these methods a bit different though, so there will need to be some refactoring necessary to compile the old Twilio requests.
Twilio manages their SDK in a very piecemeal way, with small snippets being responsible for things like connecting to a room, managing local media, rendering remote participant streams, etc.
Whereby on the other hand has two React hooks that break the SDK into two key components: Managing the Video Experience, and Managing Local Media. Below you'll find an overview of both of these Hooks, and guidance on what Twilio snippets feed in to these larger hooks.
The primary hook in the React SDK is useRoomConnection. This hook contains three main constants that handle parts of your application: state, actions, and components. Additionally, this hook returns all of your video feeds (localParticipants and remoteParticipants), so this is where you will do any UI customizations that you're building yourself. Basically this hook contains everything you need to build a basic video app in one simple to manage place!
Below are some examples of the various data types that are available on these constants, as well as a basic demonstration of using this hook. These also link to our Type Definitions, which break out each type in greater detail
| State | localParticipant | remoteParticipants | screenshares | chatMessages | RoomConnectionOptions |
| Actions | toggleCamera | toggleMicrophone | startScreenshare | stopScreenshare | sendChatMessage |
| Components | VideoView |
import { useRoomConnection } from "@whereby.com/browser-sdk/react";
function MyCallUX( { roomUrl, localStream }) {
const { state, actions, components } = useRoomConnection(
"<room_url>"
{
localMediaOptions: {
audio: true,
video: true,
}
}
);
const { connectionState, remoteParticipants } = state;
const { toggleCamera, toggleMicrophone } = actions;
const { VideoView } = components;
return <div className="videoGrid">
{ /* Render any UI, making use of state */ }
{ remoteParticipants.map((p) => (
<VideoView key={p.id} stream={p.stream} />
)) }
</div>;
}The table below is a summary of the various Twilio Methods that will migrate in to the useRoomConnection hook.
As you go through this guide you'll find that a lot of things that need to be handled manually in Twilio (for example participant join/leave events and media muting/unmuting) are automatically managed by our React hook. This means you have all the same capability and power afforded in Programmable Video with significantly less code to maintain.
| Use Case | Twilio Methods | useRoomConnection Hook | Comments |
|---|---|---|---|
| Connecting to the Room | connect({ name: 'existing-room'}) | const { state, actions, components } = userRoomConnection("<room_url>" | "existing-room" = "room_url" |
| Managing remote participants (other guests) | room.participants | remoteParticipants | (remoteParticipants are part of state, and include an id and a stream [video/audio]) |
| Managing the local participant | room.localParticipant | localParticipant | localParticipant uses the default mic/cam unless specified. |
| Handling Mute Events for Remote Participants | https://www.twilio.com/docs/video/javascript-getting-started#handle-remote-media-unmute-events | Automatically Managed | This is handled by room.participants as a part of state automatically |
| Muting/Unmuting Local Audio | room.localParticipant.audioTracks | toggleMicrophone | Used for muting and unmuting microphone for the local participant |
| Muting/Unmuting Local Video | room.localParticipant.videoTracks | toggleCamera | Used for muting and unmuting camera for the local participant |
| Handling Chat Messages | Not included in Programmable Video | chatMessages |
The useLocalMedia hook allows you to manage media devices with greater flexibility, but it's not required to have a successful implementation of Whereby. You can also use it to build a page that allows your users to test their device configurations outside of a Meeting Experience if you wish.
The useRoomConnection hook automatically selects the default mic/cam for your user's device, but it won't detect additional devices if they're connected. You might want this level of simplicity in your app, but if not you the useLocalMedia allows you to access all of the connected devices, and supply the desired device to useRoomConnection.
Below are some examples of the various data types that are available on this hook, as well as a basic demonstration of using this hook.
| localMedia.state | currentCameraDeviceId | cameraDevices | localStream |
| localMedia.actions | setCameraDevice | toggleCameraEnabled | toggleMicrophoneEnabled |
| Use Case | Twilio Methods | useLocalMedia | Notes |
|---|---|---|---|
| Access Local Devices | createLocalTracks | useLocalMedia | |
| Mute Local Audio | room.localParticipant.audioTracks.forEach(publication => { publication.track.disable(); }); | toggleCamera | These are actions that are included on useRoomConnection |
| Unmute Local Audio | room.localParticipant.audioTracks.forEach(publication => { publication.track.enable(); }); | toggleMicrophone | useRoomConnection |
| Mute Local Video | room.localParticipant.videoTracks.forEach(publication => { publication.track.disable(); }); | toggleCamera | useRoomConnection |
| Unmute Local Video | room.localParticipant.videoTracks.forEach(publication => { publication.track.enable(); }); | toggleMicrophone | useRoomConnection |