Quickstart

This page provides a step-by-step guide on how to create a basic Video Calling app using the Agora Video SDK.

Understand the tech

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

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

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

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

Prerequisites

• A camera and a microphone.
• A valid Agora account and project. See Agora account management for details.
• Android Studio 4.2 or higher.
• Android SDK API Level 21 or higher.
• Two mobile devices running Android 5.0 or higher.

Set up your project

2. Add a layout file for your activity.

   Set up two container elements in your activity to display local and remote video streams. Refer to Create a user interface to get a bare bones sample layout.

Install the SDK

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

Implement Video Calling

This section guides you through the implementation of basic real-time audio and video 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.video.VideoCanvas;
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
import io.agora.rtc2.video.VideoCanvas
import io.agora.rtc2.ChannelMediaOptions

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 initializeAgoraVideoSDK() {
    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 initializeRtcEngine() {
    try {
        val config = RtcEngineConfig().apply {
            mContext = applicationContext
            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 Video Calling, set the channelProfile to CHANNEL_PROFILE_COMMUNICATION and the clientRoleType 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;
    options.publishMicrophoneTrack = 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
        publishCameraTrack = true
    }
    mRtcEngine.joinChannel(token, channelName, 0, options)
}

Subscribe to Video SDK events

The Video 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() {
    // Triggered when the local user successfully joins the specified channel.
    @Override
    public void onJoinChannelSuccess(String channel, int uid, int elapsed) {
        super.onJoinChannelSuccess(channel, uid, elapsed);
        showToast("Joined channel " + channel);
    }

    // Triggered when a remote user/host joins the channel.
    @Override
    public void onUserJoined(int uid, int elapsed) {
        super.onUserJoined(uid, elapsed);
        runOnUiThread(() -> {
            // Initialize and display remote video view for the new user.
            setupRemoteVideo(uid);
            showToast("User joined: " + uid);
        });
    }

    // Triggered when a remote user/host leaves the channel.
    @Override
    public void onUserOffline(int uid, int reason) {
        super.onUserOffline(uid, reason);
        runOnUiThread(() -> {
            showToast("User offline: " + uid);
        });
    }
};

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")
        }
    }
}

Enable the video module

Follow these steps to enable the video module:

1. Call enableVideo to enable the video module.
2. Call startPreview to enable local video preview.

private void enableVideo() {
    mRtcEngine.enableVideo();
    mRtcEngine.startPreview();
}

private fun enableVideo() {
    mRtcEngine?.apply {
        enableVideo()
        startPreview()
    }
}

Display the local video

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

private void setupLocalVideo() {
    FrameLayout container = findViewById(R.id.local_video_view_container);
    SurfaceView surfaceView = new SurfaceView(getBaseContext());
    container.addView(surfaceView);
    mRtcEngine.setupLocalVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0));
}

/**
 * Initializes the local video view and sets the display properties.
 * This method adds a SurfaceView to the local video container and configures it.
 */
private fun setupLocalVideo() {
    val container: FrameLayout = findViewById(R.id.local_video_view_container)
    val surfaceView = SurfaceView(baseContext)
    container.addView(surfaceView)
    mRtcEngine.setupLocalVideo(VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0))
}

Display remote video

When a remote user joins the channel, call setupRemoteVideo and pass in the remote user's uid, obtained from the onUserJoined callback, to display the remote video.

private void setupRemoteVideo(int uid) {
    FrameLayout container = findViewById(R.id.remote_video_view_container);
    SurfaceView surfaceView = new SurfaceView(getBaseContext());
    surfaceView.setZOrderMediaOverlay(true);
    container.addView(surfaceView);
    mRtcEngine.setupRemoteVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid));
}

private fun setupRemoteVideo(uid: Int) {
    val container = findViewById<FrameLayout>(R.id.remote_video_view_container)
    val surfaceView = SurfaceView(baseContext).apply {
        setZOrderMediaOverlay(true)
    }
    container.addView(surfaceView)
    mRtcEngine.setupRemoteVideo(VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid))
}

