实现视频直播

本文介绍如何通过声网 SDK 快速实现音视频直播。

前提条件

• Microsoft Visual Studio 2017 或以上版本
• Windows 7 或以上版本的设备
• 有效的声网账户（免费注册）

设置开发环境

本节介绍如何创建项目，并将声网 SDK 集成至你的项目中。

创建 Windows 项目

参考以下步骤创建一个 Windows 项目。若已有 Windows 项目，直接查看集成 SDK。

创建 Windows 项目

1. 打开 Microsoft Visual Studio 并点击新建项目。
2. 进入新建项目窗口，选择项目类型为 MFC 应用程序，输入项目名称，选择项目存储路径，并点击确认。
3. 进入MFC 应用程序窗口，选择应用程序类型为基于对话框，并点击完成。

集成 SDK

参考以下步骤将声网视频 SDK 集成到你的项目中。

1. 配置项目文件

• 根据应用场景，从 SDK 下载获取最新 SDK，解压并打开。

• 根据你的开发环境将下载包中的 x86 或 x86_64 文件夹复制到你的项目文件夹下。

2. 配置项目属性

在解决方案资源管理器窗口中，右击项目名称并点击属性进行以下配置，配置完成后点击确定。

• 进入 C/C++ > 常规 > 附加包含目录菜单，点击编辑，并在弹出窗口中输入 $(SolutionDir)include。

• 进入链接器 > 常规 > 附加库目录菜单，点击编辑，并在弹出窗口中输入 $(SolutionDir)。

• 进入链接器 > 输入 > 附加依赖项菜单，点击编辑，并在弹出窗口中输入 agora_rtc_sdk.lib。

实现音视频直播

本节介绍如何实现音视频直播。视频直播的 API 使用时序见下图：

1. 创建用户界面

为直观地体验视频通话，需根据应用场景创建用户界面（UI)。若项目中已有用户界面，直接查看初始化 IRtcEngine。

如果你想实现一个视频直播，推荐在 UI 上添加以下控件：

• 主播视频窗口
• 离开频道按钮

当你使用示例项目中的 UI 设计时，你将会看到如下界面：

2. 初始化 IRtcEngine

在调用其他声网 API 前，需要创建并初始化 IRtcEngine 对象。

你需要在该步骤中填入项目的 App ID。请参考开始使用声网平台在控制台创建声网项目并获取 App ID。

调用 createAgoraRtcEngine 和 initialize 方法，传入获取到的 App ID，即可初始化 IRtcEngine。

你也可以根据需求，在初始化时实现其他功能，如注册用户加入频道和离开频道的回调。

// 创建实例。
m_lpAgoraEngine = createAgoraRtcEngine();
RtcEngineContext ctx;

// 添加注册回调和事件。
ctx.eventHandler = &m_engineEventHandler;

// 输入你的 App ID。
ctx.appId = "YourAppID";

// 初始化 IRtcEngine。
m_lpAgoraEngine->initialize(ctx);

// 继承 IRtcEngineEventHandler 类中的回调与事件。
class CAGEngineEventHandler :
    public IRtcEngineEventHandler
{
public:
    CAGEngineEventHandler();
    ~CAGEngineEventHandler();
    void setMainWnd(HWND wnd);
    HWND GetMsgReceiver() {return m_hMainWnd;};

    // 注册 onJoinChannelSuccess 回调。
    // 本地用户成功加入频道时，会触发该回调。
    virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed);

    // 注册 onLeaveChannel 回调。
    // 本地主播成功离开频道时，会触发该回调。
    virtual void onLeaveChannel(const RtcStats& stat);

    // 注册 onUserJoined 回调。
    // 远端主播成功加入频道时，会触发该回调。
    // 收到该回调后，需立即调用 setupRemoteVideo 设置远端主播的视图。
    virtual void onUserJoined(uid_t uid, int elapsed) override;

    // 注册 onUserOffline 回调。
    // 远端主播离开频道或掉线时，会触发该回调。
    virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason);
private:
    HWND m_hMainWnd;
};

3. 设置频道场景

初始化结束后，调用 setChannelProfile 方法，将频道场景设为直播。

一个 IRtcEngine 只能使用一种频道场景。如果想切换为其他模式，需要先调用 release 方法释放当前的 IRtcEngine 实例，然后调用 createAgoraRtcEngine 和 initialize 方法创建一个新实例，再调用 setChannelProfile 设置新的频道场景。

// 设置频道场景为直播。
m_lpAgoraEngine->setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING);

4. 设置用户角色和用户级别

直播频道中可设置用户角色和用户级别：

• 用户角色 (role) 确定用户在 SDK 层的权限，包含是否可以发流、是否可以收流等。直播频道有两种用户角色：主播和观众。主播既有发流权限，又有收流权限，而观众只有收流权限。默认的角色为观众。
• 用户级别 (level) 需要与用户角色结合使用，确定用户在其角色权限范围内可以操作和享受到的服务级别。例如对于观众，可以选择接收低延时还是超低延时的视频流。不同的级别会影响计费。

你可以在 app 中参考如下步骤设置用户角色：

1. 让终端用户选择自己的角色是主播还是观众。

2. 调用 setClientRole 方法，然后根据终端用户的选择设置 role 和 options 参数。

   • 当 role 设为 CLIENT_ROLE_BROADCASTER（主播）时， options 参数留空。此时主播端延时为 < 400 ms。
   • 当 role 设为 CLIENT_ROLE_AUDIENCE（观众）时，你还需要将 options 中 audienceLatencyLevel 参数设为 AUDIENCE_LATENCY_LEVEL_LOW_LATENCY。此时观众端延时为 1500 ms - 2000 ms。

