实现音视频互动

本文介绍如何集成声网实时互动 SDK，通过少量代码从 0 开始实现一个简单的实时互动 App，适用于互动直播和视频通话场景。

首先，你需要了解以下有关音视频实时互动的基础概念：

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

更多概念详见关键概念。

下图以直播场景为例，展示在 App 中实现音视频互动的基本工作流程：

1. 所有用户调用 joinChannel 方法加入频道，并根据需要设置用户角色：
   • 互动直播：如果用户需要在频道中发流，则设为主播；如果用户只需要收流，则设为观众。
   • 视频通话：将所有的用户角色都为主播。
2. 加入频道后，不同角色的用户具备不同的行为：
   • 所有用户默认都可以接收频道中的音视频流。
   • 主播可以在频道内发布音视频流。
   • 观众如果需要发流，可在频道内调用 setClientRole 方法修改用户角色，使其具备发流权限。

前提条件

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

• Android Studio 4.1 以上版本。
• Android API 级别 16 或以上。
• 两台运行 Android 4.1 或以上版本的移动设备
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。
• 一个有效的声网账号以及声网项目。请参考开通服务从声网控制台获得以下信息：
  • App ID：声网随机生成的字符串，用于识别你的项目。
  • 临时 Token：Token 也称为动态密钥，在客户端加入频道时对用户鉴权。临时 Token 的有效期为 24 小时。

创建项目

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

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/Manifests/AndroidManifest.xml 文件，在 </application> 后面添加如下权限：

   XML

    <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. 防止代码混淆。

   打开 /Gradle Scripts/proguard-rules.pro 文件，添加如下行以防止声网 SDK 的代码被混淆：

   Java

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

集成 SDK

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

通过 Maven Central 集成

1. 打开项目根目录下的 /Gradle Scripts/settings.gradle 文件，添加 Maven Central 依赖 (如果已有可忽略)：

   Java

   repositories {
      ...
      mavenCentral()
      ...
   }

   注意

   如果你的 Android 项目设置了 dependencyResolutionManagement，添加 Maven Central 依赖的方式可能存在差异。

2. 打开 /Gradle Scripts/build.gradle(Module: <projectname>.app) 文件，在 dependencies 中添加声网实时互动 SDK 的依赖。你可以从发版说明中查询 SDK 的最新版本，并将 x.y.z 替换为具体的版本号。

   Java

   ...
   dependencies {
      ...
      // x.y.z 替换为具体的 SDK 版本号，如：4.0.0 或 4.1.0-1
      implementation 'io.agora.rtc:full-sdk:x.y.z'
   }

手动集成

1. 在 SDK 下载页面下载最新版本的 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/

3. 在 Android Studio 的左侧导航栏上选择 Project Files/app/libs/agora-rtc-sdk.jar 文件，右键单击，在下拉菜单中选择 add as a library。

创建用户界面

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

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

创建用户界面示例代码

XML

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

   <TextView
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:text="Start Video Call!"
      app:layout_constraintBottom_toBottomOf="parent"
      app:layout_constraintLeft_toLeftOf="parent"
      app:layout_constraintRight_toRightOf="parent"
      app:layout_constraintTop_toTopOf="parent" />
   <FrameLayout
      android:id="@+id/local_video_view_container"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      android:background="@android:color/white" />

   <FrameLayout
      android:id="@+id/remote_video_view_container"
      android:layout_width="160dp"
      android:layout_height="160dp"
      android:layout_alignParentEnd="true"
      android:layout_alignParentRight="true"
      android:layout_alignParentTop="true"
      android:layout_marginEnd="16dp"
      android:layout_marginRight="16dp"
      android:layout_marginTop="16dp"
      android:background="@android:color/darker_gray"
      tools:ignore="MissingConstraints" />

</androidx.constraintlayout.widget.ConstraintLayout>

折叠 16 行

实现流程

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

下图展示了使用声网实时互动 SDK 实现音视频互动的 API 调用时序：

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

信息

在 appId、token 和 channelName 字段中传入你在控制台获取到的 App ID、临时 Token，以及生成临时 Token 时填入的频道名。

实现实时音视频互动示例代码

Java

import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

import android.Manifest;
import android.content.pm.PackageManager;
import android.view.SurfaceView;
import android.widget.FrameLayout;

import android.os.Bundle;
import io.agora.rtc2.Constants;
import io.agora.rtc2.IRtcEngineEventHandler;
import io.agora.rtc2.RtcEngine;
import io.agora.rtc2.RtcEngineConfig;
import io.agora.rtc2.video.VideoCanvas;
import io.agora.rtc2.ChannelMediaOptions;

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
        // 监听频道内的远端用户，获取用户的 uid 信息
        public void onUserJoined(int uid, int elapsed) {
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    // 获取 uid 后，设置远端视频视图
                    setupRemoteVideo(uid);
                }
            });
        }
    };

    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();
        // 开启本地预览
        mRtcEngine.startPreview();

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

        // 创建 ChannelMediaOptions 对象，并进行配置
        ChannelMediaOptions options = new ChannelMediaOptions();
        // 根据场景将用户角色设置为 BROADCASTER (主播) 或 AUDIENCE (观众)
        options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER;
        // 直播场景下，设置频道场景为 BROADCASTING (直播场景)
        options.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING;

        // 使用临时 Token 加入频道，自行指定用户 ID 并确保其在频道内的唯一性
        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 static final String[] REQUESTED_PERMISSIONS = {
            Manifest.permission.RECORD_AUDIO,
            Manifest.permission.CAMERA
    };
    private boolean checkSelfPermission(String permission, int requestCode) {
        if (ContextCompat.checkSelfPermission(this, permission) !=
                PackageManager.PERMISSION_GRANTED) {
            ActivityCompat.requestPermissions(this, REQUESTED_PERMISSIONS, requestCode);
            return false;
        }
        return true;
    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // 如果已经授权，则初始化 RtcEngine 并加入频道
        if (checkSelfPermission(REQUESTED_PERMISSIONS[0], PERMISSION_REQ_ID) &&
                checkSelfPermission(REQUESTED_PERMISSIONS[1], PERMISSION_REQ_ID)) {
            initializeAndJoinChannel();
        }
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();

        // 停止本地视频预览
        mRtcEngine.stopPreview();

        // 离开频道
        mRtcEngine.leaveChannel();
    }
}

