# 实现音视频互动 (/zh-CN/realtime-media/rtc/get-started/quick-start) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" /> 本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的实时互动 App,适用于互动直播和视频通话场景。首先,你需要了解以下有关音视频实时互动的基础概念: - 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。 - 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。 - 主播:可以在频道内**发布**音视频,同时也可以**订阅**其他主播发布的音视频。 - 观众:可以在频道内**订阅**音视频,不具备**发布**音视频权限。 更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。 下图展示在 App 中实现音视频互动的基本工作流程: 1. 所有用户调用 `joinChannel` 方法加入频道,并根据需要设置用户角色: - 互动直播:如果用户需要在频道中发流,则设为主播;如果用户只需要收流,则设为观众。 - 视频通话:将所有用户的角色都设为主播。 2. 加入频道后,不同角色的用户具备不同的行为: - 所有用户默认都可以接收频道中的音视频流。 - 主播可以在频道内发布音视频流。 - 观众如果需要发流,可在频道内调用 `setClientRole` 方法修改用户角色,使其具备发流权限。 ## 前提条件 [#前提条件] 在实现功能以前,请按照以下要求准备开发环境: - Android Studio 4.1 以上版本。 - Android API 级别 16 或以上。 - 两台运行 Android 4.1 或以上版本的移动设备。 - 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 一个有效的声网账号以及声网项目。请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)从声网控制台获得 App ID 和临时 Token。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。 ::: ## 创建项目 [#创建项目] 本小节介绍如何创建项目并为项目添加体验实时互动所需的权限。 1. (可选) 创建新项目。详见 [Create a project](https://developer.android.com/studio/projects/create-project)。 1. 打开 **Android Studio**,选择 **New Project**。 2. 选择 **Phone and Tablet > Empty Views Activity**,点击 **Next**。 3. 设置项目名称和存储路径,选择语言为 **Java**,点击 **Finish** 创建 Android 项目。 :::warning[注意] 创建项目后,**Android Studio** 会自动开始同步 Gradle,稍等片刻至同步成功后再进行下一步操作。 ::: 2. 添加网络及设备权限。 打开 `/app/src/main/AndroidManifest.xml` 文件,在 `` 后面添加如下权限: ```xml ``` 3. 防止代码混淆。 如果你的 App 未开启 R8/ProGuard 缩减和混淆,无需额外配置混淆规则。如果你的 App 开启了 R8/ProGuard 缩减和混淆,请根据集成方式选择以下任一配置: - 快速配置:打开 `/app/proguard-rules.pro` 文件,添加如下规则,保留所有声网 SDK 相关类: ```java -keep class io.agora.**{*;} -dontwarn io.agora.** ``` - 精细化配置:如果你对 App 包体积、代码缩减或混淆效果有更高要求,可以使用 SDK 提供的 `consumer-proguard-rules.pro` 文件。该文件仅保留 Native 层通过 JNI 访问所需的 Java 类、成员和方法,使其他 SDK Java 代码可继续参与 R8/ProGuard 的缩减、优化和混淆。 通过 AAR 集成时,`consumer-proguard-rules.pro` 已包含在 AAR 中,打包时会自动生效,无需手动拷贝。通过 JAR 集成时,你需要将 `consumer-proguard-rules.pro` 手动拷贝到工程中,并在 `build.gradle` 中添加该文件,例如: ```text android { buildTypes { release { minifyEnabled true proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro', 'consumer-proguard-rules.pro' } } } ``` ## 集成 SDK [#集成-sdk] 你可以选用以下任一方式集成声网实时互动 SDK。 通过 Gradle 自动集成 手动集成 1. 进入项目根目录,打开 `settings.gradle` 文件,在 `dependencyResolutionManagement` 的 `repositories` 中添加声网 Maven CDN 仓库。 请保留项目中已有的 Maven 仓库配置,尤其是 `mavenCentral()`,并额外添加声网 Maven CDN 仓库。 :::warning[注意] 如果你在 `settings.gradle` 中找不到 `dependencyResolutionManagement` 字段,可能是因为你的 Android Gradle Plugin 版本低于 v7.1.0。 相关信息请参考 [Android Gradle Plugin Release Note v7.1.0](https://developer.android.com/build/releases/past-releases/agp-7-1-0-release-notes)。 ::: ```groovy dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { mavenCentral() maven { url = 'https://download.shengwang.cn/maven/' } } } ``` 若你的 Android Gradle Plugin 版本低于 v7.1.0,请打开项目根目录下的 `build.gradle` 文件,在 `allprojects` 的 `repositories` 中添加如下配置: ```groovy allprojects { repositories { mavenCentral() maven { url = 'https://download.shengwang.cn/maven/' } } } ``` 2. 打开 `/app/build.gradle` 文件,在 `dependencies` 中添加声网 RTC SDK 的依赖。你可以从[发版说明](/zh-CN/realtime-media/rtc/reference/release-notes)中查询 SDK 的最新版本,并将 `x.y.z` 替换为具体的版本号。 ```groovy ... dependencies { ... // 对于 4.6.0 及之后的版本 // x.y.z 替换为具体的 SDK 版本号,如:4.6.1 // 集成 Full SDK implementation 'cn.shengwang.rtc:full-sdk:x.y.z' // 集成 Lite SDK implementation 'cn.shengwang.rtc:lite-sdk:x.y.z' // 对于 4.6.0 之前的版本 // x.y.z 替换为具体的 SDK 版本号,如:4.0.0 或 4.1.0-1 // 集成 Full SDK implementation 'io.agora.rtc:full-sdk:x.y.z' // 或集成 Lite SDK implementation 'io.agora.rtc:lite-sdk:x.y.z' } ``` :::warning[注意] Lite SDK 默认无法与 [RTC 小程序 SDK](/zh-CN/realtime-media/rtc) 互通。如果需要,请[联系技术支持](https://ticket.shengwang.cn/)。 ::: 1. 在[下载](/zh-CN/realtime-media/rtc/reference/downloads)页面下载最新版本的 Android 实时互动 SDK,并解压。 2. 打开解压文件,将以下文件或子文件夹复制到你的项目路径中。 | 文件或子文件夹 | 项目路径 | | :--------------------------------- | :----------------------- | | `agora-rtc-sdk.jar` 文件 | `/app/libs/` | | `arm64-v8a` 文件夹 | `/app/src/main/jniLibs/` | | `armeabi-v7a` 文件夹 | `/app/src/main/jniLibs/` | | `x86` 文件夹 | `/app/src/main/jniLibs/` | | `x86_64` 文件夹 | `/app/src/main/jniLibs/` | | `high_level_api` 中的`include` 文件夹 | `/app/src/main/jniLibs/` | :::warning[注意] 自 4.5.0 起,RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.so` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK,为避免冲突,请手动删除版本较低的 `libaosl.so` 库。4.6.0 RTC SDK `libaosl.so` 库版本为 1.3.0。 ::: 3. 在 **Android Studio** 的左侧导航栏上选择 `Project Files/app/libs/agora-rtc-sdk.jar` 文件,右键单击,在下拉菜单中选择 `add as a library`。 ## 创建用户界面 [#创建用户界面] 根据实时音视频互动的场景需要,为你的项目创建两个视图框,分别用于展示本地视频和远端视频。如下图所示: 复制以下代码到 `/app/src/main/res/layout/activity_main.xml` 文件中替换原有内容,即可快速创建场景所需的用户界面。 ```xml ``` ## 实现步骤 [#实现步骤] 本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中,快速体验实时音视频互动的基础功能,再按照实现步骤了解核心 API 调用。 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程: 下面列出了一段实现实时互动基本流程的完整代码以供参考。复制以下代码到 `/app/src/main/java/com/example//MainActivity.java` 文件中替换 `package com.example.` 后的全部内容,即可快速体验实时互动基础功能。 :::info[信息] 在 `appId`、`token` 和 `channelName` 字段中传入你在控制台获取到的 App ID、临时 Token,以及生成临时 Token 时填入的频道名。 ::: ```java import android.Manifest; import android.content.pm.PackageManager; import android.os.Bundle; import android.view.SurfaceView; import android.widget.FrameLayout; import android.widget.Toast; import androidx.annotation.NonNull; import androidx.appcompat.app.AppCompatActivity; import androidx.core.app.ActivityCompat; import androidx.core.content.ContextCompat; 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; public class MainActivity extends AppCompatActivity { // 填写声网控制台中获取的 App ID private String appId = "<#Your App ID#>"; // 填写频道名 private String channelName = "<#Your channel name#>"; // 填写声网控制台中生成的临时 Token private String token = "<#Your Token#>"; private RtcEngine mRtcEngine; private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() { // 成功加入频道回调 @Override public void onJoinChannelSuccess(String channel, int uid, int elapsed) { super.onJoinChannelSuccess(channel, uid, elapsed); runOnUiThread(() -> { Toast.makeText(MainActivity.this, "Join channel success", Toast.LENGTH_SHORT).show(); }); } // 远端用户或主播加入当前频道回调 @Override public void onUserJoined(int uid, int elapsed) { runOnUiThread(() -> { // 当远端用户加入频道后,显示指定 uid 的远端视频流 setupRemoteVideo(uid); }); } // 远端用户或主播离开当前频道回调 @Override public void onUserOffline(int uid, int reason) { super.onUserOffline(uid, reason); runOnUiThread(() -> { Toast.makeText(MainActivity.this, "User offline: " + uid, Toast.LENGTH_SHORT).show(); }); } }; private void initializeAndJoinChannel() { try { // 创建 RtcEngineConfig 对象,并进行配置 RtcEngineConfig config = new RtcEngineConfig(); config.mContext = getBaseContext(); config.mAppId = appId; config.mEventHandler = mRtcEventHandler; // 创建并初始化 RtcEngine mRtcEngine = RtcEngine.create(config); } catch (Exception e) { throw new RuntimeException("Check the error."); } // 启用视频模块 mRtcEngine.enableVideo(); // 创建一个 SurfaceView 对象,并将其作为 FrameLayout 的子对象 FrameLayout container = findViewById(R.id.local_video_view_container); SurfaceView surfaceView = new SurfaceView (getBaseContext()); container.addView(surfaceView); // 将 SurfaceView 对象传入声网实时互动 SDK,设置本地视图 mRtcEngine.setupLocalVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0)); // 开启本地预览 mRtcEngine.startPreview(); // 创建 ChannelMediaOptions 对象,并进行配置 ChannelMediaOptions options = new ChannelMediaOptions(); // 设置用户角色为 BROADCASTER (主播) 或 AUDIENCE (观众) options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER; // 设置频道场景为 BROADCASTING (直播场景) options.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING; // 发布麦克风采集的音频 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频 options.publishCameraTrack = true; // 自动订阅所有音频流 options.autoSubscribeAudio = true; // 自动订阅所有视频流 options.autoSubscribeVideo = true; // 使用临时 Token 和频道名加入频道,uid 为 0 表示引擎内部随机生成用户名 // 成功后会触发 onJoinChannelSuccess 回调 mRtcEngine.joinChannel(token, channelName, 0, options); } 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); // 将 SurfaceView 对象传入声网实时互动 SDK,设置远端视图 mRtcEngine.setupRemoteVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid)); } private static final int PERMISSION_REQ_ID = 22; // 获取体验实时音视频互动所需的录音、摄像头等权限 private String[] getRequiredPermissions(){ // 判断 targetSDKVersion 31 及以上时所需的权限 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 }; } } private boolean checkPermissions() { for (String permission : getRequiredPermissions()) { int permissionCheck = ContextCompat.checkSelfPermission(this, permission); if (permissionCheck != PackageManager.PERMISSION_GRANTED) { return false; } } return true; } @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 如果已经授权,则初始化 RtcEngine 并加入频道 if (checkPermissions()) { initializeAndJoinChannel(); } else { ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID); } } // 系统权限申请回调 @Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (checkPermissions()) { initializeAndJoinChannel(); } } @Override protected void onDestroy() { super.onDestroy(); if (mRtcEngine != null) { // 停止本地视频预览 mRtcEngine.stopPreview(); // 离开频道 mRtcEngine.leaveChannel(); mRtcEngine = null; // 销毁引擎 RtcEngine.destroy(); } } } ``` ### 处理权限请求 [#处理权限请求] 本小节介绍如何导入 Android 相关的类并获取 Android 设备的摄像头、录音等权限。 1. 导入 Android 相关的类 ```java import android.Manifest; import android.content.pm.PackageManager; import android.os.Bundle; import android.view.SurfaceView; import android.widget.FrameLayout; import android.widget.Toast; import androidx.annotation.NonNull; import androidx.appcompat.app.AppCompatActivity; import androidx.core.app.ActivityCompat; import androidx.core.content.ContextCompat; ``` 2. 获取 Android 权限 启动应用程序时,检查是否已在 App 中授予了实现实时互动所需的权限。 ```java private static final int PERMISSION_REQ_ID = 22; // 获取体验实时音视频互动所需的录音、摄像头等权限 private String[] getRequiredPermissions(){ // 判断 targetSDKVersion 31 及以上时所需的权限 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 }; } } private boolean checkPermissions() { for (String permission : getRequiredPermissions()) { int permissionCheck = ContextCompat.checkSelfPermission(this, permission); if (permissionCheck != PackageManager.PERMISSION_GRANTED) { return false; } } return true; } ``` ### 导入声网相关的类 [#导入声网相关的类] 导入声网 RTC SDK 相关的类和接口: ```java 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; ``` ### 定义 App ID 和 Token [#定义-app-id-和-token] 传入从声网控制台获取的 App ID、临时 Token,以及生成临时 Token 时填入的频道名,用于后续初始化引擎和加入频道。 ```java // 填写声网控制台中获取的 App ID private String appId = "<#Your App ID#>"; // 填写频道名 private String channelName = "<#Your channel name#>"; // 填写声网控制台中生成的临时 Token private String token = "<#Your Token#>"; ``` ### 初始化引擎 [#初始化引擎] 调用 `create` [2/2] 方法初始化 `RtcEngine`。 :::warning[注意] 在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。 ::: ```java private RtcEngine mRtcEngine; private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() { ... }; // 创建 RtcEngineConfig 对象,并进行配置 RtcEngineConfig config = new RtcEngineConfig(); config.mContext = getBaseContext(); config.mAppId = appId; config.mEventHandler = mRtcEventHandler; // 创建并初始化 RtcEngine mRtcEngine = RtcEngine.create(config); ``` ### 启用视频模块 [#启用视频模块] 按照以下步骤启用视频模块: 1. 调用 `enableVideo` 方法,启用视频模块。 2. 调用 `setupLocalVideo` 方法初始化本地视图,同时设置本地的视频显示属性。 3. 调用 `startPreview` 方法,开启本地视频预览。 ```java // 启用视频模块 mRtcEngine.enableVideo(); // 创建一个 SurfaceView 对象,并将其作为 FrameLayout 的子对象 FrameLayout container = findViewById(R.id.local_video_view_container); SurfaceView surfaceView = new SurfaceView (getBaseContext()); container.addView(surfaceView); // 将 SurfaceView 对象传入声网实时互动 SDK,设置本地视图 mRtcEngine.setupLocalVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0)); // 开启本地预览 mRtcEngine.startPreview(); ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流] 调用 `joinChannel` [2/2] 加入频道。在 `ChannelMediaOptions` 中进行如下配置: - 设置频道场景为 `BROADCASTING` (直播场景) 并设置用户角色设置为 `BROADCASTER` (主播) 或 `AUDIENCE` (观众)。 - 将 `publishMicrophoneTrack` 和 `publishCameraTrack` 设置为 `true`,发布麦克风采集的音频和摄像头采集的视频。 - 将 `autoSubscribeAudio` 和 `autoSubscribeVideo` 设置为 `true`,自动订阅所有音视频流。 ```java // 创建 ChannelMediaOptions 对象,并进行配置 ChannelMediaOptions options = new ChannelMediaOptions(); // 设置用户角色为 BROADCASTER (主播) 或 AUDIENCE (观众) options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER; // 设置频道场景为 BROADCASTING (直播场景) options.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING; // 发布麦克风采集的音频 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频 options.publishCameraTrack = true; // 自动订阅所有音频流 options.autoSubscribeAudio = true; // 自动订阅所有视频流 options.autoSubscribeVideo = true; // 使用临时 Token 和频道名加入频道,uid 为 0 表示引擎内部随机生成用户名 // 成功后会触发 onJoinChannelSuccess 回调 mRtcEngine.joinChannel(token, channelName, 0, options); ``` ### 设置远端视图 [#设置远端视图] 调用 `setupRemoteVideo` 方法初始化远端用户视图,同时设置远端用户的视图在本地显示属性。你可以通过 `onUserJoined` 回调获取远端用户的 `uid`。 ```java 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); // 将 SurfaceView 对象传入声网实时互动 SDK,设置远端视图 mRtcEngine.setupRemoteVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid)); } ``` ### 实现常用回调 [#实现常用回调] 根据使用场景,定义必要的回调。以下示例代码展示如何实现 `onJoinChannelSuccess`、 `onUserJoined` 和 `onUserOffline` 回调。 ```java // 成功加入频道回调 @Override public void onJoinChannelSuccess(String channel, int uid, int elapsed) { super.onJoinChannelSuccess(channel, uid, elapsed); runOnUiThread(() -> { Toast.makeText(MainActivity.this, "Join channel success", Toast.LENGTH_SHORT).show(); }); } // 远端用户或主播加入当前频道回调 @Override public void onUserJoined(int uid, int elapsed) { runOnUiThread(() -> { // 当远端用户加入频道后,显示指定 uid 的远端视频流 setupRemoteVideo(uid); }); } // 远端用户或主播离开当前频道回调 @Override public void onUserOffline(int uid, int reason) { super.onUserOffline(uid, reason); runOnUiThread(() -> { Toast.makeText(MainActivity.this, "User offline: " + uid, Toast.LENGTH_SHORT).show(); }); } ``` ### 开始音视频互动 [#开始音视频互动] 在 `onCreate` 中调用一系列方法加载界面布局、检查 App 是否获取实时互动所需权限,并加入频道开始音视频互动。 ```java @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 如果已经授权,则初始化 RtcEngine 并加入频道 if (checkPermissions()) { initializeAndJoinChannel(); } else { ActivityCompat.requestPermissions(this, getRequiredPermissions(), PERMISSION_REQ_ID); } } ``` ### 结束音视频互动 [#结束音视频互动] 按照以下步骤结束音视频互动: 1. 调用 `stopPreview` 停止视频预览。 2. 调用 `leaveChannel` 离开当前频道,释放所有会话相关的资源。 3. 调用 `destroy` 销毁引擎,并释放声网 SDK 中使用的所有资源。 :::warning[注意] - 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。 - 调用 `destroy` 后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎)。 ::: ```java @Override protected void onDestroy() { super.onDestroy(); if (mRtcEngine != null) { // 停止本地视频预览 mRtcEngine.stopPreview(); // 离开频道 mRtcEngine.leaveChannel(); mRtcEngine = null; // 销毁引擎 RtcEngine.destroy(); } } ``` ## 调试 App [#调试-app] 按照以下步骤测试直播 App: 1. 开启 Android 设备的开发者选项,打开 USB 调试,通过 USB 连接线将 Android 设备接入电脑,并在 Android 设备选项中勾选你的 Android 设备。 2. 在 Android Studio 中,点击 (**Sync Project with Gradle Files**) 进行 Gradle 同步。 3. 待同步成功后,点击 (**Run 'app'**) 开始编译。片刻后,App 便会安装到你的 Android 设备上。 4. 启动 App,授予录音和摄像头权限,如果你将用户角色设置为主播,便会在本地视图中看到自己。 5. 使用第二台 Android 设备,重复以上步骤,在该设备上安装 App、打开 App 加入频道,观察测试结果: - 如果两台设备均作为主播加入频道,则可以看到对方并且听到对方的声音。 - 如果两台设备分别作为主播和观众加入,则主播可以在本地视频窗口看到自己;观众可以在远端视频窗口看到主播、并听到主播的声音。 ## 后续步骤 [#后续步骤] 在完成音视频互动后,你可以阅读以下文档进一步了解: - 本文的示例使用了临时 Token 加入频道。在测试或生产环境中,为保证通信安全,声网推荐从服务器中获取 Token,详情请参考[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - 如果你想要实现极速直播场景,可以在实时音视频互动的基础上,通过修改观众端的延时级别为低延时 (`AUDIENCE_LATENCY_LEVEL_LOW_LATENCY`) 实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。 ## 参考信息 [#参考信息] ### 示例项目 [#示例项目] 声网提供了开源的实时音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。 Agora-RTC-QuickStart-Android} href="https://gitee.com/agoraio-community/Agora-RTC-QuickStart/tree/main/Android/Agora-RTC-QuickStart-Android" /> Agora-RTC-QuickStart-Android} href="https://github.com/AgoraIO-Community/Agora-RTC-QuickStart/tree/main/Android/Agora-RTC-QuickStart-Android" /> ### 常见问题 [#常见问题] - [直播场景下,如何监听远端观众角色用户加入/离开频道的事件?](/zh-CN/reference/faq/integration/audience_event) - [如何处理视频黑屏问题?](/zh-CN/reference/faq/quality/video_blank) - [为什么我无法打开摄像头?](/zh-CN/reference/faq/quality/video_camera) - [如何处理频道相关常见问题?](/zh-CN/reference/faq/integration/channel) - [如何设置日志文件?](/zh-CN/reference/faq/integration/set_log_file) - [为什么部分 Android 版本应用锁屏或切后台后采集音视频无效?](/zh-CN/reference/faq/quality/android_background) - [为什么 SDK 中使用的是动态库而不是静态库?](/zh-CN/reference/faq/integration/dynamic_or_static_library) ### 相关文档 [#相关文档] - [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code) - [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" /> 本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的实时互动 App,适用于互动直播和视频通话场景。 首先,你需要了解以下有关音视频实时互动的基础概念: - 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。 - 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。 - 主播:可以在频道内**发布**音视频,同时也可以**订阅**其他主播发布的音视频。 - 观众:可以在频道内**订阅**音视频,不具备**发布**音视频权限。 更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。 下图展示在 App 中实现音视频互动的基本工作流程: 1. 所有用户调用 `joinChannel` 方法加入频道,并根据需要设置用户角色: - 互动直播:如果用户需要在频道中发流,则设为主播;如果用户只需要收流,则设为观众。 - 视频通话:将所有用户的角色都设为主播。 2. 加入频道后,不同角色的用户具备不同的行为: - 所有用户默认都可以接收频道中的音视频流。 - 主播可以在频道内发布音视频流。 - 观众如果需要发流,可在频道内调用 `setClientRole` 方法修改用户角色,使其具备发流权限。 ## 前提条件 [#前提条件-1] 在实现功能以前,请按照以下要求准备开发环境: - Xcode 12.0 或以上版本。 - Apple 开发者账号。 - 如需使用 Cocoapods 集成 SDK,则确保已安装 Cocoapods,否则请参考 [Getting Started with CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 进行安装。 - 两台 iOS 9.0 或以上版本的设备。 - 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 一个有效的声网账号以及声网项目。请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)从声网控制台获得 App ID 和临时 Token。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。 ::: ## 创建项目 [#创建项目-1] 按照以下步骤,在 Xcode 中创建一个项目: 1. 参考 [Create a project](https://help.apple.com/xcode/mac/current/#/dev07db0e578) 创建一个新的项目。**Application** 选择 **App**,**Interface** 选择 **Storyboard**,**Language** 选择 **Swift**。 :::info[信息] 如果你没有添加过开发团队信息,会看到 **Add account…** 按钮。点击该按钮并按照屏幕提示登入 Apple ID,点击 **Next**,完成后即可选择你的 Apple 账户作为开发团队。 ::: 2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 3. 设置部署你的 App 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 4. 添加项目的设备权限。 在项目导航栏中打开 `info.plist` 文件,编辑[属性列表](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6),添加实时互动所需的录音和摄像头权限。 :::info[信息] - 下表中列出的权限均为可选权限。但如果不添加所列权限,你将无法使用麦克风和摄像头进行实时音视频互动。 - 如果你的项目中需要添加第三方插件或库(例如第三方摄像头),且该插件或库的签名与项目的签名不一致,你还需勾选 **Hardened Runtime** > **Runtime Exceptions** 中的 **Disable Library Validation**。 - 更多注意事项,可以参考 [Preparing Your App for Distribution](https://developer.apple.com/documentation/xcode/preparing_your_app_for_distribution)。 ::: | Key | Type | Value | | -------------------------------------- | ------ | ------------------------------------------------------------ | | Privacy - Microphone Usage Description | String | 使用麦克风的目的,例如:for a call or live interactive streaming。 | | Privacy - Camera Usage Description | String | 使用摄像头的目的,例如:for a call or live interactive streaming。 | ## 集成 SDK [#集成-sdk-1] 根据实际情况,在以下集成方式中任选一种,在你的项目中集成 SDK。 通过 CocoaPods 集成 手动集成 通过 Swift Package Manager 集成 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 2. 打开 `Podfile` 文件,在文件顶部添加声网 CocoaPods CDN 源。请保留项目中已有的源配置;如果项目还依赖公共仓库中的其他 Pod,请同时保留公共源,例如 `source 'https://cdn.cocoapods.org/'`。已有项目保留原来的 SDK 包名、版本号和组件配置,仅补充源配置。 以下示例将 CocoaPods 官方公共源放在声网源前面。将 `Your App` 替换为你的 Target 名称,将 `x.y.z` 替换为具体的 SDK 版本号,可通过[发版说明](/zh-CN/realtime-media/rtc/reference/release-notes)获取版本信息。示例默认集成 v4.6.0 及之后版本的 Full SDK;如需其他版本或 Lite SDK,请注释默认的 `pod` 行,并取消对应行的注释。 `Podfile` 中的平台版本应与工程的 **iOS Deployment Target** 保持一致,且不低于 SDK 支持的最低版本。 ```ruby source 'https://cdn.cocoapods.org/' source 'https://download.shengwang.cn/cocoapods/' platform :ios, '9.0' target 'Your App' do # 对于 4.6.0 及之后的版本 # 集成 Full SDK pod 'ShengwangRtcEngine_iOS', 'x.y.z' # 或集成 Lite SDK # pod 'ShengwangLite_iOS', 'x.y.z' # 对于 4.6.0 之前的版本 # 集成 Full SDK # pod 'AgoraRtcEngine_iOS', 'x.y.z' # 或集成 Lite SDK # pod 'AgoraLite_iOS', 'x.y.z' end ``` :::warning[注意] Lite SDK 默认无法与 [RTC 小程序 SDK](/zh-CN/realtime-media/rtc) 互通。如果需要,请[联系技术支持](https://ticket.shengwang.cn/)。 ::: 3. 在 `Podfile` 所在目录执行 `pod install --repo-update`,安装所需版本的 SDK。如遇安装问题,请参考 [CocoaPods 常见问题](/zh-CN/reference/faq/integration/cocoapods_problems#无法安装最新版-rtc-sdk)。 4. 成功安装后,项目文件夹下会生成一个后缀为 `.xcworkspace` 的文件,通过 Xcode 打开该文件进行后续操作。 1. 前往[下载](/zh-CN/realtime-media/rtc/reference/downloads)页面,获取最新版的 SDK,然后解压。 2. 将 SDK 包内 `libs` 路径下的文件,拷贝到你的项目路径下。 3. 打开 Xcode,[添加对应动态库](https://help.apple.com/xcode/mac/current/#/dev51a648b07),确保添加的动态库 **Embed** 属性设置为 **Embed & Sign**。 :::info[信息] SDK 以 XCFramework 形式提供,支持 arm64 架构的 iOS 真机,以及 arm64、x86_64 架构的模拟器。 ::: 1. 在 Xcode 中,进入 **File > Add Package Dependencies...**,根据 SDK 版本输入对应的 HTTPS 仓库地址: ```text // 对于 4.6.0 及之后的版本 https://github.com/Shengwang-Lab/ShengwangRtcEngine_iOS.git // 对于 4.6.0 之前的版本 https://github.com/AgoraIO/AgoraRtcEngine_iOS.git ``` 2. 在 **Dependency Rule** 中选择 **Exact Version**,输入需要集成的 SDK 版本(例如 `4.7.0`),然后点击 **Add Package**。 3. 在产品列表中,为应用的 Target 选择 `RtcBasic` 基础组件,其他组件按功能需要选择,然后完成添加。 添加完成后,可在工程的 **Package Dependencies** 中确认 SDK 版本。更多设置请参考 [Apple 官方文档](https://help.apple.com/xcode/mac/current/#/devb83d64851)。 :::warning[注意] 自 4.5.0 起,RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK,为避免冲突,请手动删除版本较低的 `aosl.xcframework` 库。4.6.0 RTC SDK `aosl.xcframework` 库版本为 1.3.0。你可以通过查看 `aosl.xcframework` 文件的属性来得知库的版本信息。 ::: ## 创建用户界面 [#创建用户界面-1] 在 `ViewController.swift` 文件中,为你的项目创建一个用户界面,包括本地视频窗口和远端视频窗口,分别用于展示本地视频和远端视频。如下所示: 用以下代码替换 `ViewController.swift` 文件中的内容,即可实时预览你创建的用户界面。 ```swift import UIKit import AgoraRtcKit class ViewController: UIViewController { // 本地视频视图 var localView: UIView! // 远端视频视图 var remoteView: UIView! // RTC 引擎 var agoraKit: AgoraRtcEngineKit! override func viewDidLoad() { super.viewDidLoad() // 设置本地视频视图 localView = UIView(frame: UIScreen.main.bounds) localView.backgroundColor = UIColor.darkGray.withAlphaComponent(0.1) // 设置背景颜色 self.view.addSubview(localView) // 设置远端视频视图 remoteView = UIView(frame: CGRect(x: self.view.bounds.width - 135, y: 50, width: 135, height: 240)) remoteView.backgroundColor = UIColor.lightGray.withAlphaComponent(0.5) // 设置背景颜色 remoteView.layer.borderColor = UIColor.white.cgColor // 设置边框颜色 remoteView.layer.borderWidth = 2.0 // 设置边框宽度 self.view.addSubview(remoteView) } } // 开启视图预览 #Preview("VC", body: { let vc = ViewController() return vc }) ``` ## 实现步骤 [#实现步骤-1] 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。 下面列出了一段实现实时互动基本流程的完整代码以供参考。复制以下代码到 `ViewController.swift` 文件中替换原有内容即可。 :::info[信息] 在 `appId`、`token` 和 `channelName` 字段中传入你在控制台获取到的 App ID、临时 Token,以及生成临时 Token 时填入的频道名。 ::: ```swift // ViewController.swift import UIKit import AgoraRtcKit class ViewController: UIViewController { // 本地视频视图 var localView: UIView! // 远端视频视图 var remoteView: UIView! // RTC 引擎 var agoraKit: AgoraRtcEngineKit! override func viewDidLoad() { super.viewDidLoad() // 设置本地视频视图 localView = UIView(frame: UIScreen.main.bounds) localView.backgroundColor = UIColor.darkGray.withAlphaComponent(0.1) // 设置背景颜色 self.view.addSubview(localView) // 设置远端视频视图 remoteView = UIView(frame: CGRect(x: self.view.bounds.width - 135, y: 50, width: 135, height: 240)) remoteView.backgroundColor = UIColor.lightGray.withAlphaComponent(0.5) // 设置背景颜色 remoteView.layer.borderColor = UIColor.white.cgColor // 设置边框颜色 remoteView.layer.borderWidth = 2.0 // 设置边框宽度 self.view.addSubview(remoteView) // 初始化 RTC 实例 agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId:<#Your App ID#>, delegate: self) // 开启视频模块(音频模块默认开启) agoraKit.enableVideo() // 开启本地摄像头预览 startPreview() // 加入频道 joinChannel() } deinit { agoraKit.stopPreview() agoraKit.leaveChannel(nil) AgoraRtcEngineKit.destroy() } func startPreview(){ let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.view = localView videoCanvas.renderMode = .hidden agoraKit.setupLocalVideo(videoCanvas) agoraKit.startPreview() } func joinChannel(){ let options = AgoraRtcChannelMediaOptions() // 设置频道场景为直播 options.channelProfile = .liveBroadcasting // 设置用户角色为主播;如果要将用户角色设置为观众,保持默认值即可 options.clientRoleType = .broadcaster // 发布麦克风采集的音频 options.publishMicrophoneTrack = true // 发布摄像头采集的视频 options.publishCameraTrack = true // 自动订阅所有音频流 options.autoSubscribeAudio = true // 自动订阅所有视频流 options.autoSubscribeVideo = true // 使用临时 Token 加入频道,在这里传入你的项目的 Token 和频道名 // uid 为 0 表示由引擎内部随机生成; 成功后会触发 didJoinChannel 回调 agoraKit.joinChannel(byToken: <#Your Token#>, channelId: <#Your Channel Name#>, uid: 0, mediaOptions: options) } } extension ViewController: AgoraRtcEngineDelegate{ // 成功加入频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) { print("didJoinChannel: \(channel), uid: \(uid)") } // 远端用户或主播加入当前频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int){ // 当远端用户加入频道后,显示指定 uid 的远端视频流 let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = uid videoCanvas.view = remoteView videoCanvas.renderMode = .hidden agoraKit.setupRemoteVideo(videoCanvas) } // 远端用户或主播离开当前频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) { let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = uid videoCanvas.view = nil agoraKit.setupRemoteVideo(videoCanvas) } } // 开启视图预览 #Preview("VC", body: { let vc = ViewController() return vc }) ``` ### 导入声网组件 [#导入声网组件] 在 `ViewController.swift` 文件中引入 `AgoraRtcKit`。 ```swift import AgoraRtcKit ``` ### 初始化引擎 [#初始化引擎-1] 调用 `sharedEngineWithConfig` 方法,创建并初始化 `AgoraRtcEngineKit`。 :::warning[注意] 在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。 ::: ```swift // 在这里输入你在声网控制台中获取的 App ID agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId:<#Your App ID#>, delegate: self) ``` ### 启用视频模块 [#启用视频模块-1] 按照以下步骤启用视频模块。 1. 调用 `enableVideo` 方法,启用视频模块。 2. 调用 `setupLocalVideo` 方法初始化本地视图,同时设置本地的视频显示属性。 3. 调用 `startPreview` 方法,开启本地视频预览。 ```swift // 启用视频模块 agoraKit.enableVideo() let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.view = localView videoCanvas.renderMode = .hidden // 设置本地视图 agoraKit.setupLocalVideo(videoCanvas) // 开始本地视频预览 agoraKit.startPreview() ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流-1] 调用 `joinChannelByToken`[2/4] 方法、填入你在控制台获取的临时 Token,以及获取 Token 时填入的频道名加入频道,并设置用户角色。 ```swift let options = AgoraRtcChannelMediaOptions() // 设置频道场景为直播 options.channelProfile = .liveBroadcasting // 设置用户角色为主播;如果要将用户角色设置为观众,保持默认值即可 options.clientRoleType = .broadcaster // 发布麦克风采集的音频 options.publishMicrophoneTrack = true // 发布摄像头采集的视频 options.publishCameraTrack = true // 自动订阅所有音频流 options.autoSubscribeAudio = true // 自动订阅所有视频流 options.autoSubscribeVideo = true // 使用临时 Token 加入频道,在这里传入你的项目的 Token 和频道名 // uid 为 0 表示由引擎内部随机生成; 成功后会触发 didJoinChannel 回调 agoraKit.joinChannel(byToken: <#Your Token#>, channelId: <#Your Channel Name#>, uid: 0, mediaOptions: options) ``` ### 设置远端用户视图 [#设置远端用户视图] 调用 `setupRemoteVideo` 方法初始化远端用户视图,同时设置远端用户的视图在本地显示属性。你可以通过 `didJoinedOfUid` 回调获取远端用户的 `uid`。 ```swift func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int){ // 当远端用户加入频道后,显示指定 uid 的远端视频流 let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = uid videoCanvas.view = remoteView videoCanvas.renderMode = .hidden agoraKit.setupRemoteVideo(videoCanvas) } ``` ### 实现常用回调 [#实现常用回调-1] 根据使用场景,定义必要的回调。以下示例代码展示了如何实现 `didJoinChannel` 和 `didOfflineOfUid` 回调。 ```swift // 成功加入频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) { print("didJoinChannel: \(channel), uid: \(uid)") } // 远端用户或主播离开当前频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) { let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = uid videoCanvas.view = nil agoraKit.setupRemoteVideo(videoCanvas) } ``` ### 开始音视频互动 [#开始音视频互动-1] 当视图加载完成后,在 `viewDidLoad` 中调用一系列方法加入频道,开始音视频互动。 ```swift override func viewDidLoad() { super.viewDidLoad() // 当加载视图后,你可以进行其他其他设置 // 当调用声网 API 时,以下函数会被调用 agoraKit.enableVideo() startPreview() joinChannel() } ``` ### 结束音视频互动 [#结束音视频互动-1] 1. 调用 `leaveChannel` 方法离开频道,与会话相关的资源也会被释放。 ```swift agoraKit.stopPreview() agoraKit.leaveChannel(nil) ``` 2. 调用 `destroy` 销毁引擎,并释放声网 SDK 中使用的所有资源。 ```swift AgoraRtcEngineKit.destroy() ``` :::error[警告] - 调用该方法后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎-1)。 - 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。 ::: ## 调试 App [#调试-app-1] 参考以下步骤来测试你的 App: 1. 将 iOS 设备连接至计算机。 2. 点击 **Build** 来运行你的项目,需等待几秒至 App 安装完成。 3. 允许 App 访问设备的麦克风和摄像头权限。 4. (可选)如果设备上弹出**不受信任的开发者**提示,则首先点击**取消**关闭该提示,然后在 iOS 设备上打开**设置 > 通用 > VPN 与设备管理**,在**开发者 APP** 中选择信任该开发者。 5. 使用第二台 iOS 设备,重复以上步骤,在该设备上安装 App,并打开 App 加入频道,观察测试结果: - 如果两台设备均作为主播加入频道,则可以看到对方并且听到对方的声音。 - 如果两台设备分别作为主播和观众加入,则主播可以在本地视频窗口看到自己;观众可以在远端视频窗口看到主播、并听到主播的声音。 ## 后续步骤 [#后续步骤-1] - 本文的示例使用了临时 Token 加入频道。在测试或生产环境中,为确保通信安全,声网推荐使用 Token 服务器来生成 Token,详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - 如果你想要实现极速直播场景,可以在互动直播的基础上,通过修改观众端的延时级别为低延时 (`AgoraAudienceLatencyLevelLowLatency`)实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。 ## 参考信息 [#参考信息-1] ### 示例项目 [#示例项目-1] 声网提供了开源的实时互动示例项目供你参考,你可以前往下载或查看其中的源代码。 Agora-RTC-QuickStart-iOS} href="https://gitee.com/agoraio-community/Agora-RTC-QuickStart/tree/main/iOS/Agora-RTC-QuickStart-iOS/Agora-RTC-QuickStart-iOS" /> Agora-RTC-QuickStart-iOS} href="https://github.com/AgoraIO-Community/Agora-RTC-QuickStart/tree/main/iOS/Agora-RTC-QuickStart-iOS" /> ### 常见问题 [#常见问题-1] - [直播场景下,如何监听远端观众角色用户加入/离开频道的事件?](/zh-CN/reference/faq/integration/audience_event) - [如何处理视频黑屏问题?](/zh-CN/reference/faq/quality/video_blank) - [如何处理 CocoaPods 常见问题?](/zh-CN/reference/faq/integration/cocoapods_problems) - [为什么我无法打开摄像头?](/zh-CN/reference/faq/quality/video_camera) - [如何处理频道相关常见问题?](/zh-CN/reference/faq/integration/channel) - [如何设置日志文件?](/zh-CN/reference/faq/integration/set_log_file) - [如何处理无声问题?](/zh-CN/reference/faq/quality/audio_noaudio) - [为什么部分 iOS 版本 App 锁屏或切后台后音视频采集无效?](/zh-CN/reference/faq/quality/ios_background) - [为什么 SDK 中使用的是动态库而不是静态库?](/zh-CN/reference/faq/integration/dynamic_or_static_library) - [如何增加隐私清单?](/zh-CN/reference/faq/other/ios_privacy_manifest) ### 相关文档 [#相关文档-1] - [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code) - [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="macos" /> 本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的实时互动 App,适用于互动直播和视频通话场景。 首先,你需要了解以下有关音视频实时互动的基础概念: - 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。 - 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。 - 主播:可以在频道内**发布**音视频,同时也可以**订阅**其他主播发布的音视频。 - 观众:可以在频道内**订阅**音视频,不具备**发布**音视频权限。 更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。 下图展示在 App 中实现音视频互动的基本工作流程: 1. 所有用户调用 `joinChannel` 方法加入频道,并根据需要设置用户角色: - 互动直播:如果用户需要在频道中发流,则设为主播;如果用户只需要收流,则设为观众。 - 视频通话:将所有用户的角色都设为主播。 2. 加入频道后,不同角色的用户具备不同的行为: - 所有用户默认都可以接收频道中的音视频流。 - 主播可以在频道内发布音视频流。 - 观众如果需要发流,可在频道内调用 `setClientRole` 方法修改用户角色,使其具备发流权限。 ## 前提条件 [#前提条件-2] 在实现功能以前,请按照以下要求准备开发环境: - Xcode 12.0 或以上版本。 - Apple 开发者账号。 - 如需使用 Cocoapods 集成 SDK,则确保已安装 Cocoapods,否则请参考 [Getting Started with CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 进行安装。 - 两台 macOS 10.10 或以上版本的设备。 - 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 一个有效的声网账号以及声网项目。请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)从声网控制台获得 App ID 和临时 Token。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。 ::: ## 创建项目 [#创建项目-2] 按照以下步骤,在 Xcode 中创建一个项目: 1. 参考 [Create a project](https://help.apple.com/xcode/mac/current/#/dev07db0e578) 创建一个新的项目。**Application** 选择 **App**,**Interface** 选择 **Storyboard**,**Language** 选择 **Swift**。 :::info[信息] 如果你没有添加过开发团队信息,会看到 **Add account…** 按钮。点击该按钮并按照屏幕提示登入 Apple ID,点击 **Next**,完成后即可选择你的 Apple 账户作为开发团队。 ::: 2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 3. 设置部署你的 App 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 4. 添加项目的设备权限。 在项目导航栏中打开 `info.plist` 文件,编辑[属性列表](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6),添加以下属性: :::warning[注意] - 下表中列出的权限均为可选权限。但如果不添加所列权限,你将无法使用麦克风和摄像头进行实时音视频互动。 - 如果你的项目中需要添加第三方插件或库(例如第三方摄像头),且该插件或库的签名与项目的签名不一致,你还需勾选 **Hardened Runtime** > **Runtime Exceptions** 中的 **Disable Library Validation**。 - 更多注意事项,可以参考 [Preparing Your App for Distribution](https://developer.apple.com/documentation/xcode/preparing_your_app_for_distribution)。 ::: | Key | Type | Value | | -------------------------------------- | ------ | ------------------------------------------------------------ | | Privacy - Microphone Usage Description | String | 使用麦克风的目的,例如:for a call or live interactive streaming。 | | Privacy - Camera Usage Description | String | 使用摄像头的目的,例如:for a call or live interactive streaming。 | 进入 **TARGETS > Project Name > Signing & Capabilities**,在 **App Sandbox** 和 **Hardened Runtime** 中添加如下权限: | Capability | Category | Permission | | --- | --- | --- | | App Sandbox | Network | [quick-start-1308-2-2 details](#table-slot-quick-start-1308-2-2) | | App Sandbox | Hardware | [quick-start-1308-3-2 details](#table-slot-quick-start-1308-3-2) | | Hardened Runtime | Resource Access | [quick-start-1308-4-2 details](#table-slot-quick-start-1308-4-2) | **quick-start-1308-2-2 details** - Incoming Connections (Server) - Outgoing Connections (Client) **quick-start-1308-3-2 details** - Camera - Audio Input **quick-start-1308-4-2 details** - Camera - Audio Input ## 集成 SDK [#集成-sdk-2] 根据实际情况,在以下集成方式中任选一种,在你的项目中集成 SDK。 通过 CocoaPods 集成 手动集成 通过 Swift Package Manager 集成 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 2. 打开 `Podfile` 文件,在文件顶部添加声网 CocoaPods CDN 源。请保留项目中已有的源配置;如果项目还依赖公共仓库中的其他 Pod,请同时保留公共源,例如 `source 'https://cdn.cocoapods.org/'`。已有项目保留原来的 SDK 包名、版本号和组件配置,仅补充源配置。 以下示例将 CocoaPods 官方公共源放在声网源前面。将 `Your App` 替换为你的 Target 名称,将 `x.y.z` 替换为具体的 SDK 版本号,可通过[发版说明](/zh-CN/realtime-media/rtc/reference/release-notes)获取版本信息。示例默认集成 v4.6.0 及之后版本;如需之前的版本,请注释默认的 `pod` 行,并取消 `AgoraRtcEngine_macOS` 所在行的注释。 `Podfile` 中的平台版本应与工程的 **macOS Deployment Target** 保持一致,且不低于 SDK 支持的最低版本。 ```ruby source 'https://cdn.cocoapods.org/' source 'https://download.shengwang.cn/cocoapods/' platform :macos, '10.11' target 'Your App' do # 对于 4.6.0 及之后的版本 pod 'ShengwangRtcEngine_macOS', 'x.y.z' # 对于 4.6.0 之前的版本 # pod 'AgoraRtcEngine_macOS', 'x.y.z' end ``` 3. 在 `Podfile` 所在目录执行 `pod install --repo-update`,安装所需版本的 SDK。如遇安装问题,请参考 [CocoaPods 常见问题](/zh-CN/reference/faq/integration/cocoapods_problems#无法安装最新版-rtc-sdk)。 4. 成功安装后,项目文件夹下会生成一个后缀为 `.xcworkspace` 的文件,通过 Xcode 打开该文件进行后续操作。 1. 前往[下载](/zh-CN/realtime-media/rtc/reference/downloads)页面,获取最新版的 SDK,然后解压。 2. 将 SDK 包内 `libs` 路径下的文件,拷贝到你的项目路径下。 3. 打开 Xcode,[添加对应动态库](https://help.apple.com/xcode/mac/current/#/dev51a648b07),确保添加的动态库 **Embed** 属性设置为 **Embed & Sign**。 :::info[信息] SDK 以 XCFramework 形式提供,支持 arm64 和 x86_64 架构的 Mac。 ::: 1. 在 Xcode 中,进入 **File > Add Package Dependencies...**,根据 SDK 版本输入对应的 HTTPS 仓库地址: ```text // 对于 4.6.0 及之后的版本 https://github.com/Shengwang-Lab/ShengwangRtcEngine_macOS.git // 对于 4.6.0 之前的版本 https://github.com/AgoraIO/AgoraRtcEngine_macOS.git ``` 2. 在 **Dependency Rule** 中选择 **Exact Version**,输入需要集成的 SDK 版本(例如 `4.7.0`),然后点击 **Add Package**。 3. 在产品列表中,为应用的 Target 选择 `RtcBasic` 基础组件,其他组件按功能需要选择,然后完成添加。 添加完成后,可在工程的 **Package Dependencies** 中确认 SDK 版本。更多设置请参考 [Apple 官方文档](https://help.apple.com/xcode/mac/current/#/devb83d64851)。 :::warning[注意] 自 4.5.0 起,RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK,为避免冲突,请手动删除版本较低的 `aosl.xcframework` 库。4.6.0 RTC SDK `aosl.xcframework` 库版本为 1.3.0。你可以通过查看 `aosl.xcframework` 文件的属性来得知库的版本信息。 ::: ## 创建用户界面 [#创建用户界面-2] 根据使用场景,为你的项目创建一个用户界面,包括本地视频窗口和远端视频窗口。用以下代码替换 `ViewController.swift` 文件中的内容: ```swift import Cocoa import AgoraRtcKit class ViewController: NSViewController { // 本地视频视图 var localView: NSView! // 远端视频视图 var remoteView: NSView! // RTC 引擎 var agoraKit: AgoraRtcEngineKit! override func viewDidLayout() { super.viewDidLayout() // 计算本地视图的位置和大小 let localViewWidth: CGFloat = 135 let localViewHeight: CGFloat = 240 let localViewX: CGFloat = 2 let localViewY: CGFloat = 2 // 设置本地视图的 frame localView.frame = CGRect(x: localViewX, y: localViewY, width: localViewWidth, height: localViewHeight) // 设置远端视图的 frame,让它充满整个 CustomView remoteView.frame = view.bounds } } ``` ## 实现步骤 [#实现步骤-2] 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。 下面列出了一段实现实时互动基本流程的完整代码以供参考。复制以下代码到 `ViewController.swift` 文件中替换原有内容即可。 :::info[信息] 在 `appId`、`token` 和 `channelName` 字段中传入你在控制台获取到的 App ID、临时 Token,以及生成临时 Token 时填入的频道名。 ::: ```swift // ViewController.swift import AgoraRtcKit import Cocoa class ViewController: NSViewController { // 本地视频视图 var localView: NSView! // 远端视频视图 var remoteView: NSView! // RTC 引擎 var agoraKit: AgoraRtcEngineKit! override func viewDidLayout() { super.viewDidLayout() // 计算本地视图的位置和大小 let localViewWidth: CGFloat = 135 let localViewHeight: CGFloat = 240 let localViewX: CGFloat = 2 let localViewY: CGFloat = 2 // 设置本地视图的 frame localView.frame = CGRect(x: localViewX, y: localViewY, width: localViewWidth, height: localViewHeight) // 设置远端视图的 frame,让它充满整个 CustomView remoteView.frame = view.bounds } func initView() { // 初始化远端视频窗口。 remoteView = NSView() self.view.addSubview(remoteView) // 初始化本地视频窗口。 localView = NSView() self.view.addSubview(localView) // 初始化 RTC 实例 agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: <#Your App ID#>, delegate: self) } deinit { agoraKit.stopPreview() agoraKit.leaveChannel(nil) AgoraRtcEngineKit.destroy() } func startPreview() { let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.view = localView videoCanvas.renderMode = .hidden agoraKit.setupLocalVideo(videoCanvas) agoraKit.startPreview() } func joinChannel() { let options = AgoraRtcChannelMediaOptions() // 设置频道场景为直播 options.channelProfile = .liveBroadcasting // 设置用户角色为主播;如果要将用户角色设置为观众,保持默认值即可 options.clientRoleType = .broadcaster // 发布麦克风采集的音频 options.publishMicrophoneTrack = true // 发布摄像头采集的视频 options.publishCameraTrack = true // 自动订阅所有音频流 options.autoSubscribeAudio = true // 自动订阅所有视频流 options.autoSubscribeVideo = true // 使用临时 Token 加入频道,在这里传入你的项目的 Token 和频道名 // uid 为 0 表示由引擎内部随机生成; 成功后会触发 didJoinChannel 回调 agoraKit.joinChannel(byToken: <#Your Token#>, channelId: <#Your Channel Name#>, uid: 0, mediaOptions: options) } override func viewDidLoad() { super.viewDidLoad() initView() agoraKit.enableVideo() startPreview() joinChannel() } } extension ViewController: AgoraRtcEngineDelegate { // 成功加入频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) { print("didJoinChannel: \(channel), uid: \(uid)") } // 远端用户或主播加入当前频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) { // 打印调试信息 print("User \(uid) joined after \(elapsed) milliseconds") let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = uid videoCanvas.view = remoteView videoCanvas.renderMode = .hidden agoraKit.setupRemoteVideo(videoCanvas) } // 远端用户或主播离开当前频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) { // 打印调试信息 print("User \(uid) went offline due to \(reason)") let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = uid videoCanvas.view = nil agoraKit.setupRemoteVideo(videoCanvas) } } ``` ### 导入声网组件 [#导入声网组件-1] 在 `ViewController.swift` 文件中引入 `AgoraRtcKit`。 ```swift import AgoraRtcKit ``` ### 初始化引擎 [#初始化引擎-2] 调用 `sharedEngineWithConfig` 方法,创建并初始化 `AgoraRtcEngineKit`。 :::warning[注意] 在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。 ::: ```swift agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) ``` ### 启用视频模块 [#启用视频模块-2] 按照以下步骤启用视频模块。 1. 调用 `enableVideo` 方法,启用视频模块。 2. 调用 `setupLocalVideo` 方法初始化本地视图,同时设置本地视频的显示属性。 3. 调用 `startPreview` 方法,开启本地视频预览。 ```swift // 启用视频模块 agoraKit.enableVideo() let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = 0 videoCanvas.renderMode = .hidden videoCanvas.view = localView // 设置本地视图 agoraKit.setupLocalVideo(videoCanvas) // 开始本地视频预览 agoraKit.startPreview() ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流-2] 调用 `joinChannelByToken`[2/4] 方法、填入你在控制台获取的临时 Token,以及获取 Token 时填入的频道名加入频道,并设置用户角色。 ```swift let options = AgoraRtcChannelMediaOptions() // 设置频道场景为直播 options.channelProfile = .liveBroadcasting // 设置用户角色为主播 // 如果要将用户角色设置为观众,则修改下一行代码为 options.clientRoleType = .audience options.clientRoleType = .broadcaster // 发布麦克风采集的音频 options.publishMicrophoneTrack = true // 发布摄像头采集的视频 options.publishCameraTrack = true // 自动订阅所有音频流 options.autoSubscribeAudio = true // 自动订阅所有视频流 options.autoSubscribeVideo = true // 使用临时 Token 加入频道,在这里传入你的项目的 Token 和频道名 // uid 为 0 表示由引擎内部随机生成; 成功后会触发 didJoinChannel 回调 agoraKit.joinChannel(byToken: <#Your Token#>, channelId: <#Your Channel Name#>, uid: 0, mediaOptions: options) ``` ### 设置远端用户视图 [#设置远端用户视图-1] 调用 `setupRemoteVideo` 方法初始化远端用户视图,同时设置远端用户的视图在本地显示属性。你可以通过 `didJoinedOfUid` 回调获取远端用户的 uid。 ```swift func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int){ // 当远端用户加入频道后,显示指定 uid 的远端视频流 print("User \(uid) joined after \(elapsed) milliseconds") let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = uid videoCanvas.view = remoteView videoCanvas.renderMode = .hidden agoraKit.setupRemoteVideo(videoCanvas) } ``` ### 实现常用回调 [#实现常用回调-2] 根据使用场景,定义你所需的回调。以下示例代码展示了如何实现 `didJoinChannel` 和 `didOfflineOfUid` 回调。 ```swift // 成功加入频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) { print("didJoinChannel: \(channel), uid: \(uid)") } // 远端用户或主播离开当前频道回调 func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) { // 打印调试信息 print("User \(uid) went offline due to \(reason)") let videoCanvas = AgoraRtcVideoCanvas() videoCanvas.uid = uid videoCanvas.view = nil agoraKit.setupRemoteVideo(videoCanvas) } ``` ### 开始音视频互动 [#开始音视频互动-2] 当视图加载完成后,在 `viewDidLoad` 中调用一系列方法加入频道,开始音视频互动。 ```swift override func viewDidLoad() { super.viewDidLoad() // 当加载视图后,你可以进行其他其他设置 // 初始化视频窗口 initView() // 当调用声网 API 时,以下函数会被调用 agoraKit.enableVideo() startPreview() joinChannel() } ``` ### 结束音视频互动 [#结束音视频互动-2] 1. 调用 `leaveChannel` 方法离开频道,与会话相关的资源也会被释放。 ```swift agoraKit.stopPreview() agoraKit.leaveChannel(nil) ``` 2. 调用 `destroy` 销毁引擎,并释放声网 SDK 中使用的所有资源。 ```swift AgoraRtcEngineKit.destroy() ``` :::error[警告] - 调用该方法后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎-2)。 - 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。 ::: ## 调试 App [#调试-app-2] 参考以下步骤来测试你的 App: 1. 将 macOS 设备连接至计算机。 2. 点击 **Build** 来运行你的项目,需等待几秒至 App 安装完成。 3. 允许 App 访问设备的麦克风和摄像头权限。 4. 使用第二台 macOS 设备,重复以上步骤,在该设备上安装 App,并打开 App 加入频道,观察测试结果: - 如果两台设备均作为主播加入频道,则可以看到对方并且听到对方的声音。 - 如果两台设备分别作为主播和观众加入,则主播可以在本地视频窗口看到自己;观众可以在远端视频窗口看到主播、并听到主播的声音。 ## 后续步骤 [#后续步骤-2] - 本文的示例使用了临时 Token 加入频道。在测试或生产环境中,为确保通信安全,声网推荐使用 Token 服务器来生成 Token,详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - 如果你想要实现极速直播场景,可以在互动直播的基础上,通过修改观众端的延时级别为低延时 (`AgoraAudienceLatencyLevelLowLatency`)实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。 ## 参考信息 [#参考信息-2] ### 示例项目 [#示例项目-2] 声网提供了开源的实时互动示例项目供你参考,你可以前往下载或查看其中的源代码。 JoinChannelVideo} href="https://gitee.com/agoraio-community/API-Examples/tree/main/macOS/APIExample/Examples/Basic/JoinChannelVideo" /> JoinChannelVideo} href="https://github.com/Shengwang-Community/API-Examples/tree/main/macOS/APIExample/Examples/Basic/JoinChannelVideo" /> ### 常见问题 [#常见问题-2] - [直播场景下,如何监听远端观众角色用户加入/离开频道的事件?](/zh-CN/reference/faq/integration/audience_event) - [如何处理视频黑屏问题?](/zh-CN/reference/faq/quality/video_blank) - [如何处理 CocoaPods 常见问题?](/zh-CN/reference/faq/integration/cocoapods_problems) - [为什么我无法打开摄像头?](/zh-CN/reference/faq/quality/video_camera) - [如何处理频道相关常见问题?](/zh-CN/reference/faq/integration/channel) - [编译 Xcode 项目时遇到 “无法打开 framework” 的弹窗警告怎么办?](/zh-CN/reference/faq/integration/framework_cannot_be_opened) - [如何设置日志文件?](/zh-CN/reference/faq/integration/set_log_file) - [为什么 SDK 中使用的是动态库而不是静态库?](/zh-CN/reference/faq/integration/dynamic_or_static_library) ### 相关文档 [#相关文档-2] - [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code) - [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" /> 本文介绍如何集成声网实时互动 Web SDK,通过少量代码从 0 开始实现一个简单的实时互动 App。 开始之前,你需要首先了解音视频实时互动的[相关概念和流程](/zh-CN/realtime-media/rtc/reference/key-concept#音视频基本流程)。 实时音视频互动主要包含互动直播和视频通话两大场景,你可以按需搭建想要的场景: - **互动直播**:频道内的用户分为主播和观众,只有主播可以自由发言并且被其他用户看见。 - **视频通话**:频道内的用户不区分主播和观众,所有用户都可以发言并看见彼此。 ## 前提条件 [#前提条件-3] 在集成声网实时互动 Web SDK 快速实现音视频互动前,请确保开发环境满足以下要求: - Windows 或 macOS 计算机,需满足以下要求: - 下载满足声网 [Web SDK 兼容性的浏览器](/zh-CN/realtime-media/rtc/reference/browser-compatibility)。声网强烈推荐使用[最新稳定版 Google Chrome 浏览器](https://www.google.com/chrome/)。 - 具备物理音视频采集设备。 - 可连接到互联网。如果你的网络环境部署了防火墙,请参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 搭载 2.2 GHz Intel 第二代 i3/i5/i7 处理器或同等性能的其他处理器。 - 有效的声网账户和声网项目,请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service),在声网控制台注册、登录并创建声网项目,然后获取项目的 App ID 和临时 Token。 - 安装 [Node.js](https://nodejs.org/en/download/) 18 或更高版本。 :::info[信息] 有些框架模板可能需要更高版本的 Node.js 才能工作,如果你的包管理器发出警告,请升级你的 Node.js 版本。 ::: ## 实现步骤 [#实现步骤-3] 本节介绍如何快速搭建并实现一个实时音视频互动场景。根据你的开发偏好和需要,选择如下任意一种实现方式。 使用包管理工具快速创建(推荐) 获取 SDK 后手动集成 :::info[信息] 使用包管理工具只能快速搭建开箱即用的视频通话场景。如果你希望体验互动直播场景,请选用获取 SDK 后手动集成的方式,并在创建客户端时将 `mode` 设置为 `live`。 ::: ### 1. 获取快速开始安装包 [#1-获取快速开始安装包] 在使用包管理器创建项目之前,你需要通过以下任意一种途径下载声网实时互动 Web SDK 快速开始安装包资源: 通过 GitHub 下载 使用 npm 安装 #### 通过 GitHub 下载 [#通过-github-下载] 下载或克隆 [create-agora-app](https://github.com/AgoraIO-Community/create-agora-app)获取快速开始安装包资源。 #### 通过 npm 下载 [#通过-npm-下载] 安装 [Node.js 及 npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm),然后在终端通过 npm 安装快速开始资源包: ```shell npm i create-agora-app ``` ### 2. 使用包管理器创建项目 [#2-使用包管理器创建项目] 根据你的开发需要,使用如下一款包管理工具并继续: 使用 Yarn 使用 pnpm 使用 npm 使用 Bun 开始前,请确保你的开发环境已[安装 Yarn](https://yarnpkg.com/getting-started/install)。 运行如下命令行安装快速开始资源包: ```shell yarn create agora-app ``` 开始前,请确保你的开发环境已[安装 pnpm](https://pnpm.io/installation)。 运行如下命令行安装快速开始资源包: ```shell pnpm create agora-app ``` 开始前,请确保你的开发环境已[安装 npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)。 运行如下命令行安装快速开始资源包: ```shell npm create agora-app@latest ``` 开始前,请确保你的开发环境已[安装 Bun](https://bun.sh/docs/installation)。 运行如下命令行安装快速开始资源包: ```shell bunx create-agora-app ``` 你可以在项目创建过程中修改你的项目名称,例如 `agora-project`。 ### 3. 选择框架模板 [#3-选择框架模板] 在创建过程中,系统会提示你选择一个前端框架模板(包括 `Vanilla-js`、`Vue-ts`、`React-ts` 或 `Svelte-ts`)。你可以根据你的需求选择相应的框架。 ### 4. 启动项目 [#4-启动项目] 系统将根据你的选择生成项目骨架,你需要进入项目目录并安装依赖,然后启动开发服务器。 以下是使用 yarn 创建了一个 `React-ts` 项目的示例,按照屏幕提示输入命令行来完成相关操作即可: ```shell Scaffolding project in agora-project... Done. Now run: cd agora-project yarn yarn dev ``` 此时,开发服务器将启动,你可以在浏览器中访问 `http://localhost:5173/` 查看项目运行情况。 :::info[信息] 在本地服务器 (localhost) 运行 Web 应用仅作为测试用途。部署生产环境时,请确保使用 HTTPS 协议。 ::: ### 5. 查看预期效果 [#5-查看预期效果] 你的浏览器会自动打开以下页面: 打开摄像头和麦克风确认设备没有问题,之后根据界面提示,输入 App ID、临时 Token,以及生成临时 Token 时填入的频道名,可以快速实现加入频道、发布音视频流和离开频道等基础音视频互动功能。 :::info[信息] 上图以 `React-ts` 框架打开的界面为例。根据你所选择的前端框架模板,浏览器打开的界面可能有所不同。 ::: #### 获取 SDK 后手动集成 [#获取-sdk-后手动集成] 你可以参考以下步骤,获取 SDK 后进行手动集成,以搭建你想要实现的音视频互动场景(视频通话或互动直播)。 ### 1. 创建 Web 项目 [#1-创建-web-项目] 创建一个名为 `agora_web_quickstart` 的文件夹。一个 Web 客户端项目至少需包含以下文件: - `index.html`: 用于设计 Web 应用的用户界面。 - `basicEngagement.js`: 通过 `AgoraRTCClient` 实现具体应用逻辑的代码。 - `package.json`: 安装并管理项目依赖。你可以通过命令行进入 `agora_web_quickstart` 目录并运行 `npm init` 命令来创建 `package.json` 文件。 ### 2. 集成 SDK [#2-集成-sdk] 参考以下步骤通过 npm 将声网 Web SDK 集成到你的项目中: 在 `package.json` 文件的 `dependencies` 字段中添加 `agora-rtc-sdk-ng` 及版本号: ```json { "name": "agora_web_quickstart", "version": "1.0.0", "description": "", "main": "basicEngagement.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "dependencies": { // [!code highlight:1] "agora-rtc-sdk-ng": "latest" }, "author": "", "license": "ISC" } ``` 将以下代码复制到 `basicEngagement.js` 文件中,在你的项目中导入 `AgoraRTC` 模块。 ```javascript import AgoraRTC from "agora-rtc-sdk-ng" ``` ### 3. 实现用户界面 [#3-实现用户界面] 将以下代码复制到 `index.html` 实现客户端用户界面: 互动直播 视频通话 ```html Web SDK Video Quickstart

