Quickstart

This Android quickstart shows you how to create a basic Voice Calling app using the Agora Voice SDK. Switch to the iOS or Web quickstart, or choose another platform from the selector.

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

• Android Studio 4.2 or higher.

• Android SDK API Level 21 or higher.

• Two mobile devices running Android 5.0 or higher.

• 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 Android project and install the Agora Voice SDK.

2. Add a layout file for your activity.

   Set up a basic layout for your activity. Refer to Create a user interface to get a bare bones sample layout.

Install the SDK

Use either of the following methods to add Voice SDK to your project.

Implement Voice Calling

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

The following figure illustrates the essential steps:

This guide includes complete sample code that demonstrates implementing basic real-time interaction. To understand the core API calls in the sample code, review the following implementation steps and use the code in your MainActivity file.

Import Agora classes

Import the relevant Agora classes and interfaces:

import io.agora.rtc2.Constants;
import io.agora.rtc2.IRtcEngineEventHandler;
import io.agora.rtc2.RtcEngine;
import io.agora.rtc2.RtcEngineConfig;
import io.agora.rtc2.ChannelMediaOptions;

import io.agora.rtc2.ChannelMediaOptions
import io.agora.rtc2.Constants
import io.agora.rtc2.IRtcEngineEventHandler
import io.agora.rtc2.RtcEngine
import io.agora.rtc2.RtcEngineConfig

Initialize the engine

For real-time communication, initialize an RtcEngine instance and set up event handlers to manage user interactions within the channel. Use RtcEngineConfig to specify the application context, App ID, and custom event handler, then call RtcEngine.create(config) to initialize the engine, enabling further channel operations. In your MainActivity file, add the following code:

// Fill in the app ID from Agora Console
private String myAppId = "<Your app ID>";
private RtcEngine mRtcEngine;

private void initializeAgoraVoiceSDK() {
  try {
    RtcEngineConfig config = new RtcEngineConfig();
    config.mContext = getBaseContext();
    config.mAppId = myAppId;
    config.mEventHandler = mRtcEventHandler;
    mRtcEngine = RtcEngine.create(config);
  } catch (Exception e) {
    throw new RuntimeException("Error initializing RTC engine: " + e.getMessage());
  }
}

// Fill in the App ID obtained from the Agora Console
private val myAppId = "<Your app ID>"
private var mRtcEngine: RtcEngine? = null

private fun initializeAgoraVoiceSDK() {
  try {
    val config = RtcEngineConfig().apply {
      mContext = baseContext
      mAppId = myAppId
      mEventHandler = mRtcEventHandler
    }
    mRtcEngine = RtcEngine.create(config)
  } catch (e: Exception) {
    throw RuntimeException("Error initializing RTC engine: ${e.message}")
  }
}

Join a channel

To join a channel, call joinChannel with the following parameters:

• Channel name: The name of the channel to join. Clients that pass the same channel name join the same channel. If a channel with the specified name does not exist, it is created when the first user joins.

• Authentication token: A dynamic key that authenticates a user when the client joins a channel. In a production environment, you obtain a token from a token server in your security infrastructure. For the purpose of this guide Generate a temporary token.

• User ID: A 32-bit signed integer that identifies a user in the channel. You can specify a unique user ID for each user yourself. If you set the user ID to 0 when joining a channel, the SDK generates a random number for the user ID and returns the value in the onJoinChannelSuccess callback.

• Channel media options: Configure ChannelMediaOptions to define publishing and subscription settings, optimize performance for your specific use-case, and set optional parameters.

For Voice Calling, set the channelProfile to CHANNEL_PROFILE_COMMUNICATION and the user role to CLIENT_ROLE_BROADCASTER.

// Fill in the channel name
private String channelName = "<Your channel name>";
// Fill in the temporary token generated from Agora Console
private String token = "<Your token>";

private void joinChannel() {
  ChannelMediaOptions options = new ChannelMediaOptions();
  options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER;
  options.channelProfile = Constants.CHANNEL_PROFILE_COMMUNICATION;
  options.publishCameraTrack = true;
  mRtcEngine.joinChannel(token, channelName, 0, options);
}

// Fill in the channel name
private val channelName = "<Your channel name>"
// Fill in the temporary token generated from Agora Console
private val token = "<Your token>"

private fun joinChannel() {
  val options = ChannelMediaOptions().apply {
    clientRoleType = Constants.CLIENT_ROLE_BROADCASTER
    channelProfile = Constants.CHANNEL_PROFILE_COMMUNICATION
    publishMicrophoneTrack = true;
  }
  mRtcEngine?.joinChannel(token, channelName, 0, options)
}

Subscribe to Voice SDK events

The Voice SDK provides an interface for subscribing to channel events. To use it, create an instance of IRtcEngineEventHandler and implement the event methods you want to handle.

private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() {
  // Callback when successfully joining the channel
  @Override
  public void onJoinChannelSuccess(String channel, int uid, int elapsed) {
    super.onJoinChannelSuccess(channel, uid, elapsed);
    showToast("Joined channel " + channel);
  }
  // Callback when a remote user or host joins the current channel
  @Override
  public void onUserJoined(int uid, int elapsed) {
    super.onUserJoined(uid, elapsed);
    runOnUiThread(() -> {
      showToast("User joined: " + uid); // Show toast for user joining
    });
  }
  // Callback when a remote user or host leaves the current channel
  @Override
  public void onUserOffline(int uid, int reason) {
    super.onUserOffline(uid, reason);
    runOnUiThread(() -> {
      showToast("User offline: " + uid); // Show toast for user going offline
    });
  }
};

private val mRtcEventHandler = object : IRtcEngineEventHandler() {
  override fun onJoinChannelSuccess(channel: String?, uid: Int, elapsed: Int) {
    super.onJoinChannelSuccess(channel, uid, elapsed)
    runOnUiThread {
      showToast("Joined channel $channel")
    }
  }
  override fun onUserJoined(uid: Int, elapsed: Int) {
    runOnUiThread {
      showToast("User joined: $uid")
    }
  }
  override fun onUserOffline(uid: Int, reason: Int) {
    super.onUserOffline(uid, reason)
    runOnUiThread {
      showToast("User offline: $uid")
    }
  }
}

Handle permissions

To access the microphone on Android devices, declare the necessary permissions in the app's manifest and ensure that the user grants these permissions when the app starts.

1. Open your project's AndroidManifest.xml file and add the following permissions before <application>:

   <!--Required permissions-->
   <uses-permission android:name="android.permission.INTERNET"/>
   
   <!--Optional permissions-->
   <uses-permission android:name="android.permission.RECORD_AUDIO"/>
   <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   <uses-permission android:name="android.permission.BLUETOOTH"/>
   <!-- For devices running Android 12 (API level 32) or higher and integrating Agora Voice SDK version v4.1.0 or lower, you also need to add the following permissions -->
   <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
   <!-- For Android 12 or higher, the following permissions are also required -->
   <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
   <uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>

2. Use the following code to handle runtime permissions in your Android app. The logic ensures that the necessary permissions are granted before starting Voice Calling. In your MainActivity file, add the following code:

private static final int PERMISSION_REQ_ID = 22;

  private boolean checkPermissions() {
    for (String permission : getRequiredPermissions()) {
      if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) {
        return false;
      }
    }
    return true;
  }

  private void requestPermissions() {
    ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID);
  }

  private String[] getRequiredPermissions() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
      return new String[]{
        Manifest.permission.RECORD_AUDIO,
        Manifest.permission.READ_PHONE_STATE,
        Manifest.permission.BLUETOOTH_CONNECT
      };
    } else {
      return new String[]{Manifest.permission.RECORD_AUDIO};
    }
  }

  @Override
  public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    if (checkPermissions()) {
      startVoiceCalling();
    }
  }

