实现视频通话

---

1 功能简介

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

相关概念解释:

• ZEGO Express SDK：由 ZEGO 提供的实时音视频 SDK，能够为开发者提供便捷接入、高清流畅、多平台互通、低延迟、高并发的音视频服务。
• 流：指一组按指定编码格式封装，不断发送中的音视频数据。一个用户可以同时推多条流（例如一条推摄像头数据，一条推屏幕共享数据）也可以同时拉多条流。每条流都由一个流 ID（streamID）标识。
• 推流：把封包好的音视频数据流推送到 ZEGO 实时音视频云的过程。
• 拉流：从 ZEGO 实时音视频云将已有音视频数据流拉取播放的过程。
• 房间：是 ZEGO 提供的音视频空间服务，用于组织用户群，同一房间内的用户可以互相收发实时音视频及消息。
  1. 用户需要先登录某个房间，才能进行推流、拉流操作。
  2. 用户只能收到自己所在房间内的相关消息（用户进出、音视频流变化等）。
  3. 每个房间由一个 ApplD 内唯一的 roomlD 标识。所有使用同一个 roomID 登录房间的用户即属于同房间。

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

2 前提条件

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

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

3 实现流程

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

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

3.1 创建引擎

1. 创建界面

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

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

2. 引入头文件

在项目中引入 ZegoExpressEngine 头文件。

// 引入 ZegoExpressEngine.h 头文件
#include "ZegoExpressSDK.h"

3. 创建引擎

调用 createEngine 接口，将申请到的 AppID 和 AppSign 传入参数 “appID” 和 “appSign”。

根据 App 实际的音视频业务选择一个合适的场景，请参考 场景化音视频配置 文档，把选择好的场景枚举传入参数 "scenario"。

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

ZegoEngineProfile profile;
// AppID 和 AppSign 由 ZEGO 分配给各 App；其中，为了安全考虑，建议将 AppSign 存储在 App 的业务后台，需要使用时从后台获取
profile.appID = appID;
profile.appSign = appSign;
// 指定使用直播场景 (请根据实际情况填写适合你业务的场景)
profile.scenario = ZegoScenario::ZEGO_SCENARIO_BROADCAST;
// 创建引擎实例
auto engine = ZegoExpressSDK::createEngine(profile, nullptr);

3.2 登录房间

传入用户 ID 参数 “userID” 创建 ZegoUser 用户对象后，调用 loginRoom 接口，传入房间 ID 参数 “roomID” 和用户参数 “user”，登录房间。如果房间不存在，调用该接口时会创建并登录此房间。

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

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

// 创建用户对象
ZegoUser user("user1", "user1");
// 只有传入 “isUserStatusNotify” 参数取值为 “true” 的 ZegoRoomConfig，才能收到 onRoomUserUpdate 回调。
ZegoRoomConfig roomConfig;
//如果您使用 appsign 的方式鉴权，token 参数不需填写；如果需要使用更加安全的 鉴权方式： token 鉴权，请参考[如何从 AppSign 鉴权升级为 Token 鉴权](https://doc-zh.zego.im/faq/token_upgrade?product=ExpressVideo&platform=all)
// roomConfig.token = "xxxx";
roomConfig.isUserStatusNotify = true;
// 登录房间
engine->loginRoom(roomID, user, roomConfig, [=](){
    // (可选回调) 登录房间结果，如果仅关注登录结果，关注此回调即可
});

调用登录房间接口之后，您可通过监听 onRoomStateChanged 回调实时监控自己在本房间内的连接状态。

仅当房间状态是登录成功或重连成功时，推流（startPublishingStream）、拉流（startPlayingStream）才能正常收发音视频。

void onRoomStateChanged(const std::string &roomID, ZegoRoomStateChangedReason reason, int errorCode, const std::string &extendedData) {
    if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGINING)
    {
        // 登录中
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGINED)
    {
        // 登录成功
        //只有当房间状态是登录成功或重连成功时，推流（startPublishingStream）、拉流（startPlayingStream）才能正常收发音视频
        //将自己的音视频流推送到 ZEGO 音视频云
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGIN_FAILED)
    {
        // 登录失败
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECTING)
    {
        // 重连中
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECTED)
    {
        // 重连成功
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECT_FAILED)
    {
        // 重连失败
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_KICK_OUT)
    {
        // 被踢出房间
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGOUT)
    {
        // 登出成功
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGOUT_FAILED)
    {
        // 登出失败
    }
}

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

1. （可选）预览自己的画面

设置预览视图并启动本地预览。

如果希望看到本端的画面，可调用 startPreview 接口设置预览视图，并启动本地预览。

