实现音视频互动

本文介绍如何集成声网实时互动 SDK，通过少量代码从 0 开始实现一个简单的实时互动 App，适用于互动直播和视频通话场景。首先，你需要了解以下有关音视频实时互动的基础概念：

• 声网实时互动 SDK：由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。
• 频道：用于传输数据的通道，在同一个频道内的用户可以进行实时互动。
• 主播：可以在频道内发布音视频，同时也可以订阅其他主播发布的音视频。
• 观众：可以在频道内订阅音视频，不具备发布音视频权限。

更多概念详见关键概念。

下图展示在 App 中实现音视频互动的基本工作流程：

1. 所有用户调用 joinChannel 方法加入频道，并根据需要设置用户角色：

   • 互动直播：如果用户需要在频道中发流，则设为主播；如果用户只需要收流，则设为观众。
   • 视频通话：将所有用户的角色都设为主播。

2. 加入频道后，不同角色的用户具备不同的行为：

   • 所有用户默认都可以接收频道中的音视频流。
   • 主播可以在频道内发布音视频流。
   • 观众如果需要发流，可在频道内调用 setClientRole 方法修改用户角色，使其具备发流权限。

前提条件Copy Anchor Link

在实现功能以前，请按照以下要求准备开发环境：

• Android Studio 4.1 以上版本。
• Android API 级别 16 或以上。
• 两台运行 Android 4.1 或以上版本的移动设备。
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。
• 一个有效的声网账号以及声网项目。请参考开通 RTC 服务从声网控制台获得 App ID 和临时 Token。

创建项目Copy Anchor Link

本小节介绍如何创建项目并为项目添加体验实时互动所需的权限。

1. (可选) 创建新项目。详见 Create a project。

   1. 打开 Android Studio，选择 New Project。

   2. 选择 Phone and Tablet > Empty Views Activity，点击 Next。

   3. 设置项目名称和存储路径，选择语言为 Java，点击 Finish 创建 Android 项目。

      注意

      创建项目后，Android Studio 会自动开始同步 Gradle，稍等片刻至同步成功后再进行下一步操作。

2. 添加网络及设备权限。

   打开 /app/src/main/AndroidManifest.xml 文件，在 </application> 后面添加如下权限：

   Copy Text

   <!--必要权限-->
   <uses-permission android:name="android.permission.INTERNET"/>
   
   <!--可选权限-->
   <uses-permission android:name="android.permission.CAMERA"/>
   <uses-permission android:name="android.permission.RECORD_AUDIO"/>
   <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   <uses-permission android:name="android.permission.BLUETOOTH"/>
   <!-- 对于 Android 12.0 及以上且集成 v4.1.0 以下 SDK 的设备，还需要添加以下权限 -->
   <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
   <!-- 对于 Android 12.0 及以上设备，还需要添加以下权限 -->
   <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
   <uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>

3. 防止代码混淆。

   如果你的 App 未开启 R8/ProGuard 缩减和混淆，无需额外配置混淆规则。如果你的 App 开启了 R8/ProGuard 缩减和混淆，请根据集成方式选择以下任一配置：

   • 快速配置：打开 /app/proguard-rules.pro 文件，添加如下规则，保留所有声网 SDK 相关类：

     Copy Text

     -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 中添加该文件，例如：

     Copy Text

     android {
         buildTypes {
             release {
                 minifyEnabled true
                 proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'),
                         'proguard-rules.pro',
                         'consumer-proguard-rules.pro'
             }
         }
     }

集成 SDKCopy Anchor Link

你可以选用以下任一方式集成声网实时互动 SDK。

创建用户界面Copy Anchor Link

根据实时音视频互动的场景需要，为你的项目创建两个视图框，分别用于展示本地视频和远端视频。如下图所示：

复制以下代码到 /app/src/main/res/layout/activity_main.xml 文件中替换原有内容，即可快速创建场景所需的用户界面。

实现步骤Copy Anchor Link

本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中，快速体验实时音视频互动的基础功能，再按照实现步骤了解核心 API 调用。

下图展示了使用声网 RTC SDK 实现音视频互动的基本流程：

下面列出了一段实现实时互动基本流程的完整代码以供参考。复制以下代码到 /app/src/main/java/com/example/<projectname>/MainActivity.java 文件中替换 package com.example.<projectname> 后的全部内容，即可快速体验实时互动基础功能。

处理权限请求Copy Anchor Link

本小节介绍如何导入 Android 相关的类并获取 Android 设备的摄像头、录音等权限。

1. 导入 Android 相关的类

   Copy Text

   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 中授予了实现实时互动所需的权限。

   Copy Text

   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;
   }

导入声网相关的类Copy Anchor Link

导入声网 RTC SDK 相关的类和接口：

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 和 TokenCopy Anchor Link

传入从声网控制台获取的 App ID、临时 Token，以及生成临时 Token 时填入的频道名，用于后续初始化引擎和加入频道。

// 填写声网控制台中获取的 App ID
private String appId = "<#Your App ID#>";
// 填写频道名
private String channelName = "<#Your channel name#>";
// 填写声网控制台中生成的临时 Token
private String token = "<#Your Token#>";

初始化引擎Copy Anchor Link

调用 create [2/2] 方法初始化 RtcEngine。

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);

启用视频模块Copy Anchor Link

按照以下步骤启用视频模块：

1. 调用 enableVideo 方法，启用视频模块。
2. 调用 setupLocalVideo 方法初始化本地视图，同时设置本地的视频显示属性。
3. 调用 startPreview 方法，开启本地视频预览。

// 启用视频模块
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();

加入频道并发布音视频流Copy Anchor Link

调用 joinChannel [2/2] 加入频道。在 ChannelMediaOptions 中进行如下配置：

• 设置频道场景为 BROADCASTING (直播场景) 并设置用户角色设置为 BROADCASTER (主播) 或 AUDIENCE (观众)。
• 将 publishMicrophoneTrack 和 publishCameraTrack 设置为 true，发布麦克风采集的音频和摄像头采集的视频。
• 将 autoSubscribeAudio 和 autoSubscribeVideo 设置为 true，自动订阅所有音视频流。

// 创建 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);

设置远端视图Copy Anchor Link

调用 setupRemoteVideo 方法初始化远端用户视图，同时设置远端用户的视图在本地显示属性。你可以通过 onUserJoined 回调获取远端用户的 uid。

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

实现常用回调Copy Anchor Link

根据使用场景，定义必要的回调。以下示例代码展示如何实现 onJoinChannelSuccess、 onUserJoined 和 onUserOffline 回调。

// 成功加入频道回调
@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();
    });
}

开始音视频互动Copy Anchor Link

在 onCreate 中调用一系列方法加载界面布局、检查 App 是否获取实时互动所需权限，并加入频道开始音视频互动。

@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);
    }
}

结束音视频互动Copy Anchor Link

按照以下步骤结束音视频互动：

1. 调用 stopPreview 停止视频预览。

2. 调用 leaveChannel 离开当前频道，释放所有会话相关的资源。

