DEV Community: Ekaansh Arora

Adding Video Chat or Live Streaming to Your Website in 5 lines of Code Using the Agora Web UIKit

Ekaansh Arora — Mon, 31 Jan 2022 15:20:02 +0000

When you’re building a live video streaming or a video conferencing website with Agora, a few technical steps might slow you down. Now with the Agora Web UIKit, you can easily add video calling to your website with just five lines of code! It’s fully featured to boot, and it comes with easy customization and is meant to be extended.

Features

Support for video conferencing and live streaming
Plug and play, no watermark or branding out of the box
Responsive layouts for desktop and mobile
Customizable UI and functionality using React properties
Automatically manage tokens (using two-click server deploy)
Dual-stream mode and active speaker detection
Built using modular functional components that can be recomposed
TypeScript support, with no third-party dependencies
Support for use as a web component
10,000 free minutes every month

The Agora Web UIKit is built on React. If your website uses plain JavaScript or a different framework like Svelte, Vue, or Angular, you can use the UIKit as a web component! You can skip to the last section to learn more.

Prerequisites

An Agora developer account (It’s free–sign up here!)
Node.js LTS release
A website built using React
A modern web browser

Setup

You can get the code for the example on GitHub. To create a React project with Typescript, you can open a terminal and execute:

npx create-react-app demo --template typescript
cd demo

Or you can use your own project. Install the Agora Web UIKit from NPM:

npm i agora-react-uikit

Note: At the time of writing this post, the current *agora-react-uikit release is v0.0.5, and the current agora-rtc-sdk-ng release is v4.8.1.*

That’s the set up. You can now run npm start to start the React server and visit the hello world app on localhost:3000.

Adding Video Streaming

This UIKit is easy to set up and contains a high-level component called AgoraUIKit. The component handles the logic and UI for our real-time video experience. We can pass in props to the component to customize the behavior and functionality. Let’s clear the App.tsx file and start writing the code to build a video chatting app:

import React, { useState } from 'react'
import AgoraUIKit, { PropsInterface } from 'agora-react-uikit'

const App: React.FunctionComponent = () => {
  const [videocall, setVideocall] = useState(true)
  const props: PropsInterface = {
    rtcProps: {
      appId: '<Your Agora App ID>',
      channel: 'test',
      token: null, // pass in channel token if the app is in secure mode
    },
    callbacks: {
      EndCall: () => setVideocall(false)
    }
  }
...

We’re importing the AgoraUIKit component from the agora-react-uikit package. Inside the App component we have a state variable videoCall. We’ll render the UIKit component when it’s set to true and unmount it when it’s false. We define the Agora App ID and channel name in the rtcProps object along with our role. Users on the same channel can communicate with each other. You can use any alphanumeric string for the channel name.

Note: If your app is in secure mode, you can generate a token from the Agora console and pass it in for testing. We’ll talk more about how to use tokens in a bit.

The callbacks object contains RTC events as keys and callback functions as their value — we use the EndCall event to update the state and unmount the AgoraUIKit component:

...
  return (
    <div style={styles.container}>
      {videocall ? (
        <AgoraUIKit
          rtcProps={props.rtcProps}
          callbacks={props.callbacks} />
      ) : (
        null
      )}
    </div>
  )
}

const styles = {
  container: { width: '100vw', height: '100vh', display: 'flex', flex: 1},
}

export default App

In the return statement, we render the AgoraUIKit component with the rtcProps and callbacks object. (Unmounting the AgoraUIKit component performs the required cleanup automatically.)

The UIKit component also accepts a third prop, called styleProps, which can be used to customize the look of the application by writing React styling. You can override the default styles for each piece of the UIKit (such as buttons, videos, and containers) with your own.

What About Live Streaming?

We have a video conferencing website ready to ship. But let’s now take a look at how to convert this to a live streaming app where the users can join either as a host or an audience member. Hosts can share their audio and video to everyone in the channel, while audience members can only receive video and audio from other hosts:

...
import AgoraUIKit, { PropsInterface, layout } from 'agora-react-uikit'

const App: React.FunctionComponent = () => {
  const [videocall, setVideocall] = useState(true)
  const [isHost, setHost] = useState(false)
  const [isPinned, setPinned] = useState(false)
...

Let’s add two new state variables: isHost and isPinned. The isHost variable will track whether the user is a host or audience, and the isPinned variable is used to switch between the two prebuilt layouts:

...
  const props: PropsInterface = {
    rtcProps: {
      appId: '<Your Agora App ID>',
      channel: 'test',
      role: isHost ? 'host' : 'audience',
      layout: isPinned ? layout.pin : layout.grid,
    },
    callbacks: {
      EndCall: () => setVideocall(false)
    },
    styleProps: {
      localBtnContainer: {backgroundColor: 'blueviolet'}
    }
  }
...

We can use our state to define our rtcProps. We added the role prop to the rtcProps switch between host and audience (by default the role is host). The UIKit props are dynamic. If you update the state that’s passed as a prop, the UIKit will react to it (like the standard React design pattern). We’re changing the background color of the bottom bar using styleProps so that we can see how that works as well:

...
return (
    <div style={styles.container}>
        {videocall ? (<>
          <div style={styles.nav}>
            <p style={{ fontSize: 20, width: 200 }}>You're {isHost ? 'a host' : 'an audience'}</p>
            <p style={styles.btn} onClick={() => setRole(!isHost)}>Change Role</p>
            <p style={styles.btn} onClick={() => setPinned(!isPinned)}>Change Layout</p>
          </div>
          <AgoraUIKit
            rtcProps={props.rtcProps}
            callbacks={props.callbacks}
            styleProps={props.styleProps} /></>
        ) : (
          <h3 style={styles.btn} onClick={() => setVideocall(true)}>Start Call</h3>
        )}
      </div>
    </div>
  )
}
...