Web SDK Video Quickstart

```
```html Web SDK Video Quickstart

Web SDK Video Quickstart

```
### 4. 复制项目示例代码 [#4-复制项目示例代码] 声网实时互动 Web SDK 提供两种模式的音视频互动,分别是视频通话和互动直播。两者创建客户端时设置的 `mode` 参数不同: ```javascript // 视频通话场景下 mode 设为 rtc rtc.client = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" }); // 视频直播场景下 mode 设为 live rtc.client = AgoraRTC.createClient({ mode: "live", codec: "vp8" }); ``` 你可以直接将以下代码复制到 `basicEngagement.js` 文件中来快速体验互动直播,注意将 `appID`、`token` 和频道名替换为[你自己的 App ID 和临时 Token](#rtc-web-prerequisites)以及频道名。 互动直播 视频通话 ```javascript import AgoraRTC from "agora-rtc-sdk-ng"; let rtc = { // For the local audio and video tracks. localAudioTrack: null, localVideoTrack: null, client: null, }; let options = { // Pass your app ID here. appId: "your_app_id", // Set the channel name. channel: "test", // Use a temp token token: "your_temp_token", // Uid uid: 123456, }; async function startBasicLiveStreaming() { rtc.client = AgoraRTC.createClient({mode: "live", codec: "vp8"}); window.onload = function () { document.getElementById("host-join").onclick = async function () { rtc.client.setClientRole("host"); await rtc.client.join(options.appId, options.channel, options.token, options.uid); // Create an audio track from the audio sampled by a microphone. rtc.localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack(); // Create a video track from the video captured by a camera. rtc.localVideoTrack = await AgoraRTC.createCameraVideoTrack(); // Publish the local audio and video tracks to the channel. await rtc.client.publish([rtc.localAudioTrack, rtc.localVideoTrack]); // Dynamically create a container in the form of a DIV element for playing the local video track. const localPlayerContainer = document.createElement("div"); // Specify the ID of the DIV container. You can use the `uid` of the remote user. localPlayerContainer.id = options.uid; localPlayerContainer.textContent = "Local user " + options.uid; localPlayerContainer.style.width = "640px"; localPlayerContainer.style.height = "480px"; document.body.append(localPlayerContainer); rtc.localVideoTrack.play(localPlayerContainer); console.log("publish success!"); }; document.getElementById("audience-join").onclick = async function () { rtc.client.setClientRole("audience"); await rtc.client.join(options.appId, options.channel, options.token, options.uid); rtc.client.on("user-published", async (user, mediaType) => { // Subscribe to a remote user. await rtc.client.subscribe(user, mediaType); console.log("subscribe success"); // If the subscribed track is video. if (mediaType === "video") { // Get `RemoteVideoTrack` in the `user` object. const remoteVideoTrack = user.videoTrack; // Dynamically create a container in the form of a DIV element for playing the remote video track. const remotePlayerContainer = document.createElement("div"); // Specify the ID of the DIV container. You can use the `uid` of the remote user. remotePlayerContainer.id = user.uid.toString(); remotePlayerContainer.textContent = "Remote user " + user.uid.toString(); remotePlayerContainer.style.width = "640px"; remotePlayerContainer.style.height = "480px"; document.body.append(remotePlayerContainer); // Play the remote video track. // Pass the DIV container and the SDK dynamically creates a player in the container for playing the remote video track. remoteVideoTrack.play(remotePlayerContainer); } // If the subscribed track is audio. if (mediaType === "audio") { // Get `RemoteAudioTrack` in the `user` object. const remoteAudioTrack = user.audioTrack; // Play the audio track. No need to pass any DOM element. remoteAudioTrack.play(); } }); rtc.client.on("user-unpublished", user => { // Get the dynamically created DIV container. const remotePlayerContainer = document.getElementById(user.uid); // Destroy the container. remotePlayerContainer.remove(); }); }; document.getElementById("leave").onclick = async function () { // Close all the local tracks. rtc.localAudioTrack.close(); rtc.localVideoTrack.close(); // Traverse all remote users. rtc.client.remoteUsers.forEach(user => { // Destroy the dynamically created DIV containers. const playerContainer = document.getElementById(user.uid); playerContainer && playerContainer.remove(); }); // Leave the channel. await rtc.client.leave(); }; }; } startBasicLiveStreaming(); ``` 下图展示了基础的音视频直播的 API 调用。注意图中的方法是对不同的对象调用的。 ![互动直播实现流程](https://web-cdn.agora.io/docs-portal/img/rtc/js-quick-start-live.svg) ```javascript import AgoraRTC from "agora-rtc-sdk-ng"; let rtc = { localAudioTrack: null, localVideoTrack: null, client: null, }; let options = { // Pass your App ID here. appId: "Your App ID", // Set the channel name. channel: "test", // Pass your temp token here. token: "Your temp token", // Set the user ID. uid: 123456, }; async function startBasicCall() { // Create an AgoraRTCClient object. rtc.client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"}); // Listen for the "user-published" event, from which you can get an AgoraRTCRemoteUser object. rtc.client.on("user-published", async (user, mediaType) => { // Subscribe to the remote user when the SDK triggers the "user-published" event await rtc.client.subscribe(user, mediaType); console.log("subscribe success"); // If the remote user publishes a video track. if (mediaType === "video") { // Get the RemoteVideoTrack object in the AgoraRTCRemoteUser object. const remoteVideoTrack = user.videoTrack; // Dynamically create a container in the form of a DIV element for playing the remote video track. const remotePlayerContainer = document.createElement("div"); // Specify the ID of the DIV container. You can use the uid of the remote user. remotePlayerContainer.id = user.uid.toString(); remotePlayerContainer.textContent = "Remote user " + user.uid.toString(); remotePlayerContainer.style.width = "640px"; remotePlayerContainer.style.height = "480px"; document.body.append(remotePlayerContainer); // Play the remote video track. // Pass the DIV container and the SDK dynamically creates a player in the container for playing the remote video track. remoteVideoTrack.play(remotePlayerContainer); } // If the remote user publishes an audio track. if (mediaType === "audio") { // Get the RemoteAudioTrack object in the AgoraRTCRemoteUser object. const remoteAudioTrack = user.audioTrack; // Play the remote audio track. No need to pass any DOM element. remoteAudioTrack.play(); } // Listen for the "user-unpublished" event rtc.client.on("user-unpublished", user => { // Get the dynamically created DIV container. const remotePlayerContainer = document.getElementById(user.uid); // Destroy the container. remotePlayerContainer.remove(); }); }); window.onload = function () { document.getElementById("join").onclick = async function () { // Join an RTC channel. await rtc.client.join(options.appId, options.channel, options.token, options.uid); // Create a local audio track from the audio sampled by a microphone. rtc.localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack(); // Create a local video track from the video captured by a camera. rtc.localVideoTrack = await AgoraRTC.createCameraVideoTrack(); // Publish the local audio and video tracks to the RTC channel. await rtc.client.publish([rtc.localAudioTrack, rtc.localVideoTrack]); // Dynamically create a container in the form of a DIV element for playing the local video track. const localPlayerContainer = document.createElement("div"); // Specify the ID of the DIV container. You can use the uid of the local user. localPlayerContainer.id = options.uid; localPlayerContainer.textContent = "Local user " + options.uid; localPlayerContainer.style.width = "640px"; localPlayerContainer.style.height = "480px"; document.body.append(localPlayerContainer); // Play the local video track. // Pass the DIV container and the SDK dynamically creates a player in the container for playing the local video track. rtc.localVideoTrack.play(localPlayerContainer); console.log("publish success!"); }; document.getElementById("leave").onclick = async function () { // Destroy the local audio and video tracks. rtc.localAudioTrack.close(); rtc.localVideoTrack.close(); // Traverse all remote users. rtc.client.remoteUsers.forEach(user => { // Destroy the dynamically created DIV containers. const playerContainer = document.getElementById(user.uid); playerContainer && playerContainer.remove(); }); // Leave the channel. await rtc.client.leave(); }; }; } startBasicCall(); ``` 下图展示了实现音视频互动的 API 调用流程。注意图中的方法是对不同的对象调用的。 ![视频通话实现流程](https://web-cdn.agora.io/docs-portal/img/rtc/js-quick-start-rtc.svg) ### 5. 测试 App [#5-测试-app] 本文使用 [webpack](https://webpack.js.org/) 打包项目,使用 `webpack-dev-server` 运行项目。 参考以下步骤来测试你的 App: 在 `package.json` 的 `dependencies` 字段中添加 `webpack`、`webpack-cli` 和 `webpack-dev-server`,并在 `scripts` 字段中添加 `build` 和 `start:dev`。 ```json { "name": "agora_web_quickstart", "version": "1.0.0", "description": "", "main": "basicEngagement.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", // [!code highlight:2] "build": "webpack --config webpack.config.js", "start:dev": "webpack serve --open --config webpack.config.js" }, "dependencies": { "agora-rtc-sdk-ng": "latest", // [!code highlight:3] "webpack": "5.28.0", "webpack-dev-server": "3.11.2", "webpack-cli": "4.10.0" }, "author": "", "license": "ISC" } ``` 在项目目录中创建一个名为 `webpack.config.js` 的文件,将以下代码复制到 `webpack.config.js` 配置 webpack: ```javascript const path = require("path"); module.exports = { entry: "./basicEngagement.js", output: { filename: "bundle.js", path: path.resolve(__dirname, "./dist"), }, devServer: { compress: true, port: 9000, }, }; ``` 运行下列命令安装依赖: ```shell npm install ``` 运行下列命令通过 webpack 编译项目: ```shell # Use webpack to package the project npm run build ``` 通过 webpack-dev-server 运行项目: ```shell npm run start:dev ``` :::info[信息] - 在本地服务器 (localhost) 运行 Web 应用仅作为测试用途。部署生产环境时,请确保使用 HTTPS 协议。 - 由于浏览器的安全策略,声网对除 127.0.0.1 以外的 HTTP 地址作了限制。 ::: ### 6. 查看预期效果 [#6-查看预期效果] 互动直播 视频通话 你的浏览器会自动打开以下页面: 点击 **Join as host** 以主播角色加入频道。你还可以邀请朋友克隆 [Gitee 示例项目](https://gitee.com/agoraio-community/API-Examples-Web)或 [GitHub 示例项目](https://github.com/Shengwang-Lab/API-Examples-Web)到本地,在浏览器中打开 `src/index.html` 文件,并输入相同的 App ID、频道名称和临时 Token。你的朋友以主播角色加入频道后,你们可以看到彼此,并听到彼此的声音;你的朋友以观众角色加入频道后,他可以看到你,并听到你的声音。 你的浏览器会自动打开以下页面: 点击 **JOIN** 加入频道。你还可以邀请朋友克隆 [Gitee 示例项目](https://gitee.com/agoraio-community/API-Examples-Web)或 [GitHub 示例项目](https://github.com/Shengwang-Lab/API-Examples-Web)到本地,在浏览器中打开 `src/index.html` 文件,并输入相同的 App ID、频道名称和临时 Token。你的朋友加入频道后,你们可以看到彼此,并听到彼此的声音。 ### 7. 后续步骤 [#7-后续步骤] 在完成音视频互动后,你可以阅读以下文档进一步了解: - 本文的示例使用了临时 Token 加入频道。在正式生产环境中,为保障通信安全,你需要在自己的 App 服务端生成 Token。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - 如果你想要实现极速直播场景,可以在互动直播的基础上,通过修改观众端的延时级别为低延时实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。 ## 参考信息 [#参考信息-3] ### 示例项目 [#示例项目-3] 声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。 Web-API-Examples} href="https://gitee.com/agoraio-community/API-Examples-Web/tree/main/src/example" /> Web-API-Examples} href="https://github.com/Shengwang-Lab/API-Examples-Web/tree/main/src/example" /> ### 其它集成方式 [#其它集成方式] 使用 npm 集成 Web SDK 还支持开启 Tree shaking 来减小集成 SDK 后的 App 体积,详见[使用 Tree shaking](/zh-CN/realtime-media/rtc/build/optimize-and-operate/tree-shaking)。 除使用 npm 获取 Web SDK 之外,你还可以使用以下方法获取 SDK: - 在项目 HTML 文件中,添加如下代码,使用 CDN 方法获取 SDK: ```html ``` - 下载[声网 Web SDK 4.x 版本 SDK 包](/zh-CN/realtime-media/rtc/reference/downloads)至本地,将 SDK 包中的 `.js` 文件保存到项目文件所在的目录下,然后在项目 HTML 文件中添加如下代码: ```html ``` :::info[信息] 在以上方法中,SDK 都会在全局导出一个 `AgoraRTC` 对象,直接访问这个对象即可操作 SDK。 ::: ### 常见问题 [#常见问题-3] **为什么在本地运行快速开始项目时会报错 `digital envelope routines::unsupported`?** 本文中的快速开始项目通过 webpack 打包并在本地运行。由于 Node.js 16 及以上版本更改了对 OpenSSL 的依赖(详见 [node issue](https://github.com/nodejs/node/issues/29817)),影响了项目中本地开发环境的依赖(详见 [webpack issue](https://github.com/webpack/webpack/issues/14532)),运行项目会发生错误。解决方案如下: - (推荐)运行如下命令,设置临时的环境变量: ```shell export NODE_OPTIONS=--openssl-legacy-provider ``` - 暂时换用低版本的 Node.js。 尝试以上解决方案后,再次尝试运行项目。
<_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="windows" /> 本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的实时互动 App,适用于互动直播和视频通话场景。 首先,你需要了解以下有关音视频实时互动的基础概念: - 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。 - 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。 - 主播:可以在频道内**发布**音视频,同时也可以**订阅**其他主播发布的音视频。 - 观众:可以在频道内**订阅**音视频,不具备**发布**音视频权限。 更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。 下图展示在 App 中实现音视频互动的基本工作流程: 1. 所有用户调用 `joinChannel` 方法加入频道,并根据需要设置用户角色: - 互动直播:如果用户需要在频道中发流,则设为主播;如果用户只需要收流,则设为观众。 - 视频通话:将所有用户的角色都设为主播。 2. 加入频道后,不同角色的用户具备不同的行为: - 所有用户默认都可以接收频道中的音视频流。 - 主播可以在频道内发布音视频流。 - 观众如果需要发流,可在频道内调用 `setClientRole` 方法修改用户角色,使其具备发流权限。 ## 前提条件 [#前提条件-4] 在实现功能以前,请按照以下要求准备开发环境: - Windows 7 或以上版本的设备。 - Microsoft Visual Studio 2017 或以上版本。 - C++ 11 或以上版本。 - 如果使用 C# 开发,还需要 [.NET 桌面开发组件](https://learn.microsoft.com/en-us/dotnet/framework/install/guide-for-developers)。 - 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 一个有效的声网账号以及声网项目。请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)从声网控制台获得 App ID 和临时 Token。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。 ::: C++ C# ## 创建项目 [#创建项目-3] 以 Windows 11 为例,参考以下操作或[官方文档](https://learn.microsoft.com/en-us/visualstudio/ide/create-new-project?view=vs-2022)在 Visual Studio 2022 中创建一个项目来实现实时音视频互动功能,如果你已有自己的项目,可跳过这一步骤。 1. 在 Visual Studio 中,选择**文件** > **新建** > **项目** 来创建一个新项目。在弹出的窗口中,选择 **MFC 应用**作为项目模板,点击**下一步**将项目名称设为 **AgoraQuickStart** 并设置项目储存位置,然后点击**创建**。 2. 在弹出的 MFC 应用程序窗口中,将**应用程序类型**设为**基于对话框**,将**使用 MFC** 设为**在共享 DLL 中使用 MFC**。进入**生成的类**,将**生成的类**设为 **Dlg**,将**基类**设为 **CDialog**,最后点击**完成**。 ## 集成 SDK [#集成-sdk-3] 1. 从[下载](/zh-CN/realtime-media/rtc/reference/downloads)获取最新的 Windows SDK,解压并打开。 2. 打开已下载的 SDK 文件,并将其中的 `sdk` 文件夹复制到你的项目路径下。保证 `sdk` 文件夹和你的 `sln` 文件处于同一目录。 :::warning[注意] 自 4.5.0 起,RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.dll` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK,为避免冲突,请手动删除版本较低的 `libaosl.dll` 库。4.6.0 RTC SDK `libaosl.dll` 库版本为 1.3.0。你可以通过查看 `libaosl.dll` 文件的属性来得知库的版本信息。 ::: ## 配置项目属性 [#配置项目属性] 在**解决方案资源管理器**窗口中,右击项目名称并点击**属性**进行以下配置: 1. 进入 **C/C++ > 常规 > 附加包含目录**菜单,输入 `$(SolutionDir)sdk\high_level_api\include`。 2. 进入**链接器 > 常规 > 附加库目录**菜单,输入 `$(SolutionDir)sdk\x86_64`。 :::info[信息] 如果你是 x86 的 Windows 操作系统,请输入 `$(SolutionDir)sdk\x86`。 ::: 3. 进入**链接器 > 输入 > 附加依赖项**菜单,输入 `$(SolutionDir)sdk\x86_64\agora_rtc_sdk.dll.lib`。 :::info[信息] 如果你是 x86 的 Windows 操作系统,请输入 `$(SolutionDir)sdk\x86\agora_rtc_sdk.dll.lib`。 ::: 4. 进入**高级**菜单,在**高级属性**中,把**将内容复制到 OutDir** 和**将 C++ 运行时复制到输出目录**设为**是**。 5. 进入**生成事件 > 生成后事件 >命令行** 菜单,输入 `copy $(SolutionDir)sdk\x86_64\*.dll $(SolutionDir)$(Platform)\$(Configuration)`。 6. 完成上述配置后点击**应用**。 ## 创建用户界面 [#创建用户界面-3] 根据实时音视频互动的场景需要,你需要在你的应用中添加如下 UI: - 展示本地视频的视图框 - 展示远端视频的视图框 - 输入频道名称的输入框 - 加入和离开频道按钮 你可以参考下列步骤来创建用户界面。 1. 在右侧菜单栏将项目切换为资源视图,然后打开 `.Dialog` 文件,此时你的界面如下图所示: 2. 添加展示远端视频的视图框。在**视图 > 工具箱**中,选择添加 **Picture Control** 控件,在**属性 > 杂项**中,将该控件的 ID 设为 **IDC_STATIC_REMOTE**,如下图所示: 3. 添加展示本地视频的视图框。在**视图 > 工具箱**中,选择添加 **Picture Control** 控件,在**属性 > 杂项**中,将该控件的 ID 设为 **IDC_STATIC_LOCAL**。 4. 添加输入频道名称的输入框。在**视图 > 工具箱**中,选择添加 **Static Text** 控件,在**属性**中将**描述文字**改为**频道名**。然后再添加一个 **Edit Control** 控件作为输入框,在**属性 > 杂项**中,将该控件的 ID 设为 **IDC_EDIT_CHANNEL**。 5. 添加加入和离开频道按钮。在**视图 > 工具箱**中,选择添加两个 **Button** 控件,在**属性 > 杂项**中,将控件的 ID 分设为 **ID_BTN_JOIN** 和 **ID_BTN_LEAVE**,将**描述文字**分别设为**加入**、**离开**。 此时的用户界面如下图所示: ## 实现步骤 [#实现步骤-4] 本小节介绍如何实现一个实时音视频互动应用。你可以先复制完整的示例代码到你的项目中,快速体验实时音视频互动的基础功能,再按照实现步骤了解核心 API 调用。 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。 以下展示实现实时互动基本流程的完整示例代码: :::warning[注意] 复制完整示例代码到你的项目之后,你需要将代码中的 `APP_ID` 和 `token` 替换成你在声网控制台获取的 App ID 和临时 Token。 ::: ```cpp #pragma once #include // 引入相关头文件 #include using namespace agora; using namespace agora::rtc; using namespace agora::media; using namespace agora::media::base; // 定义消息 ID #define WM_MSGID(code) (WM_USER+0x200+code) #define EID_JOIN_CHANNEL_SUCCESS 0x00000002 #define EID_USER_JOINED 0x00000004 #define EID_USER_OFFLINE 0x00000004 // 定义 CAgoraQuickStartRtcEngineEventHandler 类,用于处理用户加入、离开频道等回调事件 class CAgoraQuickStartRtcEngineEventHandler : public IRtcEngineEventHandler { public: // 设置消息接收窗口的句柄 void SetMsgReceiver(HWND hWnd) { m_hMsgHanlder = hWnd; } // 注册 onJoinChannelSuccess 回调,本地用户成功加入频道时,会触发该回调 virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_JOIN_CHANNEL_SUCCESS), uid, 0); } } // 注册 onUserJoined 回调,远端主播成功加入频道时,会触发该回调 virtual void onUserJoined(uid_t uid, int elapsed) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_USER_JOINED), uid, 0); } } // 注册 onUserOffline 回调,远端主播离开频道或掉线时,会触发该回调 virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_USER_OFFLINE), uid, 0); } } private: HWND m_hMsgHanlder; }; // CAgoraQuickStartDlg 对话框 class CAgoraQuickStartDlg : public CDialog { public: CAgoraQuickStartDlg(CWnd* pParent = nullptr); virtual ~CAgoraQuickStartDlg(); #ifdef AFX_DESIGN_TIME enum { IDD = IDD_AGORAQUICKSTART_DIALOG }; #endif // 处理加入/离开按钮点击事件 afx_msg void OnBnClickedBtnJoin(); afx_msg void OnBnClickedBtnLeave(); // 处理用户加入频道、用户离开等回调事件 afx_msg LRESULT OnEIDJoinChannelSuccess(WPARAM wParam, LPARAM lParam); afx_msg LRESULT OnEIDUserJoined(WPARAM wParam, LPARAM lParam); afx_msg LRESULT OnEIDUserOffline(WPARAM wParam, LPARAM lParam); protected: HICON m_hIcon; CStatic m_staRemote; CStatic m_staLocal; CEdit m_edtChannelName; // DDX/DDV 支持 virtual void DoDataExchange(CDataExchange* pDX); virtual BOOL OnInitDialog(); afx_msg void OnSysCommand(UINT nID, LPARAM lParam); afx_msg void OnPaint(); afx_msg HCURSOR OnQueryDragIcon(); DECLARE_MESSAGE_MAP() std::string cs2utf8(CString str); private: IRtcEngine* m_rtcEngine = nullptr; CAgoraQuickStartRtcEngineEventHandler m_eventHandler; bool m_initialize = false; bool m_remoteRender = false; }; ``` ```cpp // AgoraQuickStartDlg.cpp: 实现文件 // #include "pch.h" #include "framework.h" #include "AgoraQuickStart.h" #include "AgoraQuickStartDlg.h" #include "afxdialogex.h" #ifdef _DEBUG #define new DEBUG_NEW #endif // 用于应用程序“关于”菜单项的 CAboutDlg 对话框 class CAboutDlg : public CDialogEx { public: CAboutDlg(); // 对话框数据 #ifdef AFX_DESIGN_TIME enum { IDD = IDD_ABOUTBOX } ; #endif protected: virtual void DoDataExchange(CDataExchange* pDX); // DDX/DDV 支持 // 实现 protected: DECLARE_MESSAGE_MAP() } ; CAboutDlg::CAboutDlg() : CDialogEx(IDD_ABOUTBOX) { } void CAboutDlg::DoDataExchange(CDataExchange* pDX) { CDialogEx::DoDataExchange(pDX); } BEGIN_MESSAGE_MAP(CAboutDlg, CDialogEx) END_MESSAGE_MAP() // CAgoraQuickStartDlg 对话框,用于处理主要的用户交互和回调事件 CAgoraQuickStartDlg::CAgoraQuickStartDlg(CWnd* pParent /*=nullptr*/ ) : CDialog(IDD_AGORAQUICKSTART_DIALOG, pParent) { m_hIcon = AfxGetApp()->LoadIcon(IDR_MAINFRAME); } CAgoraQuickStartDlg::~CAgoraQuickStartDlg() { CDialog::~CDialog(); // 在删除 CAgoraQuickStartDlg 对象时,释放引擎和相关资源 if(m_rtcEngine) { m_rtcEngine->release(true); m_rtcEngine = NULL; } } void CAgoraQuickStartDlg::DoDataExchange(CDataExchange* pDX) { CDialog::DoDataExchange(pDX); // 将控件和变量关联起来,以便于读写控件的数据 DDX_Control(pDX, IDC_EDIT_CHANNEL, m_edtChannelName); DDX_Control(pDX, IDC_STATIC_REMOTE, m_staRemote); DDX_Control(pDX, IDC_STATIC_LOCAL, m_staLocal); } BEGIN_MESSAGE_MAP(CAgoraQuickStartDlg, CDialog) // 声明消息映射,用于处理 Windows 消息和用户加入、离开频道等事件 ON_WM_SYSCOMMAND() ON_WM_PAINT() ON_WM_QUERYDRAGICON() ON_BN_CLICKED(ID_BTN_JOIN, &CAgoraQuickStartDlg::OnBnClickedBtnJoin) ON_BN_CLICKED(ID_BTN_LEAVE, &CAgoraQuickStartDlg::OnBnClickedBtnLeave) ON_MESSAGE(WM_MSGID(EID_JOIN_CHANNEL_SUCCESS), CAgoraQuickStartDlg::OnEIDJoinChannelSuccess) ON_MESSAGE(WM_MSGID(EID_USER_JOINED), &CAgoraQuickStartDlg::OnEIDUserJoined) ON_MESSAGE(WM_MSGID(EID_USER_OFFLINE), &CAgoraQuickStartDlg::OnEIDUserOffline) END_MESSAGE_MAP() // CAgoraQuickStartDlg 消息处理程序 // 填入你项目的 App ID,在声网控制台获取 #define "" // 填入你在声网控制台获取的临时 Token #define "" BOOL CAgoraQuickStartDlg::OnInitDialog() { CDialog::OnInitDialog(); // 将“关于...”菜单项添加到系统菜单中 // IDM_ABOUTBOX 必须在系统命令范围内 ASSERT((IDM_ABOUTBOX & 0xFFF0) == IDM_ABOUTBOX); ASSERT(IDM_ABOUTBOX < 0xF000); CMenu* pSysMenu = GetSystemMenu(FALSE); if (pSysMenu != nullptr) { BOOL bNameValid; CString strAboutMenu; bNameValid = strAboutMenu.LoadString(IDS_ABOUTBOX); ASSERT(bNameValid); if (!strAboutMenu.IsEmpty()) { pSysMenu->AppendMenu(MF_SEPARATOR); pSysMenu->AppendMenu(MF_STRING, IDM_ABOUTBOX, strAboutMenu); } } // 设置此对话框的图标。当应用程序主窗口不是对话框时,框架将自动执行此操作 SetIcon(m_hIcon, TRUE); // 设置大图标 SetIcon(m_hIcon, FALSE); // 设置小图 m_eventHandler.SetMsgReceiver(m_hWnd); // 创建 rtcEngine 对象 m_rtcEngine = createAgoraRtcEngine(); RtcEngineContext context; context.appId = APP_ID; context.eventHandler = &m_eventHandler; //初始化 int ret = m_rtcEngine->initialize(context); if (ret == 0) { m_initialize = true; } else { m_initialize = false; } // 启用视频模块 m_rtcEngine->enableVideo(); return TRUE; // 除非将焦点设置到控件,否则返回 TRUE } void CAgoraQuickStartDlg::OnSysCommand(UINT nID, LPARAM lParam) { if ((nID & 0xFFF0) == IDM_ABOUTBOX) { CAboutDlg dlgAbout; dlgAbout.DoModal(); } else { CDialog::OnSysCommand(nID, lParam); } } // 如果向对话框添加最小化按钮,则需要下面的代码 // 来绘制该图标。对于使用文档/视图模型的 MFC 应用程序,这将由框架自动完成 void CAgoraQuickStartDlg::OnPaint() { if (IsIconic()) { CPaintDC dc(this); // 用于绘制的设备上下文 SendMessage(WM_ICONERASEBKGND, reinterpret_cast(dc.GetSafeHdc()),0); // 使图标在工作区矩形中居中 int cxIcon = GetSystemMetrics(SM_CXICON); int cyIcon = GetSystemMetrics(SM_CYICON); CRect rect; GetClientRect(&rect); int x = (rect.Width() - cxIcon + 1) / 2; int y = (rect.Height() - cyIcon + 1) / 2; // 绘制图标 dc.DrawIcon(x, y, m_hIcon); } else { CDialog::OnPaint(); } } //当用户拖动最小化窗口时系统调用此函数取得光标 HCURSOR CAgoraQuickStartDlg::OnQueryDragIcon() { return static_cast(m_hIcon); } std::string CAgoraQuickStartDlg::cs2utf8(CString str) { char szBuf[2 * MAX_PATH] = { 0 } ; WideCharToMultiByte(CP_UTF8, 0, str.GetBuffer(0), str.GetLength(), szBuf, 2 *MAX_PATH, NULL, NULL); return szBuf; } void CAgoraQuickStartDlg::OnBnClickedBtnJoin() { // 加入频道 // 获取频道名 CString strChannelName; m_edtChannelName.GetWindowText(strChannelName); if (strChannelName.IsEmpty()) { AfxMessageBox(_T("Fill channel name first")); return; } ChannelMediaOptions option; // 设置频道场景为直播 options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING; // 设置用户角色为主播 options.clientRoleType = CLIENT_ROLE_BROADCASTER; // 发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频流 options.publishCameraTrack = true; // 自动订阅频道内的音频流 options.autoSubscribeAudio = true; // 自动订阅频道内的视频流 options.autoSubscribeVideo = true; // 填入你在控制台获取的临时 Token 加入频道 int ret = m_rtcEngine->joinChannel(token, cs2utf8(strChannelName).c_str(), 0,option); // 渲染本地视图 VideoCanvas canvas; canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN; canvas.uid = 0; canvas.view = m_staLocal.GetSafeHwnd(); m_rtcEngine->setupLocalVideo(canvas); // 开启本地视频预览 m_rtcEngine->startPreview(); } void CAgoraQuickStartDlg::OnBnClickedBtnLeave() { // 停止本地视频预览 m_rtcEngine->stopPreview(); // 离开频道 m_rtcEngine->leaveChannel(); // 清除本地视图 VideoCanvas canvas; canvas.uid = 0; m_rtcEngine->setupLocalVideo(canvas); m_remoteRender = false; } LRESULT CAgoraQuickStartDlg::OnEIDJoinChannelSuccess(WPARAM wParam, LPARAM lParam) { // 加入频道成功回调 uid_t localUid = wParam; return 0; } LRESULT CAgoraQuickStartDlg::OnEIDUserJoined(WPARAM wParam, LPARAM lParam) { // 远端用户加入回调 uid_t remoteUid = wParam; if (m_remoteRender) { return 0; } // 渲染远端视图 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) { // 远端用户离开回调 uid_t remoteUid = wParam; if (!m_remoteRender) { return 0; } // 清除远端视图 VideoCanvas canvas; canvas.uid = remoteUid; m_rtcEngine->setupRemoteVideo(canvas); m_remoteRender = false; return 0; } ``` 参考下列步骤来在你的应用中实现实时互动: ### 初始化引擎 [#初始化引擎-3] 在调用其他声网 API 前,你需要调用 `createAgoraRtcEngine` 创建一个`IRtcEngine` 对象,然后调用 `initialize` 并传入 App ID,初始化 `IRtcEngine`。 :::warning[注意] 在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。 ::: ```cpp // 创建 IRtcEngine 对象 m_rtcEngine = createAgoraRtcEngine(); // 创建 IRtcEngine 上下文对象 RtcEngineContext context; // 输入你的 App ID。你可以在声网控制台获取你的项目的 App ID context.appId = APP_ID; // 添加注册回调和事件 context.eventHandler = &m_eventHandler; // 初始化 int ret = m_rtcEngine->initialize(context); if (ret == 0) { m_initialize = true; } else { m_initialize = false; } ``` ### 启用视频模块 [#启用视频模块-3] 1. 调用 `enableVideo` 方法,启用视频模块。 2. 调用 `setupLocalVideo` 初始化本地视图,同时设置本地的视频显示属性。 3. 调用 `startPreview` 方法,开启本地视频预览。 ```cpp // 启用视频模块 m_rtcEngine->enableVideo(); ... // 设置本地视频显示属性 VideoCanvas canvas; // 设置视频尺寸等比缩放 canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN; // 用户 ID canvas.uid = 0; // 视频显示窗口 canvas.view = m_staLocal.GetSafeHwnd(); m_rtcEngine->setupLocalVideo(canvas); // 开启本地视频预览 m_rtcEngine->startPreview(); ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流-3] 调用 `joinChannel`[2/2] 方法、填入你在控制台获取的临时 Token,以及获取 Token 时填入的频道名加入频道,并设置用户角色。 ```cpp void CAgoraQuickStartDlg::OnBnClickedBtnJoin() { CString strChannelName; // 获取频道名 m_edtChannelName.GetWindowText(strChannelName); if (strChannelName.IsEmpty()) { AfxMessageBox(_T("Fill channel name first")); return; } ChannelMediaOptions option; // 设置频道场景为直播场景 options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING; // 设置用户角色为主播;如果要将用户角色设置为观众,保持默认值即可 options.clientRoleType = CLIENT_ROLE_BROADCASTER; // 发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频流 options.publishCameraTrack = true; // 自动订阅所有音频流 options.autoSubscribeAudio = true; // 自动订阅所有视频流 options.autoSubscribeVideo = true; // 填入你在控制台获取的临时 Token 加入频道 m_rtcEngine->joinChannel(token, cs2utf8(strChannelName).c_str(), 0, option); } ``` ### 实现常用回调 [#实现常用回调-3] 你可以根据需求,在初始化时实现其他功能,如注册用户加入、离开频道等回调。 ```cpp class CAgoraQuickStartRtcEngineEventHandler : public IRtcEngineEventHandler { public: // 注册 onJoinChannelSuccess 回调 // 本地用户成功加入频道时,会触发该回调 virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_JOIN_CHANNEL_SUCCESS), uid, 0); } } // 注册 onUserJoined 回调 // 远端主播成功加入频道时,会触发该回调 virtual void onUserJoined(uid_t uid, int elapsed) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_USER_JOINED), uid, 0); } } // 注册 onUserOffline 回调 // 远端主播离开频道或掉线时,会触发该回调 virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_USER_OFFLINE), uid, 0); } } private: HWND m_hMsgHanlder; }; ``` ### 设置远端视图 [#设置远端视图-1] 当远端用户加入频道时,从远端用户加入频道的回调中获取到的远端用户的 uid,然后调用 `setupRemoteVideo` 设置并渲染远端视图。 ```cpp LRESULT CAgoraQuickStartDlg::OnEIDUserJoined(WPARAM wParam, LPARAM lParam) { // 远端用户加入回调 uid_t remoteUid = wParam; if (m_remoteRender) { return; } // 设置远端视频显示属性 VideoCanvas canvas; // 设置视频尺寸等比缩放 canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN; // 远端用户 ID canvas.uid = remoteUid; canvas.view = m_staRemote.GetSafeHwnd(); m_rtcEngine->setupRemoteVideo(canvas); m_remoteRender = true; } ``` ### 离开频道 [#离开频道] 根据场景需要,如关闭应用或应用切换至后台时,调用 `leaveChannel` 离开当前频道。 ```cpp void CAgoraQuickStartDlg::OnBnClickedBtnLeave() { // 停止本地视频预览 m_rtcEngine->stopPreview(); // 离开频道 m_rtcEngine->leaveChannel(); // 清除本地视图 VideoCanvas canvas; canvas.uid = 0; m_rtcEngine->setupLocalVideo(canvas); m_remoteRender = false; } ``` 如果你不再需要互动,调用 `release` 方法释放引擎资源。 :::warning[注意] - 调用 `release` 后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎-3)。 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。 ::: ```cpp CDialog::~CDialog() { // 在对象被销毁时释放资源 if(m_rtcEngine){ m_rtcEngine->release(true); m_rtcEngine = NULL; } } ``` ## 调试应用 [#调试应用] 按照以下步骤来测试你的应用: 1. 在 Visual Studio 中,选择**本地 Windows 调试器**开始编译应用。 2. 在输入框中输入你要加入的频道名,并点击**加入**按钮加入频道,你将在本地视图中看到自己。 3. 邀请一位朋友通过另一台设备来使用相同的 App ID、频道名、Token 加入频道。你的朋友加入频道后,你们可以听见、看见对方。 ## 创建项目 [#创建项目-4] 参考以下操作,在 Visual Studio 中创建一个 Windows 项目: 1. 在 Visual Studio 上创建一个 Windows Forms 应用项目,详见 [Create a Windows Forms app in Visual Studio with C#](https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2017/ide/create-csharp-winform-visual-studio?view=vs-2017)。 3. 打开 **Configuration Manager** 窗口,在 **Active solution platform** 下拉菜单中选择 **New**,在弹出的窗口中选择 **x64** 或 **x86** 作为目标平台。 ## 集成 SDK [#集成-sdk-4] 使用 Visual Studio 中的 NuGet 包管理器,将 SDK 集成到项目中。详见[快速入门:在 Visual Studio 中安装和使用包](https://learn.microsoft.com/zh-cn/nuget/quickstart/install-and-use-a-package-in-visual-studio)。 :::info[信息] 你可以在 [agora_rtc_sdk](https://www.nuget.org/packages/agora_rtc_sdk/#versions-body-tab) 中获取最新发布的 SDK 的版本信息。 ::: ## 创建用户界面 [#创建用户界面-4] 为直观地体验视频通话,你需要根据应用场景创建用户界面(UI)。若你的项目中已有用户界面,可略过此步骤。 如果你想实现音视频互动,推荐在 UI 上添加以下控件: - 本地视图窗口 - 远端视图窗口 - 加入频道按钮 - 离开频道按钮 参考以下步骤创建 UI。 1. 创建 **Join** 和 **Leave** 按钮 1. 在你的项目中,打开 **Solution Explore** 窗口,双击 **Form1.cs**,打开 **Toolbox** 窗口,选择 **Button** 控件,依次添加两个按钮,并将两个按钮拖放至合适位置。 1. 将鼠标移至其中一个按钮上,点击鼠标右键,选中 **Properties**,在打开的 **Properties** 窗口中修改 **Text** 属性为 **Join**,修改 **Name** 属性为 **btnJoin**。 1. 重复上一个步骤来修改另一个按钮的属性:修改 **Text** 为 **Leave**;修改 **Name** 为 **btnLeave**。 2. 创建本地及远端视图窗口 1. 打开 **Toolbox** 窗口,选中 **PictureBox** 控件,依次为本地视图和远端视图在合适的位置添加控件。 1. 将鼠标移至本地视图窗口控件上,点击鼠标右键,选中 **Properties**,在打开的 **Properties** 窗口中修改 **Name** 属性为 **videoboxLocal**;修改 **BorderStyle** 为 **FixedSingle**。 1. 重复上一个步骤修改远端视图窗口控件的属性:修改 **Name** 为 **videoboxRemote**;修改 **BorderStyle** 为 **FixedSingle**。 3. 创建频道名输入框 1. 打开 **Toolbox** 窗口,选中 **TextBox** 控件,然后将其拖拽至合适位置。 1. 将鼠标移至添加好的输入框控件上,点击鼠标右键,选中 **Properties** ,修改其属性 **Name** 为 **txChannelName**。 4. 保存上述步骤的更改。 5. 分别双击 **Join** 和 **Leave** 按钮,IDE 会自动关联点击事件处理函数。 此时你的 UI 界面如下图所示: ![Windows Forms 用户界面示意图](https://web-cdn.agora.io/docs-files/1684404223720) ## 实现步骤 [#实现步骤-5] 本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中,快速体验实时音视频互动的基础功能,再按照实现步骤了解核心 API 调用。 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。 下面列出了一段实现实时互动基本流程的完整代码以供参考。 :::info[信息] 在 `APP_ID` 和 `Token` 字段中传入你在控制台获取到的 App ID 和临时 Token。 ::: ```csharp using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Linq; using System.Text; using System.Threading.Tasks; using System.Windows.Forms; using Agora.Rtc; namespace WindowsFormsApp2 { public partial class Form1 : Form { private readonly string APP_ID = ""; private readonly String APP_TOKEN = ""; private IRtcEngine engine_ = null; private RtcEventHandler handler_ = null; public Form1() { InitializeComponent(); // 创建引擎 engine_ = RtcEngine.CreateAgoraRtcEngine(); // 配置引擎实例 RtcEngineContext ctx = new RtcEngineContext() { appId = APP_ID, areaCode = AREA_CODE.AREA_CODE_GLOB, logConfig = { filePath = "rtc.log" } }; // 初始化引擎 var ret = engine_.Initialize(ctx); if (ret != 0) { Console.WriteLine("=====>Initialize failed {0}", ret); return; } // 注册事件句柄 handler_ = new RtcEventHandler(); handler_.EventOnUserJoined += OnUserJoined; engine_.InitEventHandler(handler_); // 启用视频模块 ret = engine_.EnableVideo(); if (ret != 0) { Console.WriteLine("=====>EnableVideo failed {0}", ret); } // 开启本地视频采集 ret = engine_.EnableLocalVideo(true); if (ret != 0) { Console.WriteLine("=====>EnableLocalVideo failed {0}", ret); } // 开始本地视频预览 ret = engine_.StartPreview(VIDEO_SOURCE_TYPE.VIDEO_SOURCE_CAMERA_PRIMARY); if (ret != 0) { Console.WriteLine("=====>StartPreview failed {0}", ret); } // 设置本地视图 VideoCanvas canvas = new VideoCanvas(); canvas.view = (long)videoboxLocal.Handle; canvas.renderMode = RENDER_MODE_TYPE.RENDER_MODE_FIT; ret = engine_.SetupLocalVideo(canvas); if (ret != 0) { Console.WriteLine("=====>SetupLocalVideo failed {0}", ret); } } private void btnJoin_Click(object sender, EventArgs e) { if (null != engine_) { ChannelMediaOptions options = new ChannelMediaOptions(); // 设置频道场景为直播 options.channelProfile.SetValue(CHANNEL_PROFILE_TYPE.CHANNEL_PROFILE_LIVE_BROADCASTING); // 设置用户角色为主播 options.clientRoleType.SetValue(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER); // 发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频流 options.publishCameraTrack = true; // 自动订阅所有音频流 options.autoSubscribeAudio = true; // 自动订阅所有视频流 options.autoSubscribeVideo = true; var ret = engine_.JoinChannel(APP_TOKEN, txChannelName.Text, 0, options); Console.WriteLine("=====>JoinChannel result {0}", ret); } } private void btnLeave_Click(object sender, EventArgs e) { if (null != engine_) { var ret = engine_.StopPreview(); var ret = engine_.LeaveChannel(); Console.WriteLine("=====>LeaveChannel result {0}", ret); } } private void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) { VideoCanvas canvas = new VideoCanvas(); canvas.view = (long)videoboxRemote.Handle; canvas.renderMode = RENDER_MODE_TYPE.RENDER_MODE_FIT; canvas.uid = remoteUid; int ret = engine_.SetupRemoteVideo(canvas); Console.WriteLine("----->SetupRemoteVideo, ret={0}", ret); } } internal class RtcEventHandler : IRtcEngineEventHandler { public delegate void OnUserJoinedHandler( RtcConnection connection, uint remoteUid, int elapsed ); // 声明 OnUserJoined 回调 public event OnUserJoinedHandler EventOnUserJoined; public RtcEventHandler() { } public override void OnError(int error, string msg) { Console.WriteLine("=====>OnError {0} {1}", error, msg); } public override void OnJoinChannelSuccess(RtcConnection connection, int elapsed) { Console.WriteLine("----->OnJoinChannelSuccess channel={0} uid={1}", connection.channelId,connection.localUid); } public override void OnLeaveChannel(RtcConnection connection, RtcStats stats) { Console.WriteLine("----->OnLeaveChannel duration={0}", stats.duration); } public override void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) { Console.WriteLine("----->OnUserJoined uid={0}", remoteUid); if (EventOnUserJoined != null) EventOnUserJoined.Invoke(connection, remoteUid, elapsed); } public override void OnUserOffline( RtcConnection connection, uint remoteUid, USER_OFFLINE_REASON_TYPE reason ) { Console.WriteLine("----->OnUserOffline, channel={0}, remoteUid={1}, reason={2}", connection.channelId, remoteUid, reason); } public override void OnRemoteVideoStateChanged( RtcConnection connection, uint remoteUid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed ) { Console.WriteLine("----->OnRemoteVideoStateChanged, channel={0}, remoteUid={1}, state={2}, reason={3}", connection.channelId, remoteUid, state, reason); } } } ``` ### 导入声网相关的类 [#导入声网相关的类-1] 导入声网 RTC SDK 相关的类。 ```csharp using Agora.Rtc; ``` ### 初始化引擎 [#初始化引擎-4] 调用 `CreateAgoraRtcEngine` 方法创建一个 `RtcEngine` 对象,然后调用 `initialize` 初始化 `RtcEngine`。 ```csharp // 创建引擎 engine_ = RtcEngine.CreateAgoraRtcEngine(); // 配置引擎实例 RtcEngineContext ctx = new RtcEngineContext() { appId = APP_ID, areaCode = AREA_CODE.AREA_CODE_GLOB, logConfig = { filePath = "rtc.log" } }; // 初始化引擎 var ret = engine_.Initialize(ctx); if (ret != 0) { Console.WriteLine("=====>Initialize failed {0}", ret); return; } ``` ### 启用视频模块 [#启用视频模块-4] 1. 调用 `EnableVideo` 方法,启用视频模块。 1. 调用 `SetupLocalVideo` 初始化本地视图,同时设置本地的视频显示属性。 1. 调用 `StartPreview` 方法,开启本地视频预览。 ```csharp // 启用视频模块 ret = engine_.EnableVideo(); if (ret != 0) { Console.WriteLine("=====>EnableVideo failed {0}", ret); } // 设置本地视图 VideoCanvas canvas = new VideoCanvas(); canvas.view = (long)videoboxLocal.Handle; canvas.renderMode = RENDER_MODE_TYPE.RENDER_MODE_FIT; ret = engine_.SetupLocalVideo(canvas); if (ret != 0) { Console.WriteLine("=====>SetupLocalVideo failed {0}", ret); } // 开启本地视频预览 ret = engine_.StartPreview(VIDEO_SOURCE_TYPE.VIDEO_SOURCE_CAMERA_PRIMARY); if (ret != 0) { Console.WriteLine("=====>StartPreview failed {0}", ret); } ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流-4] 调用 `JoinChannel`[2/2] 加入频道,填入你在控制台获取的临时 Token,以及获取 Token 时填入的频道名加入频道,并设置用户角色。 ```csharp ChannelMediaOptions options = new ChannelMediaOptions(); // 设置频道场景为直播 options.channelProfile.SetValue(CHANNEL_PROFILE_TYPE.CHANNEL_PROFILE_LIVE_BROADCASTING); // 设置用户角色为主播 options.clientRoleType.SetValue(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER); // 发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频流 options.publishCameraTrack = true; // 自动订阅所有音频流 options.autoSubscribeAudio = true; // 自动订阅所有视频流 options.autoSubscribeVideo = true; var ret = engine_.JoinChannel(APP_TOKEN, txChannelName.Text, 0, options); ``` ### 设置远端用户视图 [#设置远端用户视图-2] 调用 `SetupRemoteVideo` 方法初始化远端用户视图,同时设置远端用户的视图在本地显示属性。你可以通过 `OnUserJoined` 回调获取远端用户的 `uid`。 ```csharp private void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) { VideoCanvas canvas = new VideoCanvas(); canvas.view = (long)videoboxRemote.Handle; canvas.renderMode = RENDER_MODE_TYPE.RENDER_MODE_FIT; canvas.uid = remoteUid int ret = engine_.SetupRemoteVideo(canvas); Console.WriteLine("----->SetupRemoteVideo, ret={0}", ret); } ``` ### 实现常用回调 [#实现常用回调-4] 根据使用场景,定义必要的回调。以下示例代码展示如何实现 `OnJoinChannelSuccess`、 `OnUserJoined` 和 `OnUserOffline` 回调。 ```csharp public override void OnJoinChannelSuccess(RtcConnection connection, int elapsed) { Console.WriteLine("----->OnJoinChannelSuccess channel={0} uid={1}", connection.channelId,connection.localUid); } public override void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) { Console.WriteLine("----->OnUserJoined uid={0}", remoteUid); if (EventOnUserJoined != null) EventOnUserJoined.Invoke(connection, remoteUid, elapsed); } public override void OnUserOffline( RtcConnection connection, uint remoteUid, USER_OFFLINE_REASON_TYPE reason ) ``` ### 开始音视频互动 [#开始音视频互动-3] 在 `btnJoin_Click` 函数中调用 `JoinChannel`[2/2] 方法,当用户点击 **Join** 按钮时开始音视频互动。 ```csharp private void btnJoin_Click(object sender, EventArgs e) { if (null != engine_) { ... var ret = engine_.JoinChannel(APP_TOKEN, txChannelName.Text, 0, options); Console.WriteLine("=====>JoinChannel result {0}", ret); } } ``` ### 结束音视频互动 [#结束音视频互动-3] 1. 在 **btnLeave_Click** 函数中调用 `LeaveChannel` 方法,当用户点击 **Leave** 按钮时结束音视频互动。 ```csharp private void btnLeave_Click(object sender, EventArgs e) { if (null != engine_) { var ret = engine_.StopPreview(); var ret = engine_.LeaveChannel(); Console.WriteLine("=====>LeaveChannel result {0}", ret); } } ``` 2. 调用 `Dispose` 销毁引擎,并释放声网 SDK 中使用的所有资源。 ```csharp engine_.Dispose() ``` :::error[警告] - 调用 `Dispose` 后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#cs-initialize)。 - 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。 ::: ## 测试你的项目 [#测试你的项目] 按照以下步骤来测试你的视频通话项目: 1. 将你从声网控制台获取的 App ID 和临时 Token 分别填入到 `Form1.cs` 文件的 `APP_ID` 和 `APP_TOKEN` 中。 1. 在 Visual Studio 中点击 **Start** 按钮运行你的项目,你将在本地视图中看到自己。 2. 在输入框中输入你在声网控制台生成临时 Token 时填写的频道名,并点击 **Join** 按钮加入频道。 4. 邀请一位朋友通过另一台设备来使用相同的 App ID、频道名、Token 加入频道。你的朋友加入频道后,你们可以听见、看见对方。 ## 后续步骤 [#后续步骤-3] - 在测试或生产环境中,为确保通信安全,声网推荐使用 Token 服务器来生成 Token,详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - 如果你想要实现极速直播场景,可以在互动直播的基础上,通过修改观众端的延时级别为低延时 (`AUDIENCE_LATENCY_LEVEL_LOW_LATENCY`)实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。 ## 参考信息 [#参考信息-4] ### 示例项目 [#示例项目-4] 声网提供了开源的音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。 C++ C# LiveBroadcasting} href="https://gitee.com/agoraio-community/API-Examples/tree/main/windows/APIExample/APIExample/Basic/LiveBroadcasting" /> LiveBroadcasting} href="https://github.com/Shengwang-Community/API-Examples/tree/main/windows/APIExample/APIExample/Basic/LiveBroadcasting" /> JoinChannelVideo} href="https://github.com/AgoraIO-Extensions/Agora-C_Sharp-SDK/tree/master/APIExample/src/Basic/JoinChannelVideo" /> JoinChannelVideo} href="https://gitee.com/agoraio-community/Agora-C_Sharp-SDK/tree/main/Agora-C_Sharp-RTC-SDK-API_Example/src/Basic/JoinChannelVideo" /> ### 常见问题 [#常见问题-4] - [直播场景下,如何监听远端观众角色用户加入/离开频道的事件?](/zh-CN/reference/faq/integration/audience_event) - [如何处理视频黑屏问题?](/zh-CN/reference/faq/quality/video_blank) - [为什么我无法打开摄像头?](/zh-CN/reference/faq/quality/video_camera) - [如何处理频道相关常见问题?](/zh-CN/reference/faq/integration/channel) - [如何设置日志文件](/zh-CN/reference/faq/integration/set_log_file) - [为什么 SDK 中使用的是动态库而不是静态库?](/zh-CN/reference/faq/integration/dynamic_or_static_library) ### 相关文档 [#相关文档-3] - [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code) - [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="harmonyos" /> 本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的实时互动 App,适用于互动直播和视频通话场景。 首先,你需要了解以下有关音视频实时互动的基础概念: - 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。 - 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。 - 主播:可以在频道内**发布**音视频,同时也可以**订阅**其他主播发布的音视频。 - 观众:可以在频道内**订阅**音视频,不具备**发布**音视频权限。 更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。 下图展示在 App 中实现音视频互动的基本工作流程: 1. 所有用户调用 `joinChannel` 方法加入频道,并根据需要设置用户角色: - 互动直播:如果用户需要在频道中发流,则设为主播;如果用户只需要收流,则设为观众。 - 视频通话:将所有用户的角色都设为主播。 2. 加入频道后,不同角色的用户具备不同的行为: - 所有用户默认都可以接收频道中的音视频流。 - 主播可以在频道内发布音视频流。 - 观众如果需要发流,可在频道内调用 `setClientRole` 方法修改用户角色,使其具备发流权限。 ## 前提条件 [#前提条件-5] 在实现功能以前,请按照以下要求准备开发环境: - DevEco Studio 5.1.0 Release 及以上版本,已包含所需的 HarmonyOS SDK。 - 运行 API 12 及以上版本 HarmonyOS 的设备。 - 华为开发者账号。可在[华为开发者联盟](https://developer.huawei.com/consumer/cn/)注册账号。 - 两台支持 HarmonyOS 的设备,建议使用 Mate 60 Pro 及更高性能的设备。 - 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 一个有效的声网账号以及声网项目。请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)从声网控制台获得 App ID 和临时 Token。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。 ::: ## 创建项目 [#创建项目-5] 本小节介绍如何创建项目并为项目添加体验实时互动所需的权限。 1. 参考[创建和运行 Hello World](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V2/hello_world-0000001054516888-V2),创建一个新工程。 2. 打开 **entry/src/main** 中的 `module.json5` 文件,在 `module` 模块中声明网络和设备权限: ```json "requestPermissions": [ // 访问互联网的权限 { "name": "ohos.permission.INTERNET", "reason": "$string:Internet_reason", "usedScene": { "abilities": [ "EntryAbility" ], "when": "always" // 始终需要该权限 } }, // 访问麦克风的权限 { "name": "ohos.permission.MICROPHONE", "reason": "$string:Audio_reason", "usedScene": { "abilities": [ "EntryAbility" ], "when": "always" // 始终需要该权限 } }, // 访问摄像头的权限 { "name": "ohos.permission.CAMERA", "reason": "$string:Video_reason", "usedScene": { "abilities": [ "EntryAbility" ], "when": "inuse" // 仅在使用时需要该权限 } } ] ``` 3. 打开 **src/main/resources/base/element** 中的 `string.json` 文件,添加如下代码,定义所需要的权限。 ```json { "name": "Internet_reason", "value": "access internet" }, { "name": "Audio_reason", "value": "access audio" }, { "name": "Video_reason", "value": "access video" } ``` ## 集成 SDK [#集成-sdk-5] 1. 在[下载](/zh-CN/realtime-media/rtc/reference/downloads)页面下载最新版本的鸿蒙视频 SDK,并在本地解压。 2. 打开解压文件,将 `AgoraRtcSdk.har` 文件复制到项目 **entry -> libs** 目录下(libs 文件夹需要手动创建)。 3. 在 **entry** 下的 `oh-package.json5` 文件中添加如下依赖,然后点击 **Sync** 开始同步。 ```json "dependencies": { "@shengwang/rtc-full":"file:./libs/AgoraRtcSdk.har" } ``` ## 实现步骤 [#实现步骤-6] 本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中,快速体验实时音视频互动的基础功能,再按照实现步骤了解核心 API 调用。 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程: 下面列出了一段实现实时互动基本流程的完整代码以供参考。复制以下代码到 `pages/Index.ets` 文件中替换原有内容,即可快速体验实时互动基础功能。 :::info[信息] 在 `appId`、`token` 和 `channelName` 字段中传入你在控制台获取到的 App ID、临时 Token,以及生成临时 Token 时填入的频道名。 ::: ```arkts import { ChannelMediaOptions, Constants, RtcEngine, RtcEngineConfig, RtcStats, VideoCanvas, } from "AgoraRtcSdk" import { common } from '@kit.AbilityKit'; @Entry @Component struct Index { private rtcEngine: RtcEngine | null = null; @State isJoined: boolean = false; private channel = "hmostest"; build() { Flex({ direction: FlexDirection.Column }) { Stack({ alignContent: Alignment.TopStart }) { XComponent({ // id 必须在当前页面是唯一的 id: 'local', // type 必须设置为 surface type: 'surface', // libraryname 必须设置为 Constants。AGORA_LIB_NAME libraryname: Constants.AGORA_LIB_NAME, }) .width('100%') .height('100%') .backgroundColor(Color.Gray) .align(Alignment.TopStart) XComponent({ id: 'remote', type: 'surface', libraryname: Constants.AGORA_LIB_NAME, }) .onLoad(() => { }) .width('33%') .height('25%') .margin({ top: 10, left: 10 }) .align(Alignment.TopStart) }.width("100%") .height("85%") .margin({ top: 10, bottom: 10 }) Row() { Button("Join") .enabled(!this.isJoined) .fontSize(20) .width("40%") .margin({ left: "5%", right: "5%" }) .align(Alignment.Center) .onClick(() => { this.initEngineAndJoinChannel(); }) Button("Leave") .enabled(this.isJoined) .fontSize(20) .width("40%") .align(Alignment.Center) .onClick(() => { this.rtcEngine!.stopPreview(); this.rtcEngine!.leaveChannel(); }) .margin({ left: "5%", right: "5%" }) }.align(Alignment.Center) .margin({ top: "5%", bottom: "5%" }) } } initEngineAndJoinChannel() { if (this.rtcEngine === null) { let config: RtcEngineConfig = new RtcEngineConfig(); let context = getContext(this) as common.UIAbilityContext; config.mContext = context; config.mAppId = "<#Your App ID#>"; config.mEventHandler = {}; config.mEventHandler.onUserJoined = (uid: number, collapse: number) => { console.info("mEventHandler.onUserJoined: " + uid + " , " + collapse); let canvas: VideoCanvas = new VideoCanvas('remote'); canvas.uid = uid; this.rtcEngine!.setupRemoteVideo(canvas); }; config.mEventHandler.onUserOffline = (uid: number, reason: number) => { console.info("mEventHandler.onUserOffline: " + uid + " , " + reason); }; config.mEventHandler.onJoinChannelSuccess = (cid: string, uid: number, elapsed: number) => { console.info("mEventHandler.onJoinChannelSuccess: " + cid + " , " + uid); this.isJoined = true; }; config.mEventHandler.onLeaveChannel = (stats: RtcStats | null) => { console.info("mEventHandler.onLeaveChannel "); this.isJoined = false; }; this.rtcEngine = RtcEngine.create(config); this.rtcEngine.enableVideo(); // 设置本地视图 // local 为用于渲染本地图像的 XComponent 的 ID let canvas: VideoCanvas = new VideoCanvas("local"); canvas.uid = 0; canvas.renderMode = VideoCanvas.RENDER_MODE_HIDDEN; this.rtcEngine.setupLocalVideo(canvas); this.rtcEngine.startPreview(); } let option: ChannelMediaOptions = new ChannelMediaOptions(); option.autoSubscribeAudio = true; option.autoSubscribeVideo = true; option.publishCameraTrack = true; option.publishMicrophoneTrack = true; option.channelProfile = Constants.ChannelProfile.LIVE_BROADCASTING; option.clientRoleType = Constants.ClientRole.BROADCASTER; // joinChannelWithOptions(token:string, channelId:string, uid:number, options:ChannelMediaOptions) // uid 为 0,表示由服务器分配 uid,分配的 uid 将通过 onJoinChannelSuccess 回调返回 this.rtcEngine.joinChannelWithOptions("<#Your Token#>", this.channel, 0, option); } aboutToDisappear(): void { if (this.rtcEngine != null) { RtcEngine.destroy(); this.rtcEngine = null; } } } ``` ### 处理权限请求 [#处理权限请求-1] 本小节介绍如何获取设备的摄像头、录音等权限。 1. 在项目中打开 **entryability** -> `EntryAbility.ets` 文件,在 `EntryAbility` 之前添加权限申请,示例代码如下所示。 启动应用程序时,检查是否已在 App 中授予了实现实时互动所需的权限。 ```arkts const permissions: Array = ['ohos.permission.INTERNET','ohos.permission.MICROPHONE',"ohos.permission.CAMERA"]; async function checkAccessToken(permission: Permissions): Promise { let atManager = abilityAccessCtrl.createAtManager(); let grantStatus: abilityAccessCtrl.GrantStatus = abilityAccessCtrl.GrantStatus.PERMISSION_DENIED; // 获取应用程序的 accessTokenID let tokenId: number = 0; try { let bundleInfo: bundleManager.BundleInfo = await bundleManager.getBundleInfoForSelf(bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION); let appInfo: bundleManager.ApplicationInfo = bundleInfo.appInfo; tokenId = appInfo.accessTokenId; } catch (error) { let err: BusinessError = error as BusinessError; console.error(`Failed to get bundle info for self. Code is ${err.code}, message is ${err.message}`); } // 校验 App 是否被授予权限 try { grantStatus = await atManager.checkAccessToken(tokenId, permission); } catch (error) { let err: BusinessError = error as BusinessError; console.error(`Failed to check access token. Code is ${err.code}, message is ${err.message}`); } return grantStatus; } export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); let context = this.context; let atManager = abilityAccessCtrl.createAtManager(); // requestPermissionsFromUser 会判断权限的授权状态来决定是否唤起弹窗 for(let i=0;i = new Array(); toGrantedPerm.push(permission) checkAccessToken(permission).then((value)=>{ if(value == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED){ granted = true; hilog.info(0x0000, 'testTag', '%{public}s', 'Permission granted'); } else { atManager.requestPermissionsFromUser(context, toGrantedPerm).then((data) => { let grantStatus: Array = data.authResults; let length: number = grantStatus.length; for (let i = 0; i < length; i++) { if (grantStatus[i] === 0) { // 用户授权,可以继续访问目标操作 } else { // 用户拒绝授权,提示用户必须授权才能访问当前页面的功能,并引导用户到系统设置中打开相应的权限 hilog.info(0x0000, 'testTag', '%{public}s', 'Permission denied'); return; } } // 授权成功 }).catch((err: BusinessError) => { hilog.info(0x0000, 'testTag', '%{public}s',`Failed to request permissions from user. Code is ${err.code}, message is ${err.message}`); }) } }) } } } ``` ### 导入声网组件 [#导入声网组件-2] 打开 `src/main/ets/pages/Index.ets` 文件,导入如下所需的声网 SDK 组件。 ```arkts import { ChannelMediaOptions, Constants, RtcEngine, RtcEngineConfig, RtcStats, VideoCanvas, } from "@shengwang/rtc-full" ``` ### 添加视频渲染组件 [#添加视频渲染组件] 在 `Index.ets` 文件中添加视频渲染组件 `XComponent`。 ```arkts @Entry @Component struct Index { @State message: string = 'Hello World'; build() { Row() { Column() { XComponent({ // id 必须在当前页面是唯一的 id: 'local', // type 必须设置为 surface type: 'surface', // libraryname 必须设置为 Constants.AGORA_LIB_NAME libraryname: Constants.AGORA_LIB_NAME, }) .width('100%') .height('100%') .align(Alignment.TopStart) XComponent({ id: 'remote', type: 'surface', libraryname: Constants.AGORA_LIB_NAME, }) .width('100%') .height('50%') .margin({ bottom: 10 }) Text(this.message) .fontSize(50) .fontWeight(FontWeight.Bold) } .width('100%') } .height('100%') } } ``` ### 初始化引擎 [#初始化引擎-5] 调用 `create` 方法初始化 `RtcEngine`。 :::warning[注意] 在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。 ::: ```arkts let config:RtcEngineConfig = new RtcEngineConfig(); let context = getContext(this) as common.UIAbilityContext; config.mContext = context; // 在这里输入你在声网控制台中获取的 App ID config.mAppId = "<#Your App ID#>"; config.mEventHandler = {}; // 创建并初始化 RtcEngine this.rtcEngine = RtcEngine.create(config); ``` ### 启用视频模块 [#启用视频模块-5] 按照以下步骤启用视频模块: 1. 调用 `enableVideo` 方法,启用视频模块。 2. 调用 `setupLocalVideo` 方法初始化本地视图,同时设置本地的视频显示属性。 3. 调用 `startPreview` 方法,开启本地视频预览。 ```arkts this.rtcEngine.enableVideo(); // 设置本地视图 // local 为用于渲染本地图像的 XComponent 的 ID let canvas: VideoCanvas = new VideoCanvas("local"); canvas.uid = 0; canvas.renderMode = VideoCanvas.RENDER_MODE_HIDDEN; canvas.mirrorMode = VideoCanvas.VIDEO_MIRROR_MODE_ENABLED; this.rtcEngine.setupLocalVideo(canvas); this.rtcEngine.startPreview(); ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流-5] 调用 `joinChannelWithOptions` 加入频道。在 `options` 中进行如下配置: - 设置频道场景为 `BROADCASTING`(直播场景),并将用户角色设置为 `BROADCASTER`(主播)或 `AUDIENCE`(观众)。 - 将 `publishMicrophoneTrack` 和 `publishCameraTrack` 设置为 `true`,发布麦克风采集的音频和摄像头采集的视频。 - 将 `autoSubscribeAudio` 和 `autoSubscribeVideo` 设置为 `true`,自动订阅所有音视频流。 ```arkts let option:ChannelMediaOptions = new ChannelMediaOptions(); // 自动订阅所有音频流 option.autoSubscribeAudio = true; // 自动订阅所有视频流 option.autoSubscribeVideo = true; // 发布摄像头采集的视频 option.publishCameraTrack = true; // 发布麦克风采集的音频 option.publishMicrophoneTrack = true; // 设置频道场景为直播 option.channelProfile = Constants.ChannelProfile.LIVE_BROADCASTING; // 设置用户角色为主播;如果要将用户角色设置为观众,保持默认值即可 option.clientRoleType = Constants.ClientRole.BROADCASTER; // 使用临时 Token 加入频道,在这里传入你的项目的 Token 和频道名 // uid 为 0,表示由服务器分配 uid,分配的 uid 将通过 onJoinChannelSuccess 回调返回 this.rtcEngine.joinChannelWithOptions(<#Your Token#>, <#Your Channel Name#>, 0,option); ``` ### 设置远端视图 [#设置远端视图-2] 调用 `setupRemoteVideo` 方法初始化远端用户视图,同时设置远端用户的视图在本地显示属性。你可以通过 `onUserJoined` 回调获取远端用户的 `uid`。 ```arkts config.mEventHandler.onUserJoined = (uid: number, collapse: number) => { // 设置远端渲染 // remote 为用于渲染远端图像的 XComponent 的 ID let canvas:VideoCanvas = new VideoCanvas('remote'); canvas.uid = uid; this.rtcEngine!.setupRemoteVideo(canvas); }; ``` ### 实现常用回调 [#实现常用回调-5] 根据使用场景,定义必要的回调。以下示例代码展示如何实现 `onJoinChannelSuccess` 和 `onUserOffline` 回调。 ```arkts config.mEventHandler.onJoinChannelSuccess = (cid: string, uid: number, elapsed: number) => { console.info("mEventHandler.onJoinChannelSuccess: " + cid + " , " + uid); }; config.mEventHandler.onUserOffline = (uid: number, reason: number) => { console.info("mEventHandler.onUserOffline: " + uid + " , " + reason); }; ``` ### 开始音视频互动 [#开始音视频互动-4] 在 `onClick` 中调用一系列方法加载界面布局、检查 App 是否获取实时互动所需权限,并加入频道开始音视频互动。 ```arkts Button("Join") .enabled(!this.isJoined) .fontSize(20) .width("40%") .margin({ left: "5%", right: "5%" }) .align(Alignment.Center) .onClick(() => { this.initEngineAndJoinChannel(); }) ``` ### 结束音视频互动 [#结束音视频互动-4] 按照以下步骤结束音视频互动: 1. 调用 `stopPreview` 停止视频预览。 2. 调用 `leaveChannel` 离开当前频道,释放所有会话相关的资源。 3. 调用 `destroy` 销毁引擎,并释放声网 SDK 中使用的所有资源。 :::warning[注意] - 调用 `destroy` 后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎-5)。 - 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。 ::: ```arkts this.rtcEngine!.stopPreview(); this.rtcEngine!.leaveChannel(); RtcEngine.destroy(); this.rtcEngine = null; ``` ## 调试 App [#调试-app-3] 按照以下步骤测试直播 App: 1. 开启鸿蒙 NEXT 设备的开发者选项,打开 USB 调试,通过 USB 连接线将鸿蒙 NEXT 设备接入电脑。 2. 在 DevEcho Studio 中,点击 **Sync and Refresh Project**进行同步。 3. 待同步成功后,点击 **Run 'app'** 开始编译。片刻后,App 便会安装到你的鸿蒙 NEXT 设备上。 4. 启动 App,授予录音和摄像头权限,如果你将用户角色设置为主播,便会在本地视图中看到自己。 5. 使用第二台鸿蒙 NEXT 设备,重复以上步骤,在该设备上安装 App、打开 App 加入频道,观察测试结果: - 如果两台设备均作为主播加入频道,则可以看到对方并且听到对方的声音。 - 如果两台设备分别作为主播和观众加入,则主播可以在本地视频窗口看到自己;观众可以在远端视频窗口看到主播、并听到主播的声音。 ## 后续步骤 [#后续步骤-4] 在完成音视频互动后,你可以阅读以下文档进一步了解: - 本文的示例使用了临时 Token 加入频道。在测试或生产环境中,为保证通信安全,声网推荐从服务器中获取 Token,详情请参考[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - 如果你想要实现极速直播场景,可以在实时音视频互动的基础上,通过修改观众端的延时级别为低延时 (`LOW_LATENCY`) 实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。 ## 参考信息 [#参考信息-5] ### 示例项目 [#示例项目-5] 声网提供了开源的实时音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。 JoinVideoChannel} href="https://gitee.com/agoraio-community/API-Examples/tree/main/HarmonyOS/APIExample/entry/src/main/ets/pages/basic" /> JoinVideoChannel} href="https://github.com/Shengwang-Community/API-Examples/tree/main/HarmonyOS/APIExample/entry/src/main/ets/pages/basic" /> ### 常见问题 [#常见问题-5] - [直播场景下,如何监听远端观众角色用户加入/离开频道的事件?](/zh-CN/reference/faq/integration/audience_event) - [如何处理视频黑屏问题?](/zh-CN/reference/faq/quality/video_blank) - [为什么我无法打开摄像头?](/zh-CN/reference/faq/quality/video_camera) - [如何处理频道相关常见问题?](/zh-CN/reference/faq/integration/channel) - [如何设置日志文件?](/zh-CN/reference/faq/integration/set_log_file) - [为什么部分鸿蒙版本 App 锁屏或切后台音视频采集无效?](/zh-CN/reference/faq/quality/harmonyos_background) ### 相关文档 [#相关文档-4] - [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code) - [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="mini-program" /> 本文介绍如何建立一个简单的项目并使用声网小程序 SDK 实现基础的视频通话。 ## 前提条件 [#前提条件-6] 开始前,请确保你的开发环境满足如下条件: - 一个经过企业认证的微信小程序账号。在调试小程序 Demo 过程中,需要使用 live-pusher 和 live-player 组件。只有特定行业的认证企业账号才可以使用这两个组件。详见[小程序官网文档](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html)。 - 下载并安装最新版本的[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)。 - 参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)在控制台创建项目、获取 App ID 和临时 Token,并[开通小程序服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service#mini-program-service)。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致鉴权失败或无法加入频道。 ::: - 至少一台安装有微信 App 的移动设备。 :::info[信息] 在集成微信小程序组件之前,声网建议你先阅读[微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)。 ::: ## 准备开发环境 [#准备开发环境] ### 1. 获取小程序组件权限 [#1-获取小程序组件权限] 在[微信公众平台](https://mp.weixin.qq.com/)的小程序**开发**选项中,切换到**接口设置**页签,打开**实时播放音视频流**和**实时录制音视频流**的开关。 ![打开音视频开关](https://web-cdn.agora.io/docs-files/1605069073929) ### 2. 配置服务器域名 [#2-配置服务器域名] 在小程序的开发设置里,将如下域名配到服务器域名里,其中 **request 合法域名**区域填入以 https 开头的域名;**socket 合法域名**区域填入以 wss 开头的域名。 如果你使用的 SDK 为 **v2.5.3** 或更高版本,你需要在 **request 合法域名**及 **socket 合法域名**中添加以下域名: ```shell wss://miniapp.agoraio.cn https://uap-ap-web-1.agora.io https://uap-ap-web-2.agoraio.cn https://uap-ap-web-3.agora.io https://uap-ap-web-4.agoraio.cn https://report-ad.agoralab.co https://rest-argus-ad.agoralab.co ``` ![添加域名](https://web-cdn.agora.io/docs-files/1638759333663) 如果你使用的 SDK 为 v2.4.6 或更低版本,你需要在 request 合法域名及 socket 合法域名中添加以下域名: ```shell wss://miniapp.agoraio.cn https://miniapp-1.agoraio.cn https://miniapp-2.agoraio.cn https://miniapp-3.agoraio.cn https://miniapp-4.agoraio.cn ``` ### 3. 创建小程序 [#3-创建小程序] 参考如下步骤创建一个新的小程序。 1. 打开**微信开发者工具**,然后按照屏幕提示扫码登录。 2. 完成登录后,点击小程序界面的 **+**。 3. 在弹出的**新建项目**界面中,依次填入小程序的**项目名称**、本地存储**目录**、小程序 **AppID**,然后点击**新建**。 成功创建小程序后,微信开发者工具的左侧会显示当前小程序的界面。你还可以点击**真机调试**,并扫描生成的二维码,在手机上进行体验。 ### 4. 添加微信小程序组件 [#4-添加微信小程序组件] 在微信小程序中实现音视频功能,需要使用微信的 live-player 组件和 live-pusher 组件。详见[微信小程序 API 说明](https://developers.weixin.qq.com/miniprogram/dev/api/)。 - live-player 组件 该组件用于实现微信小程序的实时音视频播放功能。开发者在创建该组件后,还需要在 js 文件中调用 API 接口对应的组件来实现该功能。声网小程序中,创建 `live-player` 的示例代码如下: ```javascript ``` - live-pusher 组件 该组件用于实现微信小程序的实时音视频录制功能。开发者在创建该组件后,还需要在 js 文件中调用 API 接口对应的组件来实现该功能。声网小程序中,创建 `live-pusher` 的示例代码如下: ```javascript ``` ### 5. 集成 SDK [#5-集成-sdk] 你可以通过下载压缩包或 npm 任一种方式集成小程序 SDK。 下载压缩包 通过 npm 集成 1. 下载[声网小程序 SDK](/zh-CN/realtime-media/rtc/reference/downloads) 并解压。 2. 将 SDK 包中的 **Agora_Miniapp_SDK_for_WeChat.js** 文件复制到你的小程序项目文件夹中。 3. 使用 `require` 将小程序 SDK 导入到你的项目中: ```javascript // ..Agora_Miniapp_SDK_for_WeChat.js 为你的 js 文件本地路径 const AgoraMiniappSDK = require('..Agora_Miniapp_SDK_for_WeChat.js'); ``` 如果你使用 v2.6.0 或更高版本的小程序 SDK 以及 1.02.1808300 或更高版本的[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html),可通过 npm 安装小程序 SDK。 1. 初始化项目。在你的项目根目录打开终端,运行以下命令: ```shell npm init ``` 完成后,打开你的项目文件夹中的 `package.json` 文件。在 `dependencies` 字段中添加 `agora-miniapp-sdk` 及版本号,设为 `latest` 即使用最新版本。 ```json { "name": "premium-miniapp", "version": "1.0.0", "description": "", "main": "app.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "dependencies": { "agora-miniapp-sdk": "latest" }, // 添加其他业务逻辑 } ``` 2. 安装依赖。在你的项目根目录打开终端,运行以下命令: ```shell npm install ``` 3. 构建 npm。在微信开发者工具中,从菜单栏选择**工具** > **构建 npm**。 4. 导入 SDK。使用 `require` 将小程序 SDK 导入到你的项目中: ```javascript const AgoraMiniappSDK = require("agora-miniapp-sdk"); ``` ## 实现音视频互动 [#实现音视频互动] 完成上述步骤后,你可以参考下图中的业务流程图,在你的项目中实现通话功能。 ![小程序通话流程](https://web-cdn.agora.io/docs-files/1675997572227) :::info[信息] -2301 和 -1307 是微信小程序 `live-player` 和 `live-pusher` 组件的状态码,表示网络断连,需要自行重启。详见微信小程序 [live-player](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html) 和 [live-pusher](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html) 组件文档。 ::: ### 1. 初始化客户端对象 [#1-初始化客户端对象] 调用 [`client.init`](/zh-CN/api-reference/rtc/mini-program/classes/client#init) 方法创建并初始化一个用于控制通话的客户端对象。你需要将 `APPID` 替换为你的声网项目的 App ID。详见[获取 App ID](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。 ```javascript // Callback 形式调用 let client = new AgoraMiniappSDK.Client(); client.init(APPID () => { Utils.log(`client init success`); }, e => { Utils.log(`client init failed: ${e} ${e.code} ${e.reason}`); reject(e) }); // Promise 形式调用 let client = new AgoraMiniappSDK.Client(); await client.init(APPID) ``` ### 2. 加入频道 [#2-加入频道] 调用 [`client.join`](/zh-CN/api-reference/rtc/mini-program/classes/client#join) 方法加入频道。 在 `client.join` 中你需要将 `yourToken` 替换成你自己生成的 Token。并填入想要加入的频道名以及用户 `uid`。在测试阶段,你可以直接在控制台[生成临时 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。在生产环境,我们推荐你在自己的服务端生成 Token,详见在[服务端生成 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 ```javascript // Callback 形式调用 client.join(yourToken, channel, uid, () => { Utils.log(`client join channel success`); }, e => { Utils.log(`client join channel failed: ${e.code} ${e.reason}`); reject(e) }); // Promise 形式调用 await client.join(yourToken, channel, uid) ``` ### 3. 发布本地流 [#3-发布本地流] 成功加入频道后,就能调用 [`client.publish`](/zh-CN/api-reference/rtc/mini-program/classes/client#publish) 方法将本地音视频流发布到频道中。成功发布后,SDK 会返回该路音视频流的 URL。 ```javascript // Callback 形式调用 client.publish(url => { Utils.log(`client publish success`); resolve(url); }, e => { Utils.log(`client publish failed: ${e.code} ${e.reason}`); reject(e) }); // Promise 形式调用 const url = await client.publish() ``` ### 4. 订阅远端流 [#4-订阅远端流] 当远端流发布到频道时,会触发 `stream-added` 事件,我们需要通过 [`client.on`](/zh-CN/api-reference/rtc/mini-program/classes/client#on) 监听该事件并在回调中订阅新加入的远端流。 ```javascript // Callback 形式调用 client.on("stream-added", e => { client.subscribe(uid => { Utils.log(`stream ${uid} subscribed successful`); }, e => { Utils.log(`stream subscribed failed ${e} ${e.code} ${e.reason}`); }); }); // Promise 形式调用 client.on("stream-added", async e => { const { url, rotation } = await client.subscribe(uid) }); ``` 当远端用户取消发布流或退出频道时,关闭及移除对应的流。 ```javascript client.on("stream-removed", e => { console.log(`stream-removed: ${JSON.stringify(e)}`) let uid = e.uid[0]; console.log(`stream ${uid} removed`); this.removeMedia(uid); }); ``` ### 5. 更多功能 [#5-更多功能] 在实际使用中,你还可以根据使用场景实现如下功能。 **重连** 如果你的项目中有切换到后台的场景需求,声网推荐调用 [`client.rejoin`](/zh-CN/api-reference/rtc/mini-program/classes/client#rejoin) 方法做好重连机制。你需要在该方法中传入当前频道内所有用户的 `uid` 作为额外参数。其他参数的设置与 `join` 方法相同。 ```javascript // Callback 形式调用 client.rejoin(yourToken, channel, uid, uids, () => { Utils.log(`client join channel success`); }, e => { Utils.log(`client join channel failed: ${e.code} ${e.reason}`); }); // Promise 形式调用 await client.rejoin(yourToken, channel, uid, uids) ``` ### 完整示例代码 [#完整示例代码] 你可以直接参考如下示例代码,在项目中实现想要的功能。 ```javascript tab="以下为 callback 形式调用的完整示例代码" // 以下为 callback 形式调用的完整示例代码 let client = new AgoraMiniappSDK.client(); this.client = client; // 初始化客户端 client.init(APPID, () => { Utils.log(`client init success`); // 加入频道 client.join(yourToken, channel, uid, () => { Utils.log(`client join channel success`); // 发布本地流 if (this.isBroadcaster()) { client.publish(url => { Utils.log(`client publish success`); resolve(url); }, e => { Utils.log(`client publish failed: ${e.code} ${e.reason}`); reject(e) }); } else { resolve(); } }, e => { Utils.log(`client join channel failed: ${e.code} ${e.reason}`); reject(e) }) }, e => { Utils.log(`client init failed: ${e} ${e.code} ${e.reason}`); reject(e) }); ``` ```javascript tab="以下为 promise 形式调用的完整示例代码" // 以下为 promise 形式调用的完整示例代码 try { let client = new AgoraMiniappSDK.client(); // 初始化客户端 await client.init(APPID) // 设置角色 this.role = "broadcaster" await client.setRole(this.role) // 加入频道 await client.join(yourToken, channel, uid) if (this.isBroadcaster()) { // 发布本地流 const url = await client.publish() } } catch (e) { console.error(e) } ``` ## 运行项目 [#运行项目] 为保证运行效果,我们建议你在真机上运行项目。完成开发后,点击**微信开发者工具**界面的**真机调试**。扫描生成的二维码,即可在手机端运行和调试项目。 ## 参考信息 [#参考信息-6] ### 与 Native 互通 [#与-native-互通] 频道中有小程序 SDK 和 Native SDK 时,可以选择如下一种方式实现互通: - Native 端在直播模式下,将用户角色设置为 `AgoraClientRoleBroadcaster` = 1:主播,实现互通 - Native 端在直播模式下,不设置用户角色为主播,也可以接收到小程序端的流,实现互通 小程序和 Native 互通时,Native 端视频画面可能出现上下颠倒。该问题可能是由于 Native SDK 中的 `setVideoEncoderConfiguration` 设置的方向模式 `orientationMode` 为 `ORIENTATION_MODE.ORIENTATION_MODE_ADAPTIVE` 导致的。解决方法是,将方向模式改成 `ORIENTATION_MODE.ORIENTATION_MODE_FIXED_PORTRAIT` 就可以解决问题。 ### 与 Web 互通 [#与-web-互通] 小程序和 Web 互通时,可能出现 Web 端可以看到小程序的视频,但小程序看不到 Web 端的视频。该问题可能是由于编解码格式不被支持导致的。 Web 与小程序互通时,小程序端只支持 H264 模式的编码,不支持 VP8。将 Web SDK 的 `index.html` 文件修改为如下设置即可: ```javascript client = AgoraRtc.createClient({mode: "live", codec: "h264"}); ``` ### 示例项目 [#示例项目-6] 声网在 GitHub 上提供一个开源的小程序实时音视频示例项目,你可以下载体验或参考源代码。 ### 相关文档 [#相关文档-5] 使用微信小程序 SDK 开发过程中,你还可以参考如下文档: * [跑通小程序示例项目](/zh-CN/realtime-media/rtc/get-started/run-demo) * [小程序 SDK 常见问题集](/zh-CN/reference/faq/integration/mini_program):例如日志功能,通用问题,错误排查。 * [SDK 错误码和警告码](/zh-CN/realtime-media/rtc/reference/error-code) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="electron" /> 本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的实时互动 App,适用于互动直播和视频通话场景。 首先,你需要了解以下有关音视频实时互动的基础概念: - 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。 - 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。 - 主播:可以在频道内**发布**音视频,同时也可以**订阅**其他主播发布的音视频。 - 观众:可以在频道内**订阅**音视频,不具备**发布**音视频权限。 更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。 下图展示在 App 中实现音视频互动的基本工作流程: 1. 所有用户调用 `joinChannel` 方法加入频道,并根据需要设置用户角色: - 互动直播:如果用户需要在频道中发流,则设为主播;如果用户只需要收流,则设为观众。 - 视频通话:将所有用户的角色都设为主播。 2. 加入频道后,不同角色的用户具备不同的行为: - 所有用户默认都可以接收频道中的音视频流。 - 主播可以在频道内发布音视频流。 - 观众如果需要发流,可在频道内调用 `setClientRole` 方法修改用户角色,使其具备发流权限。 ## 前提条件 [#前提条件-7] - [Node.js](https://nodejs.org/en/download/) 6.9.1 或更高版本。 - 可以访问互联网的 Windows 或 macOS 电脑。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 一个有效的声网账号以及声网项目。请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)从声网控制台获得以下信息: - App ID:声网随机生成的字符串,用于识别你的项目。 - 临时 Token:Token 也称为动态密钥,在客户端加入频道时对用户鉴权。临时 Token 的有效期为 24 小时。 ## 创建项目 [#创建项目-6] 在本地文件夹中为 Electron 项目新建一个目录,并在项目根目录下创建以下文件: - `package.json`: 用于安装和管理项目依赖项。 - `index.html`:用于设计 App 的用户界面。 - `main.js`:主进程文件。 - `renderer.js`:渲染进程文件,用于实现与声网 Electron SDK 的交互。 ## 集成 SDK [#集成-sdk-6] 根据实际情况,在以下集成方式中任选一种,在你的项目中集成 SDK。 npm 集成 手动集成 1. 在 `package.json` 文件中添加以下代码: - macOS: ```json { "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: ```json { "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" } } ``` 字段的具体含义如下: - `agora-electron-sdk`:声网 Electron SDK 的版本号。设为 `latest` 表示获取最新版本的 SDK,其它版本可在 [agora-electron-sdk](https://www.npmjs.com/package/agora-electron-sdk) 中查看。 - `electron`:Electron 的版本号,支持 5.0.0 及以上版本(包括最新版本)。如果使用搭载 M1 芯片的 macOS 设备,Electron 的版本号需要设为 11.0.0 或以上。 - (可选)`platform`:默认根据系统选择,macOS 为 `darwin`,Windows 为 `win32`。 - (可选)`prebuilt`:默认设为 `true`,防止出现 Electron 或 Node.js 版本与 SDK 不兼容的问题。 - (可选)`arch`:默认根据系统选择。 :::warning[注意] 由于不同版本的 Electron 对本地环境的要求有差异,运行项目时可能因环境不匹配报错。声网推荐你参考 [Electron 官方文档](https://releases.electronjs.org/releases/stable)选择合适的 Electron 和 Node.js 版本。 ::: 2. 在终端中进入项目根目录,运行如下命令安装依赖项: ```shell # macOS npm install # Windows npm install -D --arch=ia32 electron npm install ``` :::info[信息] - Windows 平台需要先运行 `npm install -D --arch=ia32 electron` 安装 32 位的 Electron,然后运行 `npm install`。否则会收到报错:`Not a valid win32 application`。 - 如果项目根目录下已有 `node_modules` 文件夹,建议先删除该文件夹,再运行 `npm install`,以免出现报错。 ::: 除了使用 npm 集成以外,你也可以进入 [Electron-SDK](https://github.com/AgoraIO-Extensions/Electron-SDK/tree/main/) 手动编译最新的 SDK,集成到应用中。 ## 创建用户界面 [#创建用户界面-5] 在 `index.html` 文件中添加以下代码,创建一个只包含本地视频窗口和远端视频窗口的用户界面: ```html Electron Quickstart

