快速入门

本文为您介绍如何使用 NERTC SDK 快速实现音视频通话功能。

前提条件

在开始运行工程之前，需要准备好如下材料：

• 已开通音视频功能的云信应用及其AppKey
• 开发环境：Microsoft Visual Studio 2017（推荐）
• 操作系统：Microsoft Windows 7+
• 编译器：Microsoft Visual C++ 2017+

快速跑通Sample Code

注意：在运行前，请联系商务经理开通非安全模式。非安全模式建议只在集成开发阶段使用，正式上线前请改回安全模式。

下载完 Sample Code 源码工程后，打开 nrtc_engine.h 文件，在以下位置填入您的AppKey。

#define APP_KEY ""

然后使用 Qt creator 打开 nertc_with_Qt.pro 文件，重新构建后即可运行程序。

集成SDK

• 下载 SDK，解压并打开。
• 将 api 文件夹添加到工程项目的 INCLUDE 目录下。
• 将 lib 文件夹放入工程项目的 LIB 目录下，并确认 nertc_sdk.lib 与项目有连接。
• 将 dll 文件夹下的 .dll 文件复制到工程可执行文件所在的目录下。
• 设置好 Windows 开发环境。

至此， NERtc SDK 已经导入完成。

实现音视频通话

本节主要介绍如何使用 NERTC SDK 实现音视频通话，主要流程如下图所示：

初始化

进入频道之前，调用 createNERtcEngine 方法创建一个 NERtcEngine 实例，并调用 initialize 方法完成初始化。

• 示例代码

// 创建 RTC 引擎对象并返回指针。
nertc::IRtcEngineEx *rtc_engine_ = (IRtcEngineEx *)createNERtcEngine();
// 设置已开通音视频功能的云信应用的AppKey。
rtc_engine_context_.app_key = app_key_.c_str();
// 设置日志目录的完整路径，采用UTF-8 编码。可选。
rtc_engine_context_.log_dir_path = log_dir_path_.c_str();
// 设置日志级别，默认级别为 kNERtcLogLevelInfo。
rtc_engine_context_.log_level = log_level;
// 指定 SDK 输出日志文件的大小上限，单位为 KB。如果设置为 0，则默认为 20 M。
rtc_engine_context_.log_file_max_size_KBytes = log_file_max_size_KBytes;
// 设置SDK向应用发送回调事件的通知。
rtc_engine_context_.event_handler = this;
// 初始化 NERTC SDK 服务。
if (kNERtcNoError != rtc_engine_->initialize(rtc_engine_context_))
{
    //TODO
}

设置本地视图

设置本地视频画布

调用 setupLocalVideoCanvas 方法，使应用程序绑定本地视频流的显示视窗，并设置本地视频视图。

• 示例代码

NERtcVideoCanvas canvas;
canvas.cb = nullptr;
canvas.user_data = nullptr;
canvas.window = window;
// 设置视频缩放模式。
canvas.scaling_mode = mode;
rtc_engine_->setupLocalVideoCanvas(&canvas);

本地视频预览

若要在进入频道前启动本地视频预览，需要调用 startVideoPreview 方法启动本地视频预览。

• 示例代码

int ret = rtc_engine_->startVideoPreview();

启动本地视频预览后，本地视频画面会显示在 setupLocalVideoCanvas 方法设置的画布中。

注意：正式执行加入频道操作前，需要先关闭本地视频预览。

• 示例代码

int ret = rtc_engine_->stopVideoPreview();

启动视频流

在加入频道前或加入后需要调用 enableLocalVideo 启动本地视频流，以便可以将本地视频流发布到云信服务器。

• 示例代码

bool enabled = true;
int ret = rtc_engine_->enableLocalVideo( enabled );

启动视频流后，本地视频画面会显示在 setupLocalVideoCanvas 方法设置的画布中。

请注意与 startVideoPreview 方法区分：

• 在加入频道前，需要调用 startVideoPreview 方法将本地视频显示在画布上。
• 若已加入频道，如果之前已经调用 enableLocalVideo 方法启动本地视频流，则SDK会自动将本地视频显示在画布上。

加入频道

加入频道前，请确保已完成初始化相关事项。若您的业务中涉及呼叫邀请等机制，可以使用信令。

• 参数说明

  • token：频道token。支持传入以下内容：
    • 空字符串。该种方式需要先开通非安全模式。安全性不高，建议在产品正式上线前转为安全模式。
    • 安全认证签名密钥。安全模式下必需。若未传入正确的token将无法进入频道。建议使用安全模式。
  • channel_name：频道名称，传入相同频道名称的用户会进入同一个通话频道。
  • uid：用户的唯一标识Id，频道内每个用户的 uid 必须是唯一的。

• 示例代码

int ret = rtc_engine_->joinChannel(token, channel_name, uid);

当加入频道成功后，会走入初始化时设置的 rtc_engine_context_.event_handler 回调事件通知中的 onJoinChannel ：

