业务流程
本节汇总了一些常见的业务流程,帮助您更好地理解整个场景的实现流程。
接入准备
步骤一:开通服务
1. 首先,您需要登录 实时音视频 TRTC 控制台 创建应用,完成后在 即时通信 IM 控制台 即会自动创建一个对应的体验版 IM 应用。您可根据需要选择升级 TRTC 及 IM 应用版本,例如旗舰版可解锁更多增值功能服务。
说明:
建议创建两个应用分别用于测试环境和生产环境,首次开通 TRTC 服务可前往 试用中心 免费领取 10000 分钟试用时长包。
TRTC 包月套餐(入门版、基础版、尊享版、旗舰版)可以解锁不同的增值功能服务,详情可见 包月套餐说明。
2. 创建应用完毕之后,您可以在应用管理-应用概览栏目看到该应用的基本信息,其中需要您保管好 SDKAppID、SDKSecretKey 便于后续的使用,同时应避免密钥泄露造成流量盗刷。
步骤二:导入SDK
分别把 TRTC SDK 和 IM SDK 的 Windows 端 zip 压缩包下载到本地并解压,可在项目根目录下创建一个目录 thirdparty 用于存放所有 SDK,把 TRTC SDK 和 IM SDK 移动到 thirdparty 目录下备用。
1. 使用 QTCreator 集成
// *.proINCLUDEPATH += $$PWD/thirdparty/TRTC_SDK/CPlusPlus/Win64/include \\$$PWD/thirdparty/TRTC_SDK/CPlusPlus/Win64/include/TRTC \\$$PWD/thirdparty/IM_SDK/includeLIBS += -L'$$PWD/thirdparty/TRTC_SDK/CPlusPlus/Win64/lib' -lliteav \\-L'$$PWD/thirdparty/IM_SDK/lib/Win64' -lImSDK
2. 使用 Visual Studio 集成
添加头文件目录,配置 - C/C++ - 常规 - 附加头文件目录。
$(SolutionDir)thirdparty/TRTC_SDK/CPlusPlus/Win64/include$(SolutionDir)thirdparty/TRTC_SDK/CPlusPlus/Win64/include/TRTC$(SolutionDir)thirdparty/IM_SDK/include
添加库文件目录,配置 - 链接 - 常规 - 附加库目录。
$(SolutionDir)thirdparty/TRTC_SDK/CPlusPlus/Win64/lib$(SolutionDir)thirdparty/IM_SDK/lib/Win64
引用库文件。
#pragma comment(lib,"liteav.lib")#pragma comment(lib,"ImSDK.lib")
注意:
根据具体自己业务情况,如果需要集成 x86,则使用 Win32 目录下的头文件和库文件。
dll 动态库需要拷贝到 exe 所在目录。
x86 和 x64 的 lib 文件、dll 文件不能混用,需要保持一致。
接入过程
步骤一:生成鉴权凭证
UserSig 是腾讯云设计的一种安全保护签名,目的是为了阻止恶意攻击者盗用您的云服务使用权。腾讯云实时音视频(TRTC)、即时通信(IM)等服务都采用了该套安全保护机制,TRTC 在进房时鉴权,IM 在登录时鉴权。
正式运行阶段:推荐安全等级更高的服务端计算 UserSig方案,防止客户端被逆向破解泄露密钥。
具体实现流程如下:
1. 您的 App 在调用 SDK 的初始化函数之前,首先要向您的服务器请求 UserSig。
2. 您的服务器根据 SDKAppID 和 UserID 计算 UserSig。
3. 服务器将计算好的 UserSig 返回给您的 App。
4. 您的 App 将获得的 UserSig 通过特定 API 传递给 SDK。
5. SDK 将 SDKAppID + UserID + UserSig 提交给腾讯云服务器进行校验。
6. 腾讯云校验 UserSig,确认合法性。
7. 校验通过后,会向 IM SDK 提供即时通信服务、TRTC SDK 提供实时音视频服务。
说明:
调试跑通阶段的本地 UserSig 计算方式不推荐应用到线上环境,容易被逆向破解导致密钥泄露。
我们提供了多个语言版本(Java/GO/PHP/Nodejs/Python/C#/C++)的 UserSig 服务端计算源代码,详见 UserSig 计算源码。
步骤二:初始化与监听
API 时序图
1. IM SDK 初始化与添加事件监听器
IMSDK 是函数式的回调方式,把它封装一层,封装成回调类,方便使用。
// IMWrapperCallback.hclass IMWrapperCallback{public:virtual void OnLogin(int errCode, const char* errMsg) = 0;virtual void OnLogout(int errCode, const char* errMsg) = 0;virtual void OnError(int code, const char* errMsg) = 0;virtual void OnCreateGroup(int errCode, const char* errMsg) = 0;virtual void OnJoinGroup(int errCode, const char* errMsg) = 0;virtual void OnRecvNewMsg(const char* msg) = 0;// ……};// IMWrapper.hclass IMWrapper{public:IMWrapper();bool InitIM(const char* path);bool UnInitIM();void SetCallback(IMWrapperCallback* callback);bool LoginIM(const char* id, const char* sig);bool LogoutIM();bool CreateGroup(const char* group_name, const char* group_type, const char* group_id);bool JoinGroup(const char* group_id);bool SendGroupTextMsg(const char* group_id, const char* text);private:IMWrapperCallback* m_callback;std::string m_userId;};// IMWrapper.cppbool IMWrapper::InitIM(const char* path){Json::Value json_value_init;json_value_init[kTIMSdkConfigLogFilePath] = path;int nRet = TIMInit(SDKAppID_IM, json_value_init.toStyledString().c_str());if(nRet != TIM_SUCC){return false;}TIMAddRecvNewMsgCallback([](const char* json_param, const void* user_data) {if(user_data != nullptr){IMWrapper* wrapper = (IMWrapper*)user_data;if(wrapper->m_callback != nullptr){wrapper->m_callback->OnRecvNewMsg(json_param);}}}, this);return true;}
说明:
如果您的应用生命周期跟 SDK 生命周期一致,退出应用前可以不进行反初始化。若您只在进入特定界面后才初始化 SDK,退出界面后不再使用,可以对 SDK 进行反初始化。
2. TRTC SDK 创建实例与设置事件监听器
//SmallClass.h#include "ITRTCCloud.h"class SmallClass : public ITRTCCloudCallback{public:SmallClass();~SmallClass();virtual void onWarning(TXLiteAVWarning warningCode, const char* warningMsg, void* extraInfo) override;virtual void onError(TXLiteAVError errCode, const char *errMsg, void *extraInfo) override;virtual void onEnterRoom(int result) override;virtual void onExitRoom(int reason) override;//……}SmallClass::SmallClass(){getTRTCShareInstance()->addCallback(this);//创建单例模式,设置事件监听}SmallClass::~SmallClass(){getTRTCShareInstance()->removeCallback(this);//取消事件监听destroyTRTCShareInstance();//销毁实例}
说明:
步骤三:登录与登出
初始化 IM SDK 后,您需要调用 SDK 登录接口验证账号身份,获得账号的功能使用权限。因此在使用其他功能之前,请务必确保登录成功,否则可能导致功能异常或不可用。如您仅需使用 TRTC 音视频服务,可忽略此步骤。
API 时序图
// 登录:userID 可自定义,userSig 即步骤一生成获取bool IMWrapper::LoginIM(const char* id, const char* sig){m_userId = id;int nRet = TIMLogin(id, sig, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {if(user_data != nullptr){IMWrapper* wrapper = (IMWrapper*)user_data;if(wrapper->m_callback != nullptr){wrapper->m_callback->OnLogin(code, desc);}}}, this);if(nRet != TIM_SUCC){return false;}return true;}// 登出bool IMWrapper::LogoutIM(){int nRet = TIMLogout([](int32_t code, const char* desc, const char* json_param, const void* user_data) {if(user_data != nullptr){IMWrapper* wrapper = (IMWrapper*)user_data;if(wrapper->m_callback != nullptr){wrapper->m_callback->OnLogout(code, desc);}}}, this);if(nRet != TIM_SUCC){return false;}return true;}
说明:
如果您的应用生命周期跟 IM SDK 生命周期一致,退出应用前可以不登出。若您只在进入特定界面后才使用 IM SDK,退出界面后不再使用,可以进行登出操作和对 IM SDK 进行反初始化。
步骤四:房间管理
API 时序图
1. 创建房间
主播(房主)开播时需要创建房间,这里的“房间”概念对应 IM 中的“群组”。本例展示客户端创建 IM 群组的方式,实际也可在服务端创建。
bool IMWrapper::CreateGroup(const char* name, const char* type, const char* id){Json::Value param;//群idparam[kTIMCreateGroupParamGroupId] = id;//群类型if (strcmp(type, "Public") == 0) {param[kTIMCreateGroupParamGroupType] = kTIMGroup_Public;}else if(strcmp(type, "Work") == 0) {param[kTIMCreateGroupParamGroupType] = kTIMGroup_Private;}else if(strcmp(type, "Meeting") == 0) {param[kTIMCreateGroupParamGroupType] = kTIMGroup_ChatRoom;}else if(strcmp(type, "AVChatRoom") == 0) {param[kTIMCreateGroupParamGroupType] = kTIMGroup_AVChatRoom;//邀请进群方式param[kTIMCreateGroupParamApproveOption] = kTIMGroupAddOpt_Forbid;//AnyJoin}//群名称param[kTIMCreateGroupParamGroupName] = name;std::string createParams = param.toStyledString();int nRet = TIMGroupCreate(createParams.c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {if(user_data != nullptr){IMWrapper* wrapper = (IMWrapper*)user_data;if(wrapper->m_callback != nullptr){wrapper->m_callback->OnCreateGroup(code, desc);}}}, this);if(nRet != TIM_SUCC){return false;}return true;}
说明:
小班课场景创建 IM 群组需要选用会议群类型:kTIMGroup_ChatRoom。
TRTC 没有单独创建房间的步骤,进入一个不存在的房间,该房间即被自动创建出来。
2. 进入房间
加入 IM 群组
bool IMWrapper::JoinGroup(const char* id){int nRet = TIMGroupJoin(id, "Want Join Group", [](int32_t code, const char* desc, const char* json_param, const void* user_data) {if(user_data != nullptr){IMWrapper* wrapper = (IMWrapper*)user_data;if(wrapper->m_callback != nullptr){wrapper->m_callback->OnJoinGroup(code, desc);}}}, this);if(nRet != TIM_SUCC){return false;}return true;}
进入 TRTC 房间
注意:
TRTC 房间号分为整型 roomId 和字符串类型 strRoomId,两种类型的房间不互通,选择其一即可,建议统一房间号类型。
UserSig 和 SdkAppId 建议在初始化 SDK 时即从业务后台生成并获取,其中 UserSig 只会在进房时校验,进房后过期不影响体验。
TRTC 进房场景可分为实时通话(AudioCall、VideoCall)和互动直播(Live、VoiceChatRoom)两大类。小班课场景选用 VideoCall 模式。
TRTC 用户角色,只有在互动直播模式下才区分主播和观众,其中只有主播才有推流权限,观众如需推流要先切换至主播角色。小班课由于选择的是 VideoCall 模式,没有主播和观众的区分,所以 role 参数不需要填。
进房结果事件回调中,result > 0 代表加入房间所消耗的时间(单位毫秒);result < 0 其数值为进房失败的错误码,参照 错误码表。
// 进入房间void SmallClass::EnterSmallClass(String roomId, String userId, String userName, int roleType, String userSig){TRTCParams param;param.sdkAppId = SDKAppID_TRTC;param.strRoomId = roomID.c_str();param.userId = userID.c_str();param.userSig = userSig.c_str();getTRTCShareInstance()->enterRoom(param, TRTCAppSceneVideoCall);}// 进房结果事件回调void SmallClass::onEnterRoom(int result){if (result > 0) {// 进房成功} else {// 进房失败}}
3. 退出房间
// 退出房间void SmallClass::ExitSmallClass(){getTRTCShareInstance()->exitRoom();}// 退房结果事件回调void SmallClass::onExitRoom(int reason){// 0:主动调用 exitRoom 退出房间;1:被服务器踢出当前房间;2:当前房间整个被解散}
步骤五:音频流管理
1. 老师端推流
// 在进房成功后,开始推音频和视频流void SmallClass::onEnterRoom(int result){if (result > 0) {// 进房成功getTRTCShareInstance()->startLocalAudio(TRTCAudioQualitySpeech);getTRTCShareInstance()->startLocalPreview(hwndView);} else {// 进房失败}}// 上课中途,暂停推流void SmallClass::onButtonClicked(){getTRTCShareInstance()->muteLocalAudio(true);getTRTCShareInstance()->muteLocalVideo(TRTCVideoStreamTypeBig, true);}// 上课结束,停止推流void SmallClass::ExitSmallClass(){getTRTCShareInstance()->stopLocalAudio();getTRTCShareInstance()->stopLocalPreview();getTRTCShareInstance()->exitRoom();}
2. 学生端拉流
当收到远端流事件回调后,则可以开始拉流。
void SmallClass::onUserVideoAvailable(const char* userId, bool available){if(available){if(userId == 老师){getTRTCShareInstance()->startRemoteView(userId, TRTCVideoStreamTypeBig, hwndView);//声音是自动接收的,不需要手工调用}}}
高级功能
课堂状态管理
在小班课的教学过程中,有比较多状态需要进行管理,例如开始上课的时间点、屏幕分享状态、白板锁定状态、成员列表的静音状态等。这些状态需要进行有效的管理和同步,以确保教学过程的顺畅性和一致性。
为了实现课堂状态的管理,业务方可以在自己的后台中,使用 Redis 做一个状态缓存管理模块。这个模块可以用来存储和管理房间所有的状态信息,当客户端上报各种状态事件时,把这些事件缓存起来,以便后续查询和同步。当房间解散或者课堂结束后,把对应的房间缓存清空。
在课堂开始前,进入房间的学生一般不需要同步状态;课堂开始后,进入房间的学生则可以从业务后台获取当前房间的各种状态,这样就可以与先进入房间的学生状态保持一致了。
API 时序图
以开始上课、结束上课状态管理为例。
// 老师端void SmallClass::onButtonClicked(){m_isStartClass = !m_isStartClass;if(m_isStartClass){// 开始上课// 发送群消息,广播状态m_imWrapper.SendGroupMsg(groupId, msg);// 上报状态到自己的业务后台m_roomStatus.SetStartTime(groupId, time);}else{// 上课结束// 发送群消息,广播状态m_imWrapper.SendGroupMsg(groupId, msg);// 上报状态到自己的业务后台m_roomStatus.SetStartTime(groupId, time)}}// 学生端void SmallClass::onStartClass(msg){// 计时器开始}void SmallClass::onEndClass(msg){// 计时器结束}
小班1V6视频窗口管理
在小班课场景中,老师窗口通常会固定在第一个位置,学生自己的窗口则会放在第二个位置,其他学生的窗口则按照他们进入房间的顺序排列。这种排列方式可以让老师更加方便地管理课堂,同时也方便学生进行互动和交流。
为了实现这一功能,每个用户都需要自己维护本地的窗口列表排序。当用户进房时,初始化本地列表管理,从业务后台获取到老师的 userId,自己的 userId,把列表的第一个位置设置为老师的 userId,第二个位置设置为自己的 userId,其他位置暂时留空。
当有用户进房时,从 TRTC 的
onRemoteUserEnterRoom
回调接口中获取到进房的 userId,通过 userId 去查找窗口列表,如果查找不到,则获取一个空闲的窗口。
初始化窗口列表:
void SmallClass::initListUserView(){clearListUserView();for (int i = 0; i < 7; i++) {UserVideoView *item = new UserVideoView;item->index = i;item->view = new VideoView();item->view->setPosition(x+(i*w), y, w, h);if(i == 0){// 老师窗口固定在最左边item->view->setUserInfo("teacherId", "teacherName");}else if(i == 1){// 学生自己的窗口if(m_userRole == Role_Student){item->view->setUserInfo(m_userID, m_userName);}}m_listUserView.push_back(item);}}
当有远端流事件时,可以从
onUserVideoAvailable
回调获取 userId,获取对应的视频窗口。void SmallClass::onUserVideoAvailable(const char* userId, bool available){std::string strUserId = userId;if(available && (!strUserId.empty())){VideoView *videoView = getVideoViewFromId(strUserId);if(videoView){getTRTCShareInstance()->startRemoteView(userId, TRTCVideoStreamTypeBig, videoView->hwnd);}}}
静音管理
上课过程中,老师常常需要静音全体学生,或者取消全体学生禁言,或单独对某个学生禁言。
当需要静音某个学生时,老师通过 IM 发送自定义的群消息,自定义的消息中包含学生 userId 和禁音状态。
收到群消息的学生,取出 userId,如果不是当前用户则忽略;如果是当前用户,则调用
muteLoaclAudio
接口静音本地声音,静音成功后,发送一条自定义群消息,广播静音成功的状态,其他用户收到这条消息后,就可以在 UI 上同步对应的状态了。API 时序图
void SmallClass::onMuteMic(std::string userId, bool mute){if(userId == m_userID)getTRTCShareInstance()->muteLocalAudio(mute);}
网络质量实时回调
使用
onStatistics
获取推流及拉流的质量参数,可以通过丢包率判断当前网络质量,然后在视频窗口用网络信号图标表示当前网络质量。这里判断的值为参考值,具体情况可以结合业务本身对网络情况的容忍度来设定范围。
void SmallClass::onStatistics (const TRTCStatistics& statistics){// localunsigned int localLoss = statistics.upLoss;if(localLoss<3){m_TeacherVideo.setQuality(3);}else if(localLoss>=3 && localLoss<5){m_TeacherVideo.setQuality(2);}else if(localLoss>=5){m_TeacherVideo.setQuality(1);}// remoteint count = statistics.remoteStatisticsArraySize;TRTCRemoteStatistics* remoteStatisticsArray = statistics.remoteStatisticsArray;for(int i = 0; i < count; i++){unsigned int remoteLoss = remoteStatisticsArray->videoPacketLoss;userId = remoteStatisticsArray->userId;if(remoteLoss<3){m_StudentVideo[userId].setQuality(3);}else if(remoteLoss>=3 && remoteLoss<5){m_StudentVideo[userId].setQuality(2);}else if(remoteLoss>=5){m_StudentVideo[userId].setQuality(1);}remoteStatisticsArray++;}}
异常处理
小班课 CPU 消耗高问题
1vN 的小班课,要解码多路视频,如果是自研电子白板,有可能会用到大量 WebView 加载白板教材,当机器性能跟不上,很容易导致 CPU 高。
以下是一组软解、D3D 硬解、OpenGL 硬解在 Windows 端下的测试,可查看 CPU 和 GPU 消耗对比。
渲染方式 | 帧率 | 分辨率 | CPU (取最高值) | GPU(取最高值) |
D3D Texture | 15fps | 640x480 | 0.3% | 1.7% |
D3D Surface | 15fps | 640x480 | 0% | 4.5% |
GDI 双缓冲 | 15fps | 640x480 | 0.7% | 0% |
OpenGL | 15fps | 640x480 | 0.7% | 3.2% |
GPU 利用率越高、CPU 使用率越小,则方案越优。
当使用自定义渲染的方式来显示视频,Windows 建议优先用 D3D 方式解码。