Quickstart

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

Understand the tech

To start a Broadcast Streaming 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.

  • Join as a host: A live streaming event has one or more hosts. A host publishes audio and video to the channel. Hosts can also subscribe to streams from other hosts.

  • Join as audience: Audience members can only subscribe to streams published by hosts.

• Send and receive audio and video: Hosts publish streams to the channel. Audience members subscribe to audio and video streams published by hosts.

Prerequisites

• Android Studio 4.2 or higher.

• Android SDK API Level 21 or higher.

• Two mobile devices running Android 5.0 or higher.

• A camera and 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 Video SDK.

Create a new project

1. Create a new project.

   1. Open Android Studio and select File > New > New Project....

   2. Select Phone and Tablet > Empty Activity and click Next.

   3. Set the project name and storage path.

   4. Select Java or Kotlin as the language, and click Finish to create the Android project.

      After you create a project, Android Studio automatically starts gradle sync. Ensure that the synchronization is successful before proceeding to the next step.

Add to an existing project

1. Add a new activity to your project.

   1. Open your project in Android Studio.
   2. Right-click on the app/src/main/java/<your.package.name> folder.
   3. Select New → Activity → Empty Activity.
   4. Enter an activity name and click Finish. This guide uses MainActivity as the activity name in the sample code. Replace it with your activity name where required.

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.

Maven Central

1. Open the settings.gradle file in the project's root directory and add the Maven Central dependency, if it doesn't already exist:

   repositories {
     mavenCentral()
   }

2. To integrate the Video SDK into your Android project, add the following to the dependencies block in your project module build.gradle file:

   • Groovy build.gradle

     implementation 'io.agora.rtc:full-sdk:x.y.z'

   • Kotlin build.gradle.kts

     implementation("io.agora.rtc:full-sdk:x.y.z")

   Replace x.y.z with the specific SDK version number, such as 4.5.0.

3. Prevent code obfuscation

Open the /app/proguard-rules.pro file and add the following lines to prevent the Video SDK code from being obfuscated:

-keep class io.agora.** { *; }
  -dontwarn io.agora.**

Manual integration

1. Download the latest version of Video SDK from the SDKs page and unzip it.

2. Open the unzipped file and copy the following files or subfolders to your project path.

3. Select the file /app/libs/agora-rtc-sdk.jar in the left navigation bar of Android Studio project files, right-click, and select add as a library from the drop-down menu.

4. Prevent code obfuscation

Open the /app/proguard-rules.pro file and add the following lines to prevent the Video SDK code from being obfuscated:

-keep class io.agora.** { *; }
  -dontwarn io.agora.**

Implement Broadcast Streaming

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 Broadcast Streaming, set the channelProfile to CHANNEL_PROFILE_LIVE_BROADCASTING, the clientRoleType to CLIENT_ROLE_BROADCASTER (host) or CLIENT_ROLE_AUDIENCE, and the audienceLatencyLevel to AUDIENCE_LATENCY_LEVEL_LOW_LATENCY.

// 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() {
  // Create an instance of ChannelMediaOptions and configure it
  ChannelMediaOptions options = new ChannelMediaOptions();
  // Set the user role to BROADCASTER or AUDIENCE according to the use-case
  options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER;
  // In the broadcast streaming use-case, set the channelProfile to BROADCASTING
  options.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING;
  // Set the latency level for audience
  options.audienceLatencyLevel = Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY;
  // Publish local media
  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() {
  // Create an instance of ChannelMediaOptions and configure it
  val options = ChannelMediaOptions().apply {
    // Set the user role to BROADCASTER or AUDIENCE according to the use-case
    clientRoleType = Constants.CLIENT_ROLE_BROADCASTER
    // In the broadcast streaming use-case, set the channelProfile to BROADCASTING
    channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING
    // Set the latency level for audience
    audienceLatencyLevel = Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY
    // Publish local media
    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 camera and 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>:

   <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 Broadcast Streaming. In your MainActivity file, add the following code:

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) {
    if (requestCode == PERMISSION_REQ_ID && checkPermissions()) {
      startBroadcastStreaming();
    }
  }

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()) {
      startBroadcastStreaming()
    }
  }

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()) {
      startBroadcastStreaming();
    } else {
      requestPermissions();
    }
  }

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