Handle permissions

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

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

   <uses-feature android:name="android.hardware.camera" android:required="false" />
   <!--Required permissions-->
   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.CAMERA"/>
   <uses-permission android:name="android.permission.RECORD_AUDIO"/>
   <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
   <!--Optional permissions-->
   <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 Video 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.0 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 Video Calling. In your MainActivity file, add the following code:

private static final int PERMISSION_REQ_ID = 22;

    private void requestPermissions() {
        ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID);
    }
    private boolean checkPermissions() {
        for (String permission : getRequiredPermissions()) {
            if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) {
                return false;
            }
        }
        return true;
    }
    private String[] getRequiredPermissions() {
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S) {
            return new String[]{
                Manifest.permission.RECORD_AUDIO,
                Manifest.permission.CAMERA,
                Manifest.permission.READ_PHONE_STATE,
                Manifest.permission.BLUETOOTH_CONNECT
            };
        } else {
            return new String[]{
                Manifest.permission.RECORD_AUDIO,
                Manifest.permission.CAMERA
            };
        }
    }
    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults);
        if (requestCode == PERMISSION_REQ_ID && checkPermissions()) {
            startVideoCalling();
        }
    }

private val PERMISSION_REQ_ID = 22

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

    private fun checkPermissions(): Boolean {
        for (permission in getRequiredPermissions()) {
            if (ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED) {
                return false
            }
        }
        return true
    }

    private fun getRequiredPermissions(): Array<String> {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            arrayOf(
                Manifest.permission.RECORD_AUDIO,
                Manifest.permission.CAMERA,
                Manifest.permission.READ_PHONE_STATE,
                Manifest.permission.BLUETOOTH_CONNECT
            )
        } else {
            arrayOf(
                Manifest.permission.RECORD_AUDIO,
                Manifest.permission.CAMERA
            )
        }
    }

    override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<out String>,
        grantResults: IntArray
    ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        if (requestCode == PERMISSION_REQ_ID && checkPermissions()) {
            startVideoCalling()
        }
    }

Start and close the app

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

1. In the onCreate callback, check whether the client 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()) {
            startVideoCalling();
        } else {
            requestPermissions();
        }
    }

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

2. When a user closes the client, or switches the client to the background, call stopPreview to stop the video preview and then call leaveChannel to leave the current channel and release all session-related resources.

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