3. 调用 destroy 销毁引擎，并释放声网 SDK 中使用的所有资源。

   注意

   • 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作，因此建议在子线程中调用该方法，避免主线程阻塞。
     • 调用 destroy 后，你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能，你必须重新创建一个新的引擎。详见初始化引擎。

   Copy Text

   @Override
   protected void onDestroy() {
       super.onDestroy();
       if (mRtcEngine != null) {
           // 停止本地视频预览
           mRtcEngine.stopPreview();
           // 离开频道
           mRtcEngine.leaveChannel();
           mRtcEngine = null;
           // 销毁引擎
           RtcEngine.destroy();
       }
   }

调试 AppCopy Anchor Link

按照以下步骤测试直播 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 加入频道，观察测试结果：

   • 如果两台设备均作为主播加入频道，则可以看到对方并且听到对方的声音。
   • 如果两台设备分别作为主播和观众加入，则主播可以在本地视频窗口看到自己；观众可以在远端视频窗口看到主播、并听到主播的声音。

后续步骤Copy Anchor Link

在完成音视频互动后，你可以阅读以下文档进一步了解：

• 本文的示例使用了临时 Token 加入频道。在测试或生产环境中，为保证通信安全，声网推荐从服务器中获取 Token，详情请参考使用 Token 鉴权。
• 如果你想要实现极速直播场景，可以在实时音视频互动的基础上，通过修改观众端的延时级别为低延时 (AUDIENCE_LATENCY_LEVEL_LOW_LATENCY) 实现。详见实现极速直播。

参考信息Copy Anchor Link

示例项目Copy Anchor Link

声网提供了开源的实时音视频互动示例项目供你参考，你可以前往下载或查看其中的源代码。

常见问题Copy Anchor Link

• 直播场景下，如何监听远端观众角色用户加入/离开频道的事件？
• 如何处理视频黑屏问题？
• 为什么我无法打开摄像头？
• 如何处理频道相关常见问题？
• 如何设置日志文件？
• 为什么部分 Android 版本应用锁屏或切后台后采集音视频无效？
• 为什么 SDK 中使用的是动态库而不是静态库？

相关文档Copy Anchor Link

• SDK 错误码
• 频道连接状态管理

本文介绍如何集成声网实时互动 SDK，通过少量代码从 0 开始实现一个简单的实时互动 App，适用于互动直播和视频通话场景。 首先，你需要了解以下有关音视频实时互动的基础概念：

• 声网实时互动 SDK：由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。
• 频道：用于传输数据的通道，在同一个频道内的用户可以进行实时互动。
• 主播：可以在频道内发布音视频，同时也可以订阅其他主播发布的音视频。
• 观众：可以在频道内订阅音视频，不具备发布音视频权限。

更多概念详见关键概念。

下图展示在 App 中实现音视频互动的基本工作流程：

1. 所有用户调用 joinChannel 方法加入频道，并根据需要设置用户角色：

   • 互动直播：如果用户需要在频道中发流，则设为主播；如果用户只需要收流，则设为观众。
   • 视频通话：将所有用户的角色都设为主播。

2. 加入频道后，不同角色的用户具备不同的行为：

   • 所有用户默认都可以接收频道中的音视频流。
   • 主播可以在频道内发布音视频流。
   • 观众如果需要发流，可在频道内调用 setClientRole 方法修改用户角色，使其具备发流权限。

前提条件Copy Anchor Link

在实现功能以前，请按照以下要求准备开发环境：

• Xcode 12.0 或以上版本。
• Apple 开发者账号。
• 如需使用 Cocoapods 集成 SDK，则确保已安装 Cocoapods，否则请参考 Getting Started with CocoaPods 进行安装。
• 两台 iOS 9.0 或以上版本的设备。
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。
• 一个有效的声网账号以及声网项目。请参考开通 RTC 服务从声网控制台获得 App ID 和临时 Token。

创建项目Copy Anchor Link

按照以下步骤，在 Xcode 中创建一个项目：

1. 参考 Create a project 创建一个新的项目。Application 选择 App，Interface 选择 Storyboard，Language 选择 Swift。

   信息

   如果你没有添加过开发团队信息，会看到 Add account… 按钮。点击该按钮并按照屏幕提示登入 Apple ID，点击 Next，完成后即可选择你的 Apple 账户作为开发团队。

2. 为你的项目设置自动签名。

3. 设置部署你的 App 的目标设备。

4. 添加项目的设备权限。

   在项目导航栏中打开 info.plist 文件，编辑属性列表，添加实时互动所需的录音和摄像头权限。

   信息

   • 下表中列出的权限均为可选权限。但如果不添加所列权限，你将无法使用麦克风和摄像头进行实时音视频互动。
     • 如果你的项目中需要添加第三方插件或库（例如第三方摄像头），且该插件或库的签名与项目的签名不一致，你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation。
     • 更多注意事项，可以参考 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。

   表格内容超出当前宽度，可横向滚动查看更多列。

集成 SDKCopy Anchor Link

根据实际情况，在以下集成方式中任选一种，在你的项目中集成 SDK。

创建用户界面Copy Anchor Link

在 ViewController.swift 文件中，为你的项目创建一个用户界面，包括本地视频窗口和远端视频窗口，分别用于展示本地视频和远端视频。如下所示：

用以下代码替换 ViewController.swift 文件中的内容，即可实时预览你创建的用户界面。

实现步骤Copy Anchor Link

下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。

下面列出了一段实现实时互动基本流程的完整代码以供参考。复制以下代码到 ViewController.swift 文件中替换原有内容即可。

导入声网组件Copy Anchor Link

在 ViewController.swift 文件中引入 AgoraRtcKit。

import AgoraRtcKit

初始化引擎Copy Anchor Link

调用 sharedEngineWithConfig 方法，创建并初始化 AgoraRtcEngineKit。

// 在这里输入你在声网控制台中获取的 App ID
agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId:<#Your App ID#>, delegate: self)

启用视频模块Copy Anchor Link

按照以下步骤启用视频模块。

1. 调用 enableVideo 方法，启用视频模块。
2. 调用 setupLocalVideo 方法初始化本地视图，同时设置本地的视频显示属性。
3. 调用 startPreview 方法，开启本地视频预览。

// 启用视频模块
agoraKit.enableVideo()

let videoCanvas = AgoraRtcVideoCanvas()
videoCanvas.view = localView
videoCanvas.renderMode = .hidden
// 设置本地视图
agoraKit.setupLocalVideo(videoCanvas)
// 开始本地视频预览
agoraKit.startPreview()

加入频道并发布音视频流Copy Anchor Link

调用 joinChannelByToken[2/4] 方法、填入你在控制台获取的临时 Token，以及获取 Token 时填入的频道名加入频道，并设置用户角色。

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)

设置远端用户视图Copy Anchor Link

调用 setupRemoteVideo 方法初始化远端用户视图，同时设置远端用户的视图在本地显示属性。你可以通过 didJoinedOfUid 回调获取远端用户的 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)
}

实现常用回调Copy Anchor Link

根据使用场景，定义必要的回调。以下示例代码展示了如何实现 didJoinChannel 和 didOfflineOfUid 回调。