2. When a user closes the app, or switches the app 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 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 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 to this product.

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

Next steps

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

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

Sample project

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

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

• Error codes

• Connection status management

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

Understand the tech

To start a Broadcast Streaming 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.

  • Join as a host: A live streaming event has one or more hosts. A host publishes audio and video to the channel. Hosts can also subscribe to streams from other hosts.

  • Join as audience: Audience members can only subscribe to streams published by hosts.

• Send and receive audio and video: Hosts publish streams to the channel. Audience members subscribe to audio and video streams published by hosts.

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

Create a new project Follow these steps to create a project in Xcode:

1. Refer to Create a project. Under Application select App. Use Storyboard for the user interface and choose Swift as the programming language.

   If you have not added the development team information, you see the Add account... button. Click the button and follow the on-screen prompts to log in to your Apple ID. Once login is complete, click Next, and choose your Apple account as the development team.

2. Set up automatic signing for your projects.

3. Set the target devices where your app will be deployed.

4. Create a user interface for your app. Refer to Create a user interface to create a bare bones UI.

Add to an existing project Follow these steps to add Broadcast Streaming to your Xcode project:

1. Open your project in Xcode.

2. Set the target devices where your app will be deployed.

3. Create a user interface for your app. Refer to Create a user interface to create a bare bones UI.

Install the SDK

Use one of the following methods to install Video SDK.

Swift Package Manager

1. In Xcode, go to File > Add Package Dependencies.

2. In the search bar, past the following URL:

   {`https://github.com/AgoraIO/AgoraRtcEngine_iOS.git`}

3. Click Add Package, select the latest version, and click Next.

4. For basic Broadcast Streaming, select RtcBasic.

   If needed, also select:

   • SpatialAudio for spatial audio effects.
   • VirtualBackground for virtual background.

5. Under Add to Target, select your project and click Add Package.

   For further information, refer to Apple's official documentation.

CocoaPods

1. Go to the project root directory in the terminal and run the pod init command. A text file named Podfile is generated in the project folder.

2. Open Podfile and modify the content as follows. Replace Your App with your target name.

   platform :ios, '9.0'
     target 'Your App' do
      # For x.y.z fill in the specific SDK version number, such as 4.4.0.
      # Integrate the Full SDK
      pod 'AgoraRtcEngine_iOS', 'x.y.z'
   
      # To integrate the Lite SDK, use the following line instead
      # pod 'AgoraLite_iOS', '4.4.0'
     end

   Obtain the latest version number from the release notes.

3. Run the pod install command in the terminal to install the Video SDK. After successful installation, the terminal shows Pod installation complete!.

4. After successful installation, a file with the suffix .xcworkspace is generated in the project folder. Open the file through Xcode for subsequent operations.

Manual integration

1. Download the latest version of the SDK from SDKs download and extract the contents.

2. Copy the files in the libs folder of the SDK package to your project directory.

3. Open Xcode and add the corresponding dynamic library. Make sure the Embed property of the added dynamic library is set to Embed & Sign.

   Agora SDK uses libc++ (LLVM) by default. If you need to use libstdc++ (GNU), please contact support@agora.io. The library provided by the SDK is a FAT Image, which includes 32/64-bit simulator and 32/64-bit real machine versions.

Implement Broadcast Streaming

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 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 Broadcast Streaming, set the channelProfile to .liveBroadcasting, the clientRoleType to .broadcaster (host) or .audience, and the audienceLatencyLevel to lowLatency.

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 a live streaming use-case, set the channel use-case to liveBroadcasting
  options.channelProfile = .liveBroadcasting
  // 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
  // Set the audience latency level
  options.audienceLatencyLevel = .lowLatency
  // Use a temporary Token to join the channel
  agoraKit.joinChannel(
    byToken: token,
    channelId: channelName,
    uid: 0,
    mediaOptions: options
  )
}

You can also set the latency level after joining a channel by calling the setClientRole method with role set to AgoraClientRole.audience and options.audienceLatencyLevel set to lowLatency.

// Set the user role to audience
let role = AgoraClientRole.audience
let options = AgoraClientRoleOptions()
// Set the low latency level
options.audienceLatencyLevel = .lowLatency