private fun cleanupAgoraEngine() {
        mRtcEngine?.apply {
            stopPreview()
            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

To connect the sample code to your existing UI, ensure that your XML layout includes the container UI element IDs used to Display the local video and Display remote video.

Alternatively, use the following sample code to generate a basic user interface. Replace the existing content in /app/src/main/res/layout/activity_main.xml with this code.

Sample code to create the user interface

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <FrameLayout
        android:id="@+id/local_video_view_container"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:background="@android:color/white" />

    <FrameLayout
        android:id="@+id/remote_video_view_container"
        android:layout_width="160dp"
        android:layout_height="160dp"
        android:layout_marginEnd="16dp"
        android:layout_marginTop="16dp"
        android:background="@android:color/darker_gray"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

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 recording and camera permissions. If you set the user role to host, you will see yourself in the local view.

6. On a second Android device, repeat the previous steps to install and launch the client. 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 see and hear each other.
   • If one user joins as host and the other as audience, the host can see themselves in the local video window; the audience can see the host in the remote video window and hear the host.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects of 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.

API reference

• RtcEngineConfig

• create

• ChannelMediaOptions

• joinChannel

• enableVideo

• startPreview

• leaveChannel

• IRtcEngineEventHandler

Frequently asked questions

• How can I fix black screen issues?

• Why can't I turn on the camera?

• 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

• SDK error codes
• Connection status management

This page provides a step-by-step guide on how to create a basic Video Calling app using the Agora Video SDK.

Understand the tech

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

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

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

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

Prerequisites

• A camera and a microphone.
• A valid Agora account and project. See Agora account management for details.
• Xcode 13.0 or higher.
• An Apple developer account.
• If you use CocoaPods to integrate the SDK, make sure CocoaPods is installed.
• Two devices running iOS 14.0 or higher.

Set up your project

Install the SDK

Use one of the following methods to install the Video SDK.

Implement Video Calling

This section guides you through the implementation of basic real-time audio and video 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 UIKit
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 initializeAgoraVideoSDK() {
    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 Video 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

// Join the channel with specified options
func joinChannel() {
    let options = AgoraRtcChannelMediaOptions()
    // In video calling, set the channel use-case to communication
    options.channelProfile = .communication
    // Set the user role as broadcaster (default is audience)
    options.clientRoleType = .broadcaster
    // Publish audio captured by microphone
    options.publishMicrophoneTrack = true
    // Publish video captured by camera
    options.publishCameraTrack = true
    // Auto subscribe to all audio streams
    options.autoSubscribeAudio = true
    // Auto subscribe to all video streams
    options.autoSubscribeVideo = true
    // Use a temporary Token to join the channel
    agoraKit.joinChannel(
        byToken: token,
        channelId: channelName,
        uid: 0,
        mediaOptions: options
    )
}

Subscribe to Video SDK events

The Video 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) {
        setupRemoteVideo(uid: uid, view: remoteView)
    }
    // Triggered when a remote user leaves the channel
    func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) {
        setupRemoteVideo(uid: uid, view: nil)
    }
}

To learn about the other SDK events, see AgoraRtcEngineDelegate.

Enable the video module

Follow the steps below to set up the video module.

1. To enable the video module, call enableVideo.

2. To enable local video preview, call startPreview.

   // Enable video functionality (audio is enabled by default)
   agoraKit.enableVideo()
   // Enable local video preview
   agoraKit.startPreview()

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 Video Calling 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 Video Calling. When the user closes the app, it leaves the channel and ends Video Calling.

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

   // Initialize the Agora engine
   initializeAgoraVideoSDK()
   // Start the local video preview
   setupLocalVideo()
   // Join an Agora channel
   joinChannel()

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

   // Stop local video preview
   agoraKit.stopPreview()
   // 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

To connect the sample code to your existing UI, ensure that your ViewController.swift file includes the UIViews used to Display the local video and Display remote video.

Alternatively, use the following sample code to generate a basic user interface. To use this interface, replace the contents of the ViewController.swift file with the following code:

Sample code to create the user interface

// ViewController.swift
import UIKit

class ViewController: UIViewController {

    // UI view for displaying the local video stream
    var localView: UIView!
    // UI view for displaying the remote video stream
    var remoteView: UIView!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Set up the user interface
        setupUI()
    }

    // Sets up the UI layout for local and remote video views
    func setupUI() {
        // Create the local video view covering the full screen
        localView = UIView(frame: UIScreen.main.bounds)

        // Create the remote video view positioned in the top-right corner
        remoteView = UIView(frame: CGRect(x: self.view.bounds.width - 135, y: 50, width: 135, height: 240))

        // Add video views to the main view
        self.view.addSubview(localView)
        self.view.addSubview(remoteView)
    }
}

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 and camera.

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 Video Calling device, repeat the previous steps to install and launch the client. 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 see and hear each other.
   • If one user joins as host and the other as audience, the host can see themselves in the local video window; the audience can see the host in the remote video window and hear the host.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects of 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 an open source sample project on GitHub for your reference. Download it or view the source code for a more detailed example.

Add a privacy manifest file

The Agora Video SDK for Video Calling 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 the SDK PrivacyInfo.xcprivacy file to your app PrivacyInfo.xcprivacy file 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
• enableVideo
• startPreview
• leaveChannel
• enableMultiCamera
• AgoraRtcEngineDelegate