/** 加入频道回调

     @param cid  频道 ID。
     @param uid  用户 ID。
     @param result  返回结果。
     @param elapsed 从 joinChannel 开始到发生此事件过去的时间（毫秒）。
     */
    virtual void onJoinChannel(channel_id_t cid, uid_t uid, NERtcErrorCode result, uint64_t elapsed) {
        (void)cid;
        (void)uid;
        (void)result;
        (void)elapsed;
    }

设置远端视图

视频通话过程中，除了要显示本地的视频画面，通常也要显示参与通话的其他用户的远端视频画面。

监听远端用户进出频道

当有远端用户进出频道时，会走入初始化时设置的 rtc_engine_context_.event_handler 回调事件通知中的：

• 其他用户加入频道的回调

通信模式下，该回调提示有远端用户加入了频道，并返回新加入用户的 uid；如果本端加入频道之前，频道内已经有其他用户了，在本端加入成功时，也会收到这些已有用户加入频道的回调。

    /** 远端用户加入当前频道回调。

     @param uid 新加入频道的远端用户ID。
     @param user_name 新加入频道的远端用户名。
     */
    virtual void onUserJoined(uid_t uid, const char * user_name) {
        (void)uid;
        (void)user_name;
    }

• 其他用户离开频道的回调

    /** 远端用户离开当前频道回调。

     提示有远端用户离开了频道（或掉线）。

     @param uid 远端用户ID。
     @param reason 远端用户离开原因。
     */
    virtual void onUserLeft(uid_t uid, NERtcSessionLeaveReason reason) {
        (void)uid;
        (void)reason;
    }

设置远端视频画布

监听到远端用户加入频道后，可以调用 setupRemoteVideoCanvas 方法设置远端视频画布，用来显示远端用户的视频画面。

NERtcVideoCanvas canvas;
canvas.cb = nullptr;
canvas.user_data = nullptr;
canvas.window = window;
// 设置视频缩放模式。
canvas.scaling_mode = mode;
rtc_engine_->setupRemoteVideoCanvas(uid, &canvas);

监听远端视频流发布

当频道中的其他用户有视频流发出/关闭时，分别会走入初始化时设置的 rtc_engine_context_.event_handler 回调事件通知中的以下回调：

• 远端用户开启视频回调

/** 远端用户开启视频回调。

     @param uid 远端用户ID。
     @param max_profile 最大分辨率。
     */
    virtual void onUserVideoStart(uid_t uid, NERtcVideoProfileType max_profile) {
        (void)uid;
        (void)max_profile;
    }

• 远端用户停用视频回调

    /** 远端用户停用视频回调。

     @param uid 远端用户ID。
     */
    virtual void onUserVideoStop(uid_t uid) {
        (void)uid;
    }

订阅远端视频流

在设置完远端视频画布后，且监听到远端用户有视频发布时，可以订阅远端用户的视频流。

• API描述

/** 订阅/取消订阅 指定远端用户的视频流。对方打开视频后需要主动订阅。

    @param[in] uid 指定用户的用户 ID。
    @param[in] type 流类型。 #NERtcRemoteVideoStreamType
    @param[in] subscribe
    - true: 订阅指定远端用户的视频流；
    - false: 取消订阅指定远端用户的视频流。

    @return
    - 0: 方法调用成功；
    - 其他: 方法调用失败。
    */
    virtual int subscribeRemoteVideoStream(uid_t uid, NERtcRemoteVideoStreamType type, bool subscribe) = 0;

• 示例代码

// 订阅指定用户的 kNERtcRemoteVideoStreamTypeHigh 类型的视频流
void NRTCEngine::subscribeRemoteUserVideoStream(nertc::uid_t uid) {
    int ret_temp = rtc_engine_->subscribeRemoteVideoStream(uid, kNERtcRemoteVideoStreamTypeHigh, true);
    if (ret_temp) {
        qDebug("[ERROR] can not subscribe remote video stream! ERROR CODE: %d", ret_temp);
    }
}

订阅成功后，即可显示远端的视频画面。

音频流

在 NERtc SDK 中，本地音频的采集发布和远端音频订阅播放是默认启动的，正常情况下无需开发者主动干预。

离开频道

当通话结束，需要离开频道，可以调用以下接口：

• 示例代码

int ret = rtc_engine_->leaveChannel();

不论当前是否还在通话中，调用该方法会把相关的所有资源释放掉。真正退出频道后，SDK 会走入初始化时设置的 rtc_engine_context_.event_handler 回调事件通知中的 onLeaveChannel ：

/** 离开频道回调。

     App 调用  IRtcEngine::leaveChannel "leaveChannel" 方法时，SDK提示 App 离开频道是否成功。

     @param result 返回结果。
     */
    virtual void onLeaveChannel(NERtcErrorCode result) {
        (void)result;
    }

销毁音视频实例

释放当前的音视频实例，建议在应用确定不再需要使用音视频时，通过该接口释放对象资源。

• 示例代码

void NRTCEngine::Uninit() {
    if (rtc_engine_) {
        ...

        //同步销毁 IRtcEngine 对象
        rtc_engine_->release(true);
        // 销毁 RTC 引擎对象
        destroyNERtcEngine((void*&)rtc_engine_);
        rtc_engine_ = nullptr;
    }
}