• Stars
    star
    1,808
  • Rank 25,684 (Top 0.6 %)
  • Language
    TypeScript
  • License
    Apache License 2.0
  • Created about 5 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A collaboration application built with the twilio-video.js SDK and React.js

Twilio Video React App

CircleCI

What is it

This application demonstrates a multi-party video application built with Twilio's Programmable Video JS SDK, Twilio's Conversations JS SDK, and Create React App.

  • Deploy to Twilio Serverless in just a few minutes
  • No other infrastructure is required
  • No code changes are required before your first deploy
  • There is no cost associated with deploying the app
  • Go Rooms usage is free, however standard usage charges apply for Programmable Video when using the app with all other Room types. The chat feature is built using the Conversations API and is free-of-cost up to 200 monthly active users, standard usage charges apply thereafter.

App Preview

Prerequisites

You must have the following installed:

  • Node.js v14+
  • NPM v6+ (comes installed with newer Node versions)

You can check which versions of Node.js and NPM you currently have installed with the following commands:

node --version
npm --version

Clone the repository

Clone this repository and cd into the project directory:

git clone https://github.com/twilio/twilio-video-app-react.git
cd twilio-video-app-react

Install Dependencies

Run npm install inside the main project folder to install all dependencies from NPM.

If you want to use yarn to install dependencies, first run the yarn import command. This will ensure that yarn installs the package versions that are specified in package-lock.json.

Add Noise Cancellation

Twilio Video has partnered with Krisp Technologies Inc. to add noise cancellation to the local audio track. This feature is licensed under the Krisp Plugin for Twilio. In order to add this feature to your application, please run npm run noisecancellation:krisp immediately after the previous step.

Install Twilio CLI and RTC Plugin

Install the Twilio CLI

The app is deployed to Twilio using the Twilio CLI. You can install the Twilio CLI using Homebrew on a Mac or npm.

To install twilio-cli using npm, run the following command:

npm install -g twilio-cli

Note: If you run into permissions errors when installing the twilio-cli globally with the npm install -g command, you might need to change the permissions of your global node_modules directory or configure npm to use a different directory for globally installed npm packages. See this StackOverflow thread, which has more information about both options. This code sample in GitHub is also a helpful guide for how to install npm packages globally without needing to change directory permissions and without sudo.

Login to the Twilio CLI

Login to the Twilio CLI. You will be prompted for your Account SID and Auth Token, both of which you can find on the dashboard of your Twilio console.

twilio login

Note: If you installed the Twilio CLI using npm and you receive an error that the twilio command is not found, you might need to update your Node install prefix. See this StackOverflow thread for more information.

Install the RTC Plugin

This app requires an additional plugin. Install the CLI plugin with:

twilio plugins:install @twilio-labs/plugin-rtc

Note: If you have previously installed the @twilio-labs/plugin-rtc plugin, please make sure that you are using the most recent version. You can upgrade the plugin by running twilio plugins:update. The chat feature requires version 0.8.1 or greater of @twilio-labs/plugin-rtc.

Deploy the app to Twilio

Before deploying the app, make sure you are using the correct account on the Twilio CLI (using the command twilio profiles:list to check). The app is deployed to Twilio with a single command:

npm run deploy:twilio-cli

This performs the following steps:

  • Builds the React app in the src directory
  • Generates a random code used to access the Video app
  • Deploys the React app and token server function as a Twilio Serverless service.
  • Prints the URL for the app and the passcode.

NOTE: The Twilio Function that provides access tokens via a passcode should NOT be used in a production environment. This token server supports seamlessly getting started with the collaboration app, and while convenient, the passcode is not secure enough for production environments. You should use an authentication provider to securely provide access tokens to your client applications. You can find more information about Programmable Video access tokens in this tutorial. As a precaution, the passcode will expire after one week. To generate a new passcode, redeploy the app:

npm run deploy:twilio-cli -- --override

View app details

View the URL and passcode for the Video app with

 twilio rtc:apps:video:view

Delete the app

Delete the app with

twilio rtc:apps:video:delete

This removes the Serverless app from Twilio. This will ensure that no further cost are incurred by the app.

Troubleshooting The Twilio CLI

If any errors occur after running a Twilio CLI RTC Plugin command, then try the following steps.

  1. Run twilio plugins:update to update the rtc plugin to the latest version.
  2. Run twilio rtc:apps:video:delete to delete any existing video apps.
  3. Run npm run deploy:twilio-cli to deploy a new video app.