Frequently asked questions

• How can I fix black screen issues?
• Why can't I turn on the camera?
• 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?
• How can I add a privacy manifest to my iOS app?

See also

• SDK error codes
• Connection status management

This page provides a step-by-step guide on how to create a basic Video Calling app using the Agora Video SDK.

Understand the tech

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

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

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

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

Prerequisites

• A camera and a microphone.
• A valid Agora account and project. See Agora account management for details.
• Xcode 13.0 or higher.
• An Apple developer account.
• If you use CocoaPods to integrate the SDK, make sure CocoaPods is installed.
• Two devices running macOS 10.10 or higher.

Set up your project

Install the SDK

Use one of the following methods to install the Video SDK.

Implement Video Calling

This section guides you through the implementation of basic real-time audio and video 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 Cocoa
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 initializeAgoraVideoSDK() {
    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 Video 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

// Join the channel with specified options
func joinChannel() {
    let options = AgoraRtcChannelMediaOptions()
    // In video calling, set the channel use-case to communication
    options.channelProfile = .communication
    // Set the user role as broadcaster (default is audience)
    options.clientRoleType = .broadcaster
    // Publish audio captured by microphone
    options.publishMicrophoneTrack = true
    // Publish video captured by camera
    options.publishCameraTrack = true
    // Auto subscribe to all audio streams
    options.autoSubscribeAudio = true
    // Auto subscribe to all video streams
    options.autoSubscribeVideo = true
    // Use a temporary Token to join the channel
    agoraKit.joinChannel(
        byToken: token,
        channelId: channelName,
        uid: 0,
        mediaOptions: options
    )
}

Subscribe to Video SDK events

The Video 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) {
        setupRemoteVideo(uid: uid, view: remoteView)
    }
    // Triggered when a remote user leaves the channel
    func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) {
        setupRemoteVideo(uid: uid, view: nil)
    }
}

To learn about the other SDK events, see AgoraRtcEngineDelegate.

Enable the video module

Follow the steps below to set up the video module.

1. To enable the video module, call enableVideo.

2. To enable local video preview, call startPreview.

   // Enable video functionality (audio is enabled by default)
   agoraKit.enableVideo()
   // Enable local video preview
   agoraKit.startPreview()

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 Video Calling 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 Video Calling. When the user closes the app, it leaves the channel and ends Video Calling.

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

   // Initialize the Agora engine
   initializeAgoraVideoSDK()
   // Start the local video preview
   setupLocalVideo()
   // Join an Agora channel
   joinChannel()

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

   // Stop local video preview
   agoraKit.stopPreview()
   // 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

To connect the sample code to your existing UI, ensure that your ViewController.swift file includes the UIViews used to Display the local video and Display remote video.

Alternatively, use the following sample code to generate a basic user interface. To use this interface, replace the contents of the ViewController.swift file with the following code:

Sample code to create the user interface

import Cocoa
import AgoraRtcKit

// ViewController.swift

class ViewController: NSViewController {

    // UI view for displaying the local video stream
    var localView: NSView!
    // UI view for displaying the remote video stream
    var remoteView: NSView!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Set up the user interface
        setupUI()
    }

    func setupUI() {
        guard let screenFrame = NSScreen.main?.frame else { return } // Ensure screen is available

        // Create the local video view covering the full screen
        localView = NSView(frame: screenFrame)

        // Create the remote video view positioned in the top-right corner
        remoteView = NSView(frame: CGRect(x: self.view.bounds.width - 135, y: 50, width: 250, height: 250))

        // Add video views to the main view
        self.view.addSubview(localView)
        self.view.addSubview(remoteView)
    }
}

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 and camera.

4. On a second Video Calling device, repeat the previous steps to install and launch the client. 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 see and hear each other.
   • If one user joins as host and the other as audience, the host can see themselves in the local video window; the audience can see the host in the remote video window and hear the host.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects of 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.