// 成功加入频道回调
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)
}

开始音视频互动Copy Anchor Link

当视图加载完成后，在 viewDidLoad 中调用一系列方法加入频道，开始音视频互动。

override func viewDidLoad() {
    super.viewDidLoad()
    // 当加载视图后，你可以进行其他其他设置
    // 当调用声网 API 时，以下函数会被调用
    agoraKit.enableVideo()
    startPreview()
    joinChannel()
}

结束音视频互动Copy Anchor Link

1. 调用 leaveChannel 方法离开频道，与会话相关的资源也会被释放。

   Copy Text

   agoraKit.stopPreview()
   agoraKit.leaveChannel(nil)

2. 调用 destroy 销毁引擎，并释放声网 SDK 中使用的所有资源。

   Copy Text

   AgoraRtcEngineKit.destroy()

   警告

   • 调用该方法后，你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能，你必须重新创建一个新的引擎。详见初始化引擎。
     • 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作，因此建议在子线程中调用该方法，避免主线程阻塞。

调试 AppCopy Anchor Link

参考以下步骤来测试你的 App：

1. 将 iOS 设备连接至计算机。

2. 点击 Build 来运行你的项目，需等待几秒至 App 安装完成。

3. 允许 App 访问设备的麦克风和摄像头权限。

4. （可选）如果设备上弹出不受信任的开发者提示，则首先点击取消关闭该提示，然后在 iOS 设备上打开设置 > 通用 > VPN 与设备管理，在开发者 APP 中选择信任该开发者。

5. 使用第二台 iOS 设备，重复以上步骤，在该设备上安装 App，并打开 App 加入频道，观察测试结果：

   • 如果两台设备均作为主播加入频道，则可以看到对方并且听到对方的声音。
   • 如果两台设备分别作为主播和观众加入，则主播可以在本地视频窗口看到自己；观众可以在远端视频窗口看到主播、并听到主播的声音。

后续步骤Copy Anchor Link

• 本文的示例使用了临时 Token 加入频道。在测试或生产环境中，为确保通信安全，声网推荐使用 Token 服务器来生成 Token，详见使用 Token 鉴权。
• 如果你想要实现极速直播场景，可以在互动直播的基础上，通过修改观众端的延时级别为低延时 (AgoraAudienceLatencyLevelLowLatency)实现。详见实现极速直播。

参考信息Copy Anchor Link

示例项目Copy Anchor Link

声网提供了开源的实时互动示例项目供你参考，你可以前往下载或查看其中的源代码。

常见问题Copy Anchor Link

• 直播场景下，如何监听远端观众角色用户加入/离开频道的事件？
• 如何处理视频黑屏问题？
• 如何处理 CocoaPods 常见问题？
• 为什么我无法打开摄像头？
• 如何处理频道相关常见问题？
• 如何设置日志文件？
• 如何处理无声问题？
• 为什么部分 iOS 版本 App 锁屏或切后台后音视频采集无效？
• 为什么 SDK 中使用的是动态库而不是静态库？
• 如何增加隐私清单？

相关文档Copy Anchor Link

• SDK 错误码
• 频道连接状态管理

本文介绍如何集成声网实时互动 SDK，通过少量代码从 0 开始实现一个简单的实时互动 App，适用于互动直播和视频通话场景。 首先，你需要了解以下有关音视频实时互动的基础概念：

• 声网实时互动 SDK：由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。
• 频道：用于传输数据的通道，在同一个频道内的用户可以进行实时互动。
• 主播：可以在频道内发布音视频，同时也可以订阅其他主播发布的音视频。
• 观众：可以在频道内订阅音视频，不具备发布音视频权限。

更多概念详见关键概念。

下图展示在 App 中实现音视频互动的基本工作流程：

1. 所有用户调用 joinChannel 方法加入频道，并根据需要设置用户角色：

   • 互动直播：如果用户需要在频道中发流，则设为主播；如果用户只需要收流，则设为观众。
   • 视频通话：将所有用户的角色都设为主播。

2. 加入频道后，不同角色的用户具备不同的行为：

   • 所有用户默认都可以接收频道中的音视频流。
   • 主播可以在频道内发布音视频流。
   • 观众如果需要发流，可在频道内调用 setClientRole 方法修改用户角色，使其具备发流权限。

前提条件Copy Anchor Link

在实现功能以前，请按照以下要求准备开发环境：

• Xcode 12.0 或以上版本。
• Apple 开发者账号。
• 如需使用 Cocoapods 集成 SDK，则确保已安装 Cocoapods，否则请参考 Getting Started with CocoaPods 进行安装。
• 两台 macOS 10.10 或以上版本的设备。
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。
• 一个有效的声网账号以及声网项目。请参考开通 RTC 服务从声网控制台获得 App ID 和临时 Token。

创建项目Copy Anchor Link

按照以下步骤，在 Xcode 中创建一个项目：

1. 参考 Create a project 创建一个新的项目。Application 选择 App，Interface 选择 Storyboard，Language 选择 Swift。

   信息

   如果你没有添加过开发团队信息，会看到 Add account… 按钮。点击该按钮并按照屏幕提示登入 Apple ID，点击 Next，完成后即可选择你的 Apple 账户作为开发团队。

2. 为你的项目设置自动签名。

3. 设置部署你的 App 的目标设备。

4. 添加项目的设备权限。

在项目导航栏中打开 info.plist 文件，编辑属性列表，添加以下属性：

进入 TARGETS > Project Name > Signing & Capabilities，在 App Sandbox 和 Hardened Runtime 中添加如下权限：

集成 SDKCopy Anchor Link

根据实际情况，在以下集成方式中任选一种，在你的项目中集成 SDK。

创建用户界面Copy Anchor Link

根据使用场景，为你的项目创建一个用户界面，包括本地视频窗口和远端视频窗口。用以下代码替换 ViewController.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
    }
}

实现步骤Copy Anchor Link

下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。

下面列出了一段实现实时互动基本流程的完整代码以供参考。复制以下代码到 ViewController.swift 文件中替换原有内容即可。

导入声网组件Copy Anchor Link

在 ViewController.swift 文件中引入 AgoraRtcKit。

import AgoraRtcKit

初始化引擎Copy Anchor Link

调用 sharedEngineWithConfig 方法，创建并初始化 AgoraRtcEngineKit。

    agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)

启用视频模块Copy Anchor Link

按照以下步骤启用视频模块。

1. 调用 enableVideo 方法，启用视频模块。
2. 调用 setupLocalVideo 方法初始化本地视图，同时设置本地视频的显示属性。
3. 调用 startPreview 方法，开启本地视频预览。

    // 启用视频模块
    agoraKit.enableVideo()

    let videoCanvas = AgoraRtcVideoCanvas()
    videoCanvas.uid = 0
    videoCanvas.renderMode = .hidden
    videoCanvas.view = localView
    // 设置本地视图
    agoraKit.setupLocalVideo(videoCanvas)
    // 开始本地视频预览
    agoraKit.startPreview()

加入频道并发布音视频流Copy Anchor Link