We’ll update our UI to add buttons that toggle our state. We’ll also add the styleProps to the UIKit. Instead of returning null when our video call state is false, let’s add an

tag to start the call once the call has ended by updating our state.

Here’s the updated styling if you want to follow along:

...
const styles = {
  container: { width: '100vw', height: '100vh', display: 'flex', flex: 1, backgroundColor: '#007bff22'},
  heading: { textAlign: 'center' as const, marginBottom: 0 },
  videoContainer: { display: 'flex', flexDirection: 'column', flex: 1 } as React.CSSProperties,
  nav: { display: 'flex', justifyContent: 'space-around' },
  btn: { backgroundColor: '#007bff', cursor: 'pointer', borderRadius: 5, padding: 5, color: '#ffffff', fontSize: 20 },
}

export default App

Customizing Functionality with RtcProps

The RtcProps object lets you customize how the UIKit works. You can select features and layouts. And there’s a growing list of things to customize using RtcProps. The object type definition can be found here.

Token Management

If you’re using the Agora Web UIKit in production, we strongly recommend using tokens to secure your app. There are two ways to use them: You can supply a token manually to the UIKit with the token property if you already have a token server set up.

If you don’t have a token server, you can use the tokenUrl property. This can be used to automatically fetch a new access token for the channel and renew it if it is going to expire soon. The functionality for requesting a new token expects the token to follow the URL scheme in the prebuilt Golang token server found on GitHub: AgoraIO-Community/agora-token-service. You can deploy it in two clicks to Heroku using this link.

Using the Web UIKit Without React

The Agora Web UIKit is also available as a web component to be used with websites built with vanilla JavaScript or a framework like Angular, Vue, or Avelte. To add video calling to your website, just import the web component as a script. You can then use the web component in your DOM by passing in your Agora App ID and channel name:

...
  <body>
    <script src="agora-uikit.js"></script>
    <agora-react-web-uikit
      style="width: 100%; height: 100vh; display: flex;"
      appId=''
      channel='test'
    />
    <script>
      // select web component
      const el = document.querySelector('agora-react-web-uikit');

      // alternatively you can do this to pass props
      // el.appId = '<Your App ID>'

      // Add event listener and subscribe to custom event
      el.addEventListener('agoraUIKitEndcall', (e) => {
        console.log('hello from html')
        // handle endcall event
        el.remove();
      });
    </script>
...

You can access the web component element in JS and update object properties. This lets you programmatically update props, which can be useful in building your buttons to update the user role in a live stream, for example. You can add event listeners for the end call button to handle what happens when the user clicks that button. We’re looking forward to your feedback, you can open a feature request for us to add more RTC events to the web component release.

There are a few limitations with web components for now. Everything we’ve talked about so far is supported, but the next section is React-specific. We’ll keep adding features and supporting this version of the UIKit alongside the react release, based on your feedback.

Advanced: Recomposing the UIKit

If you need finer control or want to build a custom layout for your application that the AgoraUIKit component doesn’t support yet, you can extract and use individual components that make up the UIKit and recompose them together to build your own custom solution without worrying about managing the SDK.

The UIKit isn’t limited to using the AgoraUIKit component. It’s a high-level component made up of several other modular components, which makes it easy to get started. You can import and use the individual pieces to compose your app.

RtcConfigure

The RtcConfigure component contains all the logic for the video call. It handles all the SDK events and maintains the state for the application. You can wrap the other UIKit components inside the RtcConfigure component to get access to user objects.

It also sets the RtcContext, which can be used to access the Web SDK client object and mediaStore which contains the remote tracks and the local tracks (as well as the dispatch function to mutate the state).

TracksConfigure

The TrackConfigure component handles creating audio and video tracks for the app.

Controls

The UIKit exports a LocalControls component that wraps LocalAudioMute, LocalVideoMute, and EndCall button components. The library has a RemoteAudioMute, a RemoteVideoMute, and a SwapUser (swaps the user with the maxUser) buttons. These components accept the user object as a prop.

Note: The remote controls mute the remote user’s audio and video only locally. The change isn’t reflected for anyone else on the call.

Video Views

To render the video of a user, we have two components: MaxVideoView and MinVideoView. Both require a user object as a prop. The user data is divided into two different arrays: MaxUser and MinUser. The MaxUser array always contains only one user; the other users are contained in the MinUser array. In the case of a pinned layout, we can use one array to render the big view and the other to render the video list. You don’t have to interact with the state directly. For example, if you want to swap a user, you can use the SwapUser button, which will internally mutate the state.

We also have the gridLayout and pinnedLayout components available if you don’t want to build your own layout using the views.

Props Context

PropsContext uses the React Context API, which gives you access to the provider and consumer components. Together, these let you access the props that we pass to this component elsewhere in the component tree. The library uses this to pass rtcProps, styleProps, and callbacks around the component tree.

User Contexts

The MaxUidContext gives you access to an array containing an object for the user in the MaxView (main view in the floating layout). The MinUidContext gives you access to an array of objects for the users in the MinView (top floating view in the floating layout). The LocalUserContext gives you access to the local user’s state.

Example of Recomposing

Let’s see all these components in action by building our own high-level component. The following example omits trivial details for clarity and ease of explanation (like defining props and styles). You can look at the AgoraUIKit component if you need more information.