API reference

• sharedEngine
• joinChannel
• enableVideo
• startPreview
• leaveChannel
• AgoraRtcEngineDelegate

Frequently asked questions

• How can I fix black screen issues?
• Why can't I turn on the camera?
• 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?

See also

• SDK error codes
• Connection status management

This page provides a step-by-step guide on how to create a basic Video Calling app using the Agora Video SDK.

Understand the tech

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

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

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

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

Prerequisites

• A camera and a microphone.
• A valid Agora account and project. See Agora account management for details.
• A supported browser. Agora strongly recommends using the latest stable version of Google Chrome.
• Node.js and npm

Set up your project

Install the SDK

Add the Video SDK to your project:

npm install agora-rtc-sdk-ng

Implement Video Calling

This section guides you through the implementation of basic real-time audio and video 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 and Video encoding format based on your use case.

For Video 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 a channel and publish local media
async function joinChannel() {
    await client.join(appId, channel, token, uid);
    await createLocalMediaTracks();
    displayLocalVideo();
    publishLocalTracks();
}

Create local media tracks

To set up the necessary local media tracks:

• Call createMicrophoneAudioTrack to create a local audio track.
• Call createCameraVideoTrack to create a local Video track.

// Declare variables for local tracks
let localAudioTrack = null;
let localVideoTrack = null;

// Create local audio and video tracks
async function createLocalMediaTracks() {
    localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack();
    localVideoTrack = await AgoraRTC.createCameraVideoTrack();
}

Publish local media tracks

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

async function publishLocalTracks() {
    await client.publish([localAudioTrack, localVideoTrack]);
}

See Local audio and video 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() {
    // Declare event handler for "user-published"
    client.on("user-published", async (user, mediaType) => {
        // Subscribe to media streams
        await client.subscribe(user, mediaType);
        if (mediaType === "video") {
            // Specify the ID of the DOM element or pass a DOM object.
            user.videoTrack.play("<Specify a DOM element>");
        }
        if (mediaType === "audio") {
            user.audioTrack.play();
        }
    });

    // Handle the "user-unpublished" event to unsubscribe from the user's media tracks
    client.on("user-unpublished", async (user) => {
        const remotePlayerContainer = document.getElementById(user.uid);
        remotePlayerContainer && remotePlayerContainer.remove();
    });
}

• After successfully unsubscribing, the SDK releases the corresponding RemoteTrack object. This automatically removes the video playback element and stops audio playback.
• If a remote user actively stops publishing, the local user receives the user-unpublished callback. Upon receiving this callback, the SDK automatically releases the corresponding RemoteTrack object, so you do not need to call unsubscribe again.
• The unsubscribe method is asynchronous and should be used with Promise or async/await.

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

Display the local video

To play the local video, use the play method of the local video track. Pass an element ID or a DOM element from your UI where you want to render the video.

// Display local video
function displayLocalVideo() {
    const localPlayerContainer = document.createElement("div");
    localPlayerContainer.id = uid;
    localPlayerContainer.textContent = `Local user ${uid}`;
    localPlayerContainer.style.width = "640px";
    localPlayerContainer.style.height = "480px";
    document.body.append(localPlayerContainer);
    localVideoTrack.play(localPlayerContainer);
}

Display remote video

To display the remote video, call the play method of the remote user's videoTrack and pass in either the element ID or a DOM element from your UI where you want to render the video.

// Display remote user's video
function displayRemoteVideo(user) {
    const remotePlayerContainer = document.createElement("div");
    remotePlayerContainer.id = user.uid.toString();
    remotePlayerContainer.textContent = `Remote user ${user.uid}`;
    remotePlayerContainer.style.width = "640px";
    remotePlayerContainer.style.height = "480px";
    document.body.append(remotePlayerContainer);
    user.videoTrack.play(remotePlayerContainer);
}

Leave the channel

To exit the channel, close local audio and video tracks and call leave.