private val permissionReqId = 22

  private fun checkPermissions(): Boolean {
    for (permission in getRequiredPermissions()) {
      if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) {
        return false
      }
    }
    return true
  }
  private fun requestPermissions() {
    ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID)
  }
  private fun getRequiredPermissions(): Array<String> {
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
      arrayOf(
        Manifest.permission.RECORD_AUDIO,
        Manifest.permission.READ_PHONE_STATE,
        Manifest.permission.BLUETOOTH_CONNECT
      )
    } else {
      arrayOf(Manifest.permission.RECORD_AUDIO)
    }
  }
  override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    if (checkPermissions()) {
      startVoiceCalling()
    }
  }

Start and close the app

When a user launches your app, start real-time interaction. When a user closes the app, stop the interaction.

1. In the onCreate callback, check whether the app has been granted the required permissions. If the permissions have not been granted, request the required permissions from the user. If permissions are granted, initialize RtcEngine and join a channel.

@Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    if (checkPermissions()) {
      startVoiceCalling();
    } else {
      requestPermissions();
    }
  }

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    if (checkPermissions()) {
      startVoiceCalling()
    } else {
      requestPermissions()
    }
  }

2. When a user closes the app, or switches the app to the background, call leaveChannel to leave the current channel and release all session-related resources.

private void cleanupAgoraEngine() {
    if (mRtcEngine != null) {
      mRtcEngine.leaveChannel();
      mRtcEngine = null;
    }
  }

private fun cleanupAgoraEngine() {
    mRtcEngine?.apply {
      leaveChannel()
    }
    mRtcEngine = null
  }

Complete sample code

A complete code sample demonstrating the basic process of real-time interaction is provided for your reference. To use the sample code, copy the following lines into the MainActivity file in your project. Then, replace <projectname> in package com.example.<projectname> with your project's name.

Create a user interface

Use the following code to generate a basic user interface. Paste the code into the /app/src/main/res/layout/activity_main.xml file, replacing the existing content. Sample code to create the user interface

<?xml version="1.0" encoding="UTF-8"?>
<RelativeLayout
  xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:tools="http://schemas.android.com/tools"
  android:id="@+id/activity_main"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="@android:color/darker_gray"
  tools:context=".MainActivity">

  <TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_centerInParent="true"
    android:text="Welcome to Agora Voice Calling." />

</RelativeLayout>

Test the sample code

Take the following steps to test the sample code:

1. In MainActivity update the values for myAppId, and token with values from Agora Console. Fill in the same channelName you used to generate the token.

2. Enable developer options on your Android test device. Turn on USB debugging, connect the Android device to your development machine through a USB cable, and check that your device appears in the Android device options.

3. In Android Studio, click Sync Project with Gradle Files to resolve project dependencies and update the configuration.

4. After synchronization is successful, click Run app. Android Studio starts compilation. After a few moments, the app is installed on your Android device.

5. Launch the App, grant the recording permission.

6. On a second Android device, repeat the previous steps to install and launch the app. Alternatively, use the Web demo to join the same channel and test the following use-cases:

   • If users on both devices join the channel as hosts, they can hear each other.
   • If one user joins as host and the other as audience, the audience can hear the host.

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 JoinChannelAudio project for a more detailed example.

API reference

• RtcEngineConfig

• create

• ChannelMediaOptions

• joinChannel

• leaveChannel

• IRtcEngineEventHandler

Frequently asked questions

• How can I listen for audience joining or leaving a channel?
• How can I solve channel-related issues?
• How can I set the log file?
• Why do apps on some Android versions fail to capture audio and video after screen locking or switching to the background?

See also

• Error codes

• Connection status management

This iOS quickstart shows you how to create a basic Voice Calling app using the Agora Voice 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

• Xcode 13.0 or higher.

• An Apple developer account.

• If you need to use CocoaPods integrated SDK, make sure CocoaPods is installed.

• Two devices running iOS 14.0 or higher.

• 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 iOS project and install the Agora Voice SDK.

Install the SDK

Use one of the following methods to install Voice SDK.

Implement Voice Calling

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

The following figure illustrates the essential steps:

This guide includes complete sample code that demonstrates implementing basic real-time interaction. To understand the core API calls in the sample code, review the following implementation steps.

Import Agora framework

Add the following import to your swift file:

import AgoraRtcKit

Initialize the engine

Call sharedEngine(withAppId:delegate:) to create and initialize an AgoraRtcEngineKit instance. Provide your App ID and an AgoraRtcEngineDelegate implementation to handle SDK events.

var agoraKit: AgoraRtcEngineKit!
let appId = "YOUR_AGORA_APP_ID"

// Initialize the Agora engine
func initializeAgoraVoiceSDK() {
  agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: appId, delegate: self)
}

Join a channel

To join a channel, call joinChannel with the following parameters:

• Channel name: The name of the channel to join. Clients that pass the same channel name join the same channel. If a channel with the specified name does not exist, it is created when the first user joins.

• Authentication token: A dynamic key that authenticates a user when the client joins a channel. In a production environment, you obtain a token from a token server in your security infrastructure. For the purpose of this guide Generate a temporary token.

• User ID: A 32-bit signed integer that identifies a user in the channel. You can specify a unique user ID for each user yourself. If you set the user ID to 0 when joining a channel, the SDK generates a random number for the user ID and returns the value in the didJoinChannel callback.

• Channel media options: Configure AgoraRtcChannelMediaOptions to define publishing and subscription settings, optimize performance for your specific use-case, and set optional parameters.

For Voice Calling, set the channelProfile to .communication and the clientRoleType to .broadcaster.

let channelName = "demo"  // Replace with your actual channel name
let token = "<Authentication token>" // Replace with your token

func joinChannel() {
  let options = AgoraRtcChannelMediaOptions()
  options.channelProfile = .communication
  // Set user role to broadcaster; to set user role to audience, keep the default value
  options.clientRoleType = .broadcaster
  // Publish microphone audio
  options.publishMicrophoneTrack = true
  // Automatically subscribe to all audio streams
  options.autoSubscribeAudio = true
  // Join the channel using a temporary token and channel name
  agoraKit.joinChannel(
    byToken: token,
    channelId: channelName,
    uid: 0,
    mediaOptions: options
  )
}

Subscribe to Voice SDK events

The Voice SDK provides a delegate for handling channel events. To use it, conform to the AgoraRtcEngineDelegate protocol in your class and implement the event methods you want to handle. The following code implements the didJoinChannel, didOfflineOfUid, and didJoinedOfUid callbacks:

// Extension for handling Agora SDK callbacks
extension ViewController: AgoraRtcEngineDelegate {

  // Triggered when the local user successfully joins a channel
  func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) {
    print("Successfully joined channel: \(channel) with UID: \(uid)")
  }

  // Triggered when a remote user joins the channel
  func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
    print("User \(uid) joined after \(elapsed) milliseconds")
  }
  // Triggered when a remote user leaves the channel
  func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) {
    print("User \(uid) left: Reason -> \(reason)")
  }
}

To learn about the other SDK events, see AgoraRtcEngineDelegate.

Display the local video

Call setupLocalVideo to initialize the local view and set the local video display properties.