调用 joinChannelByToken[2/4] 方法、填入你在控制台获取的临时 Token，以及获取 Token 时填入的频道名加入频道，并设置用户角色。

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)

设置远端用户视图Copy Anchor Link

调用 setupRemoteVideo 方法初始化远端用户视图，同时设置远端用户的视图在本地显示属性。你可以通过 didJoinedOfUid 回调获取远端用户的 uid。

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

实现常用回调Copy Anchor Link

根据使用场景，定义你所需的回调。以下示例代码展示了如何实现 didJoinChannel 和 didOfflineOfUid 回调。

// 成功加入频道回调
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)
}

开始音视频互动Copy Anchor Link

当视图加载完成后，在 viewDidLoad 中调用一系列方法加入频道，开始音视频互动。

override func viewDidLoad() {
    super.viewDidLoad()
    // 当加载视图后，你可以进行其他其他设置
    // 初始化视频窗口
    initView()
    // 当调用声网 API 时，以下函数会被调用
    agoraKit.enableVideo()
    startPreview()
    joinChannel()
}

结束音视频互动Copy Anchor Link

1. 调用 leaveChannel 方法离开频道，与会话相关的资源也会被释放。

   Copy Text

   agoraKit.stopPreview()
   agoraKit.leaveChannel(nil)

2. 调用 destroy 销毁引擎，并释放声网 SDK 中使用的所有资源。

   Copy Text

   AgoraRtcEngineKit.destroy()

   警告

   • 调用该方法后，你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能，你必须重新创建一个新的引擎。详见初始化引擎。
     • 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作，因此建议在子线程中调用该方法，避免主线程阻塞。

调试 AppCopy Anchor Link

参考以下步骤来测试你的 App：

1. 将 macOS 设备连接至计算机。

2. 点击 Build 来运行你的项目，需等待几秒至 App 安装完成。

3. 允许 App 访问设备的麦克风和摄像头权限。

4. 使用第二台 macOS 设备，重复以上步骤，在该设备上安装 App，并打开 App 加入频道，观察测试结果：

   • 如果两台设备均作为主播加入频道，则可以看到对方并且听到对方的声音。
   • 如果两台设备分别作为主播和观众加入，则主播可以在本地视频窗口看到自己；观众可以在远端视频窗口看到主播、并听到主播的声音。

后续步骤Copy Anchor Link

• 本文的示例使用了临时 Token 加入频道。在测试或生产环境中，为确保通信安全，声网推荐使用 Token 服务器来生成 Token，详见使用 Token 鉴权。
• 如果你想要实现极速直播场景，可以在互动直播的基础上，通过修改观众端的延时级别为低延时 (AgoraAudienceLatencyLevelLowLatency)实现。详见实现极速直播。

参考信息Copy Anchor Link

示例项目Copy Anchor Link

声网提供了开源的实时互动示例项目供你参考，你可以前往下载或查看其中的源代码。

常见问题Copy Anchor Link

• 直播场景下，如何监听远端观众角色用户加入/离开频道的事件？
• 如何处理视频黑屏问题？
• 如何处理 CocoaPods 常见问题？
• 为什么我无法打开摄像头？
• 如何处理频道相关常见问题？
• 编译 Xcode 项目时遇到 “无法打开 framework” 的弹窗警告怎么办？
• 如何设置日志文件？
• 为什么 SDK 中使用的是动态库而不是静态库？

相关文档Copy Anchor Link

• SDK 错误码
• 频道连接状态管理

本文介绍如何集成声网实时互动 Web SDK，通过少量代码从 0 开始实现一个简单的实时互动 App。 开始之前，你需要首先了解音视频实时互动的相关概念和流程。

实时音视频互动主要包含互动直播和视频通话两大场景，你可以按需搭建想要的场景：

• 互动直播：频道内的用户分为主播和观众，只有主播可以自由发言并且被其他用户看见。
• 视频通话：频道内的用户不区分主播和观众，所有用户都可以发言并看见彼此。

前提条件Copy Anchor Link

在集成声网实时互动 Web SDK 快速实现音视频互动前，请确保开发环境满足以下要求：

• Windows 或 macOS 计算机，需满足以下要求：

  • 下载满足声网 Web SDK 兼容性的浏览器。声网强烈推荐使用最新稳定版 Google Chrome 浏览器。
  • 具备物理音视频采集设备。
  • 可连接到互联网。如果你的网络环境部署了防火墙，请参考应对防火墙限制以正常使用声网服务。
  • 搭载 2.2 GHz Intel 第二代 i3/i5/i7 处理器或同等性能的其他处理器。

• 有效的声网账户和声网项目，请参考开通 RTC 服务，在声网控制台注册、登录并创建声网项目，然后获取项目的 App ID 和临时 Token。

• 安装 Node.js 18 或更高版本。

  信息

  有些框架模板可能需要更高版本的 Node.js 才能工作，如果你的包管理器发出警告，请升级你的 Node.js 版本。

实现步骤Copy Anchor Link

本节介绍如何快速搭建并实现一个实时音视频互动场景。根据你的开发偏好和需要，选择如下任意一种实现方式。

使用包管理工具快速创建（推荐）获取 SDK 后手动集成

信息

使用包管理工具只能快速搭建开箱即用的视频通话场景。如果你希望体验互动直播场景，请选用获取 SDK 后手动集成的方式，并在创建客户端时将 mode 设置为 live。

1. 获取快速开始安装包 (使用包管理工具快速创建（推荐）)Copy Anchor Link

在使用包管理器创建项目之前，你需要通过以下任意一种途径下载声网实时互动 Web SDK 快速开始安装包资源：

通过 GitHub 下载使用 npm 安装

通过 GitHub 下载 (通过 GitHub 下载)Copy Anchor Link

下载或克隆 create-agora-app获取快速开始安装包资源。

通过 npm 下载 (使用 npm 安装)Copy Anchor Link

安装 Node.js 及 npm，然后在终端通过 npm 安装快速开始资源包：

Copy Text

npm i create-agora-app

2. 使用包管理器创建项目 (使用包管理工具快速创建（推荐）)Copy Anchor Link

根据你的开发需要，使用如下一款包管理工具并继续：

使用 Yarn使用 pnpm使用 npm使用 Bun

开始前，请确保你的开发环境已安装 Yarn。

运行如下命令行安装快速开始资源包：

Copy Text

yarn create agora-app

开始前，请确保你的开发环境已安装 pnpm。

运行如下命令行安装快速开始资源包：

Copy Text

pnpm create agora-app

开始前，请确保你的开发环境已安装 npm。

运行如下命令行安装快速开始资源包：

Copy Text

npm create agora-app@latest

开始前，请确保你的开发环境已安装 Bun。

运行如下命令行安装快速开始资源包：

Copy Text

bunx create-agora-app

你可以在项目创建过程中修改你的项目名称，例如 agora-project。

3. 选择框架模板 (使用包管理工具快速创建（推荐）)Copy Anchor Link

在创建过程中，系统会提示你选择一个前端框架模板（包括 Vanilla-js、Vue-ts、React-ts 或 Svelte-ts）。你可以根据你的需求选择相应的框架。

