实时音视频开发学习13 - 小程序端API

小程序端API

小程序端API分为基础方法、发布订阅方法、视图控制方法、背景音乐方法、消息收发和其它。针对trtc-room组件来说可以传递一个config属性来打开音视频通话。

基础方法

基础方法包含on、off、enterRoom和exitRoom，on和off用于监听和取消监听事件列表，接收一个回调函数

需要注意的是，为避免漏掉组件派发的事件，需要在enterRoom前监听事件。on参数列表

enterRoom进入房间，调用参数必须传入roomID，类型为Number，可以随机生成，取值范围在1 – 4294967295。返回值为一个promise，因此需要进行异步的等待。而异步的过程往往不能明确知道事件进程到哪里，因此可以借助let/await方法。

exitRoom用于停止推流和订阅所有远端音视频，并退出房间。但需要注意的是由于微信最新版本小程序引擎限制，请勿在onHide()回调函数中调用 exitRoom()，会导致各种状态紊乱的bug。使用方法同enterRoom

发布订阅方法

该模块中包含了本地音视频的发布和取消发布，订阅/取消远端音视频流和获取远端用户列表三个模块。

publishLocalVideo和publishLocalAudio用于发布本地的音视频流，采集本地摄像头和麦克风，需要单独写，都是返回一个promise。在用户进房成功后，监听到LOCAL_JOIN便能进行开启。

需要注意的是，如果是纯音频沟通场景则不需要调用publishLocalVideo。

对应取消发布音视频，则在退房exitRoom的时候调用即可。

subscribeRemoteVideo用于订阅远端用户视频流，并进行播放。该属性许传递两个参数userID和streamType。当监听到远端用户视频流变更REMOTE_VIDEO

_ADD时订阅远端视频。

与之相同的是subscribeRemoteAudio，订阅远端用户的音频并进行播放。不过音频用户只需要传入对应的用户ID并在REMOTE_AUDIO_ADD事件触发时打开即可。

视图控制

视图控制主要用于全屏的开启与关闭、设定远端画面显示方向和填充模式、显示或隐藏某一路视频画面、设定视频画面左边和尺寸以及制定视频画面的层级。视图的操控让语音通话变得更加人性化。

enterFullscreen将远端用户视频切换为全屏播放，该属性需要传入userID和streamType两个属性。

我们在调试的时候可以给按钮绑定一个事件监听，并命名一个判断标志isShowFullScreen，默认为false。每当点击按钮时isShowFullScreen进行去反，然后执行对应的打开全屏操作和关闭全屏操作。

setViewOrientation用于设定远端画面的显示方向，除了传递用户ID和远端用户流类型外，还需传入orientation用于判断画面显示的方向vertical或horzontal。

它的使用场景有两个，一个是在进入房间后设置画面显示的方向，另一个则是在双击触屏事件进行切换。使用方式如下

setViewFillMode设置远端画面的填充模式，该模式和web端播放模式play的第二个参数的属性objectFit类似。该属性提供两种填充方式完整显示画面contain和铺满视图fillCrop。

使用场景也是在进入房间后对画面的显示方式作出选择，在这里，我们还可以根据用户ID的不同给与不一样的填充方式。

setViewRect用于设定视频画面的坐标尺寸，但该方法仅在template:’custom’时有效。我们在自定义网格显示多个远端用户的位置时候就可以使用该方法，将远端用户视频内容显示到对应的视频窗格中。

对应案例代码如下：

背景音乐

背景音乐接口主要控制了音乐的播放、停止、重置和暂停。此外还提供了两个用于设置混音中背景音乐的音量和麦克风中的音量。

playBGM播放背景音乐，背景音乐会同麦克风采集的人声混合在一起发布到云端，即“背景混音”。目前背景音乐播放地址仅支持HTTPS协议的在线音乐和以mp3,、aac结尾的音频。

使用场景可以在视频画面获取到的一瞬间进行打开，如果要关闭可以手动在画面中使用stopBGM或者暂停pauseBGM。

setBGMVolume和setMICVolume分别用于设置混音中背景音乐的音量和麦克风的音量。音量类型为number，音量大小取值范围为0 – 1。

可以结合互动条来动态修改声音大小。

其它方面还有一个switchCamera切换本地前后摄像头和snapshot用于截取制定远端视频流或者本地视频的图像，并将其保存到系统的相册当中。

消息收发

消息的收发功能需要开通即时通信IM服务并将属性表中的enableIM选项设置为treu才能有效。API提供了发送C2C的文本消息、自定义消息，和发送群组文本消息、群组自定义消息。

sendC2CTextMessage发送C2C文本消息需要传递两个参数userID用户ID和message所传递的文本，该属性返回一个promise对象。

sendC2CCustomMessage发送自定义消息，接收一个payload属性，该属性拥有三个参数data数据字段、description消息字段说明和extension消息扩展字段。

相应代码示例：

sendGroupTextMessage发送群组消息，群组消息是向房间发送消息，在房间的所有用户都能看见。接收一个roomID房间号和一个message数据消息。

sendGroupCustomMessage发送自定义群消息，和发送自定义消息类似，只不过将属性换成了roomID，也需要传递一个payload对象，切该对象的属性也和自定义消息的payload一样。

事件表

对组件对象使用on进行事件监听，并绑定EVENT属性获取到对应的状态，并进行相关的业务逻辑。常用的有进出房事件、远端用户进出房和远端音视频流加载与移除等事件。

小程序错误码

错误码用于帮助用户快速定准错误的位置，并进行修正。如摄像头和录音禁用、音视频编码失败等。

注：更多内容请关注https://cloud.tencent.com/document/product/647/17249