agoraKit.setClientRole(role, options: 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 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 Broadcast Streaming. When the user closes the app, it leaves the channel and ends Broadcast Streaming.

1. To start Broadcast Streaming, 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 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 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 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 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 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:

2. Choose File > New File.

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

4. Click Next.

5. Check your app in the Targets list.

6. Click Create.

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

7. Add the items in PrivacyInfo.xcprivacy file of the Video 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

• 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?

• 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 page provides a step-by-step guide on how to create a basic Broadcast Streaming app using the Agora Video SDK.

Understand the tech

To start a Broadcast Streaming 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.

  • Join as a host: A live streaming event has one or more hosts. A host publishes audio and video to the channel. Hosts can also subscribe to streams from other hosts.

  • Join as audience: Audience members can only subscribe to streams published by hosts.

• Send and receive audio and video: Hosts publish streams to the channel. Audience members subscribe to audio and video streams published by hosts.

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

Create a new project Follow these steps to create a project in Xcode:

1. Refer to Create a project. Under Application select App. Use Storyboard for the user interface and choose Swift as the programming language.

   If you have not added the development team information, you see the Add account... button. Click the button and follow the on-screen prompts to log in to your Apple ID. Once login is complete, click Next, and choose your Apple account as the development team.

2. Set up automatic signing for your projects.

3. Set the target devices where your app will be deployed.

4. Create a user interface for your app. Refer to Create a user interface to create a bare bones UI.

Add to an existing project Follow these steps to add Broadcast Streaming to your Xcode project:

1. Open your project in Xcode.

2. Set the target devices where your app will be deployed.

3. Create a user interface for your app. Refer to Create a user interface to create a bare bones UI.

Install the SDK

Use one of the following methods to install Video SDK.

Swift Package Manager

1. In Xcode, go to File > Add Package Dependencies.

2. In the search bar, past the following URL:

   {`https://github.com/AgoraIO/AgoraRtcEngine_macOS.git`}

3. Click Add Package, select the latest version, and click Next.

4. For basic Broadcast Streaming, select RtcBasic.

   If needed, also select:

   • SpatialAudio for spatial audio effects.
   • VirtualBackground for virtual background.

5. Under Add to Target, select your project and click Add Package.

   For further information, refer to Apple's official documentation.

CocoaPods

1. Go to the project root directory in the terminal and run the pod init command. A text file named Podfile is generated in the project folder.

2. Open Podfile and modify the content as follows. Replace Your App with your target name.

   platform :macos, '10.11'
     target 'Your App' do
      # For x.y.z fill in the specific SDK version number, such as 4.4.0.
      pod 'AgoraRtcEngine_macOS', 'x.y.z'
     end

   Obtain the latest version number from the release notes.

3. Run the pod install command in the terminal to install the Video SDK. After successful installation, the terminal shows Pod installation complete!.

4. After successful installation, a file with the suffix .xcworkspace is generated in the project folder. Open the file through Xcode for subsequent operations.

Manual integration

1. Download the latest version of the SDK from SDKs download and extract the contents.

2. Copy the files in the libs folder of the SDK package to your project directory.

3. Open Xcode and add the corresponding dynamic library. Make sure the Embed property of the added dynamic library is set to Embed & Sign.

   Agora SDK uses libc++ (LLVM) by default. If you need to use libstdc++ (GNU), please contact support@agora.io. The library provided by the SDK is a FAT Image, which includes 32/64-bit simulator and 32/64-bit real machine versions.

Implement Broadcast Streaming

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 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 Broadcast Streaming, set the channelProfile to .liveBroadcasting, the clientRoleType to .broadcaster (host) or .audience, and the audienceLatencyLevel to lowLatency.

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 a live streaming use-case, set the channel use-case to liveBroadcasting
  options.channelProfile = .liveBroadcasting
  // 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
  // Set the audience latency level
  options.audienceLatencyLevel = .lowLatency
  // Use a temporary Token to join the channel
  agoraKit.joinChannel(
    byToken: token,
    channelId: channelName,
    uid: 0,
    mediaOptions: options
  )
}

You can also set the latency level after joining a channel by calling the setClientRole method with role set to AgoraClientRole.audience and options.audienceLatencyLevel set to lowLatency.