折叠 103 行

处理权限请求

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

1. 导入 Android 相关的类

   Java

   import androidx.appcompat.app.AppCompatActivity;
   import androidx.core.app.ActivityCompat;
   import androidx.core.content.ContextCompat;
   
   import android.Manifest;
   import android.content.pm.PackageManager;
   import android.view.SurfaceView;
   import android.widget.FrameLayout;

2. 获取 Android 权限

   启动应用程序时，检查是否已在 App 中授予了实现实时互动所需的权限。如果未授权，使用内置的 Android 功能申请权限；如果已授权，则返回 true。

   Java

   private static final int PERMISSION_REQ_ID = 22;
   private static final String[] REQUESTED_PERMISSIONS = {
         Manifest.permission.RECORD_AUDIO,
         Manifest.permission.CAMERA
   };
   private boolean checkSelfPermission(String permission, int requestCode) {
      if (ContextCompat.checkSelfPermission(this, permission) !=
               PackageManager.PERMISSION_GRANTED) {
         ActivityCompat.requestPermissions(this, REQUESTED_PERMISSIONS, requestCode);
         return false;
      }
      return true;
   }

导入声网相关的类

导入声网实时互动 SDK 相关的类和接口：

Java

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

定义 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。

Java

private RtcEngine mRtcEngine;

private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() {
   @Override
   // 监听频道内的远端用户，获取用户的 uid 信息
   public void onUserJoined(int uid, int elapsed) {
      runOnUiThread(new Runnable() {
            @Override
            public void run() {
               // 获取 uid 后，设置远端视频视图
               setupRemoteVideo(uid);
            }
      });
   }
};

// 创建 RtcEngineConfig 对象，并进行配置
RtcEngineConfig config = new RtcEngineConfig();
config.mContext = getBaseContext();
config.mAppId = appId;

展开全部 23 行

启用视频模块

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

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

Java

// 启用视频模块
mRtcEngine.enableVideo();
// 开启本地预览
mRtcEngine.startPreview();

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

加入频道并发布音视频流

创建并配置 ChannelMediaOptions 对象并调用 joinChannel [2/2] 加入频道。在 ChannelMediaOptions 中设置频道场景为 BROADCASTING (直播场景) 并设置用户角色设置为 BROADCASTER (主播) 或 AUDIENCE (观众)。

Java

// 创建 ChannelMediaOptions 对象，并进行配置
ChannelMediaOptions options = new ChannelMediaOptions();
// 根据场景将用户角色设置为 BROADCASTER (主播) 或 AUDIENCE (观众)
options.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER;
// 直播场景下，设置频道场景为 BROADCASTING (直播场景)
options.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING;

// 使用临时 Token 加入频道，自行指定用户 ID 并确保其在频道内的唯一性
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));
}

启动和关闭 App

至此，你已经成功在你的 App 中添加了实时音视频互动功能。当用户启动你的 App 时，互动开始；当用户关闭 App 时，互动结束。

1. 启动 App 时，检查 App 是否有正确的权限。如果已授予权限，则加入直播频道。

   Java

   @Override
   protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);
   
      // 如果已经授权，则初始化 RtcEngine 并加入频道
      if (checkSelfPermission(REQUESTED_PERMISSIONS[0], PERMISSION_REQ_ID) &&
               checkSelfPermission(REQUESTED_PERMISSIONS[1], PERMISSION_REQ_ID)) {
         initializeAndJoinChannel();
      }
   }

2. 关闭 App 或 App 切换至后台时，调用 stopPreview 停止视频预览并调用 leaveChannel 离开当前直播频道，以释放所有会话相关的资源。

   Java

   @Override
   protected void onDestroy() {
      super.onDestroy();
   
      // 停止本地视频预览
      mRtcEngine.stopPreview();
   
      // 离开频道
      mRtcEngine.leaveChannel();
   }

   注意

   如果你想释放声网 SDK 使用的所有资源，需调用 destroy 清理你创建的所有资源。详见 destroy。

测试 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 鉴权。
• 如果你想要实现极速直播场景，可以在实时音视频互动的基础上，通过修改观众端的延时级别为低延时 (AUDIENCE_LATENCY_LEVEL_LOW_LATENCY)实现。详见实现极速直播。

相关信息

本节提供了额外的信息供参考。

示例项目

声网在 GitHub 上提供了一个开源的实时音视频互动示例项目 JoinChannelVideo 供你参考。

常见问题

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

相关文档

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