文档中心





极速直播 (Legacy)

Console 官网社区技术支持





实现视频直播

更新时间 2023/02/01 08:07:49

实时互动直播能够拉近人与人之间的距离，为用户提供沉浸式的交流体验，帮助你的 app 提高用户黏性。

本文介绍如何通过少量代码集成 Agora 视频 SDK 并调用 API，在你的应用中实现高质量、低延迟的互动直播功能。

技术原理

下图展示在 app 中集成声网极速直播的基本工作流程：

如图所示，实现极速直播的步骤如下：

设置用户角色和延时级别：极速直播频道中，用户角色可以是主播或者观众。主播在频道内发布音视频流，观众可以订阅流。你可以利用 ClientRoleOptions 控制观众用户接收主播发布的音视频流的延时。
获取 Token：当 app 客户端加入频道时，你需要使用 Token 验证用户身份。在测试或生产环境中，从 app 服务器中获取 Token。
加入频道：调用 joinChannel 创建并加入频道。使用同一频道名称的 app 客户端默认加入同一频道。
在频道内发布和订阅音视频流：加入频道后，角色为主播的 app 客户端可以发布音视频。如果观众想要发布音视频，可以调用 setClientRole 切换用户角色。

App 客户端加入频道需要以下信息：

App ID：声网随机生成的字符串，用于识别你的 app，可从声网控制台获取。
用户 ID：用户的唯一标识。你需要自行设置用户 ID，并确保它在频道内是唯一的。
Token：在测试或生产环境中，app 客户端从你的的服务器中获取 Token。在本文介绍的流程中，你可以从声网控制台获取临时 Token。临时 Token 的有效期为 24 小时。
频道名称：用于标识极速直播频道的字符串。

前提条件

开始前，请确保你的开发环境满足以下条件：

Java Development Kit
Android Studio 3.0 或以上版本。
Android SDK API 级别 16 或以上。
有效的声网账户。
带有 App ID 和临时 Token 的声网项目。详情请参考开始使用声网平台。
可以访问互联网的计算机。如果你的网络环境部署了防火墙，请参考应用企业防火墙限制。
运行 Android 4.1 或更高版本的移动设备。

项目设置

实现极速直播之前，参考如下步骤设置你的项目：

如需创建新项目，在 Android Studio 里，依次选择 Phone and Tablet > Empty Activity，创建 Android 项目。

创建项目后，Android Studio 会自动开始同步 gradle。请确保同步成功再进行下一步操作。
使用 Maven Central 将 Agora 视频 SDK 集成到你的项目中。更多集成方式，请参考集成 SDK 的其他方法。

a. 在 /Gradle Scripts/build.gradle(Project: <projectname>) 文件中添加如下代码，以添加 Maven Central 依赖：
```
 buildscript {
         repositories {
                 ...
                 mavenCentral()
         }
         ...
 }

 allprojects {
         repositories {
                 ...
                 mavenCentral()
         }
 }
```
如果你的 Android 项目设置了 dependencyResolutionManagement，添加 Maven Central 依赖的方式可能存在差异。

b. 在 /Gradle Scripts/build.gradle(Module: <projectname>.app) 文件中添加如下代码，将 Agora 视频 SDK 集成到你的 Android 项目中：

    ...
    dependencies {
     ...
     // x.y.z，请填写具体的 SDK 版本号，如：3.5.0 或 3.7.0.2。
     // 通过发版说明获取最新版本号。
     implementation 'io.agora.rtc:full-sdk:x.y.z'
    }

在 /app/Manifests/AndroidManifest.xml 文件中的 </application> 后面添加如下网络和设备权限：

    <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 及以上设备，还需要添加如下权限： -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"  />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

在 /Gradle Scripts/proguard-rules.pro 文件中添加如下行，以防止声网 SDK 的代码被混淆：
```
 -keep class io.agora.**{*;}
```

客户端实现

本节介绍如何使用声网视频 SDK 在你的 app 里实现极速直播。

创建用户界面

在用户界面中，你需要设置两个帧布局（FrameLayout），分别展示本地视图和远端视图。因此，将 /app/res/layout/activity_main.xml 文件中的内容替换成如下代码：

<?xml version="1.0" encoding="UTF-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/activity_main"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

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

      <FrameLayout
        android:id="@+id/remote_video_view_container"
        android:layout_width="160dp"
        android:layout_height="160dp"
        android:layout_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" />

</RelativeLayout>

处理 Android 系统逻辑

参考如下步骤，导入必要的 Android 类，并添加授权必要权限的逻辑。

导入必要的 Android 类

在 /app/java/com.example.<projectname>/MainActivity 文件中的 package com.example.<projectname> 后添加如下代码：

 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;

添加必要权限的授权逻辑

启动应用程序时，检查是否已在 app 中授予了实现极速直播所需的权限。如果已获取权限 true，调用 initializeAndJoinChannel 开始极速直播功能。如果未获取权限 false，Android 系统调出权限覆盖，申请权限。

