实现视频通话

1 功能简介

本文将介绍如何快速实现一个简单的实时音视频通话。

相关概念解释:

• ZEGO Express SDK：由 ZEGO 提供的实时音视频 SDK，能够为开发者提供便捷接入、高清流畅、多平台互通、低延迟、高并发的音视频服务。
• 推流：把采集阶段封包好的音视频数据流推送到 ZEGO 实时音视频云的过程。
• 拉流：从 ZEGO 实时音视频云将已有音视频数据流拉取播放的过程。
• 房间：是 ZEGO 提供的音视频空间服务，用于组织用户群，同一房间内的用户可以互相收发实时音视频及消息。
  1. 用户需要先登录某个房间，才能进行推流、拉流操作。
  2. 用户只能收到自己所在房间内的相关消息（用户进出、音视频流变化等）。

更多相关概念请参考 术语说明。

2 前提条件

在实现基本的实时音视频功能之前，请确保：

• 已在项目中集成 ZEGO Express SDK，详情请参考 快速开始 - 集成。
• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 AppSign，详情请参考 控制台 - 项目管理 中的“项目信息”。

3 实现流程

用户通过 ZEGO Express SDK 进行视频通话的基本流程为：

用户 A、B 加入房间，用户 B 预览并将音视频流推送到 ZEGO 云服务（推流），用户 A 收到用户 B 推送音视频流的通知之后，在通知中播放音视频流（拉流）。

3.1 创建引擎

1. 创建界面

根据场景需要，为您的项目创建视频通话的用户界面。我们推荐您在项目中添加如下元素：

• 本地视频窗口
• 远端视频窗口
• 结束通话按钮

添加视频通话界面的代码可参考：

<?xml version="1.0" encoding="utf-8"?>
<DirectionalLayout
    xmlns:ohos="http://schemas.huawei.com/res/ohos"
    ohos:height="match_parent"
    ohos:width="match_parent"
    ohos:alignment="center"
    ohos:orientation="vertical">

    <DependentLayout
        ohos:id="$+id:rootContainer"
        ohos:height="match_parent"
        ohos:width="match_parent">

        <!-- 本地预览视图（SurfaceProvider 实例）将通过代码动态创建，并添加到 localViewContainer 布局中 -->
        <DirectionalLayout
            ohos:id="$+id:localViewContainer"
            ohos:width="match_parent"
            ohos:height="match_parent"
            ohos:visibility="invisible"/>

        <SurfaceProvider
            ohos:id="$+id:remoteView"
            ohos:height="480"
            ohos:width="640"
            ohos:top_margin="20vp"
            ohos:right_margin="20vp"
            ohos:align_parent_top="true"
            ohos:align_parent_right="true"
            />

        <Button
            ohos:id="$+id:startButton"
            ohos:height="50vp"
            ohos:width="80vp"
            ohos:text="$string:start"
            ohos:bottom_margin="20vp"
            ohos:text_size="18fp"
            ohos:background_element="$graphic:background_button"
            ohos:align_parent_bottom="true"
            ohos:horizontal_center="true"/>

    </DependentLayout>

</DirectionalLayout>

2. 引入 ZegoExpressEngine 包

在项目中引入 ZegoExpressEngine 包。

// 引入 ZegoExpressEngine 包
import im.zego.zegoexpress.ZegoExpressEngine;
import im.zego.zegoexpress.constants.ZegoScenario;
import im.zego.zegoexpress.callback.IZegoEventHandler;
import im.zego.zegoexpress.entity.ZegoCanvas;
import im.zego.zegoexpress.entity.ZegoUser;

3. 创建引擎

调用 createEngine 接口，将 前提条件 中申请到的 AppID 和 AppSign 传入参数 “appID” 和 “appSign”，创建引擎单例对象。

注册回调，可将实现了 ZegoEventHandler 的对象（例如 “this”）传入参数 “eventHandler”。

// 定义 SDK 引擎对象
ZegoExpressEngine engine;