Electron Quickstart

``` ## 实现步骤 [#实现步骤-7] 本节介绍如何实现一个实时音视频互动 App。 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。 下面列出了实现实时音视频互动基本流程的完整代码以供参考,你可以先将 `main.js` 和 `renderer.js` 文件的全部内容分别替换为以下代码,参考[测试项目](#测试项目)中的步骤快速体验实时音视频互动的基础功能,再按照实现流程了解其中的核心 API 调用。 ```javascript const { app, BrowserWindow } = require("electron"); const path = require("path"); // 如果使用 Electron 9.x 及以上版本,需要将 allowRendererProcessReuse 设为 false app.allowRendererProcessReuse = false; function createWindow() { // 创建浏览器窗口 const mainWindow = new BrowserWindow({ width: 800, height: 600, webPreferences: { // preload: path.join(__dirname, "renderer.js"), // 将 nodeIntegration 设置 true 以及 contextIsolation 设为 false nodeIntegration: true, contextIsolation: false, }, }); // 加载 index.html 文件的内容 mainWindow.loadFile("./index.html"); // 开启开发者工具 mainWindow.webContents.openDevTools(); } // 管理 Electron 应用的浏览器窗口 app.whenReady().then(() => { createWindow(); // 如果当前没有窗口打开,则新建一个窗口(适用于 macOS) app.on("activate", function () { if (BrowserWindow.getAllWindows().length === 0) { createWindow(); } }); }); // 如果所有窗口都已关闭,则退出 Electron 应用(适用于 Windows) app.on("window-all-closed", function () { if (process.platform !== "darwin") app.quit(); }); ``` ```javascript const { createAgoraRtcEngine, ChannelProfileType, ClientRoleType, VideoSourceType, VideoViewSetupMode, } = require("agora-electron-sdk"); let rtcEngine; let localVideoContainer; let remoteVideoContainer; // 填入你的 App ID const APPID = "<-- Insert App Id -->"; // 填入你的临时 Token let token = "<-- Insert Token -->"; // 填入生成 Token 时使用的频道名 const channel = "<-- Insert Channel Name -->"; // 用户 ID,并确保其在频道内的唯一性 let uid = 123; const EventHandles = { // 监听本地用户加入频道事件 onJoinChannelSuccess: ({ channelId, localUid }, elapsed) => { console.log('成功加入频道:' + channelId); // 本地用户加入频道后,设置本地视频窗口 rtcEngine.setupLocalVideo({ sourceType: VideoSourceType.VideoSourceCameraPrimary, uid: uid, view: localVideoContainer, setupMode: VideoViewSetupMode.VideoViewSetupAdd, }); }, // 监听远端用户加入频道事件 onUserJoined: ({ channelId, localUid }, remoteUid, elapsed) => { console.log('远端用户 ' + remoteUid + ' 已加入'); // 远端用户加入频道后,设置远端视频窗口 rtcEngine.setupRemoteVideo( { sourceType: VideoSourceType.VideoSourceRemote, uid: remoteUid, view: remoteVideoContainer, setupMode: VideoViewSetupMode.VideoViewSetupAdd, }, { channelId }, ); }, // 监听用户离开频道事件 onUserOffline: ( { channelId, localUid }, remoteUid, reason ) => { console.log('远端用户 ' + remoteUid + ' 已离开频道'); // 远端用户离开频道后,关闭远端视频窗口 rtcEngine.setupRemoteVideo( { sourceType: VideoSourceType.VideoSourceRemote, uid: remoteUid, view: remoteVideoContainer, setupMode: VideoViewSetupMode.VideoViewSetupRemove, }, ); }, }; window.onload = () => { const os = require("os"); const path = require("path"); localVideoContainer = document.getElementById("join-channel-local-video"); remoteVideoContainer = document.getElementById("join-channel-remote-video"); const sdkLogPath = path.resolve(os.homedir(), "./test.log"); // 创建 RtcEngine 实例 rtcEngine = createAgoraRtcEngine(); // 初始化 RtcEngine 实例 rtcEngine.initialize({ appId: APPID, logConfig: { filePath: sdkLogPath } }); // 注册事件回调 rtcEngine.registerEventHandler(EventHandles); // 启用视频模块 rtcEngine.enableVideo(); // 开启本地视频预览 rtcEngine.startPreview(); // 使用临时 Token 加入频道 rtcEngine.joinChannel(token, channel, uid, { // 设置频道场景为直播场景 channelProfile: ChannelProfileType.ChannelProfileLiveBroadcasting, // 设置用户角色为主播;如果要将用户角色设置为观众,保持默认值即可 clientRoleType: ClientRoleType.ClientRoleBroadcaster, // 发布麦克风采集的音频 publishMicrophoneTrack: true, // 发布摄像头采集的视频 publishCameraTrack: true, // 自动订阅所有音频流 autoSubscribeAudio: true, // 自动订阅所有视频流 autoSubscribeVideo: true, }); }; ``` :::info[信息] - 将 `renderer.js` 文件中的 `<-- Insert App Id -->`、`<-- Insert Token -->` 和 `<-- Insert Channel Name -->` 分别替换为你在控制台获取到的 App ID、临时 Token,以及生成临时 Token 时填入的频道名。 - 如果你的目标平台为 macOS v10.14 及以上,还需参考[获取设备权限](#获取设备权限-macos)在 `main.js` 中补充设备权限相关代码。 ::: ### 设计主进程 [#设计主进程] 使用 Electron 框架创建一个应用程序,实现基本的 Electron 项目主进程。主进程中的行为包括: 1. 导入所需模块 2. 创建浏览器窗口 3. 加载 `index.html` 文件 4. 处理应用程序生命周期事件 将以下代码复制到 `main.js` 文件中: ```javascript const { app, BrowserWindow } = require("electron"); const path = require("path"); // 如果使用 Electron 9.x 及以上版本,需要将 allowRendererProcessReuse 设为 false app.allowRendererProcessReuse = false; function createWindow() { // 创建浏览器窗口 const mainWindow = new BrowserWindow({ width: 800, height: 600, webPreferences: { // preload: path.join(__dirname, "renderer.js"), // 将 nodeIntegration 设置 true 以及 contextIsolation 设为 false nodeIntegration: true, contextIsolation: false, }, }); // 加载 index.html 文件的内容 mainWindow.loadFile("./index.html"); // 开启开发者工具 mainWindow.webContents.openDevTools(); } // 管理 Electron 应用的浏览器窗口 app.whenReady().then(() => { createWindow(); // 如果当前没有窗口打开,则新建一个窗口(适用于 macOS) app.on("activate", function () { if (BrowserWindow.getAllWindows().length === 0) { createWindow(); } }); }); // 如果所有窗口都已关闭,则退出 Electron 应用(适用于 Windows) app.on("window-all-closed", function () { if (process.platform !== "darwin") app.quit(); }); ``` ### 获取设备权限 (macOS) [#获取设备权限-macos] (可选)该步骤仅在目标平台为 macOS 时需要执行。macOS 自 v10.14 起,使用摄像头和麦克风前需要检查并获取设备的使用权限,你需要在主进程中调用 Electron 原生的 [`askForMediaAccess`](https://www.electronjs.org/docs/latest/api/system-preferences#systempreferencesaskformediaaccessmediatype-macos) 方法,来向用户请求摄像头和麦克风权限。 在 `main.js` 文件中添加如下代码: ```javascript // 检查并获取设备权限 async function checkAndApplyDeviceAccessPrivilege() { // 检查并获取摄像头权限 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'); } // 检查并获取麦克风权限 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(); ``` ### 导入依赖项 [#导入依赖项] 在 `renderer.js` 中导入声网 SDK 中构建 App 所需的模块和函数。 ```javascript const { createAgoraRtcEngine, ChannelProfileType, ClientRoleType, VideoSourceType, VideoViewSetupMode, } = require("agora-electron-sdk"); ``` ### 定义基本信息 [#定义基本信息] 传入从声网控制台获取的 App ID、临时 Token,以及生成临时 Token 时填入的频道名,用于后续初始化引擎和加入频道。 ```javascript // 填入你的 App ID const APPID = "<-- Insert App Id -->"; // 填入你的临时 Token let token = "<-- Insert Token -->"; // 填入生成 Token 时使用的频道名 const channel = "<-- Insert Channel Name -->"; // 用户 ID,并确保其在频道内的唯一性 let uid = 123; ``` ### 初始化引擎 [#初始化引擎-6] 在 `renderer.js` 中调用 `createAgoraRtcEngine` 方法创建一个 `RtcEngine` 实例,然后调用 `initialize` 初始化引擎。 :::warning[注意] 在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。 ::: ```javascript let rtcEngine; const os = require("os"); const path = require("path"); const sdkLogPath = path.resolve(os.homedir(), "./test.log"); // 创建 RtcEngine 实例 rtcEngine = createAgoraRtcEngine(); // 初始化 RtcEngine 实例 rtcEngine.initialize({ appId: APPID, logConfig: { filePath: sdkLogPath } }); ``` ### 启用视频模块 [#启用视频模块-6] 按照以下步骤启用视频模块: 1. 调用 `enableVideo` 方法,启用视频模块。 2. 调用 `startPreview` 方法,开启本地视频预览。 ```javascript // 启用视频模块 rtcEngine.enableVideo(); // 开启本地视频预览 rtcEngine.startPreview(); ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流-6] 调用 `joinChannel` 方法,填入你在控制台获取的临时 Token,以及获取 Token 时填入的频道名加入频道,并在 `options` 参数中设置频道场景、用户角色等信息。 ```javascript // 使用临时 Token 加入频道 rtcEngine.joinChannel(token, channel, uid, { // 设置频道场景为直播场景 channelProfile: ChannelProfileType.ChannelProfileLiveBroadcasting, // 设置用户角色为主播;如果要将用户角色设置为观众,保持默认值即可 clientRoleType: ClientRoleType.ClientRoleBroadcaster, // 发布麦克风采集的音频 publishMicrophoneTrack: true, // 发布摄像头采集的视频 publishCameraTrack: true, // 自动订阅所有音频流 autoSubscribeAudio: true, // 自动订阅所有视频流 autoSubscribeVideo: true, }); ``` ### 实现常用回调 [#实现常用回调-6] 调用 `registerEventHandler` 方法注册以下回调事件,触发事件时使用 `console.log` 方法提示结果,并执行特定操作: - `onJoinChannelSuccess`:成功加入频道回调。本地用户加入频道后,调用 `setupLocalVideo` 设置本地视频窗口。 - `onUserJoined`:远端用户加入当前频道回调。远端用户加入频道后,调用 `setupRemoteVideo` 设置远端视频窗口。 - `onUserOffline`:远端用户离开当前频道回调。远端用户离开频道后,调用 `setupRemoteVideo` 关闭远端视频窗口。 ```javascript const EventHandles = { // 监听本地用户加入频道事件 onJoinChannelSuccess: ({ channelId, localUid }, elapsed) => { console.log('成功加入频道:' + channelId); // 本地用户加入频道后,设置本地视频窗口 rtcEngine.setupLocalVideo({ sourceType: VideoSourceType.VideoSourceCameraPrimary, uid: uid, view: localVideoContainer, setupMode: VideoViewSetupMode.VideoViewSetupAdd, }); }, // 监听远端用户加入频道事件 onUserJoined: ({ channelId, localUid }, remoteUid, elapsed) => { console.log('远端用户 ' + remoteUid + ' 已加入'); // 远端用户加入频道后,设置远端视频窗口 rtcEngine.setupRemoteVideo( { sourceType: VideoSourceType.VideoSourceRemote, uid: remoteUid, view: remoteVideoContainer, setupMode: VideoViewSetupMode.VideoViewSetupAdd, }, { channelId }, ); }, // 监听用户离开频道事件 onUserOffline: ( { channelId, localUid }, remoteUid, reason ) => { console.log('远端用户 ' + remoteUid + ' 已离开频道'); // 远端用户离开频道后,关闭远端视频窗口 rtcEngine.setupRemoteVideo( { sourceType: VideoSourceType.VideoSourceRemote, uid: remoteUid, view: remoteVideoContainer, setupMode: VideoViewSetupMode.VideoViewSetupRemove, }, ); }, }; // 注册事件回调 rtcEngine.registerEventHandler(EventHandles); ``` ### 离开频道 [#离开频道-1] 根据场景需要,如关闭应用或应用切换至后台时,调用 `leaveChannel` 离开当前频道。 ```javascript // 停止预览 rtcEngine.stopPreview(); // 离开频道 rtcEngine.leaveChannel(); ``` 如果你不再需要互动,调用 `release` 方法释放引擎资源。 ```javascript // 取消注册回调 rtcEngine.unregisterEventHandler(EventHandles); // 销毁引擎 rtcEngine.release(); ``` :::error[警告] - 调用 `release` 后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎-6)。 - 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。 ::: ## 测试项目 [#测试项目] 参考以下步骤测试你的 Electron 项目: 1. 确保已经在代码中传入了有效的 `appId`,`channelName` 和 `token`。详见[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。 2. 在终端中进入项目根目录,运行以下命令: ```shell npm start ``` 项目成功运行后,你会看到一个自动弹出的窗口,在窗口中看到本地的视频画面。 3. 邀请一位朋友使用第二台设备,重复以上步骤,在该设备上安装 App,并打开 App 加入频道。 4. 你的朋友成功加入后,你们可以听见、看见对方。 ## 后续步骤 [#后续步骤-5] - 本文的示例使用了临时 Token 加入频道。在测试或生产环境中,为确保通信安全,声网推荐使用 Token 服务器来生成 Token,详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - 如果你想要实现极速直播场景,可以在互动直播的基础上,通过修改观众端的延时级别为低延时 (`audienceLatencyLevelLowLatency`)实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。 ## 参考信息 [#参考信息-7] ### 示例项目 [#示例项目-7] 声网提供了开源的实时音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。 JoinChannelVideo} href="https://gitee.com/agoraio-community/Electron-SDK/blob/main/example/src/renderer/examples/basic/JoinChannelVideo/JoinChannelVideo.tsx" /> JoinChannelVideo} href="https://github.com/AgoraIO-Extensions/Electron-SDK/blob/main/example/src/renderer/examples/basic/JoinChannelVideo/JoinChannelVideo.tsx" /> ### 常见问题 [#常见问题-6] - [Electron 平台常见开发问题](/zh-CN/reference/faq/integration/electron_faq) - [直播场景下,如何监听远端观众角色用户加入/离开频道的事件?](/zh-CN/reference/faq/integration/audience_event) - [如何处理视频黑屏问题?](/zh-CN/reference/faq/quality/video_blank) - [为什么我无法打开摄像头?](/zh-CN/reference/faq/quality/video_camera) - [如何处理频道相关常见问题?](/zh-CN/reference/faq/integration/channel) - [如何设置日志文件?](/zh-CN/reference/faq/integration/set_log_file) - [编译 Xcode 项目时遇到无法打开 framework 的弹窗警告怎么办?](/zh-CN/reference/faq/integration/framework_cannot_be_opened) - [运行 Electron App 时,控制台提示 “WARNING:Too many active WebGL contexts” 怎么办?](/zh-CN/reference/faq/integration/webgl_context) - [为什么 SDK 中使用的是动态库而不是静态库?](/zh-CN/reference/faq/integration/dynamic_or_static_library) ### 相关文档 [#相关文档-6] - [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code) - [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="unity" /> 本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的实时互动 App,适用于互动直播和视频通话场景。 首先,你需要了解以下有关音视频实时互动的基础概念: - 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。 - 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。 - 主播:可以在频道内**发布**音视频,同时也可以**订阅**其他主播发布的音视频。 - 观众:可以在频道内**订阅**音视频,不具备**发布**音视频权限。 更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。 下图展示在 App 中实现音视频互动的基本工作流程: 1. 所有用户调用 `joinChannel` 方法加入频道,并根据需要设置用户角色: - 互动直播:如果用户需要在频道中发流,则设为主播;如果用户只需要收流,则设为观众。 - 视频通话:将所有用户的角色都设为主播。 2. 加入频道后,不同角色的用户具备不同的行为: - 所有用户默认都可以接收频道中的音视频流。 - 主播可以在频道内发布音视频流。 - 观众如果需要发流,可在频道内调用 `setClientRole` 方法修改用户角色,使其具备发流权限。 ## 前提条件 [#前提条件-8] 在实现功能以前,请按照以下要求准备开发环境: - 已下载 [Unity Hub](https://unity.com/download)。 - Unity 2018.4.0 或以上版本。 - 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 不同开发平台的操作系统与编译器需满足下列版本要求: | 开发平台 | 操作系统版本 | 编译器版本 | | --- | --- | --- | | Android | Android 4.1 或以上 | Android Studio 3.0 或以上 | | iOS | iOS 9.0 或以上 | Xcode 9.0 或以上 | | macOS | macOS 10.10 或以上 | Xcode 9.0 或以上 | | Windows | Windows 7 或以上 | Microsoft Visual Studio 2017 或以上 | - 一个有效的声网账号以及声网项目。请参考 [开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service),从声网控制台获得 App ID 和临时 Token。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。 ::: ## 创建项目 [#创建项目-7] 参考以下步骤或 [Unity 官方文档](https://docs.unity.com/en-us/hub/project-create)创建一个 **Unity** 项目。若已有 **Unity** 项目,可略过此步骤至下一步[集成 SDK](#integrate)。 1. 开始前确保你已安装 Unity。若未安装,点击[此处](https://unity.com/cn/products#plans-individual)下载。 2. 打开 Unity Editor,点击 **New** 新建一个项目。 3. 依次填入以下内容后,点击 **Create project** 创建一个 Unity 项目。 - **Project name**:项目名称。 - **Location**:项目存储路径。 - **Template**:项目类型。选择 **3D**。 ## 集成 SDK [#集成-sdk-7] 参考下列步骤来集成声网实时互动 SDK: 1. 前往[下载](/zh-CN/realtime-media/rtc/reference/downloads)页面,下载最新版的 Unity SDK。 2. 下载完成后在你的 Unity 编辑器中打开下载好的 SDK 包并取消勾选不需要的插件(默认会勾选 SDK 包含的所有插件),然后点击 **Import** 来导入 SDK。 ## 创建用户界面 [#创建用户界面-6] 根据应用场景为你的项目创建一个用户界面(UI)。 例如,你可以在 UI 上添加以下控件: - 本地视图窗口 - 远端视图窗口 - 加入/离开频道按钮 创建好的用户界面如下图所示: ![Unity 用户界面示意图](https://web-cdn.agora.io/docs-files/1657121618456) 你可以参考以下步骤创建 UI。若你的项目中已有用户界面可略过此步骤。 1. 创建加入/离开频道按钮。 1. 在你的 Unity 项目中,右击 **Sample Scene**,选择 **Game Object** > **UI** > **Button**。此时你可以在场景画布中看到你刚刚创建的按钮。 2. 在右侧的 **Inspector** 面板中,将 **Button** 重命名为 **Leave**。选中 **Button** 按钮的 **Text** 控件,将 **Text** 的文本内容修改为 **Leave**,并调整按钮的位置,例如: - **Pos X**:`- 350` - **Pos Y**:`- 172` 3. 重复上述步骤来创建一个 **Join** 按钮。 2. 创建本地及远端视图窗口。 1. 右击 **Canvas**,选择 **UI** > **Raw Image**。 2. 创建本地视图窗口。在右侧的 **Inspector** 面板中,将 **Raw Image** 重命名为 **LocalView**,并调整在画布中位置,例如: - **Pos X**:`-250` - **Pos Y**:`0` - **Width**:`250` - **Height**:`250` 3. 重复上述步骤创建远端视图窗口,将其命名为 **RemoteView**,并调整在画布中的位置,例如: - **Pos X**:`250` - **Pos Y**:`0` - **Width**:`250` - **Height**:`250` 3. 保存上述步骤的更改。 ## 实现步骤 [#实现步骤-8] 本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中,快速体验实时音视频互动的基础功能,再按照实现步骤了解核心 API 调用。 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程: :::info[信息] 在 `_appId`、`_token` 和 `_channelName` 字段中传入你在控制台获取到的 App ID、临时 Token,以及生成临时 Token 时填入的频道名。 ::: ```csharp using System.Collections; using System.Collections.Generic; using UnityEngine; using UnityEngine.UI; using Agora.Rtc; #if (UNITY_2018_3_OR_NEWER && UNITY_ANDROID) using UnityEngine.Android; #endif public class JoinChannelVideo : MonoBehaviour { // 填入你的 app ID private string _appID= ""; // 填入你的频道名 private string _channelName = ""; // 填入 Token private string _token = ""; internal VideoSurface LocalView; internal VideoSurface RemoteView; internal IRtcEngine RtcEngine; #if (UNITY_2018_3_OR_NEWER && UNITY_ANDROID) private ArrayList permissionList = new ArrayList() { Permission.Camera, Permission.Microphone }; #endif void Start() { SetupVideoSDKEngine(); InitEventHandler(); SetupUI(); PreviewSelf(); } void Update() { CheckPermissions(); } void OnApplicationQuit() { if (RtcEngine != null) { Leave(); // 销毁 IRtcEngine RtcEngine.Dispose(); RtcEngine = null; } } private void CheckPermissions() { #if (UNITY_2018_3_OR_NEWER && UNITY_ANDROID) foreach (string permission in permissionList) { if (!Permission.HasUserAuthorizedPermission(permission)) { Permission.RequestUserPermission(permission); } } #endif } private void PreviewSelf() { // 启用视频模块 RtcEngine.EnableVideo(); // 开启本地视频预览 RtcEngine.StartPreview(); // 设置本地视频显示 LocalView.SetForUser(0, ""); // 渲染视频 LocalView.SetEnable(true); } private void SetupUI() { GameObject go = GameObject.Find("LocalView"); LocalView = go.AddComponent(); go.transform.Rotate(0.0f, 0.0f, -180.0f); go = GameObject.Find("RemoteView"); RemoteView = go.AddComponent(); go.transform.Rotate(0.0f, 0.0f, -180.0f); go = GameObject.Find("Leave"); go.GetComponent ); }; export default Basics; ``` 接下来可以给 `` 组件添加 CSS 样式。示例项目中使用 [styles.css](https://codesandbox.io/s/github/guoxianzhe/quickstart-examples/tree/react/rtc/react-quickstart?file=/src/styles.css),加入频道界面的效果如下: ![](https://web-cdn.agora.io/docs-portal/img/video-call/react/quickstart-join.png) 现在 App 已经实现了用户加入频道的功能和界面,但用户无法听到和看到对方,还不能进行通话。 ### 渲染本地和远端的音视频 [#渲染本地和远端的音视频] 为了让用户能互相看到和听到对方,App 需要渲染本地用户和远端用户的音视频。 渲染本地用户音视频的步骤如下: 1. 使用 `useLocalMicrophoneTrack` 和 `useLocalCameraTrack` 创建麦克风音频轨道和摄像头视频轨道。 2. 使用 `usePublish` 发布本地用户的音频和视频轨道。 3. 使用 `` 组件渲染本地用户的音频和视频。 渲染远端用户音视频的步骤如下: 1. 使用 `useRemoteUsers` 获取所有远端用户。 2. 使用 `` 组件渲染每一位远端用户的音频和视频。 此外,你还可以在界面上提供以下按钮: - 打开/关闭麦克风。 - 打开/关闭摄像头。 - 结束通话。 ```jsx showLineNumbers title="/src/App.js" export const Basics = () => { const [calling, setCalling] = useState(false); const [appId, setAppId] = useState(""); const [channel, setChannel] = useState(""); const [token, setToken] = useState(""); useJoin({appid: appId, channel: channel, token: token ? token : null}, calling); // highlight-start // 本地用户 const [micOn, setMic] = useState(true); const [cameraOn, setCamera] = useState(true); const { localMicrophoneTrack } = useLocalMicrophoneTrack(micOn); const { localCameraTrack } = useLocalCameraTrack(cameraOn); usePublish([localMicrophoneTrack, localCameraTrack]); // 远端用户 const remoteUsers = useRemoteUsers(); // highlight-end return ( <> // highlight-start
You
{remoteUsers.map((user) => (
{user.uid}
))}
// highlight-end ); }; export default Basics; ``` 最终的通话界面如下: ![](https://web-cdn.agora.io/docs-portal/img/video-call/react/quickstart-in-call.png) ### 根据连接状态更新 UI [#根据连接状态更新-ui] 现在 App 已经具备加入频道界面和通话界面,但两个界面之间无法切换。 我们需要使用 `useIsConnected` 获取用户的连接状态,并且根据连接状态更新 App 界面: - 在加入频道界面点击加入频道后,如果用户连接成功,App 显示通话界面。 - 在通话界面点击退出通话后,如果连接成功断开,App 显示加入频道界面。 ```jsx showLineNumbers title="/src/App.js" export const Basics = () => { const [calling, setCalling] = useState(false); // highlight-next-line const isConnected = useIsConnected(); // 存储用户的连接状态 const [appId, setAppId] = useState(""); const [channel, setChannel] = useState(""); const [token, setToken] = useState(""); useJoin({appid: appId, channel: channel, token: token ? token : null}, calling); const [micOn, setMic] = useState(true); const [cameraOn, setCamera] = useState(true); const { localMicrophoneTrack } = useLocalMicrophoneTrack(micOn); const { localCameraTrack } = useLocalCameraTrack(cameraOn); usePublish([localMicrophoneTrack, localCameraTrack]); const remoteUsers = useRemoteUsers(); return ( <>
// highlight-next-line {isConnected ? (
You
{remoteUsers.map((user) => (
{user.uid}
))}
// highlight-next-line ) : (
agora-logo setAppId(e.target.value)} placeholder="" value={appId} /> setChannel(e.target.value)} placeholder="" value={channel} /> setToken(e.target.value)} placeholder="" value={token} />
// highlight-next-line )}
// highlight-next-line {isConnected && (
// highlight-next-line )} ); }; export default Basics; ``` ### 离开频道 [#离开频道-3] 当用户点击离开频道按钮、关闭浏览器窗口或刷新浏览器标签页时,由于触发了 React 组件的销毁,`useJoin` 会执行离开频道的操作。你不需要额外调用 API。 ## 后续步骤 [#后续步骤-11] 在测试或生产环境中,为保证通信安全,声网推荐从服务器中获取 Token,详情请参考[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 ## 参考信息 [#参考信息-13] ### 示例项目 [#示例项目-13] 声网在 GitHub 上提供一个开源的示例项目供你参考,包括 React SDK 提供的每个组件和 Hook 以及部分进阶功能的效果展示。 ### 集成 SDK 的其他方法 [#集成-sdk-的其他方法] 除了通过 npm 集成 React SDK,你也可以在 HTML 文件中添加如下代码,使用 CDN 方法获取 SDK: ```html ``` <_PlatformProcessedMarker close="true" />