腾讯云 TRTC 主功能接口
Exported C function | |
Export the following C-style interface to facilitate “LoadLibrary()” You can use the following methods to create and destroy TRTCCloud instance: ITRTCCloud *trtcCloud = getTRTCShareInstance(); if(trtcCloud) { std::string version(trtcCloud->getSDKVersion()); } // // destroyTRTCShareInstance(); trtcCloud = nullptr; | |
TRTC_API liteav::ITRTCCloud * | getTRTCShareInstance (void *context) |
TRTC_API liteav::ITRTCCloud * | getTRTCShareInstance () |
TRTC_API void | destroyTRTCShareInstance () |
结构体说明
◆ liteav::ITRTCCloud
class liteav::ITRTCCloud |
创建实例和事件回调 | |
static TRTC_API liteav::ITRTCCloud * | getTRTCShareInstance (void *context) |
static TRTC_API liteav::ITRTCCloud * | getTRTCShareInstance () |
static TRTC_API void | destroyTRTCShareInstance () |
virtual void | addCallback (ITRTCCloudCallback *callback)=0 |
virtual void | removeCallback (ITRTCCloudCallback *callback)=0 |
房间相关接口函数 | |
virtual void | enterRoom (const TRTCParams ¶m, TRTCAppScene scene)=0 |
virtual void | exitRoom ()=0 |
virtual void | switchRole (TRTCRoleType role)=0 |
virtual void | switchRoom (const TRTCSwitchRoomConfig &config)=0 |
virtual void | connectOtherRoom (const char *param)=0 |
virtual void | disconnectOtherRoom ()=0 |
virtual void | setDefaultStreamRecvMode (bool autoRecvAudio, bool autoRecvVideo)=0 |
virtual ITRTCCloud * | createSubCloud ()=0 |
virtual void | destroySubCloud (ITRTCCloud *subCloud)=0 |
virtual void | startPublishing (const char *streamId, TRTCVideoStreamType streamType)=0 |
virtual void | stopPublishing ()=0 |
virtual void | startPublishCDNStream (const TRTCPublishCDNParam ¶m)=0 |
virtual void | stopPublishCDNStream ()=0 |
virtual void | setMixTranscodingConfig (TRTCTranscodingConfig *config)=0 |
视频相关接口函数 | |
virtual void | startLocalPreview (bool frontCamera, TXView view)=0 |
virtual void | startLocalPreview (TXView view)=0 |
virtual void | updateLocalView (TXView view)=0 |
virtual void | stopLocalPreview ()=0 |
virtual void | muteLocalVideo (TRTCVideoStreamType streamType, bool mute)=0 |
virtual void | startRemoteView (const char *userId, TRTCVideoStreamType streamType, TXView view)=0 |
virtual void | updateRemoteView (const char *userId, TRTCVideoStreamType streamType, TXView view)=0 |
virtual void | stopRemoteView (const char *userId, TRTCVideoStreamType streamType)=0 |
virtual void | stopAllRemoteView ()=0 |
virtual void | muteRemoteVideoStream (const char *userId, TRTCVideoStreamType streamType, bool mute)=0 |
virtual void | muteAllRemoteVideoStreams (bool mute)=0 |
virtual void | setVideoEncoderParam (const TRTCVideoEncParam ¶m)=0 |
virtual void | setNetworkQosParam (const TRTCNetworkQosParam ¶m)=0 |
virtual void | setLocalRenderParams (const TRTCRenderParams ¶ms)=0 |
virtual void | setRemoteRenderParams (const char *userId, TRTCVideoStreamType streamType, const TRTCRenderParams ¶ms)=0 |
virtual void | setVideoEncoderRotation (TRTCVideoRotation rotation)=0 |
virtual void | setVideoEncoderMirror (bool mirror)=0 |
virtual void | enableSmallVideoStream (bool enable, const TRTCVideoEncParam &smallVideoEncParam)=0 |
virtual void | setRemoteVideoStreamType (const char *userId, TRTCVideoStreamType streamType)=0 |
virtual void | snapshotVideo (const char *userId, TRTCVideoStreamType streamType, TRTCSnapshotSourceType sourceType)=0 |
音频相关接口函数 | |
virtual void | startLocalAudio (TRTCAudioQuality quality)=0 |
virtual void | stopLocalAudio ()=0 |
virtual void | muteLocalAudio (bool mute)=0 |
virtual void | muteRemoteAudio (const char *userId, bool mute)=0 |
virtual void | muteAllRemoteAudio (bool mute)=0 |
virtual void | setRemoteAudioVolume (const char *userId, int volume)=0 |
virtual void | setAudioCaptureVolume (int volume)=0 |
virtual int | getAudioCaptureVolume ()=0 |
virtual void | setAudioPlayoutVolume (int volume)=0 |
virtual int | getAudioPlayoutVolume ()=0 |
virtual void | enableAudioVolumeEvaluation (uint32_t interval)=0 |
virtual int | startAudioRecording (const TRTCAudioRecordingParams ¶m)=0 |
virtual void | stopAudioRecording ()=0 |
virtual void | startLocalRecording (const TRTCLocalRecordingParams ¶ms)=0 |
virtual void | stopLocalRecording ()=0 |
virtual void | setRemoteAudioParallelParams (const TRTCAudioParallelParams ¶ms)=0 |
设备管理相关接口 | |
virtual ITXDeviceManager * | getDeviceManager ()=0 |
美颜特效和图像水印 | |
virtual void | setBeautyStyle (TRTCBeautyStyle style, uint32_t beautyLevel, uint32_t whitenessLevel, uint32_t ruddinessLevel)=0 |
virtual void | setWaterMark (TRTCVideoStreamType streamType, const char *srcData, TRTCWaterMarkSrcType srcType, uint32_t nWidth, uint32_t nHeight, float xOffset, float yOffset, float fWidthRatio)=0 |
背景音乐和声音特效 | |
virtual ITXAudioEffectManager * | getAudioEffectManager ()=0 |
virtual void | startSystemAudioLoopback (const char *deviceName=nullptr)=0 |
virtual void | stopSystemAudioLoopback ()=0 |
virtual void | setSystemAudioLoopbackVolume (uint32_t volume)=0 |
屏幕分享相关接口 | |
virtual void | startScreenCapture (TXView view, TRTCVideoStreamType streamType, TRTCVideoEncParam *encParam)=0 |
virtual void | stopScreenCapture ()=0 |
virtual void | pauseScreenCapture ()=0 |
virtual void | resumeScreenCapture ()=0 |
virtual ITRTCScreenCaptureSourceList * | getScreenCaptureSources (const SIZE &thumbnailSize, const SIZE &iconSize)=0 |
virtual void | selectScreenCaptureTarget (const TRTCScreenCaptureSourceInfo &source, const RECT &captureRect, const TRTCScreenCaptureProperty &property)=0 |
virtual void | setSubStreamEncoderParam (const TRTCVideoEncParam ¶m)=0 |
virtual void | setSubStreamMixVolume (uint32_t volume)=0 |
virtual void | addExcludedShareWindow (TXView windowID)=0 |
virtual void | removeExcludedShareWindow (TXView windowID)=0 |
virtual void | removeAllExcludedShareWindow ()=0 |
virtual void | addIncludedShareWindow (TXView windowID)=0 |
virtual void | removeIncludedShareWindow (TXView windowID)=0 |
virtual void | removeAllIncludedShareWindow ()=0 |
自定义采集和自定义渲染 | |
virtual void | enableCustomVideoCapture (TRTCVideoStreamType streamType, bool enable)=0 |
virtual void | sendCustomVideoData (TRTCVideoStreamType streamType, TRTCVideoFrame *frame)=0 |
virtual void | enableCustomAudioCapture (bool enable)=0 |
virtual void | sendCustomAudioData (TRTCAudioFrame *frame)=0 |
virtual void | enableMixExternalAudioFrame (bool enablePublish, bool enablePlayout)=0 |
virtual int | mixExternalAudioFrame (TRTCAudioFrame *frame)=0 |
virtual void | setMixExternalAudioVolume (int publishVolume, int playoutVolume)=0 |
virtual uint64_t | generateCustomPTS ()=0 |
virtual int | setLocalVideoProcessCallback (TRTCVideoPixelFormat pixelFormat, TRTCVideoBufferType bufferType, ITRTCVideoFrameCallback *callback)=0 |
virtual int | setLocalVideoRenderCallback (TRTCVideoPixelFormat pixelFormat, TRTCVideoBufferType bufferType, ITRTCVideoRenderCallback *callback)=0 |
virtual int | setRemoteVideoRenderCallback (const char *userId, TRTCVideoPixelFormat pixelFormat, TRTCVideoBufferType bufferType, ITRTCVideoRenderCallback *callback)=0 |
virtual int | setAudioFrameCallback (ITRTCAudioFrameCallback *callback)=0 |
virtual int | setCapturedRawAudioFrameCallbackFormat (TRTCAudioFrameCallbackFormat *format)=0 |
virtual int | setLocalProcessedAudioFrameCallbackFormat (TRTCAudioFrameCallbackFormat *format)=0 |
virtual int | setMixedPlayAudioFrameCallbackFormat (TRTCAudioFrameCallbackFormat *format)=0 |
virtual void | enableCustomAudioRendering (bool enable)=0 |
virtual void | getCustomAudioRenderingFrame (TRTCAudioFrame *audioFrame)=0 |
自定义消息发送接口 | |
virtual bool | sendCustomCmdMsg (uint32_t cmdId, const uint8_t *data, uint32_t dataSize, bool reliable, bool ordered)=0 |
virtual bool | sendSEIMsg (const uint8_t *data, uint32_t dataSize, int32_t repeatCount)=0 |
网络测试接口 | |
virtual int | startSpeedTest (const TRTCSpeedTestParams ¶ms)=0 |
virtual void | stopSpeedTest ()=0 |
调试相关接口 | |
virtual const char * | getSDKVersion ()=0 |
virtual void | setLogLevel (TRTCLogLevel level)=0 |
virtual void | setConsoleEnabled (bool enabled)=0 |
virtual void | setLogCompressEnabled (bool enabled)=0 |
virtual void | setLogDirPath (const char *path)=0 |
virtual void | setLogCallback (ITRTCLogCallback *callback)=0 |
virtual void | showDebugView (int showType)=0 |
virtual const char * | callExperimentalAPI (const char *jsonStr)=0 |
virtual void | callExperimentalAPI (const char *jsonStr)=0 |
弃用接口(建议使用对应的新接口) | |
virtual void | enableCustomVideoCapture (bool enable)=0 |
virtual void | sendCustomVideoData (TRTCVideoFrame *frame)=0 |
virtual void | muteLocalVideo (bool mute)=0 |
virtual void | muteRemoteVideoStream (const char *userId, bool mute)=0 |
virtual void | startSpeedTest (uint32_t sdkAppId, const char *userId, const char *userSig)=0 |
virtual void | startSpeedTest (uint32_t sdkAppId, const char *userId, const char *userSig)=0 |
virtual void | enableCustomVideoCapture (bool enable) |
virtual void | muteLocalVideo (bool mute) |
virtual void | muteRemoteVideoStream (const char *userId, bool mute) |
virtual void | selectScreenCaptureTarget (const TRTCScreenCaptureSourceInfo &source, const RECT &captureRect, bool captureMouse=true, bool highlightWindow=true) |
virtual void | sendCustomVideoData (TRTCVideoFrame *frame) |
virtual void | startLocalAudio () |
virtual void | startRemoteView (const char *userId, TXView rendView) |
virtual void | startScreenCapture (TXView rendView) |
virtual void | startSpeedTest (uint32_t sdkAppId, const char *userId, const char *userSig) |
virtual void | stopRemoteView (const char *userId) |
弃用接口函数 | |
virtual void | startLocalAudio () |
virtual void | startRemoteView (const char *userId, TXView rendView) |
virtual void | stopRemoteView (const char *userId) |
virtual void | setLocalViewFillMode (TRTCVideoFillMode mode) |
virtual void | setLocalViewRotation (TRTCVideoRotation rotation) |
virtual void | setLocalViewMirror (bool mirror) |
virtual void | setRemoteViewFillMode (const char *userId, TRTCVideoFillMode mode) |
virtual void | setRemoteViewRotation (const char *userId, TRTCVideoRotation rotation) |
virtual void | startRemoteSubStreamView (const char *userId, TXView rendView) |
virtual void | stopRemoteSubStreamView (const char *userId) |
virtual void | setRemoteSubStreamViewFillMode (const char *userId, TRTCVideoFillMode mode) |
virtual void | setRemoteSubStreamViewRotation (const char *userId, TRTCVideoRotation rotation) |
virtual void | setAudioQuality (TRTCAudioQuality quality) |
virtual void | setPriorRemoteVideoStreamType (TRTCVideoStreamType type) |
virtual ITRTCDeviceCollection * | getCameraDevicesList () |
virtual void | setCurrentCameraDevice (const char *deviceId) |
virtual ITRTCDeviceInfo * | getCurrentCameraDevice () |
virtual ITRTCDeviceCollection * | getMicDevicesList () |
virtual ITRTCDeviceInfo * | getCurrentMicDevice () |
virtual void | setCurrentMicDevice (const char *micId) |
virtual uint32_t | getCurrentMicDeviceVolume () |
virtual void | setCurrentMicDeviceVolume (uint32_t volume) |
virtual void | setCurrentMicDeviceMute (bool mute) |
virtual bool | getCurrentMicDeviceMute () |
virtual ITRTCDeviceCollection * | getSpeakerDevicesList () |
virtual ITRTCDeviceInfo * | getCurrentSpeakerDevice () |
virtual void | setCurrentSpeakerDevice (const char *speakerId) |
virtual uint32_t | getCurrentSpeakerVolume () |
virtual void | setCurrentSpeakerVolume (uint32_t volume) |
virtual void | setCurrentSpeakerDeviceMute (bool mute) |
virtual bool | getCurrentSpeakerDeviceMute () |
virtual void | startCameraDeviceTest (TXView rendView) |
virtual void | startCameraDeviceTest (ITRTCVideoRenderCallback *callback) |
virtual void | stopCameraDeviceTest () |
virtual void | startMicDeviceTest (uint32_t interval) |
virtual void | stopMicDeviceTest () |
virtual void | startSpeakerDeviceTest (const char *testAudioFilePath) |
virtual void | stopSpeakerDeviceTest () |
virtual void | setMicVolumeOnMixing (uint32_t volume) |
virtual void | startScreenCapture (TXView rendView) |
virtual void | playBGM (const char *path) |
virtual void | stopBGM () |
virtual void | pauseBGM () |
virtual void | resumeBGM () |
virtual uint32_t | getBGMDuration (const char *path) |
virtual void | setBGMPosition (uint32_t pos) |
virtual void | setBGMVolume (uint32_t volume) |
virtual void | setBGMPlayoutVolume (uint32_t volume) |
virtual void | setBGMPublishVolume (uint32_t volume) |
virtual void | playAudioEffect (TRTCAudioEffectParam *effect) |
virtual void | setAudioEffectVolume (int effectId, int volume) |
virtual void | stopAudioEffect (int effectId) |
virtual void | stopAllAudioEffects () |
virtual void | setAllAudioEffectsVolume (int volume) |
virtual void | pauseAudioEffect (int effectId) |
virtual void | resumeAudioEffect (int effectId) |
virtual void | selectScreenCaptureTarget (const TRTCScreenCaptureSourceInfo &source, const RECT &captureRect, bool captureMouse=true, bool highlightWindow=true) |
构造及析构函数说明
◆ ~ITRTCCloud()
| inlineprotectedvirtual |
成员函数说明
◆ addCallback()
| pure virtual |
设置 TRTC 事件回调
您可以通过 TRTCCloudDelegate 获得来自 SDK 的各类事件通知(比如:错误码,警告码,音视频状态参数等)。
◆ addExcludedShareWindow()
| pure virtual |
将指定窗口加入屏幕分享的排除列表中(该接口仅支持桌面系统)
加入排除列表中的窗口不会被分享出去,常见的用法是将某个应用的窗口加入到排除列表中以避免隐私问题。 支持启动屏幕分享前设置过滤窗口,也支持屏幕分享过程中动态添加过滤窗口。
参数
windowID | 不希望分享出去的窗口 |
注意
- 该接口只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeScreen 时生效,即只有在分享整个屏幕内容时,排除指定窗口的功能才生效。
- 使用该接口添加到排除列表中的窗口会在退出房间后被 SDK 自动清除。
- Mac 平台下请传入窗口 ID(即 CGWindowID),您可以通过 TRTCScreenCaptureSourceInfo 中的 sourceId 成员获得。
◆ addIncludedShareWindow()
| pure virtual |
将指定窗口加入屏幕分享的包含列表中(该接口仅支持桌面系统)
该接口只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeWindow 时生效。即只有在分享窗口内容时,额外包含指定窗口的功能才生效。 您在 startScreenCapture 之前和之后调用均可。
参数
windowID | 希望被分享出去的窗口(Windows 平台下为窗口句柄: HWND) |
注意
通过该方法添加到包含列表中的窗口,会在退出房间后被 SDK 自动清除。
◆ callExperimentalAPI() [1/2]
| pure virtual |
调用实验性接口
◆ callExperimentalAPI() [2/2]
| pure virtual |
◆ connectOtherRoom()
| pure virtual |
请求跨房通话
默认情况下,只有同一个房间中的用户之间可以进行音视频通话,不同的房间之间的音视频流是相互隔离的。 但您可以通过调用该接口,将另一个房间中某个主播音视频流发布到自己所在的房间中,与此同时,该接口也会将自己的音视频流发布到目标主播的房间中。 也就是说,您可以使用该接口让身处两个不同房间中的主播进行跨房间的音视频流分享,从而让每个房间中的观众都能观看到这两个主播的音视频。该功能可以用来实现主播之间的 PK 功能。 跨房通话的请求结果会通过 TRTCCloudDelegate 中的 onConnectOtherRoom() 回调通知给您。 例如:当房间“101”中的主播 A 通过 connectOtherRoom() 跟房间“102”中的主播 B 建立跨房通话后,
- 房间“101”中的用户都会收到主播 B 的 onRemoteUserEnterRoom(B) 和 onUserVideoAvailable(B,true) 这两个事件回调,即房间“101”中的用户都可以订阅主播 B 的音视频。
- 房间“102”中的用户都会收到主播 A 的 onRemoteUserEnterRoom(A) 和 onUserVideoAvailable(A,true) 这两个事件回调,即房间“102”中的用户都可以订阅主播 A 的音视频。
房间 101 房间 102 ------------- ------------ 跨房通话前:| 主播 A | | 主播 B | | 观众 U V W | | 观众 X Y Z | ------------- ------------
房间 101 房间 102 ------------- ------------ 跨房通话后:| 主播 A B | | 主播 B A | | 观众 U V W | | 观众 X Y Z | ------------- ------------
跨房通话的参数考虑到后续扩展字段的兼容性问题,暂时采用了 JSON 格式的参数:
【情况一:数字房间号】 如果房间“101”中的主播 A 要跟房间“102”中的主播 B 连麦,那么主播 A 调用该接口时需要传入:{"roomId": 102, "userId": "userB"} 示例代码如下:
Json::Value jsonObj; jsonObj["roomId"] = 102; jsonObj["userId"] = "userB"; Json::FastWriter writer; std::string params = writer.write(jsonObj); trtc.ConnectOtherRoom(params.c_str());
【情况二:字符串房间号】 如果您使用的是字符串房间号,务必请将 json 中的 “roomId” 替换成 “strRoomId”: {"strRoomId": "102", "userId": "userB"} 示例代码如下:
Json::Value jsonObj; jsonObj["strRoomId"] = "102"; jsonObj["userId"] = "userB"; Json::FastWriter writer; std::string params = writer.write(jsonObj); trtc.ConnectOtherRoom(params.c_str());
参数
param | 需要你传入 JSON 格式的字符串参数,roomId 代表数字格式的房间号,strRoomId 代表字符串格式的房间号,userId 代表目标主播的用户ID。 |
◆ createSubCloud()
| pure virtual |
创建子房间示例(用于多房间并发观看)
TRTCCloud 一开始被设计成单例模式,限制了多房间并发观看的能力。 通过调用该接口,您可以创建出多个 TRTCCloud 实例,以便同时进入多个不同的房间观看音视频流。 但需要注意的是,由于摄像头和麦克风还是只有一份,因此您只能同时在一个 TRTCCloud 实例中以“主播”的身份存在,也就是您只能同时在一个 TRTCCloud 实例中发布自己的音视频流。 该功能主要用于在线教育场景中一种被称为“超级小班课”的业务场景中,用于解决“每个 TRTC 的房间中最多只能有 50 人同时发布自己音视频流”的限制。 示例代码如下:
ITRTCCloud *mainCloud = getTRTCShareInstance(); mainCloud->enterRoom(params1, TRTCAppSceneLIVE); //... //Switch the role from "anchor" to "audience" in your own room mainCloud->switchRole(TRTCRoleAudience); mainCloud->muteLocalVideo(true); mainCloud->muteLocalAudio(true); //... //Use subcloud to enter another room and switch the role from "audience" to "anchor" ITRTCCloud *subCloud = mainCloud->createSubCloud(); subCloud->enterRoom(params2, TRTCAppSceneLIVE); subCloud->switchRole(TRTCRoleAnchor); subCloud->muteLocalVideo(false); subCloud->muteLocalAudio(false); //... //Exit from new room and release it. subCloud->exitRoom(); mainCloud->destroySubCloud(subCloud);
注意
- 同一个用户,可以使用同一个 userId 进入多个不同 roomId 的房间。
- 两台不同的终端设备不可以同时使用同一个 userId 进入同一个 roomId 的房间。
- 同一个用户,同时只能在一个 TRTCCloud 实例中推流,在不同房间同时推流会引发云端的状态混乱,导致各种 bug。
- 通过 createSubCloud 接口创建出来的 TRTCCloud 实例有一个能力限制:不能调用子实例中与本地音视频相关的接口(除 switchRole、muteLocalVideo 和 muteLocalAudio 之外), 设置美颜等接口请使用原 TRTCCloud 实例对象。
返回
子 TRTCCloud 实例
◆ destroySubCloud()
| pure virtual |
销毁子房间示例
参数
subCloud |
◆ destroyTRTCShareInstance()
| static |
销毁 TRTCCloud 实例(单例模式)
◆ disconnectOtherRoom()
| pure virtual |
退出跨房通话
退出结果会通过 TRTCCloudDelegate 中的 onDisconnectOtherRoom() 回调通知给您。
◆ enableAudioVolumeEvaluation()
| pure virtual |
启用音量大小提示
开启此功能后,SDK 会在 TRTCCloudDelegate 中的 onUserVoiceVolume 回调中反馈远端音频的音量大小。
注意
如需打开此功能,请在 startLocalAudio 之前调用才可以生效。
参数
interval | 设置 onUserVoiceVolume 回调的触发间隔,单位为ms,最小间隔为100ms,如果小于等于 0 则会关闭回调,建议设置为300ms; |
◆ enableCustomAudioCapture()
| pure virtual |
启用音频自定义采集模式
开启该模式后,SDK 不在运行原有的音频采集流程,即不再继续从麦克风采集音频数据,而是只保留音频编码和发送能力。 您需要通过 sendCustomAudioData 不断地向 SDK 塞入自己采集的音频数据。
参数
enable | 是否启用,默认值:false。 |
注意
由于回声抵消(AEC)需要严格的控制声音采集和播放的时间,所以开启自定义音频采集后,AEC 能力可能会失效。
◆ enableCustomAudioRendering()
| pure virtual |
开启音频自定义播放
如果您需要外接一些特定的音频设备,或者希望自己掌控音频的播放逻辑,您可以通过该接口启用音频自定义播放。 启用音频自定义播放后,SDK 将不再调用系统的音频接口播放数据,您需要通过 getCustomAudioRenderingFrame 获取 SDK 要播放的音频帧并自行播放。
参数
enable | 是否启用音频自定义播放,默认为关闭状态。 |
注意
需要您在进入房间前设置才能生效,暂不支持进入房间后再设置。
◆ enableCustomVideoCapture() [1/3]
| inline |
启用视频自定义采集模式
开启该模式后,SDK 不再运行原有的视频采集流程,只保留编码和发送能力。 您需要用 sendCustomVideoData() 不断地向 SDK 塞入自己采集的视频画面。
参数
enable | 是否启用,默认值:false |
◆ enableCustomVideoCapture() [2/3]
| pure virtual |
启用视频自定义采集模式
v8.5 版本开始不推荐使用,建议使用 enableCustomVideoCapture(streamType,enable) 接口替代之。
重载 IDeprecatedTRTCCloud .
◆ enableCustomVideoCapture() [3/3]
| pure virtual |
启用/关闭视频自定义采集模式
开启该模式后,SDK 不在运行原有的视频采集流程,即不再继续从摄像头采集数据和美颜,而是只保留视频编码和发送能力。 您需要通过 sendCustomVideoData 不断地向 SDK 塞入自己采集的视频画面。
参数
streamType | 用于指定视频流类型,TRTCVideoStreamTypeBig:高清大画面;TRTCVideoStreamTypeSub:辅路画面。 |
enable | 是否启用,默认值:false。 |
◆ enableMixExternalAudioFrame()
| pure virtual |
启用/关闭自定义音轨
开启后,您可以通过本接口向 SDK 混入一条自定义的音轨。通过两个布尔型参数,您可以控制该音轨是否要在远端和本地播放。
参数
enablePublish | 控制混入的音轨是否要在远端播放,默认值:false。 |
enablePlayout | 控制混入的音轨是否要在本地播放,默认值:false。 |
注意
如果您指定参数 enablePublish 和 enablePlayout 均为 false,代表完全关闭您的自定义音轨。
◆ enableSmallVideoStream()
| pure virtual |
开启大小画面双路编码模式
开启双路编码模式后,当前用户的编码器会同时输出【高清大画面】和【低清小画面】两路视频流(但只有一路音频流)。 如此以来,房间中的其他用户就可以根据自身的网络情况或屏幕大小选择订阅【高清大画面】或是【低清小画面】。
注意
双路编码开启后,会消耗更多的 CPU 和 网络带宽,所以 Mac、Windows 或者高性能 Pad 可以考虑开启,不建议手机端开启。
参数
enable | 是否开启小画面编码,默认值:false |
smallVideoEncParam | 小流的视频参数 |
返回
0:成功;-1:当前大画面已被设置为较低画质,开启双路编码已无必要。
◆ enterRoom()
| pure virtual |
进入房间
TRTC 的所有用户都需要进入房间才能“发布”或“订阅”音视频流,“发布”是指将自己的音频和视频推送到云端,“订阅”是指从云端拉取房间里其他用户的音视频流。 调用该接口时,您需要指定您的应用场景 TRTCAppScene 以获取最佳的音视频传输体验,这些场景可以分成两大类:
【直播场景(Live)】
- 包括 TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom:
- 此类场景下,每一个房间最多同时容纳 10 万人,但需要您通过 TRTCParams 中的 “role” 字段设定用户是“主播”(TRTCRoleAnchor)还是“观众”(TRTCRoleAudience)。
- 主播可以“发布”自己的音视频流,观众只能“订阅”别人的音视频流,每一个用户都可以在主播和观众两种角色间通过 switchRole 接口进行切换。
- 适用于[视频低延时直播]、[十万人互动课堂]、[直播PK]、[音乐直播间]、[在线K歌]、[远程培训]、[超大型会议]等业务形态。
【实时场景(RTC)】
- 包括 TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall:
- 此类场景下,每一个房间最多同时容纳 300 人在线,最高支持 50 人同时发言。
- 适用于 [1对1视频通话]、[300人视频会议]、[在线问诊]、[语音聊天]、[教育小班课]、[远程面试]、[在线狼人杀]等业务形态。
调用该接口后,您会收到来自 TRTCCloudDelegate 中的 onEnterRoom(result) 回调:
- 如果进房成功,参数 result 会是一个正数(result > 0),表示从函数调用到进入房间所花费的时间,单位是毫秒(ms)。
- 如果进房失败,参数 result 会是一个负数(result < 0),表示进房失败的错误码。
参数
param | 进房参数,用于指定用户的身份、角色和安全票据等信息,详情请参考 TRTCParams 。 |
scene | 应用场景,用于指定您的业务场景,同一个房间内的所有用户需要设定相同的 TRTCAppScene。 |
注意
- 同一个房间内的所有用户需要设定相同的 scene。不同的 scene 会导致偶现的异常问题。
- 当您指定参数 scene 为 TRTCAppSceneLIVE 或 TRTCAppSceneVoiceChatRoom 时,您必须通过 TRTCParams 中的 “role” 字段为当前用户设定他/她在房间中的角色。
- 请您尽量保证 enterRoom 与 exitRoom 前后配对使用,即保证”先退出前一个房间再进入下一个房间”,否则会导致很多异常问题。
◆ exitRoom()
| pure virtual |
离开房间
调用该接口会让用户离开自己所在的音视频房间,并释放摄像头、麦克风、扬声器等设备资源。 等资源释放完毕之后,SDK 会通过 TRTCCloudDelegate 中的 onExitRoom() 回调向您通知。 如果您要再次调用 enterRoom 或者切换到其他的供应商的 SDK,建议等待 onExitRoom() 回调到来之后再执行之后的操作,以避免摄像头或麦克风被占用的问题。
◆ generateCustomPTS()
| pure virtual |
生成自定义采集时的时间戳
本接口仅适用于自定义采集模式,用于解决音视频帧的采集时间(capture time)和投送时间(send time)不一致所导致的音画不同步问题。 当您通过 sendCustomVideoData 或 sendCustomAudioData 等接口进行自定义视频或音频采集时,请按照如下操作使用该接口:
- 首先,在采集到一帧视频或音频帧时,通过调用本接口获得当时的 PTS 时间戳。
- 之后可以将该视频或音频帧送入您使用的前处理模块(如第三方美颜组件,或第三方音效组件)。
- 在真正调用 sendCustomVideoData 或 sendCustomAudioData 进行投送时,请将该帧在采集时记录的 PTS 时间戳赋值给 TRTCVideoFrame 或 TRTCAudioFrame 中的 timestamp 字段。
返回
时间戳(单位:ms)
◆ getAudioCaptureVolume()
| pure virtual |
获取本地音频的采集音量
◆ getAudioEffectManager()
| pure virtual |
获取音效管理类(TXAudioEffectManager)
TXAudioEffectManager 是音效管理接口,您可以通过该接口实现如下功能:
- 背景音乐:支持在线音乐和本地音乐,支持变速、变调等特效、支持原生和伴奏并播放和循环播放。
- 耳机耳返:麦克风捕捉的声音实时通过耳机播放,常用于音乐直播。
- 混响效果:KTV、小房间、大会堂、低沉、洪亮...
- 变声特效:萝莉、大叔、重金属...
- 短音效:鼓掌声、欢笑声等简短的音效文件(对于小于10秒的文件,请将 isShortFile 参数设置为 true)。
◆ getAudioPlayoutVolume()
| pure virtual |
获取远端音频的播放音量
◆ getBGMDuration()
| inlinevirtualinherited |
获取音乐文件总时长,单位毫秒
v7.3 版本弃用,请使用 TXAudioEffectManager getMusicDurationInMS 接口
参数
path | 音乐文件路径,如果 path 为空,那么返回当前正在播放的 music 时长 |
返回
成功返回时长,失败返回-1
◆ getCameraDevicesList()
| inlinevirtualinherited |
获取摄像头设备列表
示例代码:
ITRTCDeviceCollection * pDevice = m_pCloud->getCameraDevicesList(); for (int i{}; i < pDevice->getCount(); i++) { std::wstring name = UTF82Wide(pDevice->getDeviceName(i)); } pDevice->release(); pDevice = null;
v8.0 版本弃用,请使用 ITXDeviceManager::getDevicesList 接口
注意
delete ITRTCDeviceCollection* 指针会导致编译错误,SDK 维护 ITRTCDeviceCollection 对象的生命周期,使用完毕后请调用 release 方法释放资源。
返回
摄像头管理器对象指针 ITRTCDeviceCollection*
◆ getCurrentCameraDevice()
| inlinevirtualinherited |
获取当前使用的摄像头
v8.0 版本弃用,请使用 ITXDeviceManager::getCurrentDevice 接口
返回
ITRTCDeviceInfo 设备信息,能获取设备 ID 和设备名称
◆ getCurrentMicDevice()
| inlinevirtualinherited |
获取当前选择的麦克风
v8.0 版本弃用,请使用 ITXDeviceManager::getCurrentDevice 接口
返回
ITRTCDeviceInfo 设备信息,能获取设备 ID 和设备名称
◆ getCurrentMicDeviceMute()
| inlinevirtualinherited |
获取系统当前麦克风设备是否静音
v8.0 版本弃用,请使用 ITXDeviceManager::getCurrentDeviceMute 接口
注意
查询的是系统硬件静音状态
返回
静音状态
◆ getCurrentMicDeviceVolume()
| inlinevirtualinherited |
获取系统当前麦克风设备音量
v8.0 版本弃用,请使用 ITXDeviceManager::getCurrentDeviceVolume 接口
注意
查询的是系统硬件音量大小。
返回
音量值,范围是0 - 100
◆ getCurrentSpeakerDevice()
| inlinevirtualinherited |
获取当前的扬声器设备
v8.0 版本弃用,请使用 ITXDeviceManager::getCurrentDevice 接口
返回
ITRTCDeviceInfo 设备信息,能获取设备 ID 和设备名称
◆ getCurrentSpeakerDeviceMute()
| inlinevirtualinherited |
获取系统当前扬声器设备是否静音
v8.0 版本弃用,请使用 ITXDeviceManager::getCurrentDeviceMute 接口
注意
查询的是系统硬件静音状态
返回
静音状态
◆ getCurrentSpeakerVolume()
| inlinevirtualinherited |
获取系统当前扬声器设备音量
v8.0 版本弃用,请使用 ITXDeviceManager::getCurrentDeviceVolume 接口
注意
查询的是系统硬件音量大小。
返回
扬声器音量,范围0 - 100
◆ getCustomAudioRenderingFrame()
| pure virtual |
获取可播放的音频数据
调用该接口之前,您需要先通过 enableCustomAudioRendering 开启音频自定义播放。 参数 TRTCAudioFrame 推荐下列填写方式(其他字段不需要填写):
- sampleRate:采样率,必填,支持 16000、24000、32000、44100、48000。
- channel:声道数,必填,单声道请填1,双声道请填2,双声道时数据是交叉的。
- data:用于获取音频数据的 buffer。需要您根据一阵音频帧的帧长度分配好 date 的内存大小。 获取的 PCM 数据支持 10ms 或 20ms 两种帧长,推荐使用 20ms 的帧长。 计算公式为:48000采样率、单声道、且播放时长为 20ms 的一帧音频帧的 buffer 大小为 48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节。
参数
audioFrame | 音频数据帧。 |
注意
- 参数 audioFrame 中的 sampleRate、channel 需提前设置好,同时分配好所需读取帧长的 data 空间。
- SDK 内部会根据 sampleRate 和 channel 自动填充 data 数据。
- 建议由系统的音频播放线程直接驱动该函数的调用,在播放完一帧音频之后,即调用该接口获取下一帧可播放的音频数据。
◆ getDeviceManager()
| pure virtual |
获取设备管理类(TXDeviceManager)
◆ getMicDevicesList()
| inlinevirtualinherited |
获取麦克风设备列表
示例代码:
ITRTCDeviceCollection * pDevice = m_pCloud->getMicDevicesList(); for (int i{}; i < pDevice->getCount(); i++) { std::wstring name = UTF82Wide(pDevice->getDeviceName(i)); } pDevice->release(); pDevice = null;
v8.0 版本弃用,请使用 ITXDeviceManager::getDevicesList 接口
返回
麦克风管理器对象指针 ITRTCDeviceCollection*
注意
delete ITRTCDeviceCollection* 指针会导致编译错误,SDK 维护 ITRTCDeviceCollection 对象的生命周期,使用完毕后请调用 release 方法释放资源。
◆ getScreenCaptureSources()
| pure virtual |
枚举可分享的屏幕和窗口(该接口仅支持桌面系统)
当您在对接桌面端系统的屏幕分享功能时,一般都需要展示一个选择分享目标的界面,这样用户能够使用这个界面选择是分享整个屏幕还是某个窗口。 通过本接口,您就可以查询到当前系统中可用于分享的窗口的 ID、名称以及缩略图。我们在 Demo 中提供了一份默认的界面实现供您参考。
注意
- 返回的列表中包含屏幕和应用窗口,屏幕是列表中的第一个元素。如果用户有多个显示器,那么每个显示器都是一个分享目标。
- 请不要使用 delete ITRTCScreenCaptureSourceList* 删除 SourceList,这很容易导致崩溃,请使用 ITRTCScreenCaptureSourceList 中的 release 方法释放列表。
参数
thumbnailSize | 指定要获取的窗口缩略图大小,缩略图可用于绘制在窗口选择界面上 |
iconSize | 指定要获取的窗口图标大小 |
返回
窗口列表包括屏幕
◆ getSDKVersion()
| pure virtual |
获取 SDK 版本信息
◆ getSpeakerDevicesList()
| inlinevirtualinherited |
获取扬声器设备列表
示例代码:
ITRTCDeviceCollection * pDevice = m_pCloud->getSpeakerDevicesList(); for (int i{}; i < pDevice->getCount(); i++) { std::wstring name = UTF82Wide(pDevice->getDeviceName(i)); } pDevice->release(); pDevice = null;
v8.0 版本弃用,请使用 ITXDeviceManager::getDevicesList 接口
返回
扬声器管理器对象指针 ITRTCDeviceCollection*
注意
delete ITRTCDeviceCollection* 指针会导致编译错误,SDK 维护 ITRTCDeviceCollection 对象的生命周期,使用完毕后请调用 release 方法释放资源。
◆ getTRTCShareInstance() [1/2]
| static |
◆ getTRTCShareInstance() [2/2]
| static |
创建 TRTCCloud 实例(单例模式)
参数
context | 仅适用于 Android 平台,SDK 内部会将其转化为 Android 平台的 ApplicationContext 用于调用 Androud System API。 如果传入的 context 参数为空,SDK 内部会自动获取当前进程的 ApplicationContext。 |
注意
- 如果您使用 delete ITRTCCloud* 会导致编译错误,请使用 destroyTRTCCloud 释放对象指针。
- 在 Windows、Mac 和 iOS 平台上,请调用 getTRTCShareInstance() 接口。
- 在 Android 平台上,请调用 getTRTCShareInstance(void *context) 接口。
◆ mixExternalAudioFrame()
| pure virtual |
向 SDK 混入自定义音轨
调用该接口之前,您需要先通过 enableMixExternalAudioFrame 开启自定义音轨,之后就可以通过本接口将自己的音轨以 PCM 格式混入到 SDK 中。 理想情况下,我们期望您的代码能够以非常均匀的速度向 SDK 提供音轨数据。但我们也非常清楚,完美的调用间隔是一个巨大的挑战。 所以 SDK 内部会开启一个音轨数据的缓冲区,该缓冲区的作用类似一个“蓄水池”,它能够暂存您传入的音轨数据,平抑由于接口调用间隔的抖动问题。 本接口的返回值代表这个音轨缓冲区的大小,单位是毫秒(ms),比如:如果该接口返回 50,则代表当前的音轨缓冲区有 50ms 的音轨数据。因此只要您在 50ms 内再次调用本接口,SDK 就能保证您混入的音轨数据是连续的。 当您调用该接口后,如果发现返回值 > 100ms,则可以等待一帧音频帧的播放时间之后再次调用;如果返回值 < 100ms,则代表缓冲区比较小,您可以再次混入一些音轨数据以确保音轨缓冲区的大小维持在“安全水位”以上。 参数 TRTCAudioFrame 推荐下列填写方式(其他字段不需要填写):
- data:音频帧 buffer。音频帧数据只支持 PCM 格式,支持[5ms ~ 100ms]帧长,推荐使用 20ms 帧长,长度计算方法:【48000采样率、单声道的帧长度:48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
- sampleRate:采样率,支持:16000、24000、32000、44100、48000。
- channel:声道数(如果是立体声,数据是交叉的),单声道:1; 双声道:2。
- timestamp:时间戳,单位为毫秒(ms),请使用音频帧在采集时被记录下来的时间戳(可以在获得一帧音频帧之后,通过调用 generateCustomPTS 获得时间戳)。
参数
frame | 音频数据 |
返回
>= 0 缓冲的长度,单位:ms。< 0 错误(-1 未启用 mixExternalAudioFrame)
注意
请您精准地按每帧时长的间隔调用本接口,数据投送间隔不均匀时极易触发声音卡顿。
◆ muteAllRemoteAudio()
| pure virtual |
暂停/恢复播放所有远端用户的音频流
当您静音所有用户的远端音频时,SDK 会停止播放所有来自远端的音频流,同时也会停止拉取所有用户的音频数据。
参数
mute | true:静音;false:取消静音。 |
注意
在进入房间(enterRoom)之前或之后调用本接口均生效,静音状态在退出房间(exitRoom) 之后会被重置为 false。
◆ muteAllRemoteVideoStreams()
| pure virtual |
暂停/恢复订阅所有远端用户的视频流
该接口仅暂停/恢复接收所有用户的视频流,但并不释放显示资源,视频画面会被冻屏在接口调用时的最后一帧。
参数
mute | 是否暂停接收 |
注意
该接口支持您在进入房间(enterRoom)前调用,暂停状态会在退出房间(exitRoom)在之后会被重置。
◆ muteLocalAudio()
| pure virtual |
暂停/恢复发布本地的音频流
当您暂停发布本地音频流之后,房间中的其他他用户会收到 onUserAudioAvailable(userId, false) 的通知。 当您恢复发布本地音频流之后,房间中的其他他用户会收到 onUserAudioAvailable(userId, true) 的通知。 与 stopLocalAudio 的不同之处在于,muteLocalAudio(true) 并不会释放麦克风权限,而是继续发送码率极低的静音包。 这对于需要云端录制的场景非常适用,因为 MP4 等格式的视频文件,对于音频数据的连续性要求很高,使用 stopLocalAudio 会导致录制出的 MP4 文件不易播放。 因此在对录制文件的质量要求较高的场景中,建议选择 muteLocalAudio 而不建议使用 stopLocalAudio。
参数
mute | true:静音;false:恢复。 |
◆ muteLocalVideo() [1/3]
| inline |
暂停/恢复发布本地的视频流
该接口可以暂停(或恢复)发布本地的视频画面,暂停之后,同一房间中的其他用户将无法继续看到自己画面。 该接口等效于 start/stopLocalPreview 这两个接口,但具有更好的性能和响应速度。 因为 start/stopLocalPreview 需要打开和关闭摄像头,而打开和关闭摄像头都是硬件设备相关的操作,非常耗时。 相比之下,muteLocalVideo 只需要在软件层面对数据流进行暂停或者放行即可,因此效率更高,也更适合需要频繁打开关闭的场景。 当暂停发布本地视频后,同一房间中的其他用户将会收到 onUserVideoAvailable(userId, false) 回调通知。 当恢复发布本地视频后,同一房间中的其他用户将会收到 onUserVideoAvailable(userId, true) 回调通知。
参数
mute | true:暂停;false:恢复。 |
◆ muteLocalVideo() [2/3]
| pure virtual |
暂停/恢复发布本地的视频流
v8.9 版本开始不推荐使用,建议使用 muteLocalVideo(streamType, mute) 接口替代之。
重载 IDeprecatedTRTCCloud .
◆ muteLocalVideo() [3/3]
| pure virtual |
暂停/恢复发布本地的视频流
该接口可以暂停(或恢复)发布本地的视频画面,暂停之后,同一房间中的其他用户将无法继续看到自己画面。 该接口在指定 TRTCVideoStreamTypeBig 时等效于 start/stopLocalPreview 这两个接口,但具有更好的响应速度。 因为 start/stopLocalPreview 需要打开和关闭摄像头,而打开和关闭摄像头都是硬件设备相关的操作,非常耗时。 相比之下,muteLocalVideo 只需要在软件层面对数据流进行暂停或者放行即可,因此效率更高,也更适合需要频繁打开关闭的场景。 当暂停/恢复发布指定 TRTCVideoStreamTypeBig 后,同一房间中的其他用户将会收到 onUserVideoAvailable 回调通知。 当暂停/恢复发布指定 TRTCVideoStreamTypeSub 后,同一房间中的其他用户将会收到 onUserSubStreamAvailable 回调通知。
参数
streamType | 要暂停/恢复的视频流类型(仅支持 TRTCVideoStreamTypeBig 和 TRTCVideoStreamTypeSub) |
mute | true:暂停;false:恢复。 |
◆ muteRemoteAudio()
| pure virtual |
暂停/恢复播放远端的音频流
当您静音某用户的远端音频时,SDK 会停止播放指定用户的声音,同时也会停止拉取该用户的音频数据数据。
参数
userId | 用于指定远端用户的 ID。 |
mute | true:静音;false:取消静音。 |
注意
在进入房间(enterRoom)之前或之后调用本接口均生效,静音状态在退出房间(exitRoom) 之后会被重置为 false。
◆ muteRemoteVideoStream() [1/3]
| inline |
暂停/恢复订阅远端用户的视频流
该接口仅暂停/恢复接收指定用户的视频流,但并不释放显示资源,视频画面会被冻屏在接口调用时的最后一帧。
参数
userId | 指定远端用户的 ID。 |
mute | 是否暂停接收。 |
注意
该接口支持您在进入房间(enterRoom)前调用,暂停状态会在退出房间(exitRoom)在之后会被重置。
◆ muteRemoteVideoStream() [2/3]
| pure virtual |
暂停 / 恢复订阅远端用户的视频流
v8.9 版本开始不推荐使用,建议使用 muteRemoteVideoStream(userId, streamType, mute) 接口替代之。
重载 IDeprecatedTRTCCloud .
◆ muteRemoteVideoStream() [3/3]
| pure virtual |
暂停/恢复订阅远端用户的视频流
该接口仅暂停/恢复接收指定用户的视频流,但并不释放显示资源,视频画面会被冻屏在接口调用时的最后一帧。
参数
userId | 指定远端用户的 ID。 |
streamType | 要暂停/恢复的视频流类型(仅支持 TRTCVideoStreamTypeBig 和 TRTCVideoStreamTypeSub)。 |
mute | 是否暂停接收。 |
注意
该接口支持您在进入房间(enterRoom)前调用,暂停状态会在退出房间(exitRoom)在之后会被重置。
◆ pauseAudioEffect()
| inlinevirtualinherited |
暂停音效
v7.3 版本弃用,请使用 TXAudioEffectManager pausePlayMusic 接口
参数
effectId | 音效 Id |
◆ pauseBGM()
| inlinevirtualinherited |
暂停播放背景音乐
v7.3 版本弃用,请使用 TXAudioEffectManager pausePlayMusic 接口
◆ pauseScreenCapture()
| pure virtual |
暂停屏幕分享
◆ playAudioEffect()
| inlinevirtualinherited |
播放音效
每个音效都需要您指定具体的 ID,您可以通过该 ID 对音效的开始、停止、音量等进行设置。 支持的文件格式:aac, mp3。
v7.3 版本弃用,请使用 TXAudioEffectManager startPlayMusic 接口
注意
若您想同时播放多个音效,请分配不同的 ID 进行播放。因为使用同一个 ID 播放不同音效,SDK 将会停止上一个 ID 对应的音效播放,再启动新的音效播放。
参数
effect | 音效 |
◆ playBGM()
| inlinevirtualinherited |
启动播放背景音乐
v7.3 版本弃用,请使用 TXAudioEffectManager startPlayMusic 接口,支持并发播放多个 BGM
参数
path | 音乐文件路径,支持的文件格式:aac, mp3。 |
◆ removeAllExcludedShareWindow()
| pure virtual |
将所有窗口从屏幕分享的排除列表中移除(该接口仅支持桌面系统)
◆ removeAllIncludedShareWindow()
| pure virtual |
将全部窗口从屏幕分享的包含列表中移除(该接口仅支持桌面系统)
该接口只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeWindow 时生效。 即只有在分享窗口内容时,额外包含指定窗口的功能才生效。
◆ removeCallback()
| pure virtual |
移除 TRTC 事件回调
参数
callback |
◆ removeExcludedShareWindow()
| pure virtual |
将指定窗口从屏幕分享的排除列表中移除(该接口仅支持桌面系统)
参数
windowID |
◆ removeIncludedShareWindow()
| pure virtual |
将指定窗口从屏幕分享的包含列表中移除(该接口仅支持桌面系统)
该接口只有在 TRTCScreenCaptureSourceInfo 中的 type 指定为 TRTCScreenCaptureSourceTypeWindow 时生效。 即只有在分享窗口内容时,额外包含指定窗口的功能才生效。
参数
windowID | 希望被分享出去的窗口(Mac 平台: 窗口 ID;Windows 平台: HWND) |
◆ resumeAudioEffect()
| inlinevirtualinherited |
恢复音效
v7.3 版本弃用,请使用 TXAudioEffectManager resumePlayMusic 接口
参数
effectId | 音效 Id |
◆ resumeBGM()
| inlinevirtualinherited |
继续播放背景音乐
v7.3 版本弃用,请使用 TXAudioEffectManager resumePlayMusic 接口
◆ resumeScreenCapture()
| pure virtual |
恢复屏幕分享
◆ selectScreenCaptureTarget() [1/3]
| inlinevirtualinherited |
设置屏幕共享参数
v7.9 版本弃用,请使用 selectScreenCaptureTarget(TRTCScreenCaptureSourceInfo,RECT,TRTCScreenCaptureProperty) 接口
参数
source | 指定分享源 |
captureRect | 指定捕获的区域 |
captureMouse | 指定是否捕获鼠标指针 |
highlightWindow | 指定是否高亮正在共享的窗口,以及当捕获图像被遮挡时高亮遮挡窗口提示用户移走遮挡 |
◆ selectScreenCaptureTarget() [2/3]
| inline |
设置屏幕共享参数
v7.9 版本弃用,请使用 selectScreenCaptureTarget(TRTCScreenCaptureSourceInfo,RECT,TRTCScreenCaptureProperty) 接口
参数
source | 指定分享源 |
captureRect | 指定捕获的区域 |
captureMouse | 指定是否捕获鼠标指针 |
highlightWindow | 指定是否高亮正在共享的窗口,以及当捕获图像被遮挡时高亮遮挡窗口提示用户移走遮挡 |
◆ selectScreenCaptureTarget() [3/3]
| pure virtual |
选取要分享的屏幕或窗口(该接口仅支持桌面系统)
当您通过 getScreenCaptureSources 获取到可以分享的屏幕和窗口之后,您可以调用该接口选定期望分享的目标屏幕或目标窗口。 在屏幕分享的过程中,您也可以随时调用该接口以切换分享目标。 支持如下四种情况:
- 共享整个屏幕:sourceInfoList 中 type 为 Screen 的 source,captureRect 设为 { 0, 0, 0, 0 }
- 共享指定区域:sourceInfoList 中 type 为 Screen 的 source,captureRect 设为非 nullptr,例如 { 100, 100, 300, 300 }
- 共享整个窗口:sourceInfoList 中 type 为 Window 的 source,captureRect 设为 { 0, 0, 0, 0 }
- 共享窗口区域:sourceInfoList 中 type 为 Window 的 source,captureRect 设为非 nullptr,例如 { 100, 100, 300, 300 }
参数
source 指定分享源 captureRect 指定捕获的区域 property 指定屏幕分享目标的属性,包括捕获鼠标,高亮捕获窗口等,详情参考TRTCScreenCaptureProperty 定义 注意
设置高亮边框颜色、宽度参数在 Mac 平台不生效。
◆ sendCustomAudioData()
| pure virtual |
向 SDK 投送自己采集的音频数据
参数 TRTCAudioFrame 推荐下列填写方式(其他字段不需要填写):
- audioFormat:音频数据格式,仅支持 TRTCAudioFrameFormatPCM。
- data:音频帧 buffer。音频帧数据只支持 PCM 格式,支持[5ms ~ 100ms]帧长,推荐使用 20ms 帧长,长度计算方法:【48000采样率、单声道的帧长度:48000 × 0.02s × 1 × 16bit = 15360bit = 1920字节】。
- sampleRate:采样率,支持:16000、24000、32000、44100、48000。
- channel:声道数(如果是立体声,数据是交叉的),单声道:1; 双声道:2。
- timestamp:时间戳,单位为毫秒(ms),请使用音频帧在采集时被记录下来的时间戳(可以在采集到一帧音频帧之后,通过调用 generateCustomPTS 获取时间戳)。
参考文档:自定义采集和渲染。
参数
frame | 音频数据 |
注意
请您精准地按每帧时长的间隔调用本接口,数据投送间隔不均匀时极易触发声音卡顿。
◆ sendCustomCmdMsg()
| pure virtual |
使用 UDP 通道发送自定义消息给房间内所有用户
该接口可以让您借助 TRTC 的 UDP 通道,向当前房间里的其他用户广播自定义数据,已达到传输信令的目的。 TRTC 中的 UDP 通道原本设计用来传输音视频数据的,该接口的原理是将您要发送的信令伪装成音视频数据包,与原本要发送的音视频数据一并发送出去。 房间中的其他用户可以通过 TRTCCloudDelegate 中的 onRecvCustomCmdMsg 回调接收消息。
参数
cmdID | 消息 ID,取值范围为1 - 10。 |
data | 待发送的消息,单个消息的最大长度被限制为 1KB。 |
reliable | 是否可靠发送,可靠发送可以获得更高的发送成功率,但可靠发送比不可靠发送会带来更大的接收延迟。 |
ordered | 是否要求有序,即是否要求接收端的数据包顺序和发送端的数据包顺序一致(这会带来一定的接收延时)。 |
返回
true:消息已经发出;false:消息发送失败。
注意
- 发送消息到房间内所有用户(暂时不支持 Web/小程序端),每秒最多能发送30条消息。
- 每个包最大为 1KB,超过则很有可能会被中间路由器或者服务器丢弃。
- 每个客户端每秒最多能发送总计 8KB 数据。
- 请将 reliable 和 ordered 同时设置为 true 或同时设置为 false,暂不支持交叉设置。
- 强烈建议您将不同类型的消息设定为不同的 cmdID,这样可以在要求有序的情况下减小消息时延。
◆ sendCustomVideoData() [1/3]
| inline |
TRTCVideoFrame 推荐如下填写方式(其他字段不需要填写):
- pixelFormat: Windows、Android平台仅支持 TRTCVideoPixelFormat_I420,iOS、Mac平台支持TRTCVideoPixelFormat_I420和TRTCVideoPixelFormat_BGRA32
- bufferType:仅支持 TRTCVideoBufferType_Buffer。
- data:视频帧 buffer。
- length:视频帧数据长度,I420 格式下,其值等于:width × height × 3 / 2。
- width:视频图像长度。
- height:视频图像宽度。
- timestamp:如果 timestamp 间隔不均匀,会严重影响音画同步和录制出的 MP4 质量。
参考文档:自定义采集和渲染。
参数
frame | 视频数据,支持 I420 格式数据。 |
注意
- SDK 内部有帧率控制逻辑,目标帧率以您在 setVideoEncoderParam 中设置的为准,太快会自动丢帧,太慢则会自动补帧。
- 可以设置 frame 中的 timestamp 为 0,相当于让 SDK 自己设置时间戳,但请“均匀”地控制 sendCustomVideoData 的调用间隔,否则会导致视频帧率不稳定。
- iOS、Mac平台目前仅支持传入TRTCVideoPixelFormat_I420或TRTCVideoPixelFormat_BGRA32格式的视频帧
- Windows、Android平台目前仅支持传入TRTCVideoPixelFormat_I420格式的视频帧
◆ sendCustomVideoData() [2/3]
| pure virtual |
投送自己采集的视频数据
v8.5 版本开始不推荐使用,建议使用 sendCustomVideoData(streamType, TRTCVideoFrame) 接口替代之。
重载 IDeprecatedTRTCCloud .
◆ sendCustomVideoData() [3/3]
| pure virtual |
向 SDK 投送自己采集的视频帧
使用此接口可以向 SDK 投送自己采集的视频帧,SDK 会将视频帧进行编码并通过自身的网络模块传输出去。 参数 TRTCVideoFrame 推荐下列填写方式(其他字段不需要填写):
- pixelFormat:Windows 和 Android 平台仅支持 TRTCVideoPixelFormat_I420,iOS 和 Mac平台支持 TRTCVideoPixelFormat_I420 和 TRTCVideoPixelFormat_BGRA32。
- bufferType:推荐选择 TRTCVideoBufferType_Buffer。
- data:用于承载视频帧数据的 buffer。
- length:视频帧数据长度,如果 pixelFormat 设定为 I420 格式,length 可以按照如下公式计算:length = width × height × 3 / 2。
- width:视频图像的宽度,如 640 px。
- height:视频图像的高度,如 480 px。
- timestamp:时间戳,单位为毫秒(ms),请使用视频帧在采集时被记录下来的时间戳(可以在采集到一帧视频帧之后,通过调用 generateCustomPTS 获取时间戳)。
参考文档:自定义采集和渲染。
参数
streamType | 用于指定视频流类型,TRTCVideoStreamTypeBig:高清大画面;TRTCVideoStreamTypeSub:辅路画面。 |
frame | 视频数据,支持 I420 格式数据。 |
注意
- 推荐您在采集到的一帧视频帧后,即调用 generateCustomPTS 接口获取该帧的 timestamp 数值,这样可以获得最佳的音画同步效果。
- SDK 最终编码出的视频帧率并不是由您调用本接口的频率决定的,而是由您在 setVideoEncoderParam 中所设置的 FPS 决定的。
- 请尽量保持本接口的调用间隔是均匀的,否则会导致编码器输出帧率不稳或者音画不同步等问题。
- iOS 和 Mac平台目前支持传入 TRTCVideoPixelFormat_I420 或 TRTCVideoPixelFormat_BGRA32 格式的视频帧。
- Windows 和 Android 平台目前仅支持传入 TRTCVideoPixelFormat_I420 格式的视频帧。
◆ sendSEIMsg()
| pure virtual |
使用 SEI 通道发送自定义消息给房间内所有用户
该接口可以让您借助 TRTC 的 SEI 通道,向当前房间里的其他用户广播自定义数据,已达到传输信令的目的。 视频帧的头部有一个叫做 SEI 的头部数据块,该接口的原理就是利用这个被称为 SEI 的头部数据块,将您要发送的自定义信令嵌入其中,使其同视频帧一并发送出去。 因此,与 sendCustomCmdMsg 相比,SEI 通道传输的信令具有更好的兼容性:信令可以伴随着视频帧一直传输到直播 CDN 上。 不过,由于视频帧头部的数据块不能太大,建议您使用该接口时,尽量将信令控制在几个字节的大小。 最常见的用法是把自定义的时间戳(timestamp)用本接口嵌入视频帧中,实现消息和画面的完美对齐(比如:教育场景下的课件和视频信号的对齐)。 房间中的其他用户可以通过 TRTCCloudDelegate 中的 onRecvSEIMsg 回调接收消息。
参数
data | 待发送的数据,最大支持 1KB(1000字节)的数据大小 |
repeatCount | 发送数据次数 |
返回
true:消息已通过限制,等待后续视频帧发送;false:消息被限制发送
注意
本接口有以下限制:
- 数据在接口调用完后不会被即时发送出去,而是从下一帧视频帧开始带在视频帧中发送。
- 发送消息到房间内所有用户,每秒最多能发送 30 条消息(与 sendCustomCmdMsg 共享限制)。
- 每个包最大为 1KB,若发送大量数据,会导致视频码率增大,可能导致视频画质下降甚至卡顿(与 sendCustomCmdMsg 共享限制)。
- 每个客户端每秒最多能发送总计8KB数据(与 sendCustomCmdMsg 共享限制)。
- 若指定多次发送(repeatCount > 1),则数据会被带在后续的连续 repeatCount 个视频帧中发送出去,同样会导致视频码率增大。
- 如果 repeatCount > 1,多次发送,接收消息 onRecvSEIMsg 回调也可能会收到多次相同的消息,需要去重。
◆ setAllAudioEffectsVolume()
| inlinevirtualinherited |
设置所有音效的音量
v7.3 版本弃用,请使用 TXAudioEffectManager setMusicPublishVolume / setMusicPlayoutVolume 接口
注意
该操作会覆盖通过 setAudioEffectVolume 指定的单独音效音量。
参数
volume | 音量大小,取值范围为0 - 100;默认值:100 |
◆ setAudioCaptureVolume()
| pure virtual |
设定本地音频的采集音量
参数
volume | 音量大小,取值范围为0 - 100;默认值:100 |
注意
如果将 volume 设置成 100 之后感觉音量还是太小,可以将 volume 最大设置成 150,但超过 100 的 volume 会有爆音的风险,请谨慎操作。
◆ setAudioEffectVolume()
| inlinevirtualinherited |
设置音效音量
v7.3 版本弃用,请使用 TXAudioEffectManager setMusicPublishVolume / setMusicPlayoutVolume 接口
注意
会覆盖通过 setAllAudioEffectsVolume 指定的整体音效音量。
参数
effectId | 音效 ID |
volume | 音量大小,取值范围为0 - 100;默认值:100 |
◆ setAudioFrameCallback()
| pure virtual |
设置音频数据自定义回调
设置该回调之后,SDK 内部会把音频数据(PCM 格式)回调出来,包括:
- onCapturedRawAudioFrame:本地麦克风采集到的原始音频数据回调
- onLocalProcessedAudioFrame:本地采集并经过音频模块前处理后的音频数据回调
- onRemoteUserAudioFrame:混音前的每一路远程用户的音频数据
- onMixedPlayAudioFrame:将各路音频混合之后并最终要由系统播放出的音频数据回调
注意
设置回调为空即代表停止自定义音频回调,反之,设置回调不为空则代表启动自定义音频回调。
◆ setAudioPlayoutVolume()
| pure virtual |
设定远端音频的播放音量
该接口会控制 SDK 最终交给系统播放的声音音量,调节效果会影响到本地音频录制文件的音量大小,但不会影响到耳返的音量大小。
参数
volume | 音量大小,取值范围为0 - 100,默认值:100。 |
注意
如果将 volume 设置成 100 之后感觉音量还是太小,可以将 volume 最大设置成 150,但超过 100 的 volume 会有爆音的风险,请谨慎操作。
◆ setAudioQuality()
| inlinevirtualinherited |
设置音频质量
主播端的音质越高,观众端的听感越好,但传输所依赖的带宽也就越高,在带宽有限的场景下也更容易出现卡顿。
- TRTCCloudDef#TRTCAudioQualitySpeech,流畅:采样率:16k;单声道;音频裸码率:16kbps;适合语音通话为主的场景,比如在线会议,语音通话。
- TRTCCloudDef#TRTCAudioQualityDefault,默认:采样率:48k;单声道;音频裸码率:50kbps;SDK 默认的音频质量,如无特殊需求推荐选择之。
-
TRTCCloudDef#TRTCAudioQualityMusic,高音质:采样率:48k;双声道 + 全频带;音频裸码率:128kbps;适合需要高保真传输音乐的场景,比如K歌、音乐直播等。
v8.0 版本弃用,请使用 startLocalAudio(TRTCAudioQuality) 接口
注意
该方法需要在 startLocalAudio 之前进行设置,否则不会生效。
◆ setBeautyStyle()
| pure virtual |
设置美颜、美白、红润等特效
SDK 内部集成了两套风格不同的磨皮算法: -“光滑”:算法比较激进,磨皮效果比较明显,适用于秀场直播。 -“自然”:算法更多地保留了面部细节,磨皮效果更加自然,适用于绝大多数直播场景。
参数
style | 磨皮算法,有“光滑”和“自然”两种算法。 |
beautyLevel | 美颜级别,取值范围0 - 9,0表示关闭,1 - 9值越大,效果越明显。 |
whitenessLevel | 美白级别,取值范围0 - 9,0表示关闭,1 - 9值越大,效果越明显。 |
ruddinessLevel | 红润级别,取值范围0 - 9,0表示关闭,1 - 9值越大,效果越明显。 |
◆ setBGMPlayoutVolume()
| inlinevirtualinherited |
设置背景音乐本地播放音量的大小
播放背景音乐混音时使用,用来控制背景音乐在本地播放时的音量大小。
v7.3 版本弃用,请使用 TXAudioEffectManager::setMusicPlayoutVolume 接口
参数
volume | 音量大小,100为正常音量,取值范围为0 - 100;默认值:100 |
◆ setBGMPosition()
| inlinevirtualinherited |
设置 BGM 播放进度
v7.3 版本弃用,请使用 TXAudioEffectManager seekMusicToPosInMS 接口
参数
pos | 单位毫秒 |
◆ setBGMPublishVolume()
| inlinevirtualinherited |
设置背景音乐远端播放音量的大小
播放背景音乐混音时使用,用来控制背景音乐在远端播放时的音量大小。
v7.3 版本弃用,请使用 TXAudioEffectManager::setMusicPublishVolume 接口
参数
volume | 音量大小,100为正常音量,取值范围为0 - 100;默认值:100 |
◆ setBGMVolume()
| inlinevirtualinherited |
设置背景音乐播放音量的大小
v7.3 版本弃用,请使用 TXAudioEffectManager::setMusicPublishVolume / setMusicPlayoutVolume 接口播放背景音乐混音时使用,用来控制背景音乐播放音量的大小, 该接口会同时控制远端播放音量的大小和本地播放音量的大小,因此调用该接口后,setBGMPlayoutVolume和setBGMPublishVolume设置的音量值会被覆盖。
参数
volume | 音量大小,100为正常音量,取值范围为0 - 100;默认值:100 |
◆ setCapturedRawAudioFrameCallbackFormat()
| pure virtual |
设置本地麦克风采集出的原始音频帧回调格式
本接口用于设置 onCapturedRawAudioFrame 回调出来的 AudioFrame 的格式:
- sampleRate:采样率,支持:16000、32000、44100、48000。
- channel:声道数(如果是立体声,数据是交叉的),单声道:1; 双声道:2。
- samplesPerCall:采样点数,定义回调数据帧长。帧长必须为 10ms 的整数倍。
如果希望用毫秒数计算回调帧长,则将毫秒数转换成采样点数的公式为:采样点数 = 毫秒数 * 采样率 / 1000; 举例:48000 采样率希望回调 20ms 帧长的数据,则采样点数应该填: 960 = 20 * 48000 / 1000; 注意,最终回调的帧长度是以字节为单位,采样点数转换成字节数的计算公式为:字节数 = 采样点数 * channel * 2(位宽) 举例:48000 采样率,双声道,20ms 帧长,采样点数为 960,字节数为 3840 = 960 * 2 * 2
参数
format | 音频数据回调格式。 |
返回
0:成功;<0:错误
◆ setConsoleEnabled()
| pure virtual |
启用/禁用控制台日志打印
参数
enabled | 指定是否启用,默认:禁止状态 |
◆ setCurrentCameraDevice()
| inlinevirtualinherited |
设置要使用的摄像头
v8.0 版本弃用,请使用 ITXDeviceManager::setCurrentDevice 接口
参数
deviceId | 从 getCameraDevicesList 中得到的设备 ID |
◆ setCurrentMicDevice()
| inlinevirtualinherited |
设置要使用的麦克风
选择指定的麦克风作为录音设备,不调用该接口时,默认选择索引为0的麦克风
v8.0 版本弃用,请使用 ITXDeviceManager::setCurrentDevice 接口
参数
micId | 从 getMicDevicesList 中得到的设备 ID |
◆ setCurrentMicDeviceMute()
| inlinevirtualinherited |
设置系统当前麦克风设备的是否静音
v8.0 版本弃用,请使用 ITXDeviceManager::setCurrentDeviceMute 接口
注意
该接口的功能是设置系统麦克风静音,如果用户直接设置 Windows 系统设置的麦克风静音时,该接口的设置结果会被用户的操作所覆盖。
参数
mute | 设置为 true 时,则设置麦克风设备静音 |
◆ setCurrentMicDeviceVolume()
| inlinevirtualinherited |
设置系统当前麦克风设备的音量
v8.0 版本弃用,请使用 ITXDeviceManager::setCurrentDeviceVolume 接口
注意
该接口的功能是调节系统采集音量,如果用户直接调节 Windows 系统设置的采集音量时,该接口的设置结果会被用户的操作所覆盖。
参数
volume | 麦克风音量值,范围0 - 100 |
◆ setCurrentSpeakerDevice()
| inlinevirtualinherited |
设置要使用的扬声器
v8.0 版本弃用,请使用 ITXDeviceManager::setCurrentDevice 接口
参数
speakerId | 从 getSpeakerDevicesList 中得到的设备 ID |
◆ setCurrentSpeakerDeviceMute()
| inlinevirtualinherited |
设置系统当前扬声器设备的是否静音
v8.0 版本弃用,请使用 ITXDeviceManager::setCurrentDeviceMute 接口
注意
该接口的功能是设置系统扬声器静音,如果用户直接设置 Windows 系统设置的扬声器静音时,该接口的设置结果会被用户的操作所覆盖。
参数
mute | 设置为 true 时,则设置扬声器设备静音 |
◆ setCurrentSpeakerVolume()
| inlinevirtualinherited |
设置系统当前扬声器设备音量
v8.0 版本弃用,请使用 ITXDeviceManager::setCurrentDeviceVolume 接口
注意
该接口的功能是调节系统播放音量,如果用户直接调节 Windows 系统设置的播放音量时,该接口的设置结果会被用户的操作所覆盖。
参数
volume | 设置的扬声器音量,范围0 - 100 |
◆ setDefaultStreamRecvMode()
| pure virtual |
设置订阅模式(需要在进入房前设置才能生效)
您可以通过该接口在“自动订阅”和“手动订阅”两种模式下进行切换:
- 自动订阅:默认模式,用户在进入房间后会立刻接收到该房间中的音视频流,音频会自动播放,视频会自动开始解码(依然需要您通过 startRemoteView 接口绑定渲染控件)。
- 手动订阅:在用户进入房间后,需要手动调用 {@startRemoteView} 接口才能启动视频流的订阅和解码,需要手动调用 {@muteRemoteAudio} (false) 接口才能启动声音的播放。
在绝大多数场景下,用户进入房间后都会订阅房间中所有主播的音视频流,因此 TRTC 默认采用了自动订阅模式,以求得最佳的“秒开体验”。 如果您的应用场景中每个房间同时会有很多路音视频流在发布,而每个用户只想选择性地订阅其中的 1-2 路,则推荐使用“手动订阅”模式以节省流量费用。
参数
autoRecvAudio | true:自动订阅音频;false:需手动调用 muteRemoteAudio(false) 订阅音频。默认值:true。 |
autoRecvVideo | true:自动订阅视频;false:需手动调用 startRemoteView 订阅视频。默认值:true。 |
注意
- 需要在进入房间(enterRoom)前调用该接口,设置才能生效。
- 在自动订阅模式下,如果用户在进入房间后没有调用 {@startRemoteView} 订阅视频流,SDK 会自动停止订阅视频流,以便达到节省流量的目的。
◆ setLocalProcessedAudioFrameCallbackFormat()
| pure virtual |
设置经过前处理后的本地音频帧回调格式
本接口用于设置 onLocalProcessedAudioFrame 回调出来的 AudioFrame 的格式:
- sampleRate:采样率,支持:16000、32000、44100、48000。
- channel:声道数(如果是立体声,数据是交叉的),单声道:1; 双声道:2。
- samplesPerCall:采样点数,定义回调数据帧长。帧长必须为 10ms 的整数倍。
如果希望用毫秒数计算回调帧长,则将毫秒数转换成采样点数的公式为:采样点数 = 毫秒数 * 采样率 / 1000; 举例:48000 采样率希望回调20ms帧长的数据,则采样点数应该填: 960 = 20 * 48000 / 1000; 注意,最终回调的帧长度是以字节为单位,采样点数转换成字节数的计算公式为:字节数 = 采样点数 * channel * 2(位宽) 举例:48000 采样率,双声道,20ms 帧长,采样点数为 960,字节数为 3840 = 960 * 2 * 2
参数
format | 音频数据回调格式。 |
返回
0:成功;<0:错误
◆ setLocalRenderParams()
| pure virtual |
设置本地画面的渲染参数
可设置的参数包括有:画面的旋转角度、填充模式以及左右镜像等。
参数
params | 画面渲染参数,详情请参考 TRTCRenderParams。 |
◆ setLocalVideoProcessCallback()
| pure virtual |
设置第三方美颜的视频数据回调
设置该回调之后,SDK 会把采集到的视频帧通过您设置的 callback 回调出来,用于第三方美颜组件进行二次处理,之后 SDK 会将处理后的视频帧进行编码和发送。
参数
pixelFormat | 指定回调的像素格式,出于数据处理效率的考虑,目前仅支持 OpenGL 纹理格式数据。 |
bufferType | 指定视频数据结构类型,出于数据处理效率的考虑,目前仅支持 OpenGL 纹理格式数据。 |
callback | 自定义渲染回调,详见 ITRTCVideoFrameCallback |
返回
0:成功;<0:错误
◆ setLocalVideoRenderCallback()
| pure virtual |
设置本地视频自定义渲染回调
设置该回调之后,SDK 内部会跳过原来的渲染流程,并把采集到的数据回调出来,您需要自己完成画面渲染。
- 您可以通过调用 setLocalVideoRenderCallback(TRTCVideoPixelFormat_Unknown, TRTCVideoBufferType_Unknown, nullptr) 停止回调。
- iOS、Mac、Windows 平台目前仅支持回调 TRTCVideoPixelFormat_I420 或 TRTCVideoPixelFormat_BGRA32 像素格式的视频帧。
- Android 平台目前仅支持传入 TRTCVideoPixelFormat_I420 像素格式的视频帧。
参数
pixelFormat | 指定回调的像素格式 |
bufferType | 指定视频数据结构类型,目前只支持 TRTCVideoBufferType_Buffer |
callback | 自定义渲染回调 |
返回
0:成功;<0:错误
◆ setLocalViewFillMode()
| inlinevirtualinherited |
设置本地图像的填充模式
v8.0 版本弃用,请使用 setLocalRenderParams(TRTCRenderParams) 接口
参数
mode | 填充(画面可能会被拉伸裁剪)或适应(画面可能会有黑边),默认值:TRTCVideoFillMode_Fit |
◆ setLocalViewMirror()
| inlinevirtualinherited |
设置本地摄像头预览画面的镜像模式
v8.0 版本弃用,请使用 setLocalRenderParams(TRTCRenderParams) 接口
参数
mirror | 镜像模式,默认值:false(非镜像模式) |
◆ setLocalViewRotation()
| inlinevirtualinherited |
设置本地图像的顺时针旋转角度
v8.0 版本弃用,请使用 setLocalRenderParams(TRTCRenderParams) 接口
参数
rotation | 支持 TRTCVideoRotation90 、 TRTCVideoRotation180 以及 TRTCVideoRotation270 旋转角度,默认值:TRTCVideoRotation0 |
◆ setLogCallback()
| pure virtual |
设置日志回调
◆ setLogCompressEnabled()
| pure virtual |
启用/禁用日志的本地压缩
开启压缩后,Log 存储体积明显减小,但需要腾讯云提供的 Python 脚本解压后才能阅读。 禁用压缩后,Log 采用明文存储,可以直接用记事本打开阅读,但占用空间较大。
参数
enabled | 指定是否启用,默认为启动状态 |
◆ setLogDirPath()
| pure virtual |
设置本地日志的保存路径
通过该接口您可以更改 SDK 本地日志的默认存储路径,SDK 默认的本地日志的存储位置:
- Windows 平台:在 C:/Users/[系统用户名]/AppData/Roaming/liteav/log,即 appdata%/liteav/log 下。
- iOS 或 Mac 平台:在 sandbox Documents/log 下。
- Android 平台:在 /app私有目录/files/log/liteav/ 下。
注意
请务必在所有其他接口之前调用,并且保证您指定的目录是存在的,并且您的应用程序拥有对该目录的读写权限。
参数
path | 存储日志的路径 |
◆ setLogLevel()
| pure virtual |
设置 Log 输出级别
参数
level | 参见 TRTCLogLevel,默认值:TRTCLogLevelNone |
◆ setMicVolumeOnMixing()
| inlinevirtualinherited |
设置麦克风的音量大小
从 v6.9 版本开始废弃,请使用 setAudioCaptureVolume 接口替代。
◆ setMixedPlayAudioFrameCallbackFormat()
| pure virtual |
设置最终要由系统播放出的音频帧回调格式
本接口用于设置 onMixedPlayAudioFrame 回调出来的 AudioFrame 的格式:
- sampleRate:采样率,支持:16000、32000、44100、48000。
- channel:声道数(如果是立体声,数据是交叉的),单声道:1; 双声道:2。
- samplesPerCall:采样点数,定义回调数据帧长。帧长必须为 10ms 的整数倍。
如果希望用毫秒数计算回调帧长,则将毫秒数转换成采样点数的公式为:采样点数 = 毫秒数 * 采样率 / 1000; 举例:48000 采样率希望回调20ms帧长的数据,则采样点数应该填: 960 = 20 * 48000 / 1000; 注意,最终回调的帧长度是以字节为单位,采样点数转换成字节数的计算公式为:字节数 = 采样点数 * channel * 2(位宽) 举例:48000 采样率,双声道,20ms 帧长,采样点数为 960,字节数为 3840 = 960 * 2 * 2
参数
format | 音频数据回调格式。 |
返回
0:成功;<0:错误
◆ setMixExternalAudioVolume()
| pure virtual |
设置推流时混入外部音频的推流音量和播放音量
参数
publishVolume | 设置的推流音量大小,范围0 - 100, -1表示不改变 |
playoutVolume | 设置的播放音量大小,范围0 - 100, -1表示不改变 |
◆ setMixTranscodingConfig()
| pure virtual |
设置云端混流的排版布局和转码参数
在一个直播间中可能同时会有多个主播发布自己的音视频流,但对于直播 CDN 上的观众而言,只需要观看一条 HTTP-FLV 或 HLS 格式的视频流即可。 当您调用本接口函数时,SDK 会向腾讯云的 TRTC 混流服务器发送一条指令,混流服务器会将房间里的多路音视频流混合成一路。 您可以通过 TRTCTranscodingConfig 参数来调整每一路画面的排版布局,也可以设置混合后的音视频流的各项编码参数。 参考文档:云端混流转码。
【画面1】=> 解码 ====> \ \ 【画面2】=> 解码 => 画面混合 => 编码 => 【混合后的画面】 // 【画面3】=> 解码 ====> //
【声音1】=> 解码 ====> \ \ 【声音2】=> 解码 => 声音混合 => 编码 => 【混合后的声音】 // 【声音3】=> 解码 ====> //
参数
config | 如果 config 不为空,则开启云端混流,如果 config 为空则停止云端混流。详情请参考 TRTCTranscodingConfig 。 |
注意
关于云端混流的注意事项:
- 混流转码为收费功能,调用接口将产生云端混流转码费用,详见 实时音视频 云端混流转码-购买指南-文档中心-腾讯云 。
- 调用该接口的用户,如果没设定 config 参数中的 streamId 字段,TRTC 会将房间中的多路画面混合到当前用户所对应的音视频流上,即 A + B => A。
- 调用该接口的用户,如果设定了 config 参数中的 streamId 字段,TRTC 会将房间中的多路画面混合到您指定的 streamId 上,即 A + B => streamId。
- 请注意,若您还在房间中且不再需要混流,请务必再次调用本接口并将 config 设置为空以进行取消,不及时取消混流可能会引起不必要的计费损失。
- 请放心,当您退房时 TRTC 会自动取消混流状态。
◆ setNetworkQosParam()
| pure virtual |
设置网络质量控制的相关参数
该设置决定在差网络环境下的质量调控策略,如“画质优先”或“流畅优先”等策略。
参数
param | 用于设置网络质量控制的相关参数,详情请参考 TRTCNetworkQosParam。 |
◆ setPriorRemoteVideoStreamType()
| inlinevirtualinherited |
设定观看方优先选择的视频质量
低端设备推荐优先选择低清晰度的小画面。 如果对方没有开启双路视频模式,则此操作无效。
v8.0 版本弃用,请使用 startRemoteView(userId, streamType, rendView) 接口
参数
type | 默认观看大画面还是小画面,默认为 TRTCVideoStreamTypeBig |
◆ setRemoteAudioParallelParams()
| pure virtual |
设置远端音频流智能并发播放策略
设置远端音频流智能并发播放策略,适用于上麦人数比较多的场景。
参数
params | 音频并发参数,请参考 TRTCAudioParallelParams |
◆ setRemoteAudioVolume()
| pure virtual |
设定某一个远端用户的声音播放音量
您可以通过 setRemoteAudioVolume(userId, 0) 将某一个远端用户的声音静音。
参数
userId | 用于指定远端用户的 ID。 |
volume | 音量大小,取值范围为0 - 100,默认值:100。 |
注意
如果将 volume 设置成 100 之后感觉音量还是太小,可以将 volume 最大设置成 150,但超过 100 的 volume 会有爆音的风险,请谨慎操作。
◆ setRemoteRenderParams()
| pure virtual |
设置远端画面的渲染模式
可设置的参数包括有:画面的旋转角度、填充模式以及左右镜像等。
参数
userId | 指定远端用户的 ID。 |
streamType | 可以设置为主路画面(TRTCVideoStreamTypeBig)或辅路画面(TRTCVideoStreamTypeSub) |
params | 画面渲染参数,详情请参考 TRTCRenderParams。 |
◆ setRemoteSubStreamViewFillMode()
| inlinevirtualinherited |
设置辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)的显示模式
- setRemoteViewFillMode() 用于设置远端主路画面(TRTCVideoStreamTypeBig,一般用于摄像头)的显示模式。
-
setRemoteSubStreamViewFillMode() 用于设置远端辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)的显示模式。
v8.0 版本弃用,请使用 setRemoteRenderParams(userId,streamType,param) 接口
参数
userId 用户的 ID mode 填充(画面可能会被拉伸裁剪)或适应(画面可能会有黑边),默认值:TRTCVideoFillMode_Fit
◆ setRemoteSubStreamViewRotation()
| inlinevirtualinherited |
设置辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)的顺时针旋转角度
- setRemoteViewRotation() 用于设置远端主路画面(TRTCVideoStreamTypeBig,一般用于摄像头)的旋转角度。
-
setRemoteSubStreamViewRotation() 用于设置远端辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)的旋转角度。
v8.0 版本弃用,请使用 setRemoteRenderParams(userId,streamType,param) 接口
参数
userId 用户 ID rotation 支持90、180、270旋转角度
◆ setRemoteVideoRenderCallback()
| pure virtual |
设置远端视频自定义渲染回调
设置该回调之后,SDK 内部会跳过原来的渲染流程,并把采集到的数据回调出来,您需要自己完成画面渲染。
- 您可以通过调用 setLocalVideoRenderCallback(TRTCVideoPixelFormat_Unknown, TRTCVideoBufferType_Unknown, nullptr) 停止回调。
- iOS、Mac、Windows 平台目前仅支持回调 TRTCVideoPixelFormat_I420 或 TRTCVideoPixelFormat_BGRA32 像素格式的视频帧。
- Android 平台目前仅支持传入 TRTCVideoPixelFormat_I420 像素格式的视频帧。
注意
实际使用时,需要先调用 startRemoteView(userid, nullptr) 来获取远端用户的视频流(view 设置为 nullptr 即可),否则不会有数据回调出来。
参数
userId | 远端用户id |
pixelFormat | 指定回调的像素格式 |
bufferType | 指定视频数据结构类型,目前只支持 TRTCVideoBufferType_Buffer |
callback | 自定义渲染回调 |
返回
0:成功;<0:错误
◆ setRemoteVideoStreamType()
| pure virtual |
切换指定远端用户的大小画面
当房间中某个主播开启了双路编码之后,房间中其他用户通过 startRemoteView 订阅到的画面默认会是【高清大画面】。 您可以通过此接口选定希望订阅的画面是大画面还是小画面,该接口在 startRemoteView 之前和之后调用均可生效。
注意
此功能需要目标用户已经通过 enableEncSmallVideoStream 提前开启了双路编码模式,否则此调用无实际效果。
参数
userId | 指定远端用户的 ID。 |
streamType | 视频流类型,即选择看大画面还是小画面,默认为大画面。 |
◆ setRemoteViewFillMode()
| inlinevirtualinherited |
设置远端图像的渲染模式
v8.0 版本弃用,请使用 setRemoteRenderParams(userId,streamType,param) 接口
参数
userId | 用户 ID |
mode | 填充(画面可能会被拉伸裁剪)或适应(画面可能会有黑边),默认值:TRTCVideoFillMode_Fit |
◆ setRemoteViewRotation()
| inlinevirtualinherited |
设置远端图像的顺时针旋转角度
v8.0 版本弃用,请使用 setRemoteRenderParams(userId,streamType,param) 接口
参数
userId | 用户 ID |
rotation | 支持 TRTCVideoRotation90 、 TRTCVideoRotation180 以及 TRTCVideoRotation270 旋转角度,默认值:TRTCVideoRotation0 |
◆ setSubStreamEncoderParam()
| pure virtual |
设置屏幕分享(即辅路)的视频编码参数(桌面系统和移动系统均已支持)
该接口可以设定远端用户所看到的屏幕分享(即辅路)的画面质量,同时也能决定云端录制出的视频文件中屏幕分享的画面质量。 请注意如下两个接口的差异:
- setVideoEncoderParam 用于设置主路画面(TRTCVideoStreamTypeBig,一般用于摄像头)的视频编码参数。
- setSubStreamEncoderParam 用于设置辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)的视频编码参数。
参数
param | 辅流编码参数,详情请参考 TRTCVideoEncParam。 |
注意
即使您使用主路传输屏幕分享(在调用 startScreenCapture 时设置 type=TRTCVideoStreamTypeBig),依然要使用 setSubStreamEncoderParam 设定屏幕分享的编码参数,而不要使用 setVideoEncoderParam 。
◆ setSubStreamMixVolume()
| pure virtual |
设置屏幕分享时的混音音量大小(该接口仅支持桌面系统)
这个数值越高,屏幕分享音量的占比就越高,麦克风音量占比就越小,所以不推荐设置得太大,否则麦克风的声音就被压制了。
参数
volume | 设置的混音音量大小,范围0 - 100。 |
◆ setSystemAudioLoopbackVolume()
| pure virtual |
设置系统声音的采集音量
参数
volume | 设置的音量大小,范围是:[0 ~ 150],默认值为100。 |
◆ setVideoEncoderMirror()
| pure virtual |
设置编码器输出的画面镜像模式
该设置不影响本地画面的镜像模式,但会影响房间中其他用户所观看到(以及云端录制文件)的镜像模式。
参数
mirror | 是否开启远端镜像,true:开启远端画面镜像;false:关闭远端画面镜像,默认值:false。 |
◆ setVideoEncoderParam()
| pure virtual |
设置视频编码器的编码参数
该设置能够决定远端用户看到的画面质量,同时也能决定云端录制出的视频文件的画面质量。
参数
param | 用于设置视频编码器的相关参数,详情请参考 TRTCVideoEncParam。 |
◆ setVideoEncoderRotation()
| pure virtual |
设置视频编码器输出的画面方向
该设置不影响本地画面的预览方向,但会影响房间中其他用户所观看到(以及云端录制文件)的画面方向。 当用户将手机或 Pad 上下颠倒时,由于摄像头的采集方向没有变,所以房间中其他用户所看到的画面会变成上下颠倒的, 在这种情况下,您可以通过调用该接口将 SDK 编码出的画面方向旋转180度,如此一来,房间中其他用户所看到的画面可保持正常的方向。 如果您希望实现上述这种友好的交互体验,我们更推荐您直接调用 setGSensorMode 实现更加智能的方向适配,无需您手动调用本接口。
参数
rotation | 目前支持0和180两个旋转角度,默认值:TRTCVideoRotation_0,即不旋转。 |
◆ setWaterMark()
| pure virtual |
添加水印
水印的位置是通过 xOffset, yOffset, fWidthRatio 来指定的。
- xOffset:水印的坐标,取值范围为0 - 1的浮点数。
- yOffset:水印的坐标,取值范围为0 - 1的浮点数。
- fWidthRatio:水印的大小比例,取值范围为0 - 1的浮点数。
参数
streamType | 要设置水印的流类型(TRTCVideoStreamTypeBig、TRTCVideoStreamTypeSub) |
srcData | 水印图片源数据(传 nullptr 表示去掉水印) |
srcType | 水印图片源数据类型 |
nWidth | 水印图片像素宽度(源数据为文件路径时忽略该参数) |
nHeight | 水印图片像素高度(源数据为文件路径时忽略该参数) |
xOffset | 水印显示的左上角 x 轴偏移 |
yOffset | 水印显示的左上角 y 轴偏移 |
fWidthRatio | 水印显示的宽度占画面宽度比例(水印按该参数等比例缩放显示) |
注意
本接口只支持给主路视频添加图片水印
◆ showDebugView()
| pure virtual |
显示仪表盘
“仪表盘”是位于视频渲染控件之上的一个半透明的调试信息浮层,用于展示音视频信息和事件信息,便于对接和调试。
参数
showType | 0:不显示;1:显示精简版(仅显示音视频信息);2:显示完整版(包含音视频信息和事件信息)。 |
◆ snapshotVideo()
| pure virtual |
视频画面截图
您可以通过本接口截取本地的视频画面,远端用户的主路画面以及远端用户的辅路(屏幕分享)画面。
参数
userId | 用户 ID,如指定空置表示截取本地的视频画面。 |
streamType | 视频流类型,可选择截取主路画面(TRTCVideoStreamTypeBig,常用于摄像头)或辅路画面(TRTCVideoStreamTypeSub,常用于屏幕分享)。 |
sourceType | 画面来源,可选择截取视频流画面(TRTCSnapshotSourceTypeStream)或视频渲染画面(TRTCSnapshotSourceTypeView),前者一般更清晰。 |
注意
Windows 平台目前仅支持截取 TRTCSnapshotSourceTypeStream 来源的视频画面。
◆ startAudioRecording()
| pure virtual |
开始录音
当您调用改接口后, SDK 会将本地和远端的所有音频(包括本地音频,远端音频,背景音乐和音效等)混合并录制到一个本地文件中。 该接口在进入房间前后调用均可生效,如果录制任务在退出房间前尚未通过 stopAudioRecording 停止,则退出房间后录制任务会自动被停止。
参数
param | 录音参数,请参考 TRTCAudioRecordingParams |
返回
0:成功;-1:录音已开始;-2:文件或目录创建失败;-3:后缀指定的音频格式不支持。
◆ startCameraDeviceTest() [1/2]
| inlinevirtualinherited |
开始进行摄像头测试
会触发 onFirstVideoFrame 回调接口
v8.0 版本弃用,请使用 ITXDeviceManager::startCameraDeviceTest 接口
注意
在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。
参数
callback | 摄像头预览自定义渲染画面回调 |
◆ startCameraDeviceTest() [2/2]
| inlinevirtualinherited |
开始进行摄像头测试
会触发 onFirstVideoFrame 回调接口
v8.0 版本弃用,请使用 ITXDeviceManager::startCameraDeviceTest 接口
注意
在测试过程中可以使用 setCurrentCameraDevice 接口切换摄像头。
参数
rendView | 承载预览画面的 HWND |
◆ startLocalAudio() [1/3]
| inlinevirtualinherited |
开启本地音频的采集和上行
该函数会启动麦克风采集,并将音频数据传输给房间里的其他用户。 SDK 不会默认开启本地音频采集和上行,您需要调用该函数开启,否则房间里的其他用户将无法听到您的声音。
v8.0 版本弃用,请使用 startLocalAudio(quality) 接口
注意
TRTC SDK 并不会默认打开本地的麦克风采集。
◆ startLocalAudio() [2/3]
| inline |
开启本地音频的采集和上行
该函数会启动麦克风采集,并将音频数据传输给房间里的其他用户。 SDK 不会默认开启本地音频采集和上行,您需要调用该函数开启,否则房间里的其他用户将无法听到您的声音。
v8.0 版本弃用,请使用 startLocalAudio(quality) 接口
注意
TRTC SDK 并不会默认打开本地的麦克风采集。
◆ startLocalAudio() [3/3]
| pure virtual |
开启本地音频的采集和发布
SDK 默认不开启麦克风,当用户需要发布本地音频时,需要调用该接口开启麦克风采集,并将音频编码并发布到当前的房间中。 开启本地音频的采集和发布后,房间中的其他用户会收到 onUserAudioAvailable(userId, true) 的通知。
参数
quality | 声音音质
|
注意
该函数会检查麦克风的使用权限,如果当前 App 没有麦克风权限,SDK 会自动向用户申请麦克风使用权限。
◆ startLocalPreview() [1/2]
| pure virtual |
开启本地摄像头的预览画面(移动端)
在 enterRoom 之前调用此函数,SDK 只会开启摄像头,并一直等到您调用 enterRoom 之后才开始推流。 在 enterRoom 之后调用此函数,SDK 会开启摄像头并自动开始视频推流。 当开始渲染首帧摄像头画面时,您会收到 TRTCCloudDelegate 中的 onCameraDidReady 回调通知。
参数
frontCamera | true:前置摄像头;false:后置摄像头。 |
view | 承载视频画面的控件 |
注意
如果希望开播前预览摄像头画面并通过 BeautyManager 调节美颜参数,您可以:
- 方案一:在调用 enterRoom 之前调用 startLocalPreview
- 方案二:在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
◆ startLocalPreview() [2/2]
| pure virtual |
开启本地摄像头的预览画面(桌面端)
在调用该接口之前,您可以先调用 setCurrentCameraDevice 选择使用 Mac 自带摄像头或外接摄像头。 在 enterRoom 之前调用此函数,SDK 只会开启摄像头,并一直等到您调用 enterRoom 之后才开始推流。 在 enterRoom 之后调用此函数,SDK 会开启摄像头并自动开始视频推流。 当开始渲染首帧摄像头画面时,您会收到 TRTCCloudDelegate 中的 onCameraDidReady 回调通知。
参数
view | 承载视频画面的控件 |
注意
如果希望开播前预览摄像头画面并通过 BeautyManager 调节美颜参数,您可以:
- 方案一:在调用 enterRoom 之前调用 startLocalPreview
- 方案二:在调用 enterRoom 之后调用 startLocalPreview + muteLocalVideo(true)
◆ startLocalRecording()
| pure virtual |
开启本地媒体录制
开启后把直播过程中的音视和视频内容录制到本地的一个文件中。
参数
params | 录制参数,请参考 TRTCLocalRecordingParams |
◆ startMicDeviceTest()
| inlinevirtualinherited |
开启麦克风测试
回调接口 onTestMicVolume 获取测试数据
该方法测试麦克风是否能正常工作,volume 的取值范围为0 - 100。
v8.0 版本弃用,请使用 ITXDeviceManager::startMicDeviceTest 接口
参数
interval | 反馈音量提示的时间间隔(ms),建议设置到大于 200 毫秒 |
◆ startPublishCDNStream()
| pure virtual |
开始向非腾讯云 CDN 上发布音视频流
该接口跟 startPublishing 功能类似,不同之处在于,startPublishing 仅支持向腾讯云的 CDN 发布,而本接口支持向非腾讯云的直播 CDN 上转推音视频流。
参数
param | CDN 转推参数,详情请参考 TRTCPublishCDNParam |
注意
- 使用 startPublishing 接口向腾讯云的直播 CDN 上发布音视频流不会收取额外费用
- 使用 startPublishCDNStream 接口向非腾讯云的直播 CDN 上发布音视频流,需要收取额外的转推带宽费用。
◆ startPublishing()
| pure virtual |
开始向腾讯云直播 CDN 上发布音视频流
该接口会向 TRTC 服务器发送指令,要求其将当前用户的音视频流旁路到直播 CDN 上。 您可以通过参数 streamId 设定直播流的 StreamId,从而可以指定该用户的音视频流对应在直播 CDN 上的播放地址。 例如:您可以通过该接口将当前用户的直播流 ID 指定为 user_stream_001,那么该用户音视频流对应的 CDN 播放地址为: “http://yourdomain/live/user_stream_001.flv”,其中 yourdomain 为您自己备案的播放域名, 您可以在直播控制台 配置您的播放域名,腾讯云不提供默认的播放域名。 您也可以在设置 enterRoom 的参数 TRTCParams 时指定 streamId, 而且我们更推荐您采用这种方案。
参数
streamId | 自定义流 ID。 |
streamType | 仅支持 TRTCVideoStreamTypeBig 和 TRTCVideoStreamTypeSub。 |
注意
您需要提前在 实时音视频控制台 中的功能配置页面上开启“启用旁路推流”才能生效。
- 若您选择“指定流旁路”,则您可以通过该接口将对应音视频流推送到腾讯云 CDN 且指定为填写的流 ID。
- 若您选择“全局自动旁路”,则您可以通过该接口调整默认的流 ID。
◆ startRemoteSubStreamView()
| inlinevirtualinherited |
开始显示远端用户的辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)
- startRemoteView() 用于显示主路画面(TRTCVideoStreamTypeBig,一般用于摄像头)。
-
startRemoteSubStreamView() 用于显示辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)。
v8.0 版本弃用,请使用 startRemoteView(userId,streamType,rendView) 接口
参数
userId 对方的用户标识 rendView 渲染画面的 TXView 注意
请在 onUserSubStreamAvailable 回调后再调用这个接口。
◆ startRemoteView() [1/3]
| pure virtual |
订阅远端用户的视频流,并绑定视频渲染控件
调用该接口可以让 SDK 拉取指定 userid 的视频流,并渲染到参数 view 指定的渲染控件上。您可以通过 setRemoteRenderParams 设置画面的显示模式。
- 如果您已经知道房间中有视频流的用户的 userid,可以直接调用 startRemoteView 订阅该用户的画面。
- 如果您不知道房间中有哪些用户在发布视频,您可以在 enterRoom 之后等待来自 onUserVideoAvailable 的通知。
调用本接口只是启动视频流的拉取,此时画面还需要加载和缓冲,当缓冲完毕后您会收到来自 onFirstVideoFrame 的通知。
参数
userId | 指定远端用户的 ID。 |
streamType | 指定要观看 userId 的视频流类型:
|
view | 用于承载视频画面的渲染控件 |
注意
注意几点规则需要您关注:
- SDK 支持同时观看某 userid 的大画面和辅路画面,或者同时观看某 userid 的小画面和辅路画面,但不支持同时观看大画面和小画面。
- 只有当指定的 userid 通过 enableEncSmallVideoStream 开启双路编码后,才能观看该用户的小画面。
- 当指定的 userid 的小画面不存在时,SDK 默认切换到该用户的大画面。
◆ startRemoteView() [2/3]
| inlinevirtualinherited |
开始显示远端视频画面
在收到 SDK 的 onUserVideoAvailable(userId, true) 通知时,可以获知该远程用户开启了视频,此后调用 startRemoteView(userId) 接口加载该用户的远程画面时, 可以用 loading 动画优化加载过程中的等待体验。 待该用户的首帧画面开始显示时,您会收到 onFirstVideoFrame(userId) 事件回调。
v8.0 版本弃用,请使用 startRemoteView(userId, streamType, rendView) 接口
参数
userId | 对方的用户标识 |
rendView | 承载预览画面的窗口句柄 |
◆ startRemoteView() [3/3]
| inline |
开始显示远端视频画面
在收到 SDK 的 onUserVideoAvailable(userId, true) 通知时,可以获知该远程用户开启了视频,此后调用 startRemoteView(userId) 接口加载该用户的远程画面时, 可以用 loading 动画优化加载过程中的等待体验。 待该用户的首帧画面开始显示时,您会收到 onFirstVideoFrame(userId) 事件回调。
v8.0 版本弃用,请使用 startRemoteView(userId, streamType, rendView) 接口
参数
userId | 对方的用户标识 |
rendView | 承载预览画面的窗口句柄 |
◆ startScreenCapture() [1/3]
| inlinevirtualinherited |
启动屏幕分享
从 v7.2 版本开始废弃,请使用 startScreenCapture(rendView, type, params) 接口替代。
◆ startScreenCapture() [2/3]
| inline |
启动屏幕分享
从 v7.2 版本开始废弃,请使用 startScreenCapture(rendView, type, params) 接口替代。
◆ startScreenCapture() [3/3]
| pure virtual |
开始桌面端屏幕分享
该接口可以抓取整个 Mac OS 系统的屏幕内容,或抓取您指定的某个应用的窗口内容(仅限桌面),并将其分享给同房间中的其他用户。
参数
view | 渲染控件所在的父控件,可以设置为空值,表示不显示屏幕分享的预览效果(仅限桌面)。 |
streamType | 屏幕分享使用的线路,可以设置为主路(TRTCVideoStreamTypeBig)或者辅路(TRTCVideoStreamTypeSub),推荐使用辅路。 |
encParam | 屏幕分享的画面编码参数,SDK 会优先使用您通过此接口设置的编码参数:
|
注意
- 同一个用户同时最多只能发布一路主路(TRTCVideoStreamTypeBig)画面和一路辅路(TRTCVideoStreamTypeSub)画面。
- 默认情况下,屏幕分享使用辅路画面。如果使用主路做屏幕分享,您需要提前停止摄像头采集(stopLocalPreview)以避免相互冲突。
- 同一个房间中同时只能有一个用户使用辅路做屏幕分享,也就是说,同一个房间中同时只允许一个用户开启辅路。
- 当房间中已经有其他用户在使用辅路分享屏幕时,此时调用该接口会收到来自 TRTCCloudDelegate 的 onError(ERR_SERVER_CENTER_ANOTHER_USER_PUSH_SUB_VIDEO) 回调。
◆ startSpeakerDeviceTest()
| inlinevirtualinherited |
开启扬声器测试
回调接口 onTestSpeakerVolume 获取测试数据
该方法播放指定的音频文件测试播放设备是否能正常工作。如果能听到声音,说明播放设备能正常工作。
v8.0 版本弃用,请使用 ITXDeviceManager::startSpeakerDeviceTest 接口
参数
testAudioFilePath | 音频文件的绝对路径,路径字符串使用 UTF-8 编码格式,支持文件格式:WAV、MP3 |
◆ startSpeedTest() [1/4]
| pure virtual |
开始进行网速测试(进入房间前使用)
参数
params | 测速选项 |
返回
接口调用结果,< 0:失败
注意
- 测速过程将产生少量的基础服务费用,详见 计费概述 > 基础服务 文档说明。
- 请在进入房间前进行网速测试,在房间中网速测试会影响正常的音视频传输效果,而且由于干扰过多,网速测试结果也不准确。
- 同一时间只允许一项网速测试任务运行。
◆ startSpeedTest() [2/4]
| inline |
开始进行网络测速(进入房间前使用)
v9.2 版本开始不推荐使用,建议使用 startSpeedTest(params) 接口替代之。
◆ startSpeedTest() [3/4]
| pure virtual |
开始进行网络测速(进入房间前使用)
v9.2 版本开始不推荐使用,建议使用 startSpeedTest(params) 接口替代之。
重载 IDeprecatedTRTCCloud .
◆ startSpeedTest() [4/4]
| pure virtual |
开始进行网络测速(进入房间前使用)
v9.2 版本开始不推荐使用,建议使用 startSpeedTest(params) 接口替代之。
重载 IDeprecatedTRTCCloud .
◆ startSystemAudioLoopback()
| pure virtual |
开启系统声音采集(仅适用于桌面系统)
该接口会从电脑的声卡中采集音频数据,并将其混入到 SDK 当前的音频数据流中,从而使房间中的其他用户也能听到主播的电脑所播放出的声音。 在线教育场景中,老师可以使用此功能让 SDK 采集教学影片中的声音,并广播给同房间中的学生。 音乐直播场景中,主播可以使用此功能让 SDK 采集音乐播放器中的音乐,从而为自己的直播间增加背景音乐。
参数
deviceName |
|
注意
在 Windows 平台下,您也可以将参数 deviceName 设置为某个应用程序的可执行文件(如 QQMuisc.exe)的绝对路径,此时 SDK 只会采集该应用程序的声音(仅支持 32 位版本的 SDK)。 您也可以指定该参数为某个扬声器设备的名称来采集特定扬声器声音(通过接口 TXDeviceManager 中的 getDevicesList 接口,可以获取类型为 TXMediaDeviceTypeSpeaker 的扬声器设备)。
◆ stopAllAudioEffects()
| inlinevirtualinherited |
停止所有音效
v7.3 版本弃用,请使用 TXAudioEffectManager stopPlayMusic 接口
◆ stopAllRemoteView()
| pure virtual |
停止订阅所有远端用户的视频流,并释放全部渲染资源
调用此接口会让 SDK 停止接收所有来自远端的视频流,并释放全部的解码和渲染资源。
注意
如果当前有正在显示的辅路画面(屏幕分享)也会一并被停止。
◆ stopAudioEffect()
| inlinevirtualinherited |
停止音效
v7.3 版本弃用,请使用 TXAudioEffectManager stopPlayMusic 接口
参数
effectId | 音效 ID |
◆ stopAudioRecording()
| pure virtual |
停止录音
如果录制任务在退出房间前尚未通过本接口停止,则退出房间后录音任务会自动被停止。
◆ stopBGM()
| inlinevirtualinherited |
停止播放背景音乐
v7.3 版本弃用,请使用 TXAudioEffectManager stopPlayMusic 接口
◆ stopCameraDeviceTest()
| inlinevirtualinherited |
停止摄像头测试
v8.0 版本弃用,请使用 ITXDeviceManager::stopCameraDeviceTest 接口
◆ stopLocalAudio()
| pure virtual |
停止本地音频的采集和发布
停止本地音频的采集和发布后,房间中的其他用户会收到 onUserAudioAvailable(userId, false) 的通知。
◆ stopLocalPreview()
| pure virtual |
停止摄像头预览
◆ stopLocalRecording()
| pure virtual |
停止本地媒体录制
如果录制任务在退出房间前尚未通过本接口停止,则退出房间后录音任务会自动被停止。
◆ stopMicDeviceTest()
| inlinevirtualinherited |
停止麦克风测试
v8.0 版本弃用,请使用 ITXDeviceManager::stopMicDeviceTest 接口
◆ stopPublishCDNStream()
| pure virtual |
停止向非腾讯云 CDN 上发布音视频流
◆ stopPublishing()
| pure virtual |
停止向腾讯云直播 CDN 上发布音视频流
◆ stopRemoteSubStreamView()
| inlinevirtualinherited |
停止显示远端用户的辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)。
v8.0 版本弃用,请使用 stopRemoteView(userId,streamType) 接口
参数
userId | 对方的用户标识 |
◆ stopRemoteView() [1/3]
| inlinevirtualinherited |
停止显示远端视频画面,同时不再拉取该远端用户的视频数据流
调用此接口后,SDK 会停止接收该用户的远程视频流,同时会清理相关的视频显示资源。
v8.0 版本弃用,请使用 stopRemoteView(userId,streamType) 接口
参数
userId | 对方的用户标识 |
◆ stopRemoteView() [2/3]
| inline |
停止显示远端视频画面,同时不再拉取该远端用户的视频数据流
调用此接口后,SDK 会停止接收该用户的远程视频流,同时会清理相关的视频显示资源。
v8.0 版本弃用,请使用 stopRemoteView(userId,streamType) 接口
参数
userId | 对方的用户标识 |
◆ stopRemoteView() [3/3]
| pure virtual |
停止订阅远端用户的视频流,并释放渲染控件
调用此接口会让 SDK 停止接收该用户的视频流,并释放该路视频流的解码和渲染资源。
参数
userId | 指定远端用户的 ID。 |
streamType | 指定要观看 userId 的视频流类型:
|
◆ stopScreenCapture()
| pure virtual |
停止屏幕分享
◆ stopSpeakerDeviceTest()
| inlinevirtualinherited |
停止扬声器测试
v8.0 版本弃用,请使用 ITXDeviceManager::stopSpeakerDeviceTest 接口
◆ stopSpeedTest()
| pure virtual |
停止网络测速
◆ stopSystemAudioLoopback()
| pure virtual |
停止系统声音采集(仅适用于桌面系统)
◆ switchRole()
| pure virtual |
切换角色
调用本接口可以实现用户在“主播”和“观众”两种角色之间来回切换。 由于视频直播和语音聊天室需要支持多达10万名观众同时观看,所以设定了“只有主播才能发布自己的音视频”的规则。 因此,当有些观众希望发布自己的音视频流(以便能跟主播互动)时,就需要先把自己的角色切换成“主播”。 您可以在进入房间时通过 TRTCParams 中的 role 字段事先确定用户的角色,也可以在进入房间后通过 switchRole 接口动态切换角色。
参数
role | 角色,默认为“主播”:
|
注意
- 该接口仅适用于视频直播(TRTCAppSceneLIVE)和语音聊天室(TRTCAppSceneVoiceChatRoom)这两个场景。
- 如果您在 enterRoom 时指定的 scene 为 TRTCAppSceneVideoCall 或 TRTCAppSceneAudioCall,请不要调用这个接口。
◆ switchRoom()
| pure virtual |
切换房间
使用该接口可以让用户可以快速从一个房间切换到另一个房间。
- 如果用户的身份是“观众”,该接口的调用效果等同于 exitRoom(当前房间) + enterRoom(新的房间)。
- 如果用户的身份是“主播”,该接口在切换房间的同时还会保持自己的音视频发布状态,因此在房间切换过程中,摄像头的预览和声音的采集都不会中断。
该接口适用于在线教育场景中,监课老师在多个房间中进行快速切换的场景。在该场景下使用 switchRoom 可以获得比 exitRoom+enterRoom 更好的流畅性和更少的代码量。 接口调用结果会通过 TRTCCloudDelegate 中的 onSwitchRoom(errCode, errMsg) 回调。
参数
config | 房间参数,详情请参考 TRTCSwitchRoomConfig 。 |
注意
由于对老版本 SDK 兼容的需求,参数 config 中同时包含 roomId 与 strRoomId 两个参数,这两个参数的填写格外讲究,请注意如下事项:
- 若您选用 strRoomId,则 roomId 需要填写为0。若两者都填,将优先选用 roomId。
- 所有房间需要同时使用 strRoomId 或同时使用 roomId,不可混用,否则将会出现很多预期之外的 bug。
◆ updateLocalView()
| pure virtual |
更新本地摄像头的预览画面
◆ updateRemoteView()
| pure virtual |
更新远端用户的视频渲染控件
该接口可用于更新远端视频画面的渲染控件,常被用于切换显示区域的交互场景中。
参数
view | 承载视频画面的控件 |
streamType | 要设置预览窗口的流类型(仅支持 TRTCVideoStreamTypeBig 和 TRTCVideoStreamTypeSub) |
userId | 指定远端用户的 ID。 |
函数说明
◆ destroyTRTCShareInstance()
TRTC_API void destroyTRTCShareInstance | ( | ) |
◆ getTRTCShareInstance() [1/2]
TRTC_API liteav::ITRTCCloud* getTRTCShareInstance | ( | ) |
◆ getTRTCShareInstance() [2/2]
TRTC_API liteav::ITRTCCloud* getTRTCShareInstance | ( | void * | context | ) |