观众：

ClientRoleOptions role_options;
role_options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_LOW_LATENCY;
m_lpAgoraEngine->setClientRole(CLIENT_ROLE_AUDIENCE, role_options); 

主播：

m_lpAgoraEngine->setClientRole(CLIENT_ROLE_BROADCASTER, NULL); 

5. 设置本地视图

成功初始化 IRtcEngine 对象后，需要在加入频道前设置本地视图，以便主播在直播中看到本地图像。参考以下步骤设置本地视图：

• 调用 enableVideo 方法启用视频模块。
• 调用 setupLocalVideo 方法设置本地视图。

// 启用视频模块。
m_lpAgoraEngine->enableVideo();

// 设置本地视图。
VideoCanvas vc;
vc.uid = 0;
vc.view = hVideoWnd;
vc.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN;
m_lpAgoraEngine->setupLocalVideo(vc);

6. 加入频道

完成设置角色和本地视图后，你就可以调用 joinChannel 方法加入频道。你需要在该方法中传入如下参数：

• channelName: 传入能标识频道的频道 ID。输入频道 ID 相同的用户会进入同一个频道。

• token：传入用于鉴权的 Token，可设为如下一个值：

  • 临时 Token。你可以在控制台里生成一个临时 Token，详见获取临时 Token。加入频道时，请确保填入的频道名和生成临时 Token 时填入的频道名一致。
  • 在你的服务器端生成的 Token。在安全要求高的场景下，我们推荐你使用此种方式生成的 Token，详见从服务端生成 Token。加入频道时，请确保填入的频道名和 uid 与生成 Token 时填入的频道名和 uid 一致。
  • 若项目已启用 App 证书，请使用 Token。
  • 请勿将 token 设为 ""。

• uid: 本地用户的 ID。数据类型为整型，且频道内每个用户的 uid 必须是唯一的。若将 uid 设为 0，则 SDK 会自动分配一个 uid，并在 onJoinChannelSuccess 回调中报告。
  用户成功加入频道后，会默认订阅频道内其他所有用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

更多的参数设置注意事项请参考 joinChannel 接口中的参数描述。

// 加入频道。
BOOL CAgoraObject::JoinChannel(LPCTSTR lpChannelName, UINT nUID, LPCSTR lpDynamicKey)
{
    int nRet = 0;
    LPCSTR lpStreamInfo = "{\"owner\":true,\"width\":640,\"height\":480,\"bitrate\":500}";
#ifdef UNICODE
    CHAR szChannelName[128];
    ::WideCharToMultiByte(CP_ACP, 0, lpChannelName, -1, szChannelName, 128, NULL, NULL);
    nRet = m_lpAgoraEngine->joinChannel(lpDynamicKey, szChannelName, lpStreamInfo, nUID);
#else
    nRet = m_lpAgoraEngine->joinChannel(lpDynamicKey, lpChannelName, lpStreamInfo, nUID);
#endif
    if (nRet == 0)
        m_strChannelName = lpChannelName;
    return nRet == 0 ? TRUE : FALSE;
}

7. 设置远端视图

视频直播中，不论你是主播还是观众，都应该看到频道中的所有主播。在加入频道后，可通过调用 setupRemoteVideo 方法设置远端主播的视图。

远端主播成功加入频道后，SDK 会触发 onUserJoined 回调，该回调中会包含这个主播的 uid 信息。在该回调中调用 setupRemoteVideo 方法，传入获取到的 uid，设置该主播的视图。

// 远端主播成功加入频道时，会触发该回调。
// 收到该回调后，需立即调用 setupRemoteVideo 设置远端主播的视图。
void CAGEngineEventHandler::onUserJoined(uid_t uid, int elapsed)
{
    LPAGE_USER_JOINED lpData = new AGE_USER_JOINED;

    lpData->uid = uid;
    lpData->elapsed = elapsed;

    if(m_hMainWnd != NULL)
        ::PostMessage(m_hMainWnd, WM_MSGID(EID_USER_JOINED), (WPARAM)lpData, 0);
}

VideoCanvas canvas;
canvas.renderMode = RENDER_MODE_FIT;
POSITION pos = m_listWndInfo.GetHeadPosition();
......
AGVIDEO_WNDINFO &agvWndInfo = m_listWndInfo.GetNext(pos);
canvas.uid = agvWndInfo.nUID;
canvas.view = m_wndVideo[nIndex].GetSafeHwnd();
agvWndInfo.nIndex = nIndex;

// 设置远端视图。
CAgoraObject::GetEngine()->setupRemoteVideo(canvas);

8. 离开频道

根据场景需要，如结束通话、关闭 App 或 App 切换至后台时，调用 leaveChannel 离开当前通话频道。

BOOL CAgoraObject::LeaveCahnnel()
{
    m_lpAgoraEngine->stopPreview();

    // 离开频道。
    int nRet = m_lpAgoraEngine->leaveChannel();
    m_nSelfUID = 0;
    return nRet == 0 ? TRUE : FALSE;
}


void CAgoraObject::CloseAgoraObject()
{
    if(m_lpAgoraEngine != NULL)
        // 释放 IRtcEngine 对象。
        m_lpAgoraEngine->release();
    if(m_lpAgoraObject != NULL)
        delete m_lpAgoraObject;
    m_lpAgoraEngine = NULL;
    m_lpAgoraObject = NULL;
}

运行项目

在 Windows 设备中运行该项目。当成功开始视频直播时，主播可以看到自己的画面；观众可以看到主播的画面。

相关链接

• 直播场景下，如何监听远端观众用户加入/离开频道的事件？
• 如何设置日志文件？
• 如何处理视频黑屏问题？