// Set the user role to audience
let role = AgoraClientRole.audience
let options = AgoraClientRoleOptions()
// Set the low latency level
options.audienceLatencyLevel = .lowLatency

agoraKit.setClientRole(role, options: 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 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 Broadcast Streaming. When the user closes the app, it leaves the channel and ends Broadcast Streaming.

1. To start Broadcast Streaming, 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 Cocoa
import AgoraRtcKit

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 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 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 to this product.

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

Next steps

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

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

Sample project

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

API reference

• sharedEngine

• joinChannel

• enableVideo

• startPreview

• leaveChannel

• AgoraRtcEngineDelegate

See also

• Error codes

• Connection status management

Explore sample implementations to quickly integrate Conversational AI.

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

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

Understand the tech

To start a Broadcast Streaming 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.

  • Join as a host: A live streaming event has one or more hosts. A host publishes audio and video to the channel. Hosts can also subscribe to streams from other hosts.

  • Join as audience: Audience members can only subscribe to streams published by hosts.

• Send and receive audio and video: Hosts publish streams to the channel. Audience members subscribe to audio and video streams published by hosts.

Prerequisites

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

• Node.js and npm

• A camera and 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 Video SDK.

Create a new project To initialize a new Vite project, take the following steps:

1. Open a terminal and run the following command:

   npm create vite@latest agora_web_quickstart -- --template vanilla

This creates a new folder named agora_web_quickstart and initializes a Vite project inside it using the vanilla JavaScript template.

2. Navigate to the newly created folder. Download and set up dependencies for your project:

   cd agora_web_quickstart
   npm install

3. Create a user interface for your project. The UI consists of buttons to join and leave a channel. Refer to Create a user interface to get a bare bones html layout.

Add to an existing project To add Broadcast Streaming to your existing project, take the following steps:

1. Create a JavaScript file in your project's src folder to add AgoraRTCClient code that implements specific application logic.

2. Add an HTML file to your project to create a user interface. The UI consists of buttons to join and leave a channel. Refer to Create a user interface to get a bare bones HTML layout.

3. Include the JavaScript file in your HTML file.

   <script type="module" src="/src/main.js"></script>

Install the SDK

Add the Video SDK to your project:

npm install agora-rtc-sdk-ng

Implement Broadcast Streaming

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

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 Broadcast Streaming Set mode to live.

// RTC client instance
let client = null;

// Initialize the AgoraRTC client
function initializeClient() {
  client = AgoraRTC.createClient({ mode: "live", codec: "vp8", role: "host" });
  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.

When you join as a host, you can publish local media streams in the channel; you can also subscribe to streams published by other hosts. As an audience member, you may only subscribe to media streams published by hosts.

• Join as a host

  // Join as a host
  async function joinChannel() {
    await client.join(appId, channel, token, uid);
    // A host can both publish tracks and subscribe to tracks
    client.setClientRole("host", clientRoleOptions);
    // Create and publish local tracks
    await createLocalMediaTracks();
    await publishLocalTracks();
    displayLocalVideo();
  }

• Join as audience

  To join a channel as an audience member, first call join, then use setClientRole to set the role. Listen for the user-published callback to play the tracks published in the channel.

  // Join as audience
  async function joinAsAudience() {
    await client.join(appId, channel, token, uid);
  
    // Low audience latency level for broadcast streaming
    let clientRoleOptions = { level: 1 };
    // Audience can only subscribe to tracks
    client.setClientRole("audience", clientRoleOptions);
  }

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>Agora Web SDK Quickstart</title>
  </head>
  <body>
    <h2 class="left-align">Agora Web SDK Quickstart</h2>
    <div class="row">
      <div>
        <button type="button" id="host-join">Join as host</button>
        <button type="button" id="audience-join">Join as audience</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:

   • 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; the audience can see the host in the remote video view 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 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

• 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

• Error codes

• Connection status management

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

Understand the tech

To start a Broadcast Streaming 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.

  • Join as a host: A live streaming event has one or more hosts. A host publishes audio and video to the channel. Hosts can also subscribe to streams from other hosts.

  • Join as audience: Audience members can only subscribe to streams published by hosts.

• Send and receive audio and video: Hosts publish streams to the channel. Audience members subscribe to audio and video streams published by hosts.

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

Create a new project The following steps outline the process to set up a new Visual Studio 2022 project on Windows 11 for implementing real-time audio and video interaction functions.

1. In Visual Studio, select File > New > Project to create a new project. In the pop-up window, select MFC application as the project template, click Next, update the project name to AgoraQuickStart, set the project storage location, and then click Create.

2. In the pop-up MFC application window, set the application type to Dialog-based , and set Use MFC to Use MFC in a shared DLL. Enter the generated class, set the generated class to Dlg, set the base class to CDialog, and click Finish.

Add to an existing project To integrate real-time audio and video interaction into your project:

1. Launch Visual Studio 2022 and open your existing project by selecting File > Open > Project/Solution.

2. Navigate to your project directory and open the .sln file.

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 Broadcast Streaming

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 Broadcast Streaming, set the channelProfile to CHANNEL_PROFILE_LIVE_BROADCASTING, the clientRoleType to CLIENT_ROLE_BROADCASTER (host) or CLIENT_ROLE_AUDIENCE, and the audienceLatencyLevel to AUDIENCE_LATENCY_LEVEL_LOW_LATENCY.

void CAgoraQuickStartDlg::joinChannel(const char* token, const char* channelName) {
  ChannelMediaOptions options;
  // Set channel profile to live broadcasting
  options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING;
  // 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;
  // 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;
  // Specify the audio latency level
  options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_LOW_LATENCY;
  // Join the channel using the token and channel name (both are const char*)
  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:

2. Set the video rendering mode.

3. Specify the user ID (uid).

4. Define the display window.

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

6. 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 app 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 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

• 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

• Error codes

• Connection status management

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

Understand the tech

To start a Broadcast Streaming 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.

  • Join as a host: A live streaming event has one or more hosts. A host publishes audio and video to the channel. Hosts can also subscribe to streams from other hosts.

  • Join as audience: Audience members can only subscribe to streams published by hosts.

• Send and receive audio and video: Hosts publish streams to the channel. Audience members subscribe to audio and video streams published by hosts.

Prerequisites

• Node.js 14 or higher.

• A camera and 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 Video 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.

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

npm integration Add the Video SDK to your project using npm:

1. Configure package.json

   • macOS

     {
      "name": "electron-demo-app",
      "version": "0.1.0",
      "author": "your name",
      "description": "My Electron app",
      "main": "main.js",
      "scripts": {
       "start": "electron ."
      },
      "agora_electron": {
       "platform": "darwin",
       "prebuilt": true
      },
      "dependencies": {
       "agora-electron-sdk": "latest"
      },
      "devDependencies": {
       "electron": "latest"
      }
     }

   • Windows

     {
      "name": "electron-demo-app",
      "version": "0.1.0",
      "author": "your name",
      "description": "My Electron app",
      "main": "main.js",
      "scripts": {
       "start": "electron ."
      },
      "agora_electron": {
       "platform": "win32",
       "prebuilt": true,
       "arch": "ia32"
      },
      "dependencies": { "agora-electron-sdk": "latest" },
      "devDependencies": {"electron": "latest" }
     }

     Configuration parameters

     • agora-electron-sdk: Version number of the Agora Electron SDK. Set to latest for the most recent version, or specify a version number. See agora-electron-sdk on npm for available versions.
     • electron: Electron version number. Versions 5.0.0 and above are supported. For macOS devices with M1 chips, use version 11.0.0 or higher.
     • platform (Optional): Target platform. Set to darwin for macOS or win32 for Windows.
     • prebuilt (Optional): Set to true by default to prevent compatibility issues between Electron, Node.js, and the SDK.
     • arch (Optional): Target architecture. Defaults to your system architecture.
   Different versions of Electron have different environment requirements. If you see errors due to a mismatched environment when running the project, refer to the official Electron documentation to choose the appropriate Electron and Node.js versions.

2. To install the dependencies, open a terminal in your project root directory and run the following commands::

   • macOS

     npm install

   • Windows

     npm install -D --arch=ia32 electron
     npm install

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

Implement Broadcast Streaming

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,
  AudienceLatencyLevelType
} = 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;