// Configures and starts displaying the local video feed
func setupLocalVideo() {
  let videoCanvas = AgoraRtcVideoCanvas()
  videoCanvas.view = localView
  videoCanvas.uid = 0 // UID 0 is assigned to the local user
  videoCanvas.renderMode = .hidden
  agoraKit.setupLocalVideo(videoCanvas)
}

Display remote video

To initialize the remote user view, call setupRemoteVideo and set the local display properties for the remote user. Use the didJoinedOfUid callback to get the UID of the remote user.

func setupRemoteVideo(uid: UInt, view: UIView?) {
  let videoCanvas = AgoraRtcVideoCanvas()
  videoCanvas.uid = uid
  videoCanvas.view = view // Assign view for joining, set to nil for leaving
  videoCanvas.renderMode = .hidden
  agoraKit.setupRemoteVideo(videoCanvas)
}

Handle permissions

To access the camera and microphone on iOS devices, add the required permissions for real-time interaction. Open the info.plist file from the project navigation bar, edit the property list, to add the required permissions. These permissions are optional. However, if you do not add these permissions, you will not be able to use the corresponding devices.

Start and close the app

When the user launches the app, it joins the channel and starts Voice Calling. When the user closes the app, it leaves the channel and ends Voice Calling.

1. To start Voice Calling, call the following methods:

   // Initialize the Agora engine
   initializeAgoraVoiceSDK()
   // Join the channel
   joinChannel()

2. To leave the channel and release SDK resources when the app is closed, call the following methods:

   // Leave the channel and release session-related resources
   agoraKit.leaveChannel(nil)
   // Release all resources used by the Agora SDK
   AgoraRtcEngineKit.destroy()

Complete sample code

A complete code sample demonstrating the basic process of real-time interaction is provided for your reference. Copy the following code into your ViewController.swift file:

Create a user interface

Based on your use-case, create a user interface for your project.

The following example uses a UILabel to display the current app status. To use this interface, replace the contents of the ViewController.swift file with the following code:

Sample code to create the user interface

import UIKit

class ViewController: UIViewController {
  var statusLabel: UILabel!

  override func viewDidLoad() {
    super.viewDidLoad()

    // Set up user interface
    setupUI();
  }

  func setupUI() {
    let mainView = UIView(frame: view.bounds)
    mainView.backgroundColor = .black

    statusLabel = UILabel(frame: mainView.bounds)
    statusLabel.text = "Waiting for other user"
    statusLabel.textColor = .white
    statusLabel.textAlignment = .center
    statusLabel.autoresizingMask = [.flexibleWidth, .flexibleHeight]

    mainView.addSubview(statusLabel)
    view.addSubview(mainView)
  }
}

Test the sample code

Take the following steps to test the sample code:

1. In your code update the appId and token, with the app ID and temporary token you obtained from Agora Console. Use the same channelName you filled in when generating the temporary token.

2. Connect your iOS device to your computer.

3. Click Build to run your project and wait a few seconds for the app installation to complete.

4. Allow the app to access the device's microphone.

5. If an untrusted developer prompt pops up on the device, click Cancel to close the prompt, then open Settings > General > VPN and Device Management on the iOS device, and choose to trust the developer in the Developer APP.

6. On a second iOS device, repeat the previous steps to install and launch the app. Alternatively, use the Web demo to join the same channel and test the following use-cases:

   • If users on both devices join the channel as hosts, they can hear each other.
   • If one user joins as host and the other as audience, the audience can hear the host.

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 JoinChannelAudio project for a more detailed example.

Add a privacy manifest file

The Agora Voice SDK for iOS provides the PrivacyInfo.xcprivacy file that contains the required reasons for the APIs used by the SDK. To add the privacy manifest to your app in Xcode, follow these steps:

1. Create a privacy manifest in your app project:

   1. Choose File > New File.

   2. Scroll down to the Resource section and select App Privacy File type.

   3. Click Next.

   4. Check your app in the Targets list.

   5. Click Create.

   The default file name is PrivacyInfo.xcprivacy which is also the required file name for bundled privacy manifests.

2. Add the items in PrivacyInfo.xcprivacy file of the Voice SDK to PrivacyInfo.xcprivacy of the app using the following source code:

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
     <key>NSPrivacyTracking</key>
     <false/>
     <key>NSPrivacyCollectedDataTypes</key>
     <array/>
     <key>NSPrivacyAccessedAPITypes</key>
     <array>
       <dict>
         <key>NSPrivacyAccessedAPIType</key>
         <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
         <key>NSPrivacyAccessedAPITypeReasons</key>
         <array>
           <string>35F9.1</string>
         </array>
       </dict>
       <dict>
         <key>NSPrivacyAccessedAPIType</key>
         <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
         <key>NSPrivacyAccessedAPITypeReasons</key>
         <array>
           <string>DDA9.1</string>
         </array>
       </dict>
       <dict>
         <key>NSPrivacyAccessedAPIType</key>
         <string>NSPrivacyAccessedAPICategoryDiskSpace</string>
         <key>NSPrivacyAccessedAPITypeReasons</key>
         <array>
           <string>E174.1</string>
         </array>
       </dict>
     </array>
   </dict>
   </plist>

API reference

• sharedEngine

• joinChannel

• leaveChannel

• AgoraRtcEngineDelegate

Frequently asked questions

• How can I listen for audience joining or leaving a channel?
• How can I solve channel-related issues?
• How can I set the log file?
• How can I troubleshoot the issue of no sound?
• What can I do if I get a pop-up warning saying 'the framework cannot be opened' when compiling an Xcode project?
• How can I add a privacy manifest to my iOS app?

See also

• Error codes

• Connection status management

This macOS quickstart shows you how to create a basic Voice Calling app using the Agora Voice 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

• Xcode 13.0 or higher.

• An Apple developer account.

• If you need to use CocoaPods integrated SDK, make sure CocoaPods is installed.

• Two devices running macOS 10.10 or higher.

• 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 macOS project and install the Agora Voice SDK.

Install the SDK

Use one of the following methods to install Voice SDK.

Implement Voice Calling

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

The following figure illustrates the essential steps:

This guide includes complete sample code that demonstrates implementing basic real-time interaction. To understand the core API calls in the sample code, review the following implementation steps.

Import Agora framework

Add the following import to your swift file:

import AgoraRtcKit

Initialize the engine

Call sharedEngine(withAppId:delegate:) to create and initialize an AgoraRtcEngineKit instance. Provide your App ID and an AgoraRtcEngineDelegate implementation to handle SDK events.

var agoraKit: AgoraRtcEngineKit!
let appId = "YOUR_AGORA_APP_ID"

// Initialize the Agora engine
func initializeAgoraVoiceSDK() {
  agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: appId, delegate: self)
}

Join a channel

To join a channel, call joinChannel with the following parameters:

• Channel name: The name of the channel to join. Clients that pass the same channel name join the same channel. If a channel with the specified name does not exist, it is created when the first user joins.

• Authentication token: A dynamic key that authenticates a user when the client joins a channel. In a production environment, you obtain a token from a token server in your security infrastructure. For the purpose of this guide Generate a temporary token.

• User ID: A 32-bit signed integer that identifies a user in the channel. You can specify a unique user ID for each user yourself. If you set the user ID to 0 when joining a channel, the SDK generates a random number for the user ID and returns the value in the didJoinChannel callback.

• Channel media options: Configure AgoraRtcChannelMediaOptions to define publishing and subscription settings, optimize performance for your specific use-case, and set optional parameters.