// 填写 appID 和 appSign
long appID = ;  // 请通过官网注册获取，格式为：1234567890
String appSign = ;  //请通过官网注册获取，格式为：@"0123456789012345678901234567890123456789012345678901234567890123"（共64个字符）

// 获取 AbilityPackage 对象
AbilityPackage abilityPackage = getAbility().getAbilityPackage();
abilityPackage.attachBaseContext(getContext());

// 创建引擎，通用场景接入，传入 AbilityPackage 对象，并注册 this 为 eventHandler 回调
// 不需要注册回调的话，eventHandler 参数可以传 null，后续可调用 "setEventHandler" 方法设置回调
engine = ZegoExpressEngine.createEngine(appID, appSign, false, ZegoScenario.GENERAL, abilityPackage, this);

3.2 登录房间

1. 登录

传入用户 ID 参数 “userID” 创建 ZegoUser 用户对象后，调用 loginRoom 接口，传入房间 ID 参数 “roomID” 和用户参数 “user”，登录房间。

“roomID” 和 “user” 的参数由您本地生成，但是需要满足以下条件：

• 同一个 AppID 内，需保证 “roomID” 全局唯一。
• 同一个 AppID 内，需保证 “userID” 全局唯一，建议开发者将其设置成一个有意义的值，可将 “userID” 与自己业务账号系统进行关联。

// 创建用户
ZegoUser user = new ZegoUser("user1");

// 登录房间
engine.loginRoom("room1", user);

调用登录房间接口之后，您可通过监听 onRoomStateUpdate 回调实时监控自己在本房间内的连接状态，详情请参考 房间内的连接状态变化通知。

只有当房间状态是连接成功时，才能进行推流（startPublishingStream ）、拉流（startPlayingStream ）等操作。

@Override
public void onRoomStateUpdate(String roomID, ZegoRoomState state, int errorCode, JSONObject extendedData) {
    if (errorCode != 0) {
        // 房间状态出错
    } else {
        if (state.equals(ZegoRoomState.CONNECTED)) {
            //只有当房间状态是连接成功时，才能进行推流（startPublishingStream）、拉流（startPlayingStream）等操作
            //将自己的音视频流推送到 ZEGO 实时音视频云
        } else if (state.equals(ZegoRoomState.CONNECTING)) {
            // 房间连接中
        } else if (state.equals(ZegoRoomState.DISCONNECTED)) {
            // 房间连接断开
        }
    }
}

3.3 预览自己的画面，并推送到 ZEGO 实时音视频云

1. 预览自己的画面

// 设置本地预览视图并启动预览，视图模式采用 SDK 默认的模式，等比缩放填充整个 View
// 如下 previewView 为 UI 界面上的 Surface 对象
engine.startPreview(new ZegoCanvas(previewView));

2. 将自己的音视频流推送到 ZEGO 实时音视频云

在用户登录房间成功之后，调用 startPublishingStream 接口，传入 “streamID”，将自己的音视频流推送到 ZEGO 实时音视频云。

“streamID” 由您本地生成，但是需要保证： 同一个 AppID 下，“streamID” 全局唯一。如果同一个 AppID 下，不同用户各推了一条 “streamID” 相同的流，会导致后推流的用户推流失败。

@Override
public void onRoomStateUpdate(String roomID, ZegoRoomState state, int errorCode, JSONObject extendedData) {
    if (state.equals(ZegoRoomState.CONNECTED)) {
        //只有当房间状态是连接成功时，才能进行推流、拉流等操作。
        //将自己的音视频流推送到 ZEGO 实时音视频云
        engine.startPublishingStream("stream1");
    }
}

3.4 拉取其他用户的音视频流

进行视频通话时，我们需要拉取到其他用户的音视频流。

onRoomStreamUpdate：在同一房间内的其他用户将音视频流推送到 ZEGO 实时音视频云时，我们会在此回调中收到音视频流新增的通知。

