Voice-only quickstart

This Unreal Blueprint quickstart shows you how to create a basic Voice Calling app using the Agora RTC SDK.

Understand the tech

To start a Voice Calling session, implement the following steps in your app:

• Initialize the Agora Engine: Before calling other APIs, create and initialize an Agora Engine instance.

• Join a channel: Call methods to create and join a channel.

• Send and receive audio: All users can publish streams to the channel and subscribe to audio streams published by other users in the channel.

Prerequisites

• Unreal Engine 4.27 or higher

• Prepare your development environment according to your target platform and engine version:

  Dev environment requirements	Other requirements
  Android	-
  iOS	A valid Apple developer signature.
  macOS	A valid Apple developer signature.
  Windows	32-bit Windows only supports Unreal Engine 4 and below. To use Unreal Engine with 32-bit Windows, uncomment the code relating to Win32 in the AgoraPluginLibrary.Build.cs file.

• Two physical devices for testing

• A microphone

• A valid Agora account and project. Please refer to Agora account management for details.

Set up your project

This section shows you how to set up your Unreal (Blueprint) project and install the Agora RTC SDK.

Install the SDK

Take the following steps to add the Unreal (Blueprint) RTC SDK to your project:

1. Download the latest version of Agora Unreal RTC SDK from Download SDKs and unzip it.
2. In your project root folder, create a Plugins folder.
3. Copy AgoraPlugin from the Unreal SDK folder to Plugins.

Implement Voice Calling

This section guides you through the implementation of basic real-time audio interaction in your game.

Create a level

1. In the Content folder of the Content Browser, right-click and select Level to create a Level Blueprint and name it BasicAudioCallScene.

2. Double-click BasicAudioCallScene and click Blueprints > Open Level Blueprint above the editor to open the level blueprint.

   

Implement basic processes

In the My Blueprint panel, double-click Graphs > EventGraph to open the event graph. You see two event nodes: Event BeginPlay (game starts) and Event End Play (game ends). Create event nodes with the corresponding functions and variables, and connect them as shown in the following figure to implement the Voice Calling logic:

The following table lists the main nodes:

#	Node	Type	Description
1	Set Show Mouse Cursor	Native*	(Optional) Set whether to display the mouse cursor. Check to display it. Information: This node is available on Windows and macOS only. If the node is not retrieved at creation time, uncheck Context Sensitive.
2	Load Agora Config	Custom**	Loads Agora configuration. Used to verify user identity when creating and joining channels.
3	Create BP Audio Widget	Native	Create user interface: Add Create Widget node. Select the node's Class as BP_AudioWidget and associate the node with the already created user interface.
4	Set Basic Audio Call Widget	Custom	Set up the user interface: Create the BasicAudioCallWidget variable and select the Variable Type of the variable as BP_AudioWidget, which is the user interface created to store a reference to the user interface in the blueprint. After dragging the created variables to EventGraph, two options, Set BasicAudioCallWidget and Get BasicAudioCallWidget, appear. Select Set BasicAudioCallWidget to create a node for accessing and setting the user interface.
5	BindUIEvent	Custom	Use Bind UI events to handle event logic after clicking the Join Channel and Leave Channel buttons.
6	Add to Viewport	Native	Add user interface to the viewport.
7	Check Permission	Custom	(Optional) Check whether you have obtained the system permissions required for real-time audio and video interaction, such as access to the camera and microphone. Note: If your target platform is Android, create this node to check system permissions.
8	Init Rtc Engine	Custom	Create and initialize the RTC engine.
9	Un Init Rtc Engine	Custom	Leave the channel and release resources.

* Native nodes are nodes that come with the blueprint and can be added and called directly.
** Custom nodes are not included in the blueprint. You create a custom function before you can add the corresponding node.

Add channel-related variables

Add variables to create an engine instance and join a channel.

1. Create three variables:

   Token, ChannelId, and AppId. Select the Variable Type as String.

2. In the Load Agora Config function, add the Sequence node, and then connect Set Token, Set Channel Id, and Set App Id respectively. Fill in the token, channel name, and app ID values obtained from Agora Console.

   

Initialize RTC engine

1. If your target platform is Android, check whether system permissions have been granted before initializing the RTC engine. Refer to the following figure to create nodes for adding permissions to access the microphone and camera in the CheckPermission function.

   

   If your target platform is macOS or iOS, please refer to How do I add the permissions needed for real-time interaction to my Unreal Engine project?

2. To initialize the RTC engine, in the InitRtcEngine function, create and connect nodes as shown in the following figure:

   