For Voice Calling, set the channelProfile to .communication and the clientRoleType to .broadcaster.

let channelName = "demo"  // Replace with your actual channel name
let token = "<Authentication token>" // Replace with your token

func joinChannel() {
  let options = AgoraRtcChannelMediaOptions()
  options.channelProfile = .communication
  // Set user role to broadcaster; to set user role to audience, keep the default value
  options.clientRoleType = .broadcaster
  // Publish microphone audio
  options.publishMicrophoneTrack = true
  // Automatically subscribe to all audio streams
  options.autoSubscribeAudio = true
  // Join the channel using a temporary token and channel name
  agoraKit.joinChannel(
    byToken: token,
    channelId: channelName,
    uid: 0,
    mediaOptions: options
  )
}

Subscribe to Voice SDK events

The Voice SDK provides a delegate for handling channel events. To use it, conform to the AgoraRtcEngineDelegate protocol in your class and implement the event methods you want to handle. The following code implements the didJoinChannel, didOfflineOfUid, and didJoinedOfUid callbacks:

// Extension for handling Agora SDK callbacks
extension ViewController: AgoraRtcEngineDelegate {

  // Triggered when the local user successfully joins a channel
  func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) {
    print("Successfully joined channel: \(channel) with UID: \(uid)")
  }

  // Triggered when a remote user joins the channel
  func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
    print("User \(uid) joined after \(elapsed) milliseconds")
  }
  // Triggered when a remote user leaves the channel
  func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) {
    print("User \(uid) left: Reason -> \(reason)")
  }
}

To learn about the other SDK events, see AgoraRtcEngineDelegate.

Display the local video

Call setupLocalVideo to initialize the local view and set the local video display properties.

// Configures and starts displaying the local video feed
func setupLocalVideo() {
  let videoCanvas = AgoraRtcVideoCanvas()
  videoCanvas.view = localView
  videoCanvas.uid = 0 // UID 0 is assigned to the local user
  videoCanvas.renderMode = .hidden
  agoraKit.setupLocalVideo(videoCanvas)
}

Display remote video

To initialize the remote user view, call setupRemoteVideo and set the local display properties for the remote user. Use the didJoinedOfUid callback to get the UID of the remote user.

func setupRemoteVideo(uid: UInt, view: UIView?) {
  let videoCanvas = AgoraRtcVideoCanvas()
  videoCanvas.uid = uid
  videoCanvas.view = view // Assign view for joining, set to nil for leaving
  videoCanvas.renderMode = .hidden
  agoraKit.setupRemoteVideo(videoCanvas)
}

Handle permissions

To access the camera and microphone on macOS devices, add the required permissions for real-time interaction. Open the info.plist file from the project navigation bar, edit the property list, to add the required permissions. These permissions are optional. However, if you do not add these permissions, you will not be able to use the corresponding devices.

Configure your macOS project settings by navigating to TARGETS > Project Name > Signing & Capabilities. Enable App Sandbox and Hardened Runtime, and add the necessary permissions as follows:

Start and close the app

When the user launches the app, it joins the channel and starts Voice Calling. When the user closes the app, it leaves the channel and ends Voice Calling.

1. To start Voice Calling, call the following methods:

   // Initialize the Agora engine
   initializeAgoraVoiceSDK()
   // Join the channel
   joinChannel()

2. To leave the channel and release SDK resources when the app is closed, call the following methods:

   // Leave the channel and release session-related resources
   agoraKit.leaveChannel(nil)
   // Release all resources used by the Agora SDK
   AgoraRtcEngineKit.destroy()

Complete sample code

A complete code sample demonstrating the basic process of real-time interaction is provided for your reference. Copy the following code into your ViewController.swift file:

Create a user interface

Based on your use-case, create a user interface for your project.

The following example uses a UILabel to display the current app status. To use this interface, replace the contents of the ViewController.swift file with the following code:

Sample code to create the user interface

import UIKit

class ViewController: UIViewController {
  var statusLabel: UILabel!

  override func viewDidLoad() {
    super.viewDidLoad()

    // Set up user interface
    setupUI();
  }

  func setupUI() {
    let mainView = UIView(frame: view.bounds)
    mainView.backgroundColor = .black

    statusLabel = UILabel(frame: mainView.bounds)
    statusLabel.text = "Waiting for other user"
    statusLabel.textColor = .white
    statusLabel.textAlignment = .center
    statusLabel.autoresizingMask = [.flexibleWidth, .flexibleHeight]

    mainView.addSubview(statusLabel)
    view.addSubview(mainView)
  }
}

Test the sample code

Take the following steps to test the sample code:

1. In your code update the appId and token, with the app ID and temporary token you obtained from Agora Console. Use the same channelName you filled in when generating the temporary token.

2. Click Build to run your project and wait a few seconds for the app installation to complete.

3. Allow the app to access the device's microphone.

4. On a second macOS device, repeat the previous steps to install and launch the app. Alternatively, use the Web demo to join the same channel and test the following use-cases:

   • If users on both devices join the channel as hosts, they can hear each other.
   • If one user joins as host and the other as audience, the audience can hear the host.

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 JoinChannelAudio project for a more detailed example.

API reference

• sharedEngine

• joinChannel

• leaveChannel

• AgoraRtcEngineDelegate

See also

• Error codes

• Connection status management

This Web quickstart shows you how to create a basic Voice Calling app using the Agora Voice SDK. Switch to the Android or iOS quickstart, or choose another platform from the selector.

• RTC SDK API examples: Sample projects for the Agora RTC Web SDK 4.x, covering basic, advanced examples for Vue and React.

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

• A supported browser. Agora strongly recommends using the latest stable version of Google Chrome.

• Node.js and npm

• 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 Web project and install the Agora Voice SDK.

Install the SDK

Add the Voice SDK to your project:

npm install agora-rtc-sdk-ng

Implement Voice Calling

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

The following figure illustrates the essential steps:

This guide includes complete sample code that demonstrates implementing basic real-time interaction. To understand the core API calls in the sample code, review the following implementation steps.

Import the AgoraRTC SDK

import AgoraRTC from "agora-rtc-sdk-ng";

Initialize an instance of AgoraRTCClient

Call createClient to initialize an AgoraRTCClient object. Set the Channel mode based on your use case.

For Voice Calling Set mode to rtc.

// RTC client instance
let client = null;

// Initialize the AgoraRTC client
function initializeClient() {
  client = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });
  setupEventListeners();
}

Join a channel

To join a channel, call join with the following parameters:

• App ID: The App ID for your project.

• Channel name: The name of the channel to join. Clients that pass the same channel name join the same channel. If a channel with the specified name does not exist, it is created when the first user joins.

• Authentication token: A dynamic key that authenticates a user when the client joins a channel. In a production environment, you obtain a token from a token server in your security infrastructure. For the purpose of this guide Generate a temporary token.

• User ID: A 32-bit signed integer that identifies a user in the channel. You can specify a unique user ID for each user yourself. If you set the user ID to 0 when joining a channel, the SDK generates a random number for the user ID.

// Join the channel and publish local audio
async function joinChannel() {
  await client.join(appId, channel, token, uid);
  await createMicrophoneAudioTrack();
  await publishMicrophoneAudioTrack();
}

Create a local audio track

Use createMicrophoneAudioTrack to create a local audio track.

let localAudioTrack;
async function createMicrophoneAudioTrack() {
  // Create a local audio track
  localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack();
}

Publish local media tracks

To make the created audio tracks available for other users in the channel, use the publish method.