// Leave the channel and clean up
async function leaveChannel() {
    // Stop the local media tracks to release the microphone and camera resources
    if (localAudioTrack) {
        localAudioTrack.close();
        localAudioTrack = null;
    }
    if (localVideoTrack) {
        localVideoTrack.close();
        localVideoTrack = null;
    }
    // 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>Web SDK Video Quickstart</title>
</head>
<body>
    <h2 class="left-align">Web SDK Video 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 client. 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.

      Information

      • Run the web app on a local server (localhost) for testing purposes only. When deploying to a production environment, use the HTTPS protocol.
      • Due to browser security policies that restrict HTTP addresses to 127.0.0.1, the Agora Web SDK only supports HTTPS protocol and http://localhost (http://127.0.0.1). Please do not use the HTTP protocol to access your project, except for http://localhost (http://127.0.0.1).

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects of 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

• Build a NextJS Video Call App

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

API reference

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

Channel modes

The Video 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 and video, but audience cannot send and may only receive audio and video. You can specify user roles by setting the parameters createClient of role, or you can call setClientRole to dynamically modify user roles.

Video encoding formats

You can set the codec parameter in the createClient method to the following video encoding formats:

• vp8 (VP8)
• h264 (H.264)
• vp9 (VP9)

This setting only affects the video encoding format of the host. For the audience, as long as their device and browser support the decoding of this format, the subscription can be completed normally.

Support for these formats may vary across browsers and devices. The following table lists the codec formats supported by different browsers for reference:

Local audio and video 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 and LocalVideoTrack 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.

There are two main types of local tracks: LocalAudioTrack and LocalVideoTrack for publishing audio and video, respectively. Each type of LocalTrack comes with its own set of tools. For example, LocalAudioTrack lets you control the volume, while LocalVideoTrack has functions for customizing video.

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

The following diagram shows the relationship between the LocalTrack classes:

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 Video 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

• SDK error codes

This page provides a step-by-step guide on how to create a basic Video Calling app using the Agora Video SDK.

Understand the tech

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

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

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

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

Prerequisites

• A camera and a microphone.
• A valid Agora account and project. See Agora account management for details.
• A device running Windows 7 or higher.
• Microsoft Visual Studio 2017 or higher with C++ desktop development support and C++ 11 or above.
• If you use C# for development, you also need the .NET Framework.

Set up your project

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

   A basic UI consists of the following controls:

   • A Picture Control for displaying local video
   • A Picture Control for displaying remote video
   • An Edit Control for entering a channel name
   • Buttons to join and leave a channel

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

Install the SDK

Install the Agora Video 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 Video Calling

This section guides you through the implementation of basic real-time audio and video 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) {
        // Enable the video module
        m_rtcEngine->enableVideo();
    } else {
        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 Video Calling, set the channelProfile to CHANNEL_PROFILE_COMMUNICATION and the clientRoleType to CLIENT_ROLE_BROADCASTER.

void CAgoraQuickStartDlg::joinChannel(const char* token, const char* channelName) {
    ChannelMediaOptions options;
    // Set the channel profile to live broadcasting
    options.channelProfile = CHANNEL_PROFILE_COMMUNICATION;
    // Set the user role to broadcaster; to set the user role as audience, keep the default value
    options.clientRoleType = CLIENT_ROLE_BROADCASTER;
    // Publish the audio stream captured by the microphone
    options.publishMicrophoneTrack = true;
    // Publish the camera track
    options.publishCameraTrack = true;
    // Automatically subscribe to all audio streams
    options.autoSubscribeAudio = true;
    // Automatically subscribe to all video streams
    options.autoSubscribeVideo = true;
    // Join the channel using the temporary token obtained from the console
    m_rtcEngine->joinChannel(token, channelName, 0, options);
}

Subscribe to Video SDK events

The Video 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
    uid_t remoteUid = wParam;
    if (m_remoteRender) {
        return 0;
    }
    // Render remote view
    VideoCanvas canvas;
    canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN;
    canvas.uid = remoteUid;
    canvas.view = m_staRemote.GetSafeHwnd();
    m_rtcEngine->setupRemoteVideo(canvas);
    m_remoteRender = true;
    return 0;
}