App Behavior with Different Room Types

After running the command to deploy the app to Twilio, the room type will be returned in the command line output. Each room type provides a different video experience. More details about these room types can be found here. The rest of this section explains how these room types affect the behavior of the video app.

Group - The Group room type allows up to fifty participants to join a video room in the app. The Network Quality Level (NQL) indicators, dominant speaker, and start-stop recordings are demonstrated with this room type. Also, the VP8 video codec with simulcast enabled along with a bandwidth profile are set by default in order to provide an optimal group video app experience.

Small Group - This is a legacy room type; we recommend using Group Rooms instead when developing multiparty applications. The Small Group room type provides an identical group video app experience except for a smaller limit of four participants.

Peer-to-peer - Although up to ten participants can join a room using the Peer-to-peer (P2P) room type, it is ideal for a one to one video experience. The NQL indicators, bandwidth profiles, dominant speaker, and start-stop recordings cannot be used with this room type. Thus, they are not demonstrated in the video app. Also, the VP8 video codec with simulcast disabled and 720p minimum video capturing dimensions are also set by default in order to provide an optimal one to one video app experience. If more than ten participants join a room with this room type, then the video app will present an error.

Go - The Go room type provides a similar Peer-to-peer video app experience except for a smaller limit of two participants. If more than two participants join a room with this room type, then the video app will present an error.

If the max number of participants is exceeded, then the video app will present an error for all room types.

Features

The Video app has the following features:

Browser Support

See browser support table for twilio-video.js SDK.

Deeper dive

Running a local token server

This application requires an access token to connect to a Room for Video and a Conversation for Chat. The included local token server provides the application with access tokens. This token server can be used to run the app locally, and it is the server that is used when this app is run in development mode with npm start. Perform the following steps to setup the local token server:

  • Create an account in the Twilio Console.
  • Click on 'Settings' and take note of your Account SID.
  • Create a new API Key in the API Keys Section under Programmable Video Tools in the Twilio Console. Take note of the SID and Secret of the new API key.
  • Create a new Conversations service in the Services section under the Conversations tab in the Twilio Console. Take note of the SID generated.
  • Store your Account SID, API Key SID, API Key Secret, and Conversations Service SID in a new file called .env in the root level of the application (example below).
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_KEY_SID=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_KEY_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_CONVERSATIONS_SERVICE_SID=ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Now the local token server (see server/index.ts) can dispense Access Tokens to connect to a Room and a Conversation. See .env.example for information on additional environment variables that can be used.

Note: the use of Twilio Conversations is optional. If you wish to opt out, simply run or build this app with the REACT_APP_DISABLE_TWILIO_CONVERSATIONS environment variable set to true.

Running the App locally

Run the app locally with

npm start

This will start the local token server and run the app in the development mode. Open http://localhost:3000 to see the application in the browser.

The page will reload if you make changes to the source code in src/. You will also see any linting errors in the console. Start the token server locally with

npm run server

The token server runs on port 8081 and expects a POST request at the /token route with the following JSON parameters:

{
  "user_identity": string, // the user's identity
  "room_name": string, // the room name
}

The response will be a token that can be used to connect to a room. The server provided with this application uses the same endpoints as the plugin-rtc Twilio CLI plugin that is used to deploy the app. For more detailed information on the server endpoints, please see the plugin-rtc README.

Multiple Participants in a Room

If you want to see how the application behaves with multiple participants, you can simply open localhost:3000 in multiple tabs in your browser and connect to the same room using different user names.

Additionally, if you would like to invite other participants to a room, each participant would need to have their own installation of this application and use the same room name and Account SID (the API Key and Secret can be different).

Building

Build the React app with

npm run build

This script will build the static assets for the application in the build/ directory.

Tests

This application has unit tests (using Jest) and end-to-end tests (using Cypress). You can run the tests with the following scripts.

Unit Tests

Run unit tests with

npm test

This will run all unit tests with Jest and output the results to the console.

E2E Tests

Run end to end tests with

npm run cypress:open

This will open the Cypress test runner. When it's open, select a test file to run.

Note: Be sure to complete the 'Getting Started' section before running these tests. These Cypress tests will connect to real Twilio rooms and real Twilio conversations, so you may be billed for any time that is used.

Application Architecture

The state of this application (with a few exceptions) is managed by the room object that is supplied by the SDK. The room object contains all information about the room that the user is connected to. The class hierarchy of the room object can be viewed here.

One great way to learn about the room object is to explore it in the browser console. When you are connected to a room, the application will expose the room object as a window variable: window.twilioRoom.