async function publishMicrophoneAudioTrack() {
  await client.publish([localAudioTrack]);
}

See Local audio tracks to learn more about local tracks.

Set up event listeners

Use the on method to register event listeners for SDK events. The SDK triggers the user-published event when a user publishes an audio track in the channel. Similarly, it triggers the user-unpublished event when a user leaves the channel, goes offline, or unpublishes a media track.

// Handle client events
function setupEventListeners() {
  // Set up event listeners for remote tracks
  client.on("user-published", async (user, mediaType) => {
    // Subscribe to the remote user when the SDK triggers the "user-published" event
    await client.subscribe(user, mediaType);

    // If the remote user publishes an audio track
    if (mediaType === "audio") {
      // Get the RemoteAudioTrack object in the AgoraRTCRemoteUser object
      const remoteAudioTrack = user.audioTrack;
      // Play the remote audio track
      remoteAudioTrack.play();
    }
  });

  // Handle the "user-unpublished" event to unsubscribe from the user's media tracks
  client.on("user-unpublished", async (user) => {
    // Remote user unpublished
  });
}

For more information about other AgoraRTCClient events, refer to the API reference.

Leave the channel

To exit the channel, close the local audio track and call the leave method.

// Leave the channel and clean up
async function leaveChannel() {
  // Stop the local audio track and release the microphone
  if (localAudioTrack) {
    localAudioTrack.close(); // Stop local audio
    localAudioTrack = null; // Clean up the track reference
  }
  // Leave the channel
  await client.leave();
}

Complete sample code

A complete code sample demonstrating the basic process of real-time interaction is provided here for your reference. To use the sample, copy the following code to the JavaScript file in the project's src folder.

Create a user interface

Open index.html in the project's root folder and replace the contents with the following code to implement a basic client user interface:

Sample code to create the user interface

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Agora Web SDK Quickstart</title>
</head>
<body>
  <h2 class="left-align">Agora Web SDK Quickstart</h2>
    <div class="row">
      <div>
        <button type="button" id="join">Join</button>
        <button type="button" id="leave">Leave</button>
      </div>
    </div>
  <!-- Include the JavaScript file -->
  <script type="module" src="/src/main.js"></script>
</body>
</html>

Test the sample code

Take the following steps to run and test the sample code:

1. In your .js file, update the values for appId, and token with values from Agora Console. Use the same channel name you used to generate the token.

2. To start the development server, use the following command:

   npm run dev

3. Open your browser and navigate to the URL displayed in your terminal, for example, http://localhost:5173.

   You see the following page:

   

4. On a second device, repeat the previous steps to install and launch the app. Alternatively, use the Web demo or clone the sample project on Github to join the same channel and test the following use-cases:

   1. Click Join to join the channel.
   2. Enter the same app ID, channel name, and temporary token.

   Once your friend joins the channel, you can hear 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 basicVoiceCall project for a more detailed example.

API reference

• AgoraRTC.createClient
• IAgoraRTCRemoteUser
• play
• join
• createMicrophoneAudioTrack
• publish
• AgoraRTCClient events

Channel modes

The Voice SDK supports the following channel modes:

• rtc: Communication use-case
• live: Live broadcast use-case

Communication use-case

It is suitable for use-cases where all users in the channel need to communicate with each other and the total number of users is not too large, such as multi-person conferences and online chats.

Live broadcast use-case

It is suitable for use-cases where there are few publishers but many subscribers. In this use-case, the SDK defines two user roles: audience (default) and host. Hosts can send and receive audio, but audience cannot send and may only receive audio. You can specify user roles by setting the parameters createClient of role, or you can call setClientRole to dynamically modify user roles.

Local audio tracks

The SDK uses a hierarchy where all local track objects derive from the LocalTrack base class. This class defines the common behavior for all local tracks. Specific track types, such as LocalAudioTrack inherit from LocalTrack and extend its functionality.

To publish a local track, you call the publish method of the client with the LocalTrack object as an input parameter. This approach makes publishing a track independent of how you create your local track.

Each type of LocalTrack comes with its own set of tools. For example, LocalAudioTrack lets you control the volume.

The SDK includes more specific classes based on LocalAudioTrack. For example, the MicrophoneAudioTrack, is a type of LocalAudioTrack that you can use to publish audio from your microphone. It comes with extra features for controlling the microphone and adjusting audio quality.

Other integration methods

When you use npm to install the Web SDK, you can enable tree shaking to reduce the size of the app after integration. For details, see Using tree shaking.

In addition to using npm to install the Web SDK, you can also use the following methods:

• In the project HTML file, add the following tag to obtain the SDK from CDN:

  <script src="https://download.agora.io/sdk/release/AgoraRTC_N-4.24.5.js"></script>

• Download the Voice SDK package locally, save the .js files in the SDK package to the project directory, and then add the following tag to the project HTML file:

  <script src="./AgoraRTC_N-4.24.5.js"></script>

Visit the Download page to obtain the link for the latest SDK version.

Frequently asked questions

Why do I get a digital envelope routines::unsupported error when running the quickstart project locally?

This issue arises in projects configured with webpack for local execution due to changes in Node.js 16 and above. The modifications in Node.js, particularly its dependency on OpenSSL (detailed in the node issue), impact the local development environment dependencies of the project. Refer to the webpack issue for details.

Use one of the following solutions to resolve the issue:

• Run the following command to set a temporary environment variable (Recommended):

  export NODE_OPTIONS=--openssl-legacy-provider

• Temporarily switch to a lower version of Node.js.

See also

• Error codes

• Connection status management

This Windows quickstart shows you how to create a basic Voice Calling app using the Agora Voice 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

• A device running Windows 7 or higher.

• Microsoft Visual Studio 2017 or higher with C++ desktop development support. C++ 11 or above.

• If you use C# for development, you also need the .NET framework.

• 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 Windows project and install the Agora Voice SDK.

3. Create a user-interface for your app based on your application use-case.

   A basic UI consists of the following controls:

   • Join channel button
   • Leave channel button
   • An Edit Control for entering a channel name

   Refer to Create a user interface to get a bare bones sample layout.

Install the SDK

Install the Agora Voice SDK:

1. Download the latest Windows SDK.

2. Unzip and open the downloaded SDK. Copy all subfolders in sdk/ to your solution folder. Make sure these subfolders are in the same directory as your .sln file.

Configure the project

In the Solution Explorer window, right-click the project name and click Properties to configure the following:

1. Go to the C/C++ > General > Additional Include Directory menu, click Edit, and in the pop-up window enter $(SolutionDir)sdk\high_level_api\include.
2. Go to the Linker > General > Additional Library Directory menu, click Edit, and in the pop-up window:
   • for 64 bit Windows, enter $(SolutionDir)sdk\x86_64.
   • for x86 Windows, enter $(SolutionDir)sdk\x86.
3. Go to the Linker > Input > Additional Dependencies menu, click Edit, and in the pop-up window:
   • for 64 bit Windows, enter $(SolutionDir)sdk\x86_64\agora_rtc_sdk.dll.lib.
   • for x86 Windows, enter $(SolutionDir)sdk\x86\agora_rtc_sdk.dll.lib.
4. Enter the Advanced menu, and in Advanced Properties, set Copy contents to OutDir and Copy C++ runtime to output directory to Yes.
5. Go to the Build Events > Post-Build Events > Command Line menu and enter copy $(SolutionDir)sdk\x86_64\*.dll $(SolutionDir)$(Platform)\$(Configuration).
6. Click Apply to save the configuration.

Implement Voice Calling

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