// 设置本地预览视图并启动预览，视图模式采用 SDK 默认的模式，等比缩放填充整个 View
ZegoCanvas canvas((void*)view);
engine->startPreview(&canvas);

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

在用户调用 loginRoom 接口后，可以直接调用 startPublishingStream 接口，传入 streamID，将自己的音视频流推送到 ZEGO 音视频云。您可通过监听 onPublisherStateUpdate 回调知晓推流是否成功。

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

此处示例在调用 loginRoom 接口后立即进行推流。在实现具体业务时，您可选择其他时机进行推流，只要保证先调用 loginRoom 即可。

// 用户调用 loginRoom 之后再调用此接口进行推流
// 在同一个 AppID 下，开发者需要保证“streamID” 全局唯一，如果不同用户各推了一条 “streamID” 相同的流，后推流的用户会推流失败。
engine->startPublishingStream("stream1");

3.4 拉取其他用户的音视频

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

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

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

// 房间内其他用户推流/停止推流时，我们会在这里收到相应流增减的通知
void VideoTalk::onRoomStreamUpdate(const std::string &roomID, ZegoUpdateType updateType, const std::vector<ZegoStream> &streamList, const std::string &extendData) {
    //当 updateType 为 ZEGO_UPDATE_TYPE_ADD 时，代表有音视频流新增，此时我们可以调用 startPlayingStream 接口拉取播放该音视频流
    if (updateType == ZEGO_UPDATE_TYPE_ADD) {
        // 开始拉流，设置远端拉流渲染视图，视图模式采用 SDK 默认的模式，等比缩放填充整个 View
        // 如下 playView 为 UI 窗口句柄
        std::string streamID = streamList[0].streamID;
        ZegoCanvas canvas((void*)playView);
        engine->startPlayingStream(streamID , &canvas);
    }
}

4 常用功能

常见通知回调

我在房间内的连接状态变化通知

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

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

virtual void onRoomStateChanged(const std::string& roomID, ZegoRoomStateChangedReason reason, int errorCode, const std::string& extendedData) {

}

ZegoRoomStateChangedReason 状态含义如下：

其他用户进出房间的通知

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

void VideoTalk::onRoomUserUpdate(const std::string &roomID, ZegoUpdateType updateType, const std::vector<ZegoUser> &userList) {
    // 您可以在回调中根据用户的进出/退出情况，处理对应的业务逻辑
    if (updateType == ZEGO_UPDATE_TYPE_ADD) {

    } else if (updateType == ZEGO_UPDATE_TYPE_DELETE) {

    }
}

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

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

void VideoTalk::onPublisherStateUpdate(const std::string &streamID, ZegoPublisherState state, int errorCode, const std::string &extendData) {
    if (errorCode != 0) {
        // 推流状态出错
    } else {
        switch (state) {
            case ZEGO_PUBLISHER_STATE_PUBLISHING:
                // 正在推流
                break;
            case ZEGO_PUBLISHER_STATE_PUBLISH_REQUESTING:
                // 正在请求推流
                break;
            case ZEGO_PUBLISHER_STATE_NO_PUBLISH:
                // 没有推流
                break;
        }
    }
}

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

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

void VideoTalk::onPlayerStateUpdate(const std::string &streamID, ZegoPlayerState state, int errorCode, const std::string &extendData) {
    if (errorCode != 0) {
        //拉流状态出错
    } else {
        switch (state) {
            case ZEGO_PLAYER_STATE_NO_PLAY:
                // 正在拉流中
                break;
            case ZEGO_PLAYER_STATE_PLAY_REQUESTING:
                // 正在请求拉流中
                break;
            case ZEGO_PLAYER_STATE_NO_PLAY:
                // 未进行拉流
                break;
        }
    }
}

停止音视频通话

停止推送和拉取音视频流

1. 停止推流，停止预览

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

// 停止推流
engine->stopPublishingStream();

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

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

2. 停止拉流

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

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

退出房间

调用 logoutRoom 接口退出房间。

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

销毁引擎

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

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

• 如果不需要监听回调，可传入 “nullptr”。

ZegoExpressSDK::destroyEngine(engine, nullptr);
engine = nullptr;

5 调试视频通话功能

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

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

6 视频通话 API 调用时序

7 常见问题

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

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

相关文档

• 常见错误码

• 如何处理房间与用户的相关问题？

• 如何设置和获取 SDK 的日志、堆栈信息？

• SDK 是否支持断线重连？

• 直播场景下，如何监听远端观众角色用户登录/退出房间的事件？

• 如何调节摄像头的焦距（变焦功能）？

• 为什么我无法打开摄像头？

• 如何在较差的网络环境中保证音视频流畅（流量控制功能）？