Since the Twilio Video SDK manages the room object state, it can be used as the source of truth. It isn't necessary to use a tool like Redux to track the room state. The room object and most child properties are event emitters, which means that we can subscribe to these events to update React components as the room state changes.

React hooks can be used to subscribe to events and trigger component re-renders. This application frequently uses the useState and useEffect hooks to subscribe to changes in room state. Here is a simple example:

import { useEffect, useState } from 'react';

export default function useDominantSpeaker(room) {
  const [dominantSpeaker, setDominantSpeaker] = useState(room.dominantSpeaker);

  useEffect(() => {
    room.on('dominantSpeakerChanged', setDominantSpeaker);
    return () => {
      room.off('dominantSpeakerChanged', setDominantSpeaker);
    };
  }, [room]);

  return dominantSpeaker;
}

In this hook, the useEffect hook is used to subscribe to the dominantSpeakerChanged event emitted by the room object. When this event is emitted, the setDominantSpeaker function is called which will update the dominantSpeaker variable and trigger a re-render of any components that are consuming this hook.

For more information on how React hooks can be used with the Twilio Video SDK, see this tutorial: https://www.twilio.com/blog/video-chat-react-hooks. To see all of the hooks used by this application, look in the src/hooks directory.

The VideoProvider component contains much of the logic that relates to connecting to video rooms and acquiring local input devices. The VideoProvider component exposes many properties and methods to the rest of the application through the useVideoContext hook. Similarly, the ChatProvider contains logic that relates to connecting to a Twilio Conversation, and it exposes properties and methods through the useChatContext hook.

Configuration

The connect function from the SDK accepts a configuration object. The configuration object for this application can be found in src/utils/useConnectionOptions/useConnectionOptions.ts. In this object, we 1) enable dominant speaker detection, 2) enable the network quality API, and 3) supply various options to configure the bandwidth profile.

Track Priority Settings

This application dynamically changes the priority of remote video tracks to provide an optimal collaboration experience. Any video track that will be displayed in the main video area will have track.setPriority('high') called on it (see the VideoTrack component) when the component is mounted. This higher priority enables the track to be rendered at a high resolution. track.setPriority(null) is called when the component is unmounted so that the track's priority is set to its publish priority (low).

Google Authentication using Firebase (optional)

This application can be configured to authenticate users before they use the app. Once users have signed into the app with their Google credentials, their Firebase ID Token will be included in the Authorization header of the HTTP request that is used to obtain an access token. The Firebase ID Token can then be verified by the server that dispenses access tokens for connecting to a room.

See .env.example for an explanation of the environment variables that must be set to enable Google authentication.

Related

License

See the LICENSE file for details.

More Repositories

1

twilio-python

A Python module for communicating with the Twilio API and generating TwiML.
Python
1,707
star
2

stashboard

An open-source status dashboard running on App Engine
Python
1,594
star
3

twilio-php

A PHP library for communicating with the Twilio REST API and generating TwiML.
PHP
1,447
star
4

twilio-ruby

A Ruby gem for communicating with the Twilio API and generating TwiML
Ruby
1,335
star
5

twilio-node

Node.js helper library
TypeScript
1,304
star
6

OpenVBX

OpenVBX is a web-based open source phone system for business.
PHP
699
star
7

twilio-csharp

Twilio C#/.NET Helper Library for .NET Framework 3.5+ and supported .NET Core versions
C#
636
star
8

BankersBox

redis-like wrapper for javascript storage
CoffeeScript
571
star
9

twilio-video.js

Twilio’s Programmable Video JavaScript SDK
JavaScript
569
star
10

video-quickstart-ios

Twilio Video Quickstart for iOS
Swift
458
star
11

twilio-java

A Java library for communicating with the Twilio REST API and generating TwiML.
Java
440
star
12

video-quickstart-js

A quickstart and code samples for Twilio Video JavaScript SDK. https://www.twilio.com/docs/video
JavaScript
390
star
13

shadow

A HTTP debugging proxy that helps you with your continuous deployments
JavaScript
330
star
14

twilio-go

A Go package for communicating with the Twilio API.
Go
278
star
15

twilio-sans-mono

Twilio Sans Mono is a beautiful and extensive open source programming font
Shell
255
star
16

twilio-video-app-ios

A collaboration application built with the Twilio Video iOS SDK
Swift
246
star
17

authy-php

A PHP client for Authy
PHP
245
star
18

twilio-video-app-android