The following figure illustrates the essential steps:

This guide includes complete sample code that demonstrates implementing basic real-time interaction. To understand the core API calls in the sample code, review the following implementation steps.

Initialize the engine

For real-time communication, initialize an IRtcEngine instance and set up event handlers to manage user interactions within the channel. Use RtcEngineContext to specify the App ID, and custom event handler, then call initialize to initialize the engine, enabling further channel operations. Add the following code to your header and .cpp files:

// Declare the required variables
IRtcEngine* m_rtcEngine = nullptr; // RTC engine instance
CAgoraQuickStartRtcEngineEventHandler m_eventHandler; // IRtcEngineEventHandler

void CAgoraQuickStartDlg::initializeAgoraEngine() {
  // Create IRtcEngine object
  m_rtcEngine = createAgoraRtcEngine();
  // Create IRtcEngine context object
  RtcEngineContext context;
  // Input your App ID. You can obtain your project's App ID from the Agora Console
  context.appId = APP_ID;
  // Add event handler for callbacks and events
  context.eventHandler = &m_eventHandler;
  // Initialize
  int ret = m_rtcEngine->initialize(context);
  m_initialize = (ret == 0);

  if (!m_initialize) {
    AfxMessageBox(_T("Failed to initialize Agora RTC engine"));
  }
}

Join a channel

To join a channel, call joinChannel[2/2] with the following parameters:

• Channel name: The name of the channel to join. Clients that pass the same channel name join the same channel. If a channel with the specified name does not exist, it is created when the first user joins.

• Authentication token: A dynamic key that authenticates a user when the client joins a channel. In a production environment, you obtain a token from a token server in your security infrastructure. For the purpose of this guide Generate a temporary token.

• User ID: A 32-bit signed integer that identifies a user in the channel. You can specify a unique user ID for each user yourself. If you set the user ID to 0 when joining a channel, the SDK generates a random number for the user ID and returns the value in the onJoinChannelSuccess callback.

• Channel media options: Configure ChannelMediaOptions to define publishing and subscription settings, optimize performance for your specific use-case, and set optional parameters.

For Voice Calling, set the channelProfile to CHANNEL_PROFILE_COMMUNICATION and the user role to CLIENT_ROLE_BROADCASTER.

void CAgoraQuickStartDlg::joinChannel(const char* token, const char* channelName) {
  ChannelMediaOptions options;
  // Set channel profile to live broadcasting
  options.channelProfile = CHANNEL_PROFILE_COMMUNICATION;
  // Set user role to broadcaster; keep default value if setting user role to audience
  options.clientRoleType = CLIENT_ROLE_BROADCASTER;
  // Publish the audio stream captured by the microphone
  options.publishMicrophoneTrack = true;
  // Automatically subscribe to all audio streams
  options.autoSubscribeAudio = true;
  // Join the channel using the token and channel name (both are const char*)
  m_rtcEngine->joinChannel(token, channelName, 0, options);
}

Subscribe to Voice SDK events

The Voice SDK provides an interface for subscribing to channel events. To use it, create a custom event handler class by inheriting from IRtcEngineEventHandler and override its methods to handle real-time interaction events. Add callbacks to receive notification of users joining and leaving the channel.

// Define the CAgoraQuickStartRtcEngineEventHandler class to handle callback events such as users joining and leaving the channel
class CAgoraQuickStartRtcEngineEventHandler
  : public IRtcEngineEventHandler {
  public:
    CAgoraQuickStartRtcEngineEventHandler()
      : m_hMsgHandler(nullptr) {
    }

    // Set the handle of the message receiving window
    void SetMsgReceiver(HWND hWnd) {
      m_hMsgHandler = hWnd;
    }

    // Register onJoinChannelSuccess callback
    // This callback is triggered when a local user successfully joins a channel
    virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed) {
      if (m_hMsgHandler) {
        ::PostMessage(m_hMsgHandler, WM_MSGID(EID_JOIN_CHANNEL_SUCCESS), uid, 0);
      }
    }

    // Register onUserJoined callback
    // This callback is triggered when the remote host successfully joins the channel
    virtual void onUserJoined(uid_t uid, int elapsed) {
      if (m_hMsgHandler) {
        ::PostMessage(m_hMsgHandler, WM_MSGID(EID_USER_JOINED), uid, 0);
      }
    }

    // Register onUserOffline callback
    // This callback is triggered when the remote host leaves the channel or is offline
    virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason) {
      if (m_hMsgHandler) {
        ::PostMessage(m_hMsgHandler, WM_MSGID(EID_USER_OFFLINE), uid, 0);
      }
    }

  private:
    HWND m_hMsgHandler;
};

Implement the callback functions.

LRESULT CAgoraQuickStartDlg::OnEIDJoinChannelSuccess(WPARAM wParam, LPARAM lParam) {
  // Join channel success callback
  uid_t localUid = wParam;
  return 0;
}

LRESULT CAgoraQuickStartDlg::OnEIDUserJoined(WPARAM wParam, LPARAM lParam) {
  // Remote user joined callback
  return 0;
}

LRESULT CAgoraQuickStartDlg::OnEIDUserOffline(WPARAM wParam, LPARAM lParam) {
  // Remote user left callback
  return 0;
}

Leave the channel

When a user ends a call, or closes the app call leaveChannel to exit the current channel.

// Leave the channel
m_rtcEngine->leaveChannel();

Release resources

To destroy the engine instance, call release :

// Release resources when the object is destroyed
m_rtcEngine->release(true);
m_rtcEngine = NULL;

Complete sample code

A complete code sample that implements the basic process of real-time interaction is presented here for your reference. Copy the sample code into your project to quickly implement the basic functions of real-time interaction.

AgoraQuickStartDlg.h

Create a user interface

Follow these steps to create a bare-bones UI for your project.

Steps to create a minimalistic UI

1. In the right menu bar, switch the project to resource view, then open the .Dialog file.

2. Add an input box for the channel name:

   1. Go to View > Toolbox and select Add Static Text control.
   2. Change the description text to Channel name in the properties.
   3. Add an Edit Control as an input box.
   4. In Properties > Miscellaneous, set the control's ID to IDC_EDIT_CHANNEL.

3. Add join and leave channel buttons:

   1. In View > Toolbox, add two Button controls.
   2. In Properties > Miscellaneous, set the IDs of the controls to ID_BTN_JOIN and ID_BTN_LEAVE.
   3. Set the description text to Join and Leave respectively.

   Your interface looks similar to the following:

Test the sample code

To test your app, follow these steps:

1. In Visual Studio, select local Windows debugger to start compiling the application.

2. Enter the name of the channel you want to join in the input box and click the Join button to join the channel.

3. Use the Web demo to join the same channel and test the following use-cases:

   • If users on both devices join the channel as hosts, they can hear each other.
   • If one user joins as host and the other as audience, the audience can hear the host.

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 sample project for a more detailed example.
• For a Windows C# implementation, see this sample project.

API Reference

• createAgoraRtcEngine

• joinChannel

• IRtcEngineEventHandler

• leaveChannel

• release

Frequently asked questions

• How can I listen for audience joining or leaving a channel?
• How can I solve channel-related issues?
• How can I set the log file?

See also

• Error codes

• Connection status management

This Electron quickstart shows you how to create a basic Voice Calling app using the Agora Voice 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

• Node.js 14 or higher.

• 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 Electron project and install the Agora Voice SDK.