3. Create IRtcEngine and IRtcEngineEventHandler.

   1. To store references to the engine and event-handler interface classes, create RtcEngine and EventHandler variables, and set the Variable Type to Agora Rtc Engine and IRtc Engine Event Handler, respectively.

   2. Add two Construct Object From Class nodes, set Class to Agora Rtc Engine and IRtc Engine Event Handler respectively. Connect to Set Rtc Engine and Set Event Handler, respectively.

   3. Bind IRtcEngineEventHandler class-related callback functions.

   4. Create onJoinChannelSuccess, onLeaveChannel, onUserJoined, and onUserOffline callback functions. Refer to the following table to configure the input parameters of the callbacks:

      Callback	Description	Input parameters
      FOnJoinChannelSuccess	The local user successfully joined a channel.	channel: (String) Channel name. uid: (Integer64) The ID of the user joining the channel. elapsed: (Integer) The time (in milliseconds) that elapsed from the local call to JoinChannel till the occurrence of this event.
      FOnLeaveChannel	The local user left the channel.	stats: Call statistics.
      FOnUserJoined	A remote user joined the current channel.	uid: (Integer64) The user ID of the remote user joining the channel. elapsed: (Integer) The time (in milliseconds) that elapsed from the local call to JoinChannel till the occurrence of this event.
      FOnUserOffline	A remote user left the current channel.	uid: (Integer64) The ID of the user going offline. reason: Offline reason. For details, see EUSER_OFFLINE_REASON_TYPE.

   5. Create a Bind Event function. In this function, add a Sequence node, and then bind the onJoinChannelSuccess, onLeaveChannel, onUserJoined, and onUserOffline callback events.

      

   6. IRtcEngine initialization

   7. Call Initialize to initialize the RTC engine.

   8. Connect to the RtcEngineContext configuration IRtcEngine instance and select Channel Profile as CHANNEL_PROFILE_COMMUNICATION.

Bind UI events

To bind UI events:

1. Create and implement the OnJoinChannelClicked event callback.

   

   1. Call Enable Audio to enable the audio modules.
   2. Call Join Channel to join the channel.
   3. Set the following parameters in Make ChannelMediaOptions:
      • Set Publish Microphone Track to AGORA TRUE VALUE to publish the audio stream recorded by the microphone.
      • Set Auto Subscribe Video to AGORA TRUE VALUE to automatically subscribe to all video streams.
      • Check Client Role Type Set Value and set Client Role Type to CLIENT_ROLE_BROADCASTER or CLIENT_ROLE_AUDIENCE, to set the user role to host or audience.
      • Check Channel Profile Set Value and set Channel Profile to CHANNEL_PROFILE_COMMUNICATION.

2. Create and implement the OnLeaveChannelClicked event callback. When the event is triggered, call Leave Channel to leave the channel.

   

3. In the Bind UIEvent function, refer to the figure below to bind the OnJoinChannelClicked and OnLeaveChannelClicked callback functions to the Join Channel and Leave Channel buttons respectively. When the button is clicked, the corresponding event callback is triggered.

   

Implement callback function

Configure the previously created onJoinChannelSuccess, onLeaveChannel, onUserJoined, and onUserOffline callback functions as follows:

1. After the local user successfully joins the channel, the onJoinChannelSuccess callback is triggered and the local view is created. The uid is set to 0 by default, but it is assigned a random value by the SDK. The video source type is VIDEO_SOURCE_CAMERA_PRIMARY (first camera):

   

2. After the local user leaves the channel, the onLeaveChannel callback is triggered which releases the local view:

   

3. When a remote user joins the channel, the onUserJoined callback is triggeredd to create a remote view. uid is the uid sent from the remote end, and the video source type is VIDEO_SOURCE_REMOTE (remote video obtained from the network):

   

4. When a remote user leaves the channel, the onUserOffline callback is triggered to release the remote view:

   

Leave the channel and release resources

To leave the channel, implement the following steps:

1. Leave the channel.
2. Unregister Agora SDRTN® event callback.
3. Destroy IRtcEngineObject to release all resources used by Agora SDK.

Refer to the figure below to implement the UnInitRtcEngine function:

Test the sample code

Take the following steps to test the sample code:

1. In the Load Agora Config function, fill in the app ID, channel name, and temporary token for your project.

2. In the Unreal Editor, click Play to run your project. Click JoinChannel to join a channel.

3. Invite a friend to run the demo game on a second device. Use the same app ID, channel name, and token to join. After your friend joins successfully, you can hear and see each other.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

• If a firewall is deployed in your network environment, refer to Connect with Cloud Proxy to use Agora services normally.

Next steps

After implementing the quickstart sample, read the following documents to learn more:

• To ensure communication security in a test or production environment, best practice is to obtain and use a token from an authentication server. For details, see Secure authentication with tokens.

Sample project

Agora provides open source sample projects on GitHub for your reference. Download or view the JoinChannelVideo project for a more detailed example.

Frequently asked questions

• How can I listen for audience joining or leaving a channel?
• How can I fix black screen issues?
• Why can't I turn on the camera?
• How can I solve channel-related issues?
• How can I set the log file?

See also

• Error codes

• Connection status management