import React, { useContext } from 'react'
import RtcConfigure from './RTCConfigure'
import PropsContext, { PropsProvider, PropsInterface } from './PropsContext'
import LocalControls from './Controls/LocalControls'
import TracksConfigure from './TracksConfigure'
import { MaxUidContext, MaxVideoView, MinUidContext } from './'
import RtcContext from './RtcContext'

const AgoraUIKit: React.FC<PropsInterface> = () => {
  const rtcProps = {
    // define your props
  }

  return (
    <PropsProvider value={rtcProps}>
      {rtcProps.role === 'audience' ? (
        <VideocallUI />
      ) : (
        <TracksConfigure>
          <VideocallUI />
        </TracksConfigure>
      )}
    </PropsProvider>
  )
}

const VideocallUI = () => {
  const { rtcProps } = useContext(PropsContext)

  return (
    <RtcConfigure callActive={rtcProps.callActive}>
      <RenderVideos />
      <LocalControls />
    </RtcConfigure>
  )
}

const RenderVideos = () => {
  const max = useContext(MaxUidContext)
  const min = useContext(MinUidContext)
  const users = [...max, ...min]

  // you can access the Web SDK client and tracks here
  const { client, localVideoTrack } = useContext(RtcContext)
  console.log(client.getRTCStats())
  console.log(localVideoTrack?.getCurrentFrameData())

  return (
    <div>
      {users.map((user) => (
        <MaxVideoView user={user} key={user.uid} />
      ))}
    </div>
  )
}

export default AgoraUIKit

We wrap our application in to give the other components access to the props. If the user is a host, we wrap the in the component that creates and passes along the microphone and camera tracks.

The is wrapped by , which contains all the logic for our video call or live stream and also sets up the local or remote user state. We render the control bottom bar using next to the component that accesses the user contexts and renders the videos using the component mapping over each user.

You can find an example here that shows how to add RTMP streaming to the Web UIKit.

Conclusion

We’re looking forward to your contributions. If you have a feature request, please open a pull request. If you find a bug, please report it on GitHub issues. We also have similar UIKits for Android, iOS, React Native, and Flutter, so be sure to check those out as well.

If you have questions while using the Web UIKit, I invite you to join the Agora Developer Slack community, where you can ask them in the #web-help-me channel. Feel free to open issues for feature requests or to report bugs on the GitHub Repo. Or you can reach out to me on Twitter.

Dynamic Channels for Video Chat Using Agora RTM on React Native

Ekaansh Arora — Fri, 10 Dec 2021 16:25:39 +0000

The Agora RTC (Real-time Communication) SDK makes it easy to build video chat apps on React Native. We can have multiple users communicate with each other by using the same channel name for our video chat room.

If you’re building a social video chat app, you might want to let your users generate rooms that other users can browse, join, and communicate in. You can do this with a back-end server to handle these requests and update other users with information about created rooms, but that would involve writing back-end code and hosting your own server.

In this tutorial, we’re going to see an alternative way of achieving the same goal by using the Agora RTM (Real-time Messaging) SDK. We’ll use messages sent by users to communicate the creation and updating of dynamic video chat rooms, all with front-end code.

This can be handy because when you don’t want to build a back-end server, you can use messages to update other users on the status of the rooms. This approach can be easily extended to having fully managed rooms as well as features like admin admit/deny a user, mute another user, and remove a user from the room.

We’ll be using the Agora RTC SDK and Agora RTM SDK for React Native in this example. I’m using v3.2.2 of the RTC SDK and v1.2.2-alpha.3 of the RTM SDK at the time of writing.

Project Overview

We have an RTM room called ‘lobby’. We’ll use it to signal users when someone creates a new room or when the members in a room change.
The way we’ll do this is by having the most senior member in the video chat room send messages to others. The oldest member in the room is considered the senior member, more on this later.
We’ll send messages in the form of ‘roomName:memberCount’ which can be processed by other users to store the room name and member count as a dictionary in their application state. We’ll use it to render a list of rooms with the number of members in it.
Once we have the list, we can join the room by using the RTC SDK. We’ll also need to listen for users joining and leaving to update the member count for everyone else. This is done only by the senior member to avoid overhead.
We also need to consider two cases to update room information for other users. First, when a new user joins the lobby, the senior-most member in each channel sends the user a peer message. Second, when a channel’s member count is updated we send a channel message to all users connected to the lobby to update their room list.

Creating an Agora account

Navigate to the Project List tab under the Project Management tab, and create a project by clicking the blue Create button. (When prompted to use App ID + Certificate, select only App ID.) The App ID will be used to authorize your requests while you’re developing the application, without generating tokens. Copy the App ID someplace safe, we’ll need it in a bit.

Note: This guide does not implement token authentication, which is recommended for all RTE apps running in production environments. For more information about token-based authentication in the Agora platform, see https://docs.agora.io/en/Video/token?platform=All%20Platforms.

Download the Source

You can jump to the code if you like. The code is open source and available on GitHub. To try it out for yourself, see the readme for steps on how to run the app.

Structure of our example

This is the structure of the application that we are building:

**.**  
├── android  
├── components  
│ └── **Permission.ts**  
│ └── **Style.ts**  
├── ios  
├── **App.tsx  
.**

App.tsx

App.tsx will be the entry point into the app. We’ll have all our code in this file.

We start by writing the import statements. Next, we define an interface for our application state containing the following:

**appId**: our Agora App ID
**token**: token generated to join the channel
**inCall**: boolean to store if we’re in an active video chat room
**inLobby**: boolean to store if we’re in the lobby
**input**: string to store input when creating a new room
**peerIdsRTC**: array to store the RTC UIDs of other users in the video chat room
**seniors**: array storing RTM members who have joined the video chat room before us
**myUsername**: local user’s name to log in to RTM
**rooms**: dictionary to store room names and their member count