LRESULT CAgoraQuickStartDlg::OnEIDUserOffline(WPARAM wParam, LPARAM lParam) {
    // Remote user left callback
    uid_t remoteUid = wParam;
    if (!m_remoteRender) {
        return 0;
    }
    // Clear remote view
    VideoCanvas canvas;
    canvas.uid = remoteUid;
    m_rtcEngine->setupRemoteVideo(canvas);
    m_remoteRender = false;
    return 0;
}

Enable the video module

Call the enableVideo method to enable the video module.

// Enable the video module
m_rtcEngine->enableVideo();

Display the local video

Follow these steps to set up and start the local video preview:

1. Create a VideoCanvas instance and configure its properties:

   1. Set the video rendering mode.
   2. Specify the user ID (uid).
   3. Define the display window.

2. Call the setupLocalVideo method to apply the VideoCanvas configuration.

3. Call the startPreview method to start the local video preview.

   void CAgoraQuickStartDlg::setupLocalVideo() {
       // Set local video display properties
       VideoCanvas canvas;
       // Set video to be scaled proportionally
       canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN;
       // User ID
       canvas.uid = 0;
       // Video display window
       canvas.view = m_staLocal.GetSafeHwnd();
       m_rtcEngine->setupLocalVideo(canvas);
       // Preview the local video
       m_rtcEngine->startPreview();
   }

Display remote video

To display the remote user's video:

1. Define the video display properties using VideoCanvas.

2. Call setupRemoteVideo to render the video.

   void CAgoraQuickStartDlg::setupRemoteVideo(uid_t remoteUid) {
       // Set remote video display properties
       VideoCanvas canvas;
       // Set video size to be proportionally scaled
       canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN;
       // Remote user ID
       canvas.uid = remoteUid;
       // You can only choose to set either view or surfaceTexture. If both are set, only the settings in view take effect.
       canvas.view = m_staRemote.GetSafeHwnd();
       m_rtcEngine->setupRemoteVideo(canvas);
       m_remoteRender = true;
       return 0;
   }

Leave the channel

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

To stop the local video preview and clear the view:

1. Call stopPreview to stop playing the local video.

2. Call setupLocalVideo, passing an empty VideoCanvas to reset the view.

   void CAgoraQuickStartDlg::LeaveChannel() {
       if (m_rtcEngine) {
           // Stop local video preview
           m_rtcEngine->stopPreview();
           // Leave the channel
           m_rtcEngine->leaveChannel();
           // Clear local view
           VideoCanvas canvas;
           canvas.uid = 0;
           m_rtcEngine->setupLocalVideo(canvas);
           m_remoteRender = false;
       }
   }

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

To connect the sample code to your existing user interface, ensure that your UI includes the controls used to Display the local video and Display remote video.

Alternatively, follow these steps to create a bare-bones UI for your project.

Steps to create a minimalistic UI

1. Switch the project to resource view in the right menu bar, and then open the .Dialog file.

2. From View > Toolbox, select Add Picture Control, and in Properties > Miscellaneous, set the ID of the control to IDC_STATIC_REMOTE.

3. From View > Toolbox , select Add Picture Control , and in Properties > Miscellaneous , set the control's ID to IDC_STATIC_LOCAL.

4. To set up an input box for entering the channel name, from View > Toolbox , select add Static Text control, and change the description text to Channel name in the properties. Add an Edit Control as an input box, and in Properties > Miscellaneous, set the control's ID to IDC_EDIT_CHANNEL.