1. Create a new directory for your Electron project in a local folder. Add the following files to the root of the project directory:

   • package.json: Manages project dependencies and scripts.
   • index.html: Defines the app's user interface.
   • main.js: The main process entry point.
   • renderer.js: The renderer process script, responsible for interacting with the Agora Electron SDK.

2. Create a user interface for your app based on your use-case.

   Refer to Create a user interface to get a bare bones sample layout.

Install the SDK

Manual Integration Compile the latest SDK from the Electron SDK repository and integrate it into your application.

Implement Voice Calling

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

The following figure illustrates the essential steps:

This guide includes complete sample code that demonstrates implementing basic real-time interaction. To understand the core API calls in the sample code, review the following implementation steps.

Set up the main process

The main.js file is the entry point for your Electron application. It defines the main process, which is responsible for creating and managing browser windows. This script initializes the app, loads the UI from index.html, and ensures proper behavior across platforms.

const { app, BrowserWindow } = require("electron");
const path = require("path");

// If using Electron 9.x or later, set allowRendererProcessReuse to false
app.allowRendererProcessReuse = false;

function createWindow() {
  // Create the browser window
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      // preload: path.join(__dirname, "renderer.js"),
      // Enable Node integration and disable context isolation
      nodeIntegration: true,
      contextIsolation: false,
    },
  });

  // Load the contents of the index.html file
  mainWindow.loadFile("./index.html");
  // Open the Developer Tools
  mainWindow.webContents.openDevTools();
}