4. 启动项目 (使用包管理工具快速创建（推荐）)Copy Anchor Link

系统将根据你的选择生成项目骨架，你需要进入项目目录并安装依赖，然后启动开发服务器。

以下是使用 yarn 创建了一个 React-ts 项目的示例，按照屏幕提示输入命令行来完成相关操作即可：

Copy Text

Scaffolding project in agora-project...
Done. Now run:

cd agora-project
yarn
yarn dev

此时，开发服务器将启动，你可以在浏览器中访问 http://localhost:5173/ 查看项目运行情况。

信息

在本地服务器 (localhost) 运行 Web 应用仅作为测试用途。部署生产环境时，请确保使用 HTTPS 协议。

5. 查看预期效果 (使用包管理工具快速创建（推荐）)Copy Anchor Link

你的浏览器会自动打开以下页面：

打开摄像头和麦克风确认设备没有问题，之后根据界面提示，输入 App ID、临时 Token，以及生成临时 Token 时填入的频道名，可以快速实现加入频道、发布音视频流和离开频道等基础音视频互动功能。

信息

上图以 React-ts 框架打开的界面为例。根据你所选择的前端框架模板，浏览器打开的界面可能有所不同。

获取 SDK 后手动集成 (获取 SDK 后手动集成)Copy Anchor Link

你可以参考以下步骤，获取 SDK 后进行手动集成，以搭建你想要实现的音视频互动场景（视频通话或互动直播）。

1. 创建 Web 项目 (获取 SDK 后手动集成)Copy Anchor Link

创建一个名为 agora_web_quickstart 的文件夹。一个 Web 客户端项目至少需包含以下文件：

• index.html: 用于设计 Web 应用的用户界面。
• basicEngagement.js: 通过 AgoraRTCClient 实现具体应用逻辑的代码。
• package.json: 安装并管理项目依赖。你可以通过命令行进入 agora_web_quickstart 目录并运行 npm init 命令来创建 package.json 文件。

2. 集成 SDK (获取 SDK 后手动集成)Copy Anchor Link

参考以下步骤通过 npm 将声网 Web SDK 集成到你的项目中：

在 package.json 文件的 dependencies 字段中添加 agora-rtc-sdk-ng 及版本号：

Copy Text

{
    "name": "agora_web_quickstart",
    "version": "1.0.0",
    "description": "",
    "main": "basicEngagement.js",
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
    },
    "dependencies": {
        "agora-rtc-sdk-ng": "latest"
    },
    "author": "",
    "license": "ISC"
}

将以下代码复制到 basicEngagement.js 文件中，在你的项目中导入 AgoraRTC 模块。

Copy Text

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

3. 实现用户界面 (获取 SDK 后手动集成)Copy Anchor Link

将以下代码复制到 index.html 实现客户端用户界面：

互动直播视频通话

Copy Text

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>Web SDK Video Quickstart</title>
        <!--
        This line is used to refer to the bundle.js file packaged by webpack. A sample webpack configuration is shown in the later step of running your app.
        -->
        <script src="./dist/bundle.js"></script>
    </head>
    <body>
        <h2 class="left-align">Web SDK Video Quickstart</h2>
        <div class="row">
            <div>
                <button type="button" id="host-join">Join as host</button>
                <button type="button" id="audience-join">Join as audience</button>
                <button type="button" id="leave">Leave</button>
            </div>
        </div>
    </body>
</html>

Copy Text

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>Web SDK Video Quickstart</title>
        <!--
        This line is used to refer to the bundle.js file packaged by webpack. A sample webpack configuration is shown in the later step of running your app.
        -->
        <script src="./dist/bundle.js"></script>
    </head>
    <body>
        <h2 class="left-align">Web SDK Video Quickstart</h2>
        <div class="row">
            <div>
                <button type="button" id="join">JOIN</button>
                <button type="button" id="leave">LEAVE</button>
            </div>
        </div>
    </body>
</html>

4. 复制项目示例代码 (获取 SDK 后手动集成)Copy Anchor Link

声网实时互动 Web SDK 提供两种模式的音视频互动，分别是视频通话和互动直播。两者创建客户端时设置的 mode 参数不同：

Copy Text

// 视频通话场景下 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以及频道名。

互动直播视频通话

实现互动直播示例代码

下图展示了基础的音视频直播的 API 调用。注意图中的方法是对不同的对象调用的。

实现视频通话示例代码

下图展示了实现音视频互动的 API 调用流程。注意图中的方法是对不同的对象调用的。

5. 测试 App (获取 SDK 后手动集成)Copy Anchor Link

本文使用 webpack 打包项目，使用 webpack-dev-server 运行项目。

参考以下步骤来测试你的 App：

在 package.json 的 dependencies 字段中添加 webpack、webpack-cli 和 webpack-dev-server，并在 scripts 字段中添加 build 和 start:dev。

Copy Text

