use-twilio-video-hooks

A library of React hooks to make working with twlio-video easier.

Acknowledgements

This repository is an unofficial extension of use-twilio-video by Nur Latifah Ulfah. We'd like to express our gratitude for the foundational work they provided, which greatly assisted in the development of this project. Please visit the original repository to appreciate the great work they started with.

Features

• Connect and disconnect from a room.
• Toggle camera mute.
• Toggle microphone mute.
• Identify the dominant speaker.

Install

1npm install --save twilio-video use-twilio-video-hooks

Prerequisite

You need Twilio Access Token to use Twilio Video. You can use Testing Tools in the Twilio Console to generate the token. You can read the guide here.

Or you can also follow the next instruction while running the sample project in folder example. To run example:

1. From root repo directory, change directory to example folder: cd example
2. Install dependencies: npm install
3. Copy .env.example and rename to .env
4. Add your Twilio API Key to the .env file. You can get your API Key from your Twilio account. You can follow this guide.
5. Run server to generate token: npm run server
6. Open different tab and run the react app: npm start

Usage

There are two main hooks, useRoom and useTrack.

useRoom is used to manage room state. In Twilio, a Room represents a real-time audio, data, video, and/or screen-share session, and is the basic building block for a Programmable Video application.

useTrack is used to manage tracks in a room. In Twilio, Tracks represent the individual audio, data, and video media streams that are shared within a Room. This tracks are shared by Participants. Participants represent client applications that are connected to a Room and sharing audio, data, and/or video media with one another.

The following are the minimum components needed to be able to create a simple video call application using twilio and use-twilio-video-hooks.

1. Create a component that represent a Room.

   1// Room.js
   2import Participant from './Participant'
   3import { useRoom } from 'use-twilio-video-hooks'
   4
   5function Room ({ token, roomName }) {
   6  const { room, error, connectRoom, disconnectRoom, localParticipant, remoteParticipants, dominantSpeaker, isCameraOn, toggleCamera, isMicrophoneOn, toggleMicrophone } = useRoom()
   7
   8
   9  useEffect(() => {
   10    if (!room && token && roomName) {
   11      connectRoom({ token, options: { name: roomName, dominantSpeaker: true } })
   12      return () => disconnectRoom()
   13    }
   14  }, [connectRoom, disconnectRoom, room, roomName, token])
   15
   16  // ... other
   17
   18  // usage example in simple component
   19  if (room)
   20    return (
   21      <div>
   22        <div>
   23          <button onClick={() => disconnectRoom()}>disconnect</button>
   24          <button onClick={() => toggleCamera()}>
   25            {isCameraOn ? 'turn off camera' : 'turn on camera'}
   26          </button>
   27          <button onClick={() => toggleMicrophone()}>
   28            {isMicrophoneOn ? 'turn off mic' : 'turn on mic'}
   29          </button>
   30        </div>
   31
   32        <div>Local participant: {JSON.stringify(localParticipant?.identity)}</div>
   33        <Participant participant={localParticipant} />
   34
   35        <div>
   36          Remote participants:{' '}
   37          {JSON.stringify(remoteParticipants.map(v => v.identity))}
   38        </div>
   39
   40        <div>Dominant speaker: {JSON.stringify(dominantSpeaker?.identity)}</div>
   41
   42        <div>
   43          {remoteParticipants.map(p => (
   44            <Participant participant={p} />
   45          ))}
   46        </div>
   47      </div>
   48    )
   49
   50  // ... other
   51}

2. Create a component represent Participants.

   1// Participant.js
   2import AudioTrack from './AudioTrack'
   3import VideoTrack from './VideoTrack'
   4import { useTrack } from 'use-twilio-video-hooks'
   5
   6function Participant ({ participant }) {
   7  const { videoOn, audioOn, videoTrack, audioTrack } = useTrack({ participant })
   8
   9  return (
   10    <div>
   11      {videoOn ? <VideoTrack track={videoTrack} /> : 'video off'}
   12      <br />
   13      {audioOn ? <AudioTrack track={audioTrack} /> : 'audio off'}
   14    </div>
   15  )
   16}
   17
   18export default Participant

3. Create two components, to attach participants' video and audio

   1// VideoTrack.js
   2import { useEffect, useRef } from 'react'
   3
   4export default function VideoTrack ({ track }) {
   5  const ref = useRef()
   6
   7  useEffect(() => {
   8    if (track) {
   9      const el = ref.current
   10      track.attach(el)
   11
   12      return () => {
   13        track.detach(el)
   14      }
   15    }
   16  }, [track])
   17
   18  return <video style={{ maxWidth: '100%' }} ref={ref} />
   19}
   20

   1// AudioTrack.js
   2import { useEffect, useRef } from 'react'
   3
   4export default function AudioTrack ({ track }) {
   5  const ref = useRef()
   6
   7  useEffect(() => {
   8    if (track) {
   9      const el = ref.current
   10      track.attach(el)
   11
   12      return () => {
   13        track.detach(el)
   14      }
   15    }
   16  }, [track])
   17
   18  return <audio ref={ref} />
   19}

License

MIT © Jay Mathew