我们可以在该回调中，调用 startPlayingStream 接口，传入 “streamID” 拉取播放该用户的音视频流。

拉取播放用户的音视频流后，如果无法正常看到远端画面，可以检查设置的远端拉流渲染视图类型是否正确，详情请参考 常见问题 中的“为什么调用了 startPreview/startPlayingStream 后，无法看到本地预览/远端画面？”

@Override
public void onRoomStreamUpdate(String roomID, ZegoUpdateType updateType, ArrayList<ZegoStream> streamList, JSONObject extendedData) {
    //当 updateType 为 ZegoUpdateType.ADD 时，代表有音视频流新增，此时我们可以调用 startPlayingStream 接口拉取播放该音视频流
    if (updateType.equals(ZegoUpdateType.ADD)) {
        // 开始拉流，设置远端拉流渲染视图，视图模式采用 SDK 默认的模式，等比缩放填充整个 View
        // 如下 playView 为 UI 界面上的 Surface 对象
        String streamID = streamList.get(0).streamID;
        engine.startPlayingStream(streamID, new ZegoCanvas(playView));
    }
}

注意事项

如果您在音视频通话的过程中，遇到相关错误，可查询 错误码。

4 常用功能

4.1 常见通知回调

4.1.1 用户自己在房间内的连接状态变化通知

onRoomStateUpdate：本地调用 loginRoom 接口加入房间时，您可通过监听 onRoomStateUpdate 回调实时监控自己在本房间内的连接状态。

您可以在回调中根据不同状态处理业务逻辑。

@Override
public void onRoomStateUpdate (String roomID, ZegoRoomState state, int errorCode, JSONObject extendedData) {
}

ZegoRoomState 状态含义如下：

详情可参考 房间连接状态说明 。

4.1.2 其他用户进出房间的通知

onRoomUserUpdate ：同一房间内的其他用户进出房间时，您可通过此回调收到通知。

回调中的 ZegoUpdateType 参数为 “ADD” 时，表示有用户进入了房间；为 “DELETE” 时，表示有用户退出了房间。

@Override
public void onRoomUserUpdate (String roomID, ZegoUpdateType updateType, ArrayList< ZegoUser > userList) {
    // 您可以在回调中根据用户的进出/退出情况，处理对应的业务逻辑
    if (updateType.equals(ZegoUpdateType.ADD)) {
        for (ZegoUser user in userList) {
            // 用户进入了房间
        }
    } else if (updateType.equals(ZegoUpdateType.DELETE)) {
        for (ZegoUser user in userList) {
            // 用户退出了房间
        }
    }
}

4.1.3 用户推送音视频流的状态通知

onPublisherStateUpdate：根据实际应用需要，用户推送音视频流之后，当推送视频流的状态发生变更时（例如出现网络中断导致推流异常等情况），您会收到此回调，同时 SDK 会进行自动进行重试。

@Override
public void onPublisherStateUpdate(String streamID, ZegoPublisherState state, int errorCode, JSONObject extendedData) {
    if (errorCode != 0) {
        // 推流状态出错
    } else {
        if (state.equals(ZegoPublisherState.PUBLISHING)) {
            // 正在推流
        } else if (state.equals(ZegoPublisherState.PUBLISH_REQUESTING)) {
            // 正在请求推流
        } else if (state.equals(ZegoPublisherState.NO_PUBLISH)) {
            // 没有推流
        }
    }
}

4.1.4 用户拉取音视频流的状态通知

onPlayerStateUpdate：根据实际应用需要，用户拉取音视频流之后，当拉取的音视频流的状态发生变更时（例如出现网络中断导致拉流异常等情况），您会收到该回调，同时 SDK 会进行自动进行重试。

@Override
public void onPlayerStateUpdate (String streamID, ZegoPlayerState state, int errorCode, JSONObject extendedData) {
    if (errorCode != 0) {
        // 拉流状态出错
    } else {
        if (state.equals(ZegoPublisherState.PLAYING)) {
            // 正在拉流中
        } else if (state.equals(ZegoPublisherState.PLAY_REQUESTING)) {
            // 正在请求拉流中
        } else if (state.equals(ZegoPublisherState.NO_PLAY)) {
            // 未进行拉流
        }
    }
}