{
    "name": "agora_web_quickstart",
    "version": "1.0.0",
    "description": "",
    "main": "basicEngagement.js",
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "build": "webpack --config webpack.config.js",
        "start:dev": "webpack serve --open --config webpack.config.js"
    },
    "dependencies": {
        "agora-rtc-sdk-ng": "latest",
        "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：

Copy Text

const path = require("path");

module.exports = {
    entry: "./basicEngagement.js",
    output: {
        filename: "bundle.js",
        path: path.resolve(__dirname, "./dist"),
    },
    devServer: {
        compress: true,
        port: 9000,
    },
};

运行下列命令安装依赖：

Copy Text

npm install

运行下列命令通过 webpack 编译项目：

Copy Text

# Use webpack to package the project
npm run build

通过 webpack-dev-server 运行项目：

Copy Text

npm run start:dev

信息

• 在本地服务器 (localhost) 运行 Web 应用仅作为测试用途。部署生产环境时，请确保使用 HTTPS 协议。
• 由于浏览器的安全策略，声网对除 127.0.0.1 以外的 HTTP 地址作了限制。

6. 查看预期效果 (获取 SDK 后手动集成)Copy Anchor Link

互动直播视频通话

你的浏览器会自动打开以下页面：

点击 Join as host 以主播角色加入频道。你还可以邀请朋友克隆 Gitee 示例项目或 GitHub 示例项目到本地，在浏览器中打开 src/index.html 文件，并输入相同的 App ID、频道名称和临时 Token。你的朋友以主播角色加入频道后，你们可以看到彼此，并听到彼此的声音；你的朋友以观众角色加入频道后，他可以看到你，并听到你的声音。

你的浏览器会自动打开以下页面：

点击 JOIN 加入频道。你还可以邀请朋友克隆 Gitee 示例项目或 GitHub 示例项目到本地，在浏览器中打开 src/index.html 文件，并输入相同的 App ID、频道名称和临时 Token。你的朋友加入频道后，你们可以看到彼此，并听到彼此的声音。

7. 后续步骤 (获取 SDK 后手动集成)Copy Anchor Link

在完成音视频互动后，你可以阅读以下文档进一步了解：

• 本文的示例使用了临时 Token 加入频道。在正式生产环境中，为保障通信安全，你需要在自己的 App 服务端生成 Token。详见使用 Token 鉴权。
• 如果你想要实现极速直播场景，可以在互动直播的基础上，通过修改观众端的延时级别为低延时实现。详见实现极速直播。

参考信息 (获取 SDK 后手动集成)Copy Anchor Link

示例项目 (获取 SDK 后手动集成)Copy Anchor Link

声网提供了开源的示例项目供你参考，你可以前往下载或查看其中的源代码。

Web-API-Examples（Gitee）

Web-API-Examples（GitHub）

其它集成方式 (获取 SDK 后手动集成)Copy Anchor Link

使用 npm 集成 Web SDK 还支持开启 Tree shaking 来减小集成 SDK 后的 App 体积，详见使用 Tree shaking。

除使用 npm 获取 Web SDK 之外，你还可以使用以下方法获取 SDK：

• 在项目 HTML 文件中，添加如下代码，使用 CDN 方法获取 SDK：

  Copy Text

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

• 下载声网 Web SDK 4.x 版本 SDK 包至本地，将 SDK 包中的 .js 文件保存到项目文件所在的目录下，然后在项目 HTML 文件中添加如下代码：

  Copy Text

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

信息

在以上方法中，SDK 都会在全局导出一个 AgoraRTC 对象，直接访问这个对象即可操作 SDK。

常见问题 (获取 SDK 后手动集成)Copy Anchor Link

为什么在本地运行快速开始项目时会报错 digital envelope routines::unsupported？

本文中的快速开始项目通过 webpack 打包并在本地运行。由于 Node.js 16 及以上版本更改了对 OpenSSL 的依赖（详见 node issue），影响了项目中本地开发环境的依赖（详见 webpack issue），运行项目会发生错误。解决方案如下：

• （推荐）运行如下命令，设置临时的环境变量：

  Copy Text

  export NODE_OPTIONS=--openssl-legacy-provider

• 暂时换用低版本的 Node.js。

尝试以上解决方案后，再次尝试运行项目。

本文介绍如何集成声网实时互动 SDK，通过少量代码从 0 开始实现一个简单的实时互动 App，适用于互动直播和视频通话场景。 首先，你需要了解以下有关音视频实时互动的基础概念：

• 声网实时互动 SDK：由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。
• 频道：用于传输数据的通道，在同一个频道内的用户可以进行实时互动。
• 主播：可以在频道内发布音视频，同时也可以订阅其他主播发布的音视频。
• 观众：可以在频道内订阅音视频，不具备发布音视频权限。

更多概念详见关键概念。

下图展示在 App 中实现音视频互动的基本工作流程：

1. 所有用户调用 joinChannel 方法加入频道，并根据需要设置用户角色：

   • 互动直播：如果用户需要在频道中发流，则设为主播；如果用户只需要收流，则设为观众。
   • 视频通话：将所有用户的角色都设为主播。

2. 加入频道后，不同角色的用户具备不同的行为：

   • 所有用户默认都可以接收频道中的音视频流。
   • 主播可以在频道内发布音视频流。
   • 观众如果需要发流，可在频道内调用 setClientRole 方法修改用户角色，使其具备发流权限。

前提条件Copy Anchor Link

在实现功能以前，请按照以下要求准备开发环境：

• Windows 7 或以上版本的设备。
• Microsoft Visual Studio 2017 或以上版本。
• C++ 11 或以上版本。
• 如果使用 C# 开发，还需要 .NET 桌面开发组件。
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。
• 一个有效的声网账号以及声网项目。请参考开通 RTC 服务从声网控制台获得 App ID 和临时 Token。

C++C#

创建项目 (C++)Copy Anchor Link

以 Windows 11 为例，参考以下操作或官方文档在 Visual Studio 2022 中创建一个项目来实现实时音视频互动功能，如果你已有自己的项目，可跳过这一步骤。

1. 在 Visual Studio 中，选择文件 > 新建 > 项目 来创建一个新项目。在弹出的窗口中，选择 MFC 应用作为项目模板，点击下一步将项目名称设为 AgoraQuickStart 并设置项目储存位置，然后点击创建。

2. 在弹出的 MFC 应用程序窗口中，将应用程序类型设为基于对话框，将使用 MFC 设为在共享 DLL 中使用 MFC。进入生成的类，将生成的类设为 Dlg，将基类设为 CDialog，最后点击完成。

集成 SDK (C++)Copy Anchor Link

1. 从下载获取最新的 Windows SDK，解压并打开。
2. 打开已下载的 SDK 文件，并将其中的 sdk 文件夹复制到你的项目路径下。保证 sdk 文件夹和你的 sln 文件处于同一目录。

注意

自 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 文件的属性来得知库的版本信息。

配置项目属性 (C++)Copy Anchor Link

在解决方案资源管理器窗口中，右击项目名称并点击属性进行以下配置：

1. 进入 C/C++ > 常规 > 附加包含目录菜单，输入 $(SolutionDir)sdk\high_level_api\include。

2. 进入链接器 > 常规 > 附加库目录菜单，输入 $(SolutionDir)sdk\x86_64。

   信息

   如果你是 x86 的 Windows 操作系统，请输入 $(SolutionDir)sdk\x86。

3. 进入链接器 > 输入 > 附加依赖项菜单，输入 $(SolutionDir)sdk\x86_64\agora_rtc_sdk.dll.lib。

   信息

   如果你是 x86 的 Windows 操作系统，请输入 $(SolutionDir)sdk\x86\agora_rtc_sdk.dll.lib。

4. 进入高级菜单，在高级属性中，把将内容复制到 OutDir 和将 C++ 运行时复制到输出目录设为是。

5. 进入生成事件 > 生成后事件 >命令行 菜单，输入 copy $(SolutionDir)sdk\x86_64\*.dll $(SolutionDir)$(Platform)\$(Configuration)。

6. 完成上述配置后点击应用。

创建用户界面 (C++)Copy Anchor Link

根据实时音视频互动的场景需要，你需要在你的应用中添加如下 UI：

• 展示本地视频的视图框
• 展示远端视频的视图框
• 输入频道名称的输入框
• 加入和离开频道按钮

你可以参考下列步骤来创建用户界面。

创建用户界面步骤

实现步骤 (C++)Copy Anchor Link

本小节介绍如何实现一个实时音视频互动应用。你可以先复制完整的示例代码到你的项目中，快速体验实时音视频互动的基础功能，再按照实现步骤了解核心 API 调用。

下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。

以下展示实现实时互动基本流程的完整示例代码：

注意

复制完整示例代码到你的项目之后，你需要将代码中的 APP_ID 和 token 替换成你在声网控制台获取的 App ID 和临时 Token。

AgoraQuickStartDlg.h

AgoraQuickStartDlg.cpp

参考下列步骤来在你的应用中实现实时互动：

初始化引擎 (C++)Copy Anchor Link

在调用其他声网 API 前，你需要调用 createAgoraRtcEngine 创建一个IRtcEngine 对象，然后调用 initialize 并传入 App ID，初始化 IRtcEngine。

注意

在初始化 SDK 前，需确保终端用户已经充分了解并同意相关的隐私政策。

Copy Text

// 创建 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;
}