为实现授权逻辑，在 /app/java/com.example.<projectname>/MainActivity 文件中的 onCreate 函数前添加如下代码：

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

实现极速直播逻辑

应用开启时，你需要依次创建 RtcEngine 实例，开启视频模块，让本地用户加入频道，将本地视图与处于较低图层的帧布局（FrameLayout）绑定。当其他用户加入频道时，你的 app 会捕捉到这一加入事件，并将远端视图与处于较高图层的帧布局（FrameLayout）绑定。

下图展示极速直播的 API 调用时序：

按照以下步骤实现该逻辑：

导入必要的声网类。

在 /app/java/com.example.<projectname>/MainActivity 文件中的 import android.os.Bundle 后添加如下代码：

 import io.agora.rtc.Constants;
 import io.agora.rtc.IRtcEngineEventHandler;
 import io.agora.rtc.RtcEngine;
 import io.agora.rtc.models.ClientRoleOptions;
 import io.agora.rtc.video.VideoCanvas;

创建变量用以创建并加入互动直播。

在 /app/java/com.example.<projectname>/MainActivity 文件中的 AppCompatActivity { 后添加如下代码：

  // 填写你的项目在声网控制台中生成的 App ID。
  private String appId = "";
  // 填写频道名称。
  private String channelName = "";  
  // 填写声网控制台中生成的临时 Token。
  private String 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() {
                                  // 从 onUserJoined 回调获取 uid 后，调用 setupRemoteVideo，设置远端视频视图。
                                  setupRemoteVideo(uid);
                          }
                  });
          }
  };

初始化 app 并加入频道。

调用核心方法来加入 MainActivity 类中的频道。在如下示例代码中，我们使用 initializeAndJoinChannel 函数来封装这些核心方法。

在 /app/java/com.example.<projectname>/MainActivity 文件中的 onCreate 函数后添加如下代码：

  private void initializeAndJoinChannel() {
          try {
                  mRtcEngine = RtcEngine.create(getBaseContext(), appId, mRtcEventHandler);
          } catch (Exception e) {
                  throw new RuntimeException("Check the error.");
          }

          // 直播场景下，设置频道场景为 BROADCASTING。
          mRtcEngine.setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING);
          // 将用户角色设置为观众，将延时性设置为低延时。
          ClientRoleOptions clientRoleOptions = new ClientRoleOptions();
          clientRoleOptions.audienceLatencyLevel = Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY;
          mRtcEngine.setClientRole(Constants.CLIENT_ROLE_AUDIENCE, clientRoleOptions);

          // 视频默认禁用，你需要调用 enableVideo 开始视频流。
          mRtcEngine.enableVideo();

          FrameLayout container = findViewById(R.id.local_video_view_container);
          // 调用 CreateRendererView 创建一个 SurfaceView 对象，并将其作为 FrameLayout 的子对象。
          SurfaceView surfaceView = RtcEngine.CreateRendererView(getBaseContext());
          container.addView(surfaceView);
          // 将 SurfaceView 对象传入声网，以渲染本地视频。
          mRtcEngine.setupLocalVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0));

          // 使用 Token 加入频道。
          mRtcEngine.joinChannel(token, channelName, "", 0);
  }

当远端用户加入频道时，更新远端用户界面。

在 /app/java/com.example.<projectname>/MainActivity 文件中的initializeAndJoinChannel 函数后加入如下代码：

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

启动和关闭 app

现在你已经完成极速直播的逻辑，接下来需要添加启动和关闭 app 的逻辑。用户打开你的 app 启动时，直播开始；用户关闭你的 app 时，直播结束。

检查 app 是否已获取正确的权限。如果已获取权限，调用 initializeAndJoinChannel 加入直播频道。

在 /app/java/com.example.<projectname>/MainActivity 文件中，用如下代码替换 MainActivity 类中的 onCreate：

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

当用户关闭 app 时，清理你在 initializeAndJoinChannel 函数中创建的所有资源。

在 /app/java/com.example.<projectname>/MainActivity 文件中的 onCreate 函数后添加 onDestroy：
```
  protected void onDestroy() {
          super.onDestroy();

          mRtcEngine.leaveChannel();
          mRtcEngine.destroy();
  }
```

测试你的 app

按照以下步骤测试你的 app：

在 appId 和 token 参数中分别填写从声网控制台获取的 App ID 和临时 Token。在 channelName 中填写用于生成临时 token 的频道名称。
将 Android 设备连接到你的电脑，并在 Android Studio 里点击 Run 'app'。片刻后，项目便会安装到你的设备上。
在你的设备上启动 app。在你的 app 里，用户角色被设置为观众。你无法在本地视图中看到自己。
请一位朋友加入你的极速直播：克隆 API-Examples-Web 项目到本地，在浏览器中打开 Demo/index.html 文件，并输入相同的 App ID 和频道名称。

后续步骤

在生产环境中，为保证通信安全，声网推荐从服务器中获取 Token，详情请参考使用 Token 鉴权。

文件或子文件夹	你的项目路径
`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/`
`include` 文件夹	`/app/src/main/jniLibs/`