We define a class-based component: the _rtcEngine variable will store the instance of the RtcEngine class, and the _rtmEngine variable will store the instance of the RtmEngine class, which we can use to access the SDK functions.

In the constructor, we set our state variables and request permission for recording audio on Android. (We use a helper function from permission.ts as described below.) When the component is mounted, we call the initRTC and initRTM functions, which initialize the RTC and RTM engines using the App ID. When the component unmounts, we destroy our engine instances.

RTC Initialization

We use the App ID to create our engine instance. We use the enableVideo method to set the SDK in video mode.

The RTC triggers a userJoined event for each user present when we join the channel and for each new user who joins later. The userOffline event is triggered when a user leaves the channel. We use event listeners to keep our peerIds array updated with UIDs. We will use this array later to render the video feeds from other users.

Once we’ve joined a channel, the SDK triggers the JoinChannelSuccess event. We set our state variable inCall as true to render the video chat UI.

When a new user joins our video chat room, if we’re the senior member as discussed before, we send a channel message with the updated user count to all members across channels using the lobby RTM channel.

RTM Initialization

We’re using RTM to send our room name and member count. We maintain an array of seniors, that is, members who have joined the call before us. If the seniors array size is <2, it means we’re the senior-most member, responsible for the signaling. (The local user is also part of the array.)

First, we attach the channelMemberJoined and channelMemberLeft listeners, which are triggered when a user joins or leaves the RTM channel. When a user joins the lobby channel, if we’re the senior-most member we send them a peer message. If a user leaves the current video chat channel, we update the seniors array (removing them from it if they had arrived before us). We also send a channel message to the lobby if we are the senior member updating the count.

Next, we attach the channelMessageReceived and messageReceived event listeners, which are triggered when we receive a channel message and a peer message, respectively. We split the channelName:memberCount string (for example, ‘helloWorld:5’) and use the two pieces of data to update our dictionary. (for example, rooms: { ‘helloWorld’: 5, ‘roomTwo’: 3 }).

Join a Call

We define a function to join the call that takes in the channel name as an argument. We update the state with the channel name and join the channel on both RTM and RTC, using the joinChannel methods.

We use the getChannelMembersBychannelId method on RTM to get the UIDs of the users on the channel. If we’re the only member, we send a channel message to the lobby channel on RTM to update everyone about the created room.

Leaving the Call

We leave the RTM and RTC video chat room channels but stay connected to the lobby channel on RTM to keep receiving updates. We update our state by clearing the peerIds array, the seniors array, and the channelName. We also set inCall as false and inLobby as true to render the lobby UI.

Rendering Our UI

We define the render function for displaying buttons to display the status if we’re in a call or the lobby.

We use the _renderRooms function to render a scroll view, which iterates over the rooms dictionary to show a list of created rooms with their member count. The user can tap any room to join it, which calls the joinCall function. We also render a text input to let the user create a room that calls the same joinCall function with that input.

We use the _renderCall function to render the videos once we’re connected to a video chat room. We use the RtcLocalView component from the SDK to render our own (local user’s) video. We use RtcRemoteView inside a scroll view to render the videos of connected users using the UIDs stored in the peerIds array. We also display a button to leave the room.

Permission.ts

We’re exporting a helper function to request microphone permissions from the Android OS.

Style.ts

The Style.ts file contains the styling for the components.

What’s next?

The same technique can be used to communicate other information, such as names of users connected, room description, and room title. We can even use the same mechanism to kick users off the call by sending an RTM message that, when evaluated, calls the leave channel method on the remote user’s device.

Conclusion

You’ve seen how we can leverage the Agora RTM SDK to share information and dynamically create video chat rooms. You can refer to the Agora React Native API Reference for methods that can help you quickly add more features to your next real-time engagement application.

Building a React Native Live Video Broadcasting App using Agora

Ekaansh Arora — Tue, 02 Nov 2021 07:55:16 +0000

Live video broadcasting has seen a range of uses from live shopping to live concerts. There are a lot of aspects to building a scalable, high-quality, live video streaming app. For example, maintaining low latency, load balancing, and managing thousands of users in the audience can be stressful while also maintaining cross-platform compatibility.

There’s a really easy way to make this happen using the Agora React Native SDK. In this article, we’ll build a live broadcasting app that can have multiple broadcasters and host thousands of users by using the magic of the Agora Video SDK. We’ll go over the structure, setup, and execution of the app before diving into how it works. You can get a live broadcast going in a few simple steps within a matter of minutes.

We’ll be using the Agora RTC SDK for React Native for the example below. I’m using v3.4.6 at the time of writing.

Creating an Agora account