启用视频模块 (C++)Copy Anchor Link

1. 调用 enableVideo 方法，启用视频模块。
2. 调用 setupLocalVideo 初始化本地视图，同时设置本地的视频显示属性。
3. 调用 startPreview 方法，开启本地视频预览。

Copy Text

// 启用视频模块
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();

加入频道并发布音视频流 (C++)Copy Anchor Link

调用 joinChannel[2/2] 方法、填入你在控制台获取的临时 Token，以及获取 Token 时填入的频道名加入频道，并设置用户角色。

Copy Text

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

实现常用回调 (C++)Copy Anchor Link

你可以根据需求，在初始化时实现其他功能，如注册用户加入、离开频道等回调。

Copy Text

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;
};

设置远端视图 (C++)Copy Anchor Link

当远端用户加入频道时，从远端用户加入频道的回调中获取到的远端用户的 uid，然后调用 setupRemoteVideo 设置并渲染远端视图。

Copy Text

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;
}

离开频道 (C++)Copy Anchor Link

根据场景需要，如关闭应用或应用切换至后台时，调用 leaveChannel 离开当前频道。

Copy Text

void CAgoraQuickStartDlg::OnBnClickedBtnLeave() {
    // 停止本地视频预览
    m_rtcEngine->stopPreview();
    // 离开频道
    m_rtcEngine->leaveChannel();

    // 清除本地视图
    VideoCanvas canvas;
    canvas.uid = 0;
    m_rtcEngine->setupLocalVideo(canvas);

    m_remoteRender = false;
}

如果你不再需要互动，调用 release 方法释放引擎资源。

注意

• 调用 release 后，你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能，你必须重新创建一个新的引擎。详见初始化引擎。 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作，因此建议在子线程中调用该方法，避免主线程阻塞。

Copy Text

CDialog::~CDialog() {
    // 在对象被销毁时释放资源
    if(m_rtcEngine){
       m_rtcEngine->release(true);
       m_rtcEngine = NULL;
    }
}

调试应用 (C++)Copy Anchor Link

按照以下步骤来测试你的应用：

1. 在 Visual Studio 中，选择本地 Windows 调试器开始编译应用。
2. 在输入框中输入你要加入的频道名，并点击加入按钮加入频道，你将在本地视图中看到自己。
3. 邀请一位朋友通过另一台设备来使用相同的 App ID、频道名、Token 加入频道。你的朋友加入频道后，你们可以听见、看见对方。