5. To add join and leave channel buttons, open View > Toolbox and add two Button controls. In Properties > Miscellaneous , set the IDs to ID_BTN_JOIN and ID_BTN_LEAVE, and set the description text to Join and Leave respectively. Your user interface looks similar to the following:

   

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

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.

   You see yourself in the local view.

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 see and hear each other.
   • If one user joins as host and the other as audience, the host can see themselves in the local video window; the audience can see the host in the remote video window and hear the host.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects of 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

• enableVideo

• startPreview

• leaveChannel

• release

Frequently asked questions

• How can I fix black screen issues?

• Why can't I turn on the camera?

• 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

• SDK error codes
• Connection status management

This page provides a step-by-step guide on how to create a basic Video Calling app using the Agora Video SDK.

Understand the tech

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

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

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

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

Prerequisites

• A camera and a microphone.
• A valid Agora account and project. See Agora account management for details.
• Node.js 14 or higher.

Set up your project

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.

   A basic user interface consists of an element for local video and an element for remote video. Refer to Create a user interface to get a bare bones sample layout.

Install the SDK

Implement Video Calling

This section guides you through the implementation of basic real-time audio and video 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 camera or microphone. Use Electron’s askForMediaAccess method to request these permissions from the user.

Add the following code to the main.js file:

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

    // Check and request microphone permission
    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 Video SDK. Add the following code to renderer.js:

const {
    createAgoraRtcEngine,
    ChannelProfileType,
    ClientRoleType,
    VideoSourceType,
    VideoViewSetupMode
} = 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 }
});

Enable the video module

Call the enableVideo method to enable the video module, and then call startPreview to start the local video preview.

// Enable the video module
rtcEngine.enableVideo();
// Start the local video preview
rtcEngine.startPreview();

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 Video 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,
    // Publish video collected from the camera
    publishCameraTrack: true,
    // Automatically subscribe to all audio streams
    autoSubscribeAudio: true,
    // Automatically subscribe to all video streams
    autoSubscribeVideo: true,
});

Register event handlers

Call the registerEventHandler method to register the following callback events:

• onJoinChannelSuccess: Triggered when the local user successfully joins a channel. After joining, call setupLocalVideo to configure the local video window.
• onUserJoined: Triggered when a remote user joins the current channel. After the remote user joins, call setupRemoteVideo to configure the remote video window.
• onUserOffline: Triggered when a remote user leaves the current channel. After the remote user leaves, call setupRemoteVideo to close the remote video window.

const EventHandles = {
    // Listen for the local user joining the channel
    onJoinChannelSuccess: ({ channelId, localUid }, elapsed) => {
        console.log('Successfully joined channel: ' + channelId);
        // After the local user joins the channel, set up the local video view
        rtcEngine.setupLocalVideo({
             sourceType: VideoSourceType.VideoSourceCameraPrimary,
             uid: uid,
             view: localVideoContainer,
             setupMode: VideoViewSetupMode.VideoViewSetupAdd,
        });
    },

    // Listen for remote users joining the channel
    onUserJoined: ({ channelId, localUid }, remoteUid, elapsed) => {
        console.log('Remote user ' + remoteUid + ' joined');
        // After a remote user joins the channel, set up the remote video view
        rtcEngine.setupRemoteVideo(
            {
                sourceType: VideoSourceType.VideoSourceRemote,
                uid: remoteUid,
                view: remoteVideoContainer,
                setupMode: VideoViewSetupMode.VideoViewSetupAdd,
            },
            { channelId },
        );
    },

    // Listen for users leaving the channel
    onUserOffline: ( { channelId, localUid }, remoteUid, reason ) => {
        console.log('Remote user ' + remoteUid + ' left the channel');
        // After a remote user leaves the channel, remove the remote video view
        rtcEngine.setupRemoteVideo(
            {
                sourceType: VideoSourceType.VideoSourceRemote,
                uid: remoteUid,
                view: remoteVideoContainer,
                setupMode: VideoViewSetupMode.VideoViewSetupRemove,
            },
        );
    },
};

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