A collaboration application built with the Twilio Video Android SDK
Kotlin
240
star
19

video-quickstart-android

Twilio Video Quickstart for Android
Java
210
star
20

authy-devise

Authy Devise plugin to add Two-Factor Authentication
Ruby
201
star
21

authy-python

Authy API Client for Python
Python
189
star
22

twilio-salesforce

A Salesforce/Force.com library for communicating with the Twilio REST API and generating TwiML. Need help? Post your questions to http://getsatisfaction.com/twilio or email us at [email protected]
Apex
186
star
23

voice-quickstart-android

Quickstart app for the Voice Android SDK
Java
184
star
24

voice-quickstart-ios

Twilio Voice Quickstart for iOS with Swift
Objective-C
179
star
25

twilio-cli

Unleash the power of Twilio from your command prompt
JavaScript
160
star
26

audioswitch

An Android audio management library for real-time communication apps.
Kotlin
159
star
27

authy-ruby

**Deprecated** Ruby library to access the authy API
Ruby
156
star
28

authy-openvpn

Authy Open VPN Two-Factor Authentication
C
152
star
29

gameday

A collection of Twilio SRE's Gameday Templates
140
star
30

twilio-oai

The Twilio OpenAPI Specification
Makefile
122
star
31

TwilioChatJsReactNative

ReactNative app example for Twilio Programmable Chat with working iOS and Android push messages https://www.twilio.com/chat
JavaScript
114
star
32

chessms

Play Chess over SMS!
Erlang
112
star
33

media-streams

Quick start guides for configuring and consuming Twilio Media Streams
Ruby
102
star
34

twilio-conversations-demo-react

Twilio Conversations Demo Web Application
TypeScript
97
star
35

apkscale

A Gradle plugin to measure the app size impact of Android libraries
Kotlin
93
star
36

OpenVBX-iPhone

OpenVBX for iPhone
Objective-C
92
star
37

twilio-chat-demo-js

Programmable Chat API Demo Application for JavaScript
JavaScript
92
star
38

starter-node

A starter app for node.js developers embarking on their first Twilio quest!
JavaScript
84
star
39

authy-form-helpers

Authy javascripts and css file to help create quick forms for the authy api
CoffeeScript
83
star
40

flex-plugin-builder

Packages related to building a Twilio Flex Plugin
TypeScript
83
star
41

starter-python

A starter app for Python developers embarking on their first Twilio quest!
CSS
76
star
42

sourd.io

sourd.io: temperature, humidity, and rise monitoring for your sourdough starter
C++
73
star
43

twilio-voice-react-native

TypeScript
67
star
44

twilio-client.js

Twilio’s Programmable Voice JavaScript SDK
TypeScript
67
star
45

authy-java

Java Client for Twilio Authy Two-Factor Authentication (2FA) API
Java
65
star
46

twilio-video-ios

Programmable Video SDK by Twilio
Swift
64
star
47

twilio-chat-demo-android

Chat API Demo Application for Android
Kotlin
63
star
48

twilio-webchat-react-app

Twilio Webchat React App is an application that demonstrates a website chat widget built with Twilio's Conversations JS SDK, Twilio Paste Design library and Create React App.
TypeScript
63
star
49

terraform-provider-twilio

Terraform Twilio provider
Go
62
star
50

twilio-voice.js

Twilio's JavaScript Voice SDK
TypeScript
50
star
51

twilio-webrtc.js

WebRTC-related APIs and shims used by twilio-video.js
JavaScript
49
star
52

rtc-diagnostics

TypeScript
44
star
53

flex-ui-sample

Twilio Flex UI Sample
JavaScript
44
star
54

twilio-video-diagnostics-react-app

A diagnostics tool that tests a participant's ability to have a quality video call. Built with the twilio-video.js SDK, RTC Diagnostics SDK, and React.js.
TypeScript
41
star
55

wiztowar

Build WARs from your Dropwizard apps
Java
40
star
56

hackathons

A collection of tips and tricks for using Twilio at hackathons
40
star
57

twilio-voice-ios

Programmable Voice SDK by Twilio
Swift
39
star
58

voice-quickstart-objc

Twilio Voice Quickstart for iOS with Objective-C
Objective-C
38
star
59

twilio-voice-notification-app

Reference app built in ReactJS that demonstrates how to leverage Twilio Programmable Voice and Twilio SDKs to create a voice notification system.
TypeScript
36
star
60

sample-code

Auto-generated code samples for the Twilio REST API
Java
35
star
61