创建项目 (C#)Copy Anchor Link

参考以下操作，在 Visual Studio 中创建一个 Windows 项目：

1. 在 Visual Studio 上创建一个 Windows Forms 应用项目，详见 Create a Windows Forms app in Visual Studio with C#。
2. 打开 Configuration Manager 窗口，在 Active solution platform 下拉菜单中选择 New，在弹出的窗口中选择 x64 或 x86 作为目标平台。

集成 SDK (C#)Copy Anchor Link

使用 Visual Studio 中的 NuGet 包管理器，将 SDK 集成到项目中。详见快速入门：在 Visual Studio 中安装和使用包。

信息

你可以在 agora_rtc_sdk 中获取最新发布的 SDK 的版本信息。

创建用户界面 (C#)Copy Anchor Link

为直观地体验视频通话，你需要根据应用场景创建用户界面（UI）。若你的项目中已有用户界面，可略过此步骤。

如果你想实现音视频互动，推荐在 UI 上添加以下控件：

• 本地视图窗口
• 远端视图窗口
• 加入频道按钮
• 离开频道按钮

参考以下步骤创建 UI。

1. 创建 Join 和 Leave 按钮

   1. 在你的项目中，打开 Solution Explore 窗口，双击 Form1.cs，打开 Toolbox 窗口，选择 Button 控件，依次添加两个按钮，并将两个按钮拖放至合适位置。
   2. 将鼠标移至其中一个按钮上，点击鼠标右键，选中 Properties，在打开的 Properties 窗口中修改 Text 属性为 Join，修改 Name 属性为 btnJoin。
   3. 重复上一个步骤来修改另一个按钮的属性：修改 Text 为 Leave；修改 Name 为 btnLeave。

2. 创建本地及远端视图窗口

   1. 打开 Toolbox 窗口，选中 PictureBox 控件，依次为本地视图和远端视图在合适的位置添加控件。
   2. 将鼠标移至本地视图窗口控件上，点击鼠标右键，选中 Properties，在打开的 Properties 窗口中修改 Name 属性为 videoboxLocal；修改 BorderStyle 为 FixedSingle。
   3. 重复上一个步骤修改远端视图窗口控件的属性：修改 Name 为 videoboxRemote；修改 BorderStyle 为 FixedSingle。

3. 创建频道名输入框

   1. 打开 Toolbox 窗口，选中 TextBox 控件，然后将其拖拽至合适位置。
   2. 将鼠标移至添加好的输入框控件上，点击鼠标右键，选中 Properties ，修改其属性 Name 为 txChannelName。

4. 保存上述步骤的更改。

5. 分别双击 Join 和 Leave 按钮，IDE 会自动关联点击事件处理函数。

此时你的 UI 界面如下图所示：

实现步骤 (C#)Copy Anchor Link

本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中，快速体验实时音视频互动的基础功能，再按照实现步骤了解核心 API 调用。

下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。

下面列出了一段实现实时互动基本流程的完整代码以供参考。

信息

在 APP_ID 和 Token 字段中传入你在控制台获取到的 App ID 和临时 Token。

实现音视频互动示例代码

导入声网相关的类 (C#)Copy Anchor Link

导入声网 RTC SDK 相关的类。

Copy Text

using Agora.Rtc;

初始化引擎 (C#)Copy Anchor Link

调用 CreateAgoraRtcEngine 方法创建一个 RtcEngine 对象，然后调用 initialize 初始化 RtcEngine。

Copy Text

// 创建引擎
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;
}

启用视频模块 (C#)Copy Anchor Link

1. 调用 EnableVideo 方法，启用视频模块。
2. 调用 SetupLocalVideo 初始化本地视图，同时设置本地的视频显示属性。
3. 调用 StartPreview 方法，开启本地视频预览。

Copy Text

// 启用视频模块
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);
}

加入频道并发布音视频流 (C#)Copy Anchor Link

调用 JoinChannel[2/2] 加入频道,填入你在控制台获取的临时 Token，以及获取 Token 时填入的频道名加入频道，并设置用户角色。

Copy Text

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);

设置远端用户视图 (C#)Copy Anchor Link

调用 SetupRemoteVideo 方法初始化远端用户视图，同时设置远端用户的视图在本地显示属性。你可以通过 OnUserJoined 回调获取远端用户的 uid。

Copy Text

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

实现常用回调 (C#)Copy Anchor Link

根据使用场景，定义必要的回调。以下示例代码展示如何实现 OnJoinChannelSuccess、 OnUserJoined 和 OnUserOffline 回调。

Copy Text

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
)

开始音视频互动 (C#)Copy Anchor Link

在 btnJoin_Click 函数中调用 JoinChannel[2/2] 方法，当用户点击 Join 按钮时开始音视频互动。

Copy Text

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

结束音视频互动 (C#)Copy Anchor Link

1. 在 btnLeave_Click 函数中调用 LeaveChannel 方法，当用户点击 Leave 按钮时结束音视频互动。

   Copy Text

   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 中使用的所有资源。

   Copy Text

   engine_.Dispose()

   警告

   • 调用 Dispose 后，你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能，你必须重新创建一个新的引擎。详见初始化引擎。
     • 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作，因此建议在子线程中调用该方法，避免主线程阻塞。

测试你的项目 (C#)Copy Anchor Link

按照以下步骤来测试你的视频通话项目：

1. 将你从声网控制台获取的 App ID 和临时 Token 分别填入到 Form1.cs 文件的 APP_ID 和 APP_TOKEN 中。
2. 在 Visual Studio 中点击 Start 按钮运行你的项目，你将在本地视图中看到自己。
3. 在输入框中输入你在声网控制台生成临时 Token 时填写的频道名，并点击 Join 按钮加入频道。
4. 邀请一位朋友通过另一台设备来使用相同的 App ID、频道名、Token 加入频道。你的朋友加入频道后，你们可以听见、看见对方。

后续步骤Copy Anchor Link

• 在测试或生产环境中，为确保通信安全，声网推荐使用 Token 服务器来生成 Token，详见使用 Token 鉴权。
• 如果你想要实现极速直播场景，可以在互动直播的基础上，通过修改观众端的延时级别为低延时 (AUDIENCE_LATENCY_LEVEL_LOW_LATENCY)实现。详见实现极速直播。

参考信息Copy Anchor Link

示例项目Copy Anchor Link

声网提供了开源的音视频互动示例项目供你参考，你可以前往下载或查看其中的源代码。

常见问题Copy Anchor Link

• 直播场景下，如何监听远端观众角色用户加入/离开频道的事件？
• 如何处理视频黑屏问题？
• 为什么我无法打开摄像头？
• 如何处理频道相关常见问题？
• 如何设置日志文件
• 为什么 SDK 中使用的是动态库而不是静态库？

相关文档Copy Anchor Link

• SDK 错误码
• 频道连接状态管理

本文介绍如何集成声网实时互动 SDK，通过少量代码从 0 开始实现一个简单的实时互动 App，适用于互动直播和视频通话场景。 首先，你需要了解以下有关音视频实时互动的基础概念：

• 声网实时互动 SDK：由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。
• 频道：用于传输数据的通道，在同一个频道内的用户可以进行实时互动。
• 主播：可以在频道内发布音视频，同时也可以订阅其他主播发布的音视频。
• 观众：可以在频道内订阅音视频，不具备发布音视频权限。

更多概念详见关键概念。

下图展示在 App 中实现音视频互动的基本工作流程：

1. 所有用户调用 joinChannel 方法加入频道，并根据需要设置用户角色：

   • 互动直播：如果用户需要在频道中发流，则设为主播；如果用户只需要收流，则设为观众。
   • 视频通话：将所有用户的角色都设为主播。

2. 加入频道后，不同角色的用户具备不同的行为：

   • 所有用户默认都可以接收频道中的音视频流。
   • 主播可以在频道内发布音视频流。
   • 观众如果需要发流，可在频道内调用 setClientRole 方法修改用户角色，使其具备发流权限。

前提条件Copy Anchor Link

在实现功能以前，请按照以下要求准备开发环境：

• DevEco Studio 5.1.0 Release 及以上版本，已包含所需的 HarmonyOS SDK。
• 运行 API 12 及以上版本 HarmonyOS 的设备。
• 华为开发者账号。可在华为开发者联盟注册账号。
• 两台支持 HarmonyOS 的设备，建议使用 Mate 60 Pro 及更高性能的设备。
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。
• 一个有效的声网账号以及声网项目。请参考开通 RTC 服务从声网控制台获得 App ID 和临时 Token。

创建项目Copy Anchor Link

本小节介绍如何创建项目并为项目添加体验实时互动所需的权限。

1. 参考创建和运行 Hello World，创建一个新工程。

2. 打开 entry/src/main 中的 module.json5 文件，在 module 模块中声明网络和设备权限：

   Copy Text

   "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 文件，添加如下代码，定义所需要的权限。

   Copy Text

   {
     "name": "Internet_reason",
     "value": "access internet"
   },
   {
     "name": "Audio_reason",
     "value": "access audio"
   },
   {
     "name": "Video_reason",
     "value": "access video"
   }

集成 SDKCopy Anchor Link

1. 在下载页面下载最新版本的鸿蒙视频 SDK，并在本地解压。

2. 打开解压文件，将 AgoraRtcSdk.har 文件复制到项目 entry -> libs 目录下（libs 文件夹需要手动创建）。

3. 在 entry 下的 oh-package.json5 文件中添加如下依赖，然后点击 Sync 开始同步。

   Copy Text

   "dependencies": {
     "@shengwang/rtc-full":"file:./libs/AgoraRtcSdk.har"
   }

实现步骤Copy Anchor Link

本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中，快速体验实时音视频互动的基础功能，再按照实现步骤了解核心 API 调用。

下图展示了使用声网 RTC SDK 实现音视频互动的基本流程：

下面列出了一段实现实时互动基本流程的完整代码以供参考。复制以下代码到 pages/Index.ets 文件中替换原有内容，即可快速体验实时互动基础功能。

处理权限请求Copy Anchor Link

本小节介绍如何获取设备的摄像头、录音等权限。

1. 在项目中打开 entryability -> EntryAbility.ets 文件，在 EntryAbility 之前添加权限申请，示例代码如下所示。

   启动应用程序时，检查是否已在 App 中授予了实现实时互动所需的权限。

   Copy Text

   const permissions: Array<Permissions> = ['ohos.permission.INTERNET','ohos.permission.MICROPHONE',"ohos.permission.CAMERA"];
   
   
   async function checkAccessToken(permission: Permissions): Promise<abilityAccessCtrl.GrantStatus> {
     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<permissions.length;i++) {
         let permission: Permissions = permissions[i]
         let granted : boolean = false;
         let toGrantedPerm: Array<Permissions> = new Array<Permissions>();
         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<number> = 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}`);
             })
           }
         })
       }
     }
   
   }

导入声网组件Copy Anchor Link

打开 src/main/ets/pages/Index.ets 文件，导入如下所需的声网 SDK 组件。

import {
    ChannelMediaOptions,
    Constants,
    RtcEngine,
    RtcEngineConfig,
    RtcStats,
    VideoCanvas,
} from "@shengwang/rtc-full"

添加视频渲染组件Copy Anchor Link

在 Index.ets 文件中添加视频渲染组件 XComponent。

@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%')
  }
}

初始化引擎Copy Anchor Link

调用 create 方法初始化 RtcEngine。

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);