Create an account [https://sso.agora.io/en/signup?utm_source=medium&utm_medium=blog&utm_campaign=building-a-react-native-live-video-broadcasting-app-using-agora) and log in to the dashboard. You can follow this guide for reference: https://www.agora.io/en/blog/how-to-get-started-with-agora

Navigate to the Project List tab under the Project Management tab, and create a new project by clicking the blue Create button.
Create a new project and retrieve the App ID. If you select App ID with a token, obtain a temporary token as well for your project. You can find a link to generate temporary tokens on the edit page. The temporary token will be used to authorize your requests while you’re developing the application.

Note: Token authentication is recommended for all RTE apps running in production environments. For more information about token-based authentication in the Agora platform, see this guide: https://docs.agora.io/en/Video/token?platform=All%20Platforms

Structure of our example

This is the structure of our application:

.
├── android
├── components
│ └── Permission.ts
│ └── Style.ts
├── ios
├── App.tsx
├── index.js
.

Let’s run the app

You’ll need to have the LTS version of Node.js and NPM installed.

Make sure you’ve registered an Agora account, set up a project, and generated an App ID (and temporary token).
Download and extract the ZIP file from the master branch.
Run npm install to install the app dependencies in the unzipped directory.
Navigate to ./App.tsx and enter the App ID that we obtained from the Agora Console (appId: ‘<YourAppIDHere>’). If you’re using tokens, enter your token and channel name as well.
If you’re building for iOS, open a terminal and execute cd ios && pod install. You can then open ios/<projectName>.xcworkspace file to open your project in XCode and build the app. (The iOS simulator does not support the camera. Use a physical device instead.)
If you’re building for Android connect your device and execute npm run android to start the app. Wait for a few minutes for the app to build.
Once you see the home screen on your mobile or emulator, click the Start Call button on the device.

That’s it. You should have a video call going between the two devices. The app uses test as the channel name.

Getting to how it works

Permission.ts

We’re exporting a function to request camera and microphone permissions from the OS on Android.

App.tsx

The App.tsx file contains the core logic of our video call.

We start by writing the import statements. Next, we have some constants for our App ID, token, and channel name.

We define an interface for our application state containing isHost (a Boolean value to switch between audience and broadcaster; a host can both send and receive streams, whereas an audience can only receive streams), joinSucceed (a Boolean value to store if we’ve connected successfully), and peerIds (an array to store the UIDs of other users in the channel).

We define a class-based component, the _engine variable, which will store the instance of the RtcEngine class, which provides methods that can be invoked by our application to manage the live stream.

In the constructor, we set our state variables and request permission for the camera and the mic on Android. When the component is mounted, we call the init function, which initializes the RTC engine using the App ID. It also enables the video by calling the enableVideo method on our engine instance.

We set channelProfile as Live Broadcasting and clientRole based on our isHost state variable value.
The init function also adds event listeners for various events in the live broadcast. For example, the UserJoined event gives us the UID of a user when they join the channel. We store this UID in our state.

(If there are users connected to the channel before we joined, a UserJoined event is fired for each user after they successfully join the channel.)

Next, we have the function toggleRole, which changes roles between audience and broadcaster. We have startCall and endCall to start and end the call. The toggleRole function updates the state and calls the setClientRole function with a role argument based on the state. The joinChannel method takes in a token, channel name, optional info, and an optional UID. (If you set UID to 0, the SDK automatically assigns a UID.)

We define the render function for displaying buttons to start and end the call and to display our local video feed as well as the remote users’ video feeds. We define the _renderVideos function, which renders our video feeds.

To display the local user’s video feed, we use the component, which takes in channelId and renderMode (which can be used to fit the video inside a view or zoom to fill the view) as props. To display the remote user’s video feed, we use the component from the SDK, which takes in the UID of the remote user along with channelId and renderMode. We map over the Remote users’ UIDs to display a video for each, using the peerIDs array.

Style.ts

The Style.ts file contains the styling for the components.

Conclusion

That’s how easy it is to build a live video broadcasting app. You can refer to the Agora React Native API Reference to see methods that can help you quickly add features like muting the camera and mic, setting video profiles, audio mixing, and much more.

If you’re deploying your app to production, you can read more about how to use tokens in this blog.

I invite you to join the Agora Developer Slack community. Feel free to ask any React Native questions in the #react-native-help-me channel.

Connecting to Multiple Channels with Agora on React-Native

Ekaansh Arora — Mon, 18 Oct 2021 11:33:57 +0000

Since the release of v3.0.0 of Agora’s SDK for React-Native users can now join an unlimited number of channels at the same time. But you can publish your own camera feed to only one channel at a time.

This ability can be really handy in the case of multiple breakout rooms, where you can both send and receive video from a primary room while also receiving videos from secondary rooms.

We’ll be using the Agora RTC SDK for React Native for our example.

Before diving into how it works, let’s look at a few key points

We’ll use the SDK to connect to the first channel and join a video call normally. We’ll be streaming our video as well as receiving video from other users on the channel.
Next, we’ll join a second channel to receive video streams from all the users on that channel. Note that users on channel 2 will not be able to receive our video.
The two channels are separate: users on channel 1 and channel 2 don’t see each other. We can extend this functionality to join as many channels as required.

Structure of our example

This is the structure of the application:

.
├── android  
├── components  
│ └── Permission.ts
│ └── Style.ts  
├── ios  
├── App.tsx  
.

Download the source

If you want to jump to the code and try it out for yourself, you can look at the readme for steps on how to run the app. The code is open source and available on GitHub. The app uses channel-1 and channel-2 as the channel names.

When you run the app, you’ll see two buttons: one to join and one to end the call. When you click start call, you should see your video in the top row, which contains videos from channel 1. The bottom row contains videos from channel 2.

Note: This guide does not implement token authentication which is recommended for all RTE apps running in production environments. For more information about token based authentication within the Agora platform please refer to this guide: https://docs.agora.io/en/Video/token?platform=All%20Platforms

How the App Works

App.tsx

App.tsx will be the entry point into the app. We’ll have all our code in this file:

We start by writing the import statements. Next, we define an interface for our application state containing the following:

appId: Our Agora App ID
token: Token generated to join the channel
channelNameOne: Name for channel 1
channelNameTwo: Name for channel 2
joinSucceed: Boolean value to store if we’ve connected successfully
peerIdsOne: Array to store the UIDs of other users in channel 1
peerIdsTwo: Array to store the UIDs of other users in channel 2

We define a class-based component: the _rtcEngine variable will store the instance of the RtcEngine class, and the _channel variable will store the instance of the RtcChannel class, which we can use to access the SDK functions.

In the constructor, we set our state variables and request permission for recording audio on Android. (We use a helper function from permission.ts, as described below.) When the component is mounted, we call the init function, which initializes the RTC engine and RTC channel. When the component unmounts, we destroy our engine and channel instances.

RTC initialization

We use the App ID to create our engine instance. The engine instance will be used to connect to channel 1, where we both send and receive the video. We also create our channel instance using the name of our second channel. The channel instance will be used only to receive videos from channel 2.

The RTC triggers a userJoined event for each user present when we join the channel and for each new user who joins after. The userOffline event is triggered when a user leaves the channel. We use event listeners on _engine and _channel to store and maintain our peerIdsOne and peerIdsTwo arrays containing the UIDs for users on both the channels.

We also attach a listener for joinChannelSuccess to update our state variable which is used to render our UI while we’re in the call.

Functions for our buttons

The startCall function joins both the channels using the joinChannel method.

The endCall function leaves both the channels using the leaveChannel method and updates the state.

The destroy function destroys the instances of our engine and channel.

Rendering our UI

We define the render function for displaying buttons to start and end the call and to display user videos from both channels.

We define a _renderVideos function to render the videos from both our channels using the _renderRemoteVideosOne and _renderRemoteVideosTwo functions for channel 1 and channel 2. Each function contains scrollViews to hold videos from the channel. We use the UIDs stored in peerId arrays to render remote users’ videos by passing them to the RtcRemoteView.SurfaceView component.

Permission.ts

We’re exporting a helper function to request microphone permissions from the Android OS.

Style.ts

The Style.ts file contains the styling for the components.

Conclusion

That’s how we can build a video call app that can connect to two channels simultaneously. You can refer to the Agora React Native API Reference to see methods that can help you quickly add many features like muting the mic, setting audio profiles and audio mixing.

Building a Live Audio Streaming React Native App with Agora

Ekaansh Arora — Tue, 12 Oct 2021 09:36:55 +0000

Live audio streaming is increasingly popular across a wide range of uses, from live podcasts and interviews to live music performances. The possibilities are endless once you have a few users engaging with an audience in real-time.

There’s an easy way to accomplish live audio streaming using the Agora React Native SDK. In this tutorial, we’ll walk through building a live audio broadcasting app that can have multiple broadcasters and host thousands of users by utilizing the Agora Audio SDK. We’ll go over the structure, setup, and execution of the app before diving into the code. The open-source code is available here

We’ll be using Agora RTC SDK for React Native for the example. I’m using v3.2.2 at the time of writing.

Creating an Agora Account

Sign up at https://console.agora.io/ and log in to the dashboard.

Navigate to the Project List tab under the Project Management tab and create a project by clicking the blue Create button.

Create a project and retrieve the App ID. (When prompted to use App ID + Certificate, select only App ID.) The App ID will be used to authorize your requests while you’re developing the application, without generating tokens.

Note: This guide does not implement token authentication which is recommended for all RTE apps running in production environments. For more information about token-based authentication within the Agora platform please refer to this guide: https://docs.agora.io/en/Video/token?platform=All%20Platforms

Structure of Our Example

This is the structure of the application:

.
├── android
├── components
│ └── Permission.ts
│ └── Style.ts
├── ios
├── App.tsx
├── index.js
.

Running the App

You’ll need to have a recent version of Node.js and NPM installed;

Make sure you’ve set up an Agora account, set up a project, and generated an App ID (as discussed above).
Download and extract the ZIP file from the master branch.
Run npm install to install the app dependencies in the unzipped directory.
Navigate to ./App.tsx and enter the App ID as appId: YourAppIdHere in the state declaration.
If you’re building for iOS, open a terminal and execute cd ios && pod install.
Connect your device, and run npx react-native run-android / npx react-native run-ios to start the app. Give it a few minutes to build the app and install it on your device.
Once you see the home screen on your mobile device (or emulator), click the start call button on the device.

That’s it. You should have an audio broadcast going between the two devices.

The app uses channel-x as the channel name.

Before we dive into the code, let’s get a few basics out of the way:

We’ll use the Agora RTC (Real-time Communication) SDK to connect to a channel and join an audio call.
We can have multiple users broadcasting to a channel. All users as an audience on that channel can listen to the broadcasters.
The audience can dynamically switch to a broadcaster role.
The Agora RTC SDK uses unique IDs (UIDs) for each user. To associate these UIDs with a username, we’ll use the Agora RTM (Real-time Messaging) SDK to signal the username to others on the call. We’ll discuss how it’s done below. Let’s take a look at how the code works:

App.tsx

App.tsx will be the entry point into the app. We’ll have all our code in this file. When you open the app, there will be a username field with three buttons: to join the call, end the call, and toggle our user role between broadcaster and audience.

We start by writing the used import statements. Next, we define an interface for our application state containing the following:
appId: our Agora App ID
token: token generated to join the channel
isHost: boolean value to switch between audience and broadcaster
channelName: name for the channel
joinSucceed: boolean value to store if we’ve connected successfully
rtcUid: local user’s UID on joining the RTC channel
myUsername: local user’s name to log in to RTM
usernames: a dictionary associating RTC UIDs of remote users to their usernames that we’ll get using RTM
peerIds: an array to store the UIDs of other users in the channel

We define a class-based component: the _rtcEngine variable will store the instance of the RtcEngine class, and the _rtmEngine variable will store the instance of the RtmEngine class, which we can use to access the SDK functions.

In the constructor, we set our state variables and request permission for recording audio on Android. (We use a helper function from permission.ts, as described below.) When the component is mounted, we call the initRTC and initRTM functions, which initialize the RTC and RTM engines using the App ID. When the component unmounts, we destroy our engine instances.

RTC Initialization

We use the App ID to create our engine instance. Next, we set channelProfile to Live Broadcasting and clientRole based on our isHost state variable value.

Note: Audience members don’t trigger the userJoined/userOffline event.

RTM Initialization

We’re using RTM to send our username to other usernames on the call. And this is how we associate our usernames with our RTC UID

When a user joins a channel, we send a message to all channel members as UID:Username.
On receiving a channel message, all users add the key-value pair to their username dictionary.
When a new user joins, all members on the channel send a peer message to that user in the same schema UID:Username.
On receiving peer messages, we do the same (add the key-value pair to the dictionary) and update our usernames.

Following our plan, we attach event listeners with functions to populate and update usernames on channelMessageReceived (broadcast message to channel), messageReceived (peer message), and channelMemberJoined events. We also create a client on the engine using the same App ID.

Functions for Our Buttons

The toggleRole function updates the state and calls the setClientRole function with the correct argument based on the state.
The startCall function checks if a username is entered. It then joins the RTC channel. It also logs in to RTM, joins the channel, and sends the channel message for the username, as we discussed before.
The endCall function leaves the RTC channel, sends a message that is used to remove the username from our remote users dictionary, and then leaves and logs out of RTM.

Rendering Our UI

We define the render function for displaying buttons to start and end the call as well as to toggle roles. We define a function _renderUsers that renders a list of all broadcasters and audience members.

Permission.ts

We’re exporting a helper function to request microphone permissions from the Android OS.

Style.ts

The Style.ts file contains the styling for the components.

Conclusion

That’s how easy it is to build a live audio streaming app. For more information about building applications using Agora SDKs, take a look at the Agora Video Call Quickstart Guide and Agora API Reference.

I invite you to join the Agora Developer Slack community. You can ask any questions about Agora in the #react-native-help-me channel.

React Native: Streaming Agora Cloud-Recording HLS Videos from an S3 Bucket

Ekaansh Arora — Mon, 11 Oct 2021 10:03:34 +0000

In a previous blog post, we looked at how to add Agora cloud recording to a video chat application for storing the recordings in an Amazon S3 bucket. Here, we’ll go over how to fetch and playback the recorded videos in a React Native application.

We’ve updated the app and the back end from the last blog post to bring everything together. If you just want the demo, you can deploy the back end and build the app from the links provided.

Prerequisites

An Agora developer account (see How to Get Started)
An Amazon AWS account
A Heroku account or another service to deploy the back end
Understanding of React Native

Agora Setup

Create a project: Once you have an Agora account, click the Project Management tab in the console. Click the Create button. Enter a name for your project. Select Secured Mode while creating the project.
Enable cloud recording: Click the View usage button and select the option to enable cloud recording.
Get app credentials: Copy the App ID and the App Certificate from the same page to a text file. We’ll use these later.
Get customer credentials: Visit the RESTful API page and click the Add Secret button. Copy the Customer ID and the Customer Secret to a text file.

AWS Setup

Once you’ve created an AWS account, we need to create an Amazon S3 bucket to store our video recordings and an IAM user to access our bucket. If you have already completed this setup, you can skip this section.

Go to your AWS IAM Console and create a user. Add the AmazonS3FullAccess policy with Programmatic Access. Copy your AWS Access Key and Secret Key to the text file.
Create an Amazon S3 bucket: Choose a name for your bucket and copy it to a text file. We’ll use this text file later. Allow public access to stream media from your bucket by deselecting the block all public access check box. Click the Create Bucket button.

Note: With the URL for your recording, anyone on the internet can view it. We’ll discuss how to make the recording secure at the end of the post.

We’ll also need the region number for the selected AWS region. Go to this table, click the Amazon S3 tab, and note your region number. For example, if you’re using the US_EAST_1 region, your bucket number is 0.

Add the bucket policy. To make files accessible by all users, we’ll add a bucket policy. Go to the Permissions tab in your newly created bucket and add this policy:

{
    "Version": "2012-10-17",
    "Id": "Policy1620917655085",
    "Statement": [
        {
            "Sid": "Stmt1620917653925",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::agora-rec123/*"
        }
    ]
}

Deploying Our Back End

Before deploying our back end, we need the following variables. (It’s time to use our text file.) We’ll be using the Heroku one-click deploy to make it super simple to get our back end up and running. You can use any other service as well.

Note: We’ve updated the back end, so if you’re using the back end from the previous post, you should update it now.

APP_ID=
APP_CERTIFICATE=
RECORDING_VENDOR=
RECORDING_REGION=
BUCKET_NAME=
BUCKET_ACCESS_KEY=
BUCKET_ACCESS_SECRET=
CUSTOMER_ID=
CUSTOMER_CERTIFICATE=

Note: RECORDING_VENDOR=1 for AWS. Click this link for more information.

Create an account on Heroku if you haven’t done so already.
Click this link to use the Heroku one-click deploy.
Enter your variables and click the Deploy App button at the bottom of the page.
Wait a few minutes. Once the deployment is complete, save your back-end URL in a text file, which we’ll use in the app.

Building Our App

We’ll start from the app we developed in the last post, which lets you take part in group video calls and record them. I’ve refactored the app to move all the video call and recording components to ./components/Call.tsx. We’ll start with a new file: ./components/PlayRecording.tsx

We’ll use the Video component from react-native-video for HLS playback. We take in the back-end URL, App ID, and channel name as props to our PlayRecording component. We define an interface for our state. tracks will contain an array of URLs for each m3u8 file. currentTrack is the index of the URL we’re playing. statusMsg holds a string to display the current status of the video player.

We define our component and our initial state. In the componentDidMount we perform a GET request to the /api/get/recordingUrls/<ChannelName> route of our back-end server. We get the response JSON and update the tracks state array.

In our render method, we’re returning a list of tracks wrapped in TouchableOpacity using a ScrollView. When a track is selected, we update the currentTrack state with the track index.

We use the Video component with the source set as the URL we want to play (currentTrack index of our tracks array). We have event handlers to update our statusMsg. We also display the statusMsg in a Text component.

Putting it back together

We use the PlayRecording component in our App.tsx along with the Call component to put everything back together.

Security Consideration: As we discussed, with our current configuration all the recordings stored on the S3 bucket are public so that the React Native client can access them. Before we use the app in production, it’s important to set access control for our videos. Once we get our users authenticated, we can issue them access to the files, while keeping the files private for everyone else. You can find more information here and here.

Conclusion

You can find more information about cloud recording here. If you’re starting out with the Agora SDKs, take a look at the Agora Video Call Quickstart Guide and this blog post.

And I invite you to join the Agora Developer Slack community. Feel free to ask any React Native questions in the #react-native-help-me channel and cloud recording questions in the #cloud-recording-help-me channel.

Building a Video Calling App Using the Agora SDK on Expo (React Native)

Ekaansh Arora — Fri, 08 Oct 2021 07:16:40 +0000

With the release of Expo SDK 42, it’s now possible to customize the native runtime of your apps using custom development clients. It took me a while to wrap my head around all the new concepts, but I’m really excited!

Essentially, this means that we can now use libraries that contain native code (like Swift and Kotlin) with Expo without having to resort to the bare workflow (which would take away most of the Expo benefits and ease of use). The new experience is really easy to set up and start using. You can find more information in this official blog and the Expo docs.

What this isn’t:

You cannot use the Expo Go app for testing the code with native modules. This means you’ll need to build and distribute your app to anyone who wants to test it.
If you want to build for iOS without having access to a Mac, you’ll need to use EAS Build or an alternative cloud service.
This is going to be slightly more involved than the Expo JS-only experience. You’ll need to set up Android Studio and/or XCode.

Requirements

Installing Node.js and Git would depend on your operating system. To install Yarn and Expo, you can simply run npm i -g yarn expo-cli.

Create a new project

To create an Expo project, we’ll use the Expo CLI. Open a new terminal and execute expo init to bring up the CLI that will guide you through the process. Let’s leverage the typescript template by selecting the blank TS option.
You can run native platform code in React Native with the use of native modules. With the new release of Expo dev clients, it’s now possible to use native modules without leaving the managed workflow.
To make native modules (libraries that use native platform code) work with Expo, we’ll install the Expo dev client by running yarn add expo-dev-client in the project directory created by the Expo CLI.

Note: We can’t use the Expo Go app to run the project, because we’re bundling native code. We’ll get around this by building a custom client.

Installing native modules

Let’s install the native dependency: the Agora React Native SDK. In a terminal, execute yarn add react-native-agora. You don’t need any extra configuration for the Agora SDK. If your library requires modifying the native runtime, you can read more about how to write a custom plug-in here.

For the app demo, let’s install the Agora React Native UIKit.

AgoraIO-Community / ReactNative-UIKit

A React Native package to simply integrate Agora Video Calling or Live Video Streaming to your app with just a few lines of code.

It is a pure JavaScript library that helps us build a video calling app with ten lines of code. You can execute yarn add agora-rn-uikit to install it. It relies on the Agora React Native SDK for its functionality.

We can now start writing the app:

To get better errors and logs, I recommend adding import ‘expo-dev-client’; to the top of your App.tsx file.

To build a video calling app, all we need is the AgoraUIKit high-level component from the UIKit library. We can pass in the appId and channel to the RtcProps. We can use a state variable to render the call UI that we can update using the EndCall callback. The AgoraUIKit component is rendered when the videoCall state is true.

You can read more about how the UIKit works here.

Run your app

Now for the moment of truth: let’s try running the app. To build a custom client, we can execute expo run:android or expo run:ios in a terminal. If you’re building for iOS, use a physical device to test since camera functionality is not available in the iOS simulator. You will be prompted to select a bundle ID (a unique identifier for your app). You can enter a custom ID or use the prefilled option.

Note: If you’re building for iOS, you’ll need to add camera and microphone permissions text to your info.plist file using XCode:

Once that’s done, you’ll need to wait a couple of minutes for the CLI to build the custom client and install it on your device. You’ll see the project directory get populated with iOS and Android folders. You can now run the Expo dev server by executing expo start --dev-client in the project directory. Once the app loads, you can then scan the server QR code or select it from the list in the app. Your app should load from metro just like a normal React Native app.

Conclusion

The Expo SDK offers a lot of developer-friendly features on top of React Native. In the past, we’d use the bare workflow. If our app needed any native modules, however, it would take away some of the benefits. Plus, setting it up was a task. Using custom clients, we can leverage the power of Expo with the flexibility of native modules.

You can read my blog about the React Native UIKit here.

Other Resources

For more information about building applications using Agora SDKs, take a look at the Agora Video Call Quickstart Guide and Agora API Reference. You can also take a look at the UIKit GitHub Repo.
I invite you to join the Agora Developer Slack community. You can ask any questions about Agora in the #react-native-help-me channel.