跳转至

重要概念

房间

非即时房间: 使用本SDK之前,您需要使用 webapi 或 访问管理系统页面 来创建的房间。使用获得的房间号即可与同房间用户进行音视频和其他数据的交换了。

即时房间: 直接调用SDK接口,创建即时房间,同时可以进入房间进行音视频交互。

用户

使用网页、客户端或手机app皆可进入房间,每一个接入房间的客户端实例,我们称为一个用户。

音视频

每个具有可用的音视频采集设备的用户都可以单独发布自己的音频数据,也可以同时发布音视频数据。

使用指南

进出房间

调用 joinroom: 或者 joinRoomEx: 接口加入房间。成功加入房间后,自己将收到事件 on_roomjoined:(加入房间成功事件),同时房间内的其他用户将会收到事件 on_roomuserjoined:(有用户加入房间事件)。

当需要离开房间时,您需要调用 leaveroom: 接口,离开房间成功后,您将收到事件 on_roomleaved:(离开房间事件),同时房间内其他用户将收到事件 on_roomuserleft(有用户离开房间事件)。

当遇到网络闪断等异常情况时,您也会收到事件 on_roomleaved。在这种情况下,您需要做好项目的相关清除工作。

关于用户

每一个连接到房间内的客户端,被称为一个用户。用户的身份由peerID来唯一标识。当您在调用 joinroom 接口时,如果传入一个thirdid,则本地用户的peerID即为您设定的thirdid。如果没有传,则SDK会自动生成一个guid作为您的peerID。但请注意,无论是哪种情况,系统不允许同一个房间内存在peerID相等的两个用户。所以当您使用一个房间内已经存在的thirdid进入房间时,服务器会把之前使用这个peerID的用户请出房间。 除了peerID外,每个用户还有一些其他属性(预定义的和自定义的),您可以使用 changeuserproperty 接口来修改任一用户的任一属性,并且可以指定把这项修改通知给哪个(些)用户(或者只包括自己)。随后,on_roomuserchanged(用户属性改变),告知某个用户的某些属性被修改了。 除此之外,还有getuser这些接口,用于获取本地用户,获取某个peerID对应的用户,或房间内的全体用户。

音视频

您可以调用changeuserpublish接口来指定自己或某个其他用户发布自己的音频或视频。一旦用户开始发布音、视频数据,房间内的所有其他用户都会自动播放其中的音频数据。如果该用户发布了视频数据,所有用户将收到on_roomuserpublishstate回调。此时您可以选择忽略它(则您将看不到这个用户的视频),也可以在该用户结束发布前,随时调用playvideo接口,传入该用户的peerIDview(window为HWND,mac为NSView指针)。该用户的视频就显示在view对象中了。要注意的是,您不需要发布本地用户的视频,即可随时观看自己的视频图像。

一旦开始播放某个用户的视频,您以随时调用unplayvideo接口结束收看。 调用changeuserpublish接口,并指定publish=0(音视频同时停止发布)或1(只发布音频),可以停止发布视频数据。此时房间内的所有用户将收到回调on_roomuserpublishstate。如果您正在观看该用户,您需要调用unplayvideo接口来停止观看,并需在调用此接口前解除对视频view的占用。

自定义信令

利用自定义信令接口,您可以完成您设计的各种业务流程,创造各种激动人心的用户体验。我们把各种信令都抽象成了消息,和用户类似,消息有自己的id(msgid)和昵称(msgname),昵称可以和其他消息重名,但id必须在房间内唯一,id相同的消息,后来的会替换之前的。除了这两个属性,消息还有这些属性:
towhom:谁会接收到该消息的通知。可以填入目标用户的peerID(可以是自己),也可以填入如下5种宏定义:
__all:通知给所有人,包括调用者
__allExceptSenderr:通知给除了调用者以外的所有人
__allExceptAuditor:通知给除了旁听用户以外的所有人
__none:不通知给任何人
某用户的peerID:只发给该用户
ts:时间戳,以服务器接收到消息的时间为准
data:数据(可存放各种数据结构,包括数字、字符串、map和list)
save:是否保存。当为真时,服务器会在房间内保存该条消息,新进入的用户会收到该条消息。如果连续发两条id相同且需要保存的消息,服务器只会保存后一条。当为假时,服务器在转发完这条消息后,即将此消息抛弃。

具体流程如下:

调用 pubmsg 接口发布一条消息,则所有指定用户将收到事件 on_roomremotepubmsg(第一个参数为true,代表发布消息)。
如果这条消息是指定保存的,则之后新进入房间的用户会收到on_roomremotepubmsg回调。且在发布之后,可以再次调用pubmsg接口,发布一条相同id的消息来覆盖它,则指定用户会再次收到on_roomremotepubmsg回调。也可以调用delmsg接口来删除此消息,此时指定用户会收到on_roomremotedelmsg回调。

© 2016-2023 北京拓课网络科技有限公司 版权所有  京ICP备17018423号-1 京公网安备11010502043461号