// Manage the browser window for the Electron app
app.whenReady().then(() => {
  createWindow();
  // On macOS, create a new window if none are open
  app.on("activate", function () {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

// Quit the Electron app when all windows are closed (except on macOS)
app.on("window-all-closed", function () {
  if (process.platform !== "darwin") app.quit();
});

Handle permissions

Perform this step only when the target platform is macOS. Starting with macOS v10.14, you must check and obtain permission before accessing the microphone. Use Electron’s askForMediaAccess method to request the permission from the user.

Add the following code to the main.js file:

// Check and request microphone permission
async function checkAndApplyDeviceAccessPrivilege() {
  const micPrivilege = systemPreferences.getMediaAccessStatus('microphone');
  console.log(`Microphone privilege before applying: ${micPrivilege}`);
  if (micPrivilege !== 'granted') {
    await systemPreferences.askForMediaAccess('microphone');
    console.log('Requested microphone access from user');
  }
}

checkAndApplyDeviceAccessPrivilege();

Import dependencies

Import the modules and functions required to build the app using Voice SDK. Add the following code to renderer.js:

const {
  createAgoraRtcEngine,
  ChannelProfileType,
  ClientRoleType,
} = require("agora-electron-sdk");

Specify connection parameters

Provide the App ID, temporary token, and the channel name you used when generating the token. The engine uses these values to initialize and join the channel.

// Enter your App ID
const APPID = "<-- Insert App Id -->";
// Enter your temporary token
let token = "<-- Insert Token -->";
// Enter the channel name used when generating the token
const channel = "<-- Insert Channel Name -->";
// Specify a unique user ID for this session
let uid = 123;

Initialize the engine

For real-time communication, create an IRtcEngine object by calling createAgoraRtcEngine and then call initialize with RtcEngineContext to specify the App ID. Call registerEventHandler to register a custom event handler for managing user interactions within the channel.

let rtcEngine;
const os = require("os");
const path = require("path");
const sdkLogPath = path.resolve(os.homedir(), "./test.log");

// Create RtcEngine instance
rtcEngine = createAgoraRtcEngine();

// Initialize RtcEngine instance
rtcEngine.initialize({
  appId: APPID,
  logConfig: { filePath: sdkLogPath }
});

Join a channel

To join a channel, call joinChannel with the following parameters:

• Channel name: The name of the channel to join. Clients that pass the same channel name join the same channel. If a channel with the specified name does not exist, it is created when the first user joins.

• Authentication token: A dynamic key that authenticates a user when the client joins a channel. In a production environment, you obtain a token from a token server in your security infrastructure. For the purpose of this guide Generate a temporary token.

• User ID: A 32-bit signed integer that identifies a user in the channel. You can specify a unique user ID for each user yourself. If you set the user ID to 0 when joining a channel, the SDK generates a random number for the user ID and returns the value in the onJoinChannelSuccess callback.

• Channel media options: Configure ChannelMediaOptions to define publishing and subscription settings, optimize performance for your specific use-case, and set optional parameters.

For Voice Calling, set the channelProfile to ChannelProfileCommunication and the clientRoleType to ClientRoleBroadcaster.

// Join the channel using a temporary token
rtcEngine.joinChannel(token, channel, uid, {
  // Set the channel profile to communication
  channelProfile: ChannelProfileType.ChannelProfileCommunication,
  // Set the user role to broadcaster; keep the default value for audience role
  clientRoleType: ClientRoleType.ClientRoleBroadcaster,
  // Publish audio collected from the microphone
  publishMicrophoneTrack: true,
  // Automatically subscribe to all audio streams
  autoSubscribeAudio: true,
});

Register event handlers

Call the registerEventHandler method to register the following callback events:

• onJoinChannelSuccess: Triggered when the local user successfully joins a channel.
• onUserJoined: Triggered when a remote user joins the current channel.
• onUserOffline: Triggered when a remote user leaves the current channel.

const EventHandles = {
  // Listen for the local user joining the channel
  onJoinChannelSuccess: ({ channelId, localUid }, elapsed) => {
    console.log('Successfully joined channel: ' + channelId);
  },

  // Listen for remote users joining the channel
  onUserJoined: ({ channelId, localUid }, remoteUid, elapsed) => {
    console.log('Remote user ' + remoteUid + ' joined');
  },

  // Listen for users leaving the channel
  onUserOffline: ( { channelId, localUid }, remoteUid, reason ) => {
    console.log('Remote user ' + remoteUid + ' left the channel');
  },
};

// Register the event handler
rtcEngine.registerEventHandler(EventHandles);

Start and close the app

When a user launches your app, start Voice Calling. When a user closes the app, stop Voice Calling and release resources.

1. To start Voice Calling, initialize the engine and join a channel.

2. When Voice Calling ends, leave the channel and clean up resources:

   // Leave the channel
   rtcEngine.leaveChannel();

   When you no longer need to interact, unregister the event handler and call release to release engine resources.

   // Unregister the event handler
   rtcEngine.unregisterEventHandler(EventHandles);
   // Release the engine
   rtcEngine.release();

   After destroying the engine, you can no longer use SDK methods and callbacks. To use the real-time interaction functions again, create a new engine instance. See Initialize the engine for details.

Complete sample code

A complete code sample demonstrating the basic process of real-time interaction is provided for your reference. Replace the entire contents of the main.js and renderer.js with the following code samples:

main.js

To test the complete code, see Test the sample code.

Create a user interface

To create a minimal interface, add the following code to index.html: Sample code to create the user interface

<!DOCTYPE html>
<html>
 <head>
  <meta charset="UTF-8" />
  <title>Electron Voice Quickstart</title>
 </head>
 <body>
  <h1>Electron Voice Quickstart</h1>
 </body>
 <script src="./renderer.js"></script>
</html>

Test the sample code

Take the following steps to test the sample code:

1. Update the APPID, token, and channel parameter values in your code.

2. To run the app, execute the following command in the project root directory:

   npm start

3. Invite a friend to run the demo app on a second device. Alternatively, use the Web demo to join the same channel.

   • If users on both devices join the channel as hosts, they can hear each other.
   • If one user joins as host and the other as audience, the audience can hear the host.

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 JoinChannelAudio project for a more detailed example.

API Reference

• createAgoraRtcEngine

• joinChannel

• IRtcEngineEventHandler

• leaveChannel

• release

Frequently asked questions

• How can I listen for audience joining or leaving a channel?
• How can I solve channel-related issues?
• How can I set the log file?

See also

• Error codes

• Connection status management

This Flutter quickstart shows you how to create a basic Voice Calling app using the Agora Voice 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

• Flutter 2.10.5 or higher with Dart 2.14.0 or higher.
• Android Studio, IntelliJ, VS Code, or any other IDE that supports Flutter. See Set up an editor.
• Prepare your development and testing environment according to your target platform.

Run the flutter doctor command to confirm that your development environment is set up correctly for Flutter development.

• 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 Flutter project and install the Agora Voice SDK.

flutter create agora_project
cd agora_project

Install the SDK

Install the Agora Voice SDK and other dependencies.

1. Add the latest version of Agora Voice SDK to your Flutter project:

   flutter pub add agora_rtc_engine

2. Add the permission processing package:

   flutter pub add permission_handler

   The dependencies in your pubspec.yaml file should look like the following:

   dependencies:
    flutter:
     sdk: flutter
    agora_rtc_engine: ^6.5.0 # Agora Flutter SDK, please use the latest version
    permission_handler: ^11.3.1 # Package for managing runtime permissions
    cupertino_icons: ^1.0.8

3. Install the dependencies.

   Execute the following command in the project path:

   flutter pub get

Implement Voice Calling

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

The following figure illustrates the essential steps:

This guide includes complete sample code that demonstrates implementing basic real-time interaction. To understand the core API calls in the sample code, review the following implementation steps.

Import packages

Import the following packages in your dart file.

import 'dart:async';

import 'package:agora_rtc_engine/agora_rtc_engine.dart';
import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';

Initialize the engine

For real-time communication, initialize an RtcEngine instance. Use RtcEngineContext to specify the App ID, and other configuration parameters. In your dart file, add the following code:

// Set up the Agora RTC engine instance
Future<void> _initializeAgoraVoiceSDK() async {
 _engine = createAgoraRtcEngine();
 await _engine.initialize(const RtcEngineContext(
  appId: "<-- Insert app Id -->",
  channelProfile: ChannelProfileType.channelProfileCommunication,
 ));
}

Join a channel

To join a channel, call joinChannel with the following parameters:

• Channel name: The name of the channel to join. Clients that pass the same channel name join the same channel. If a channel with the specified name does not exist, it is created when the first user joins.

• Authentication token: A dynamic key that authenticates a user when the client joins a channel. In a production environment, you obtain a token from a token server in your security infrastructure. For the purpose of this guide Generate a temporary token.

• User ID: A 32-bit signed integer that identifies a user in the channel. You can specify a unique user ID for each user yourself. If you set the user ID to 0 when joining a channel, the SDK generates a random number for the user ID and returns the value in the onJoinChannelSuccess callback.

• Channel media options: Configure ChannelMediaOptions to define publishing and subscription settings, optimize performance for your specific use-case, and set optional parameters.

For Voice Calling, set the clientRoleType to clientRoleBroadcaster.

// Join a channel
Future<void> _joinChannel() async {
 await _engine.joinChannel(
  token: token,
  channelId: channel,
  options: const ChannelMediaOptions(
   autoSubscribeAudio: true, // Automatically subscribe to all audio streams
   publishMicrophoneTrack: true, // Publish microphone-captured audio
   // Use clientRoleBroadcaster to act as a host or clientRoleAudience for audience
   clientRoleType: ClientRoleType.clientRoleBroadcaster,
  ),
  uid: 0,
 );
}

Subscribe to Voice SDK events

The SDK provides the RtcEngineEventHandler for subscribing to channel events. To use it, pass an instance of RtcEngineEventHandler to registerEventHandler and implement the event methods you want to handle.

Call registerEventHandler to bind the event handler to the SDK.

// Register an event handler for Agora RTC
void _setupEventHandlers() {
 _engine.registerEventHandler(
  RtcEngineEventHandler(
   onJoinChannelSuccess: (RtcConnection connection, int elapsed) {
    debugPrint("Local user ${connection.localUid} joined");
   },
   onUserJoined: (RtcConnection connection, int remoteUid, int elapsed) {
    debugPrint("Remote user $remoteUid joined");
    setState(() {
     _remoteUid = remoteUid; // Store remote user ID
    });
   },
   onUserOffline: (RtcConnection connection, int remoteUid, UserOfflineReasonType reason) {
    debugPrint("Remote user $remoteUid left");
    setState(() {
     _remoteUid = null; // Remove remote user ID
    });
   },
  ),
 );
}

Handle permissions

Request the microphone permission for Voice Calling.

// Requests microphone permission
Future<void> _requestPermissions() async {
 await [Permission.microphone].request();
}

Start and close the app

To start Voice Calling, request microphone permission, initialize the Agora SDK instance, set up an event handler, and join a channel.

await _requestPermissions();
await _initializeAgoraVoiceSDK();
_setupEventHandlers();
await _joinChannel();

To stop Voice Calling, leave the channel and release the engine instance.

// Leaves the channel and releases resources
Future<void> _cleanupAgoraEngine() async {
 await _engine.leaveChannel();
 await _engine.release();
}

Complete sample code

A complete code sample demonstrating the basic process of real-time interaction is provided for your reference. To use the sample code, copy the following code to replace the entire contents of the .dart file in your project.

Create a user interface

To connect the sample code to your existing UI, ensure that your widget tree includes the _remoteVideo and _localVideo widgets used to Display the local video and Display remote video.

Alternatively, use the following sample code to generate a basic user interface:

Sample code to create the user interface

Use the following code sample to build a basic user interface:

// Build UI
@override
Widget build(BuildContext context) {
 return MaterialApp(
  title: 'Agora Voice Call',
  home: Scaffold(
   appBar: AppBar(
    title: const Text('Agora Voice Call'),
   ),
   body: Center(
    child: Text(
     _remoteUid != null
       ? "Remote user $_remoteUid joined"
       : "No remote user in the channel", // Show appropriate message
     style: const TextStyle(fontSize: 18),
    ),
   ),
  ),
 );
}

Test the sample code

Take the following steps to test the sample code:

1. In main.dart update the values for appId, and token with values from Agora Console. Fill in the same channel name you used to generate the token.

2. Connect a target device to your development computer.

3. Open Terminal and execute the following command in the project folder to run the sample project:

   flutter run

4. Launch the App, grant microphone permission.

5. On a second target device, repeat the previous steps to install and launch the app. Test the following use-cases:

   • If users on both devices join the channel as hosts, they can hear each other.
   • If one user joins as host and the other as audience, the audience can hear the host.

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 join_channel_audio.dart for a more detailed example.

API reference

• registerEventHandler

• setClientRole

• setChannelProfile

• joinChannel

• leaveChannel

Frequently asked questions

• How can I listen for audience joining or leaving a channel?
• How can I solve channel-related issues?
• How can I set the log file?

See also

• Error codes

• Connection status management

This React Native quickstart shows you how to create a basic Voice Calling app using the Agora Voice 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

• React Native 0.60 or later. For more information, see Get Started with React Native.
• Node 16 or later For your target platform, prepare the following:

• 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 React Native project and install the Agora Voice SDK.

Create a project

To create a new application using React Native Community CLI, see Get Started Without a Framework.

Install the SDK