4.2 停止音视频通话

4.2.1 停止推送/拉取音视频流

1. 停止推流/预览

调用 stopPublishingStream 接口停止向远端用户发送本端的音视频流。

// 停止推流
engine.stopPublishingStream();

如果启用了本地预览，调用 stopPreview 接口停止预览。

// 停止本地预览
engine.stopPreview();

2. 停止拉流

调用 stopPlayingStream 接口停止拉取远端推送的音视频流。

// 停止拉流
engine.stopPlayingStream("stream1");

4.2.2 退出房间

调用 logoutRoom 接口退出房间。

// 退出房间
engine.logoutRoom("room1");

4.2.3 销毁引擎

如果用户彻底不使用音视频功能时，可调用 destroyEngine 接口销毁引擎，释放麦克风、摄像头、内存、CPU 等资源。

• 如果需要监听回调来确保设备硬件资源释放完成，可在销毁引擎时传入 “callback”。该回调只用于发送通知，开发者不可以在回调内释放与引擎相关的资源。
• 如果不需要监听回调，可传入 “null”。

ZegoExpressEngine.destroyEngine(null);

5 调试视频通话功能

在真机中运行项目，运行成功后，可以看到本端视频画面。

为方便体验，ZEGO 提供了一个 Web 端调试示例 ，在该页面下，输入相同的 AppID、RoomID，输入不同的 UserID、以及对应的 Token，即可加入同一房间与真机设备互通。当成功开始音视频通话时，可以听到远端的音频，看到远端的视频画面。

6 常见问题

1. 调用 logoutRoom 接口退出房间时，能否直接杀掉进程？

调用 logoutRoom 接口后直接杀掉进程，有一定概率会导致 logoutRoom 信令没发出去，ZEGO 服务端只能等心跳超时后才认为该用户退出了房间，为了确保 logoutRoom 信令发送出去，建议再调用 destroyEngine 接口并收到回调后再杀进程。

2. 鸿蒙系统如何打印调试日志？

鸿蒙系统提供了与 Android Log 类似的日志打印工具类 HiLog，具体用法可参考 HiLog 日志打印 。

3. 为什么调用了 startPreview/startPlayingStream 接口后，无法看到本地预览/远端画面？

可能的原因是，传递给 startPreview/startPlayingStream 的 ZegoCanvas 参数中的 view 成员不是 Surface 类型实例，例如：将 view 成员设置为 SurfaceProvider 实例了。SDK 无法直接绘制到 SurfaceProvider 上，只能绘制到与 SurfaceProvider 关联的 Surface 上。可参考下述代码获取与 SurfaceProvider 关联的 Surface。

// 获取 SurfaceProvider 对象
SurfaceProvider surfaceProvider = (SurfaceProvider) findComponentById((ResourceTable.Id_surfaceeView));

// 将 surfaceProvider 置于屏幕最顶层显示
surfaceProvider.pinToZTop(true);

// 注册回调获取 Surface 实例
surfaceProvider.getSurfaceOps().get().addCallback(new SurfaceOps.Callback() {
    @Override
    public void surfaceCreated(SurfaceOps surfaceOps) {
        // surfaceOps.getSurface() 返回的即为 Surface 实例
    }

    @Override
    public void surfaceChanged(SurfaceOps surfaceOps, int i, int i1, int i2) {

    }

    @Override
    public void surfaceDestroyed(SurfaceOps surfaceOps) {

    }
});

相关文档

• 如何设置和获取 SDK 的日志、堆栈信息？
• SDK 是否支持断线重连机制？
• 如何处理房间相关问题？
• 直播场景下，如何监听远端观众角色用户登录/退出房间的事件？
• 为什么我无法打开摄像头？

整个推拉流过程的 API 调用时序如下图：