draw-with-twilio

Draw with Twilio
JavaScript
35
star
62

video-quickstart-objc

Twilio Video Quickstart for iOS with Objective-C
Objective-C
33
star
63

twilio-video-processors.js

Twilio Video Processors is a collection of video processing tools which can be used with Twilio Video JavaScript SDK to apply transformations and filters to a video track.
TypeScript
33
star
64

twilio-voice-react-native-app

TypeScript
32
star
65

TwilioChatXamarinBindings

Twilio Chat Bindings for Xamarin (Android and iOS) and Sample app with working FCM and APN pushes using those bindings.
C#
32
star
66

flex-webchat-ui-sample

Twilio Flex Web Chat UI Sample
JavaScript
31
star
67

twilio-live-interactive-video

An interactive live video app built with Twilio Live and Twilio Video
TypeScript
31
star
68

twilio-video.js-recording-bot

JavaScript
30
star
69

twilio-chat-demo-ios

Twilio Programmable Chat Demo Application for iOS
Objective-C
28
star
70

calcite-kudu

Apache Calcite Adapter for Apache Kudu
Java
28
star
71

ortc-adapter

ORTC to WebRTC Adapter
JavaScript
28
star
72

cloudsec

27
star
73

starter-ruby

A starter app for Ruby developers embarking on their first Twilio quest!
JavaScript
27
star
74

twilio-oai-generator

Twilio OpenAPI client generator
Java
26
star
75

autopilot-cli

The Twilio Autopilot CLI is now deprecated. Please use the Autopilot Plugin for the Twilio CLI here https://www.twilio.com/docs/autopilot/twilio-autopilot-cli
JavaScript
26
star
76

voice-quickstart-server-python

Python
25
star
77

twilio-taskrouter.js

JS SDK v2 for Twilio's TaskRouter skills based routing system.
JavaScript
24
star
78

twilio-boost-build

Build tool for boost libraries on android, ios, linux and osx
Shell
24
star
79

wireless-security-camera

Create a Twilio-powered device that keeps watch over dangerous and remote locations and alerts stakeholders of intrusions or safety concerns.
CSS
24
star
80

twilio-video-room-monitor.js

A browser-based tool that displays information and metrics about Twilio Video JavaScript applications
TypeScript
24
star
81

video-shared-arkit-sample

ARKit + Twilio Video Data Tracks demo
Swift
24
star
82

voice-quickstart-server-node

voice quickstart server example in node
JavaScript
24
star
83

starter-java

A starter app for Java developers embarking on their first Twilio quest!
CSS
22
star
84

wireless-fleet-tracker

Create a Twilio-powered Fleet Tracker that uses off-the-shelf components to track and log: miles driven, hours of uptime and downtime, locations, average speed, and fuel consumption.
CSS
22
star
85

voices

Twilio Voices - Contribute programming tutorials to the Twilio blog. Get paid for each post you publish.
20
star
86

rtc-diagnostics-react-app

TypeScript
20
star
87

autopilot-templates

JavaScript
19
star
88

client-js-1.4-examples

Examples for using the new Client JS 1.4 Audio functionality
JavaScript
19
star
89

wp-click2call

Wordpress Plugin for Click2Call
PHP
19
star
90

authy.net

.NET Library to access the Authy API
C#
19
star
91

starter-php

A starter app for PHP developers embarking on their first Twilio quest!
PHP
19
star
92

Breakout_Arduino_Library

C
18
star
93

howtos

Sample applications that cover common use cases in a variety of languages.
Python
18
star
94

twilio-conversations-demo-android-kotlin

An application demonstrating use of Twilio Conversations on Android - this is a full working Kotlin application
Kotlin
18
star
95

cerebro

Python
17
star
96

linkit-one-sensor-samples

Samples for the LinkIt ONE Starter Kit
C++
17
star
97

twilio-flex-token-validator

Flex JWE Token Validator
TypeScript
17
star
98

wireless-postman-collection

This repository includes a group of Programmable Wireless HTTP requests for your convenience. You can learn more about Programmable Wireless HTTP request formats in the Programmable Wireless Documentation.
17
star
99

twilio-verify-ios

Twilio Verify Push SDK helps you verify users by adding a low-friction, secure, cost-effective, "push verification" factor into your own apps. This project provides an SDK to implement Verify Push for your iOS app.
Swift
17
star
100

twilio-conversations-demo-ios-swift

Twilio Conversations for iOS Demo application in Swift
Swift
17
star