互动直播房间接入

网易云通信提供简单的互动直播和连麦接口,只需要创建并加入互动房间即可以实现直播推流;连麦者使用相同的房间名加入互动房间即可以实现实时连麦互动。阅读该章节,您可以迅速完成一个最简单的互动直播房间的创建、加入,快速实现互动直播的功能。

在这里需要明确几个基本概念: 房间:互动直播房间与云通信音视频多人会议的房间概念一致,以房间名称为唯一标识。互动直播房间需要先创建成功后才能加入,当所有用户都离开房间后,可以复用该房间名重新创建。 主播:是互动直播房间的主用户,推流地址的指定者,直播的主画面源。主播需要首先加入房间。一个互动直播房间同时只能有一个主播。 连麦者:是互动直播房间的次用户,直播辅画面源,与主播加入同一房间,即能实现实时连麦互动,需要主播在房间时才能加入。 观众:互动直播中除了主播和连麦者,观看直播画面的其他用户。可以通过停止播放直播并加入互动房间转变为连麦者。

另外,理解网易云通信互动直播与音视频音视频通话的关系可以更好地帮助开发者快速集成: 互动直播与多人音视频通话:云通信互动直播基于多人音视频通话开发,通过将多人会议中用户的音视频数据处理后推送给视频流服务器实现直播和实时连麦。在功能的提供上,互动直播复用多人音视频接口,增加互动开关、推流地址指定与切换、直播角色指定等扩展设置。

互动直播房间接入流程

sequenceDiagram participant 主播 participant Meeting participant 连麦者 participant ... Meeting->>Meeting:创建互动直播房间(nim_vchat_create_room) 主播->>Meeting:加入互动直播房间(nim_vchat_join_room) Meeting->>主播: 连接建立(nim_vchat_cb_func kNIMVideoChatSessionTypeConnect code = 200) 连麦者->>Meeting:加入互动直播房间(nim_vchat_join_room) Meeting->>连麦者: 连接建立(nim_vchat_cb_func kNIMVideoChatSessionTypeConnect code = 200) Meeting->>Meeting:用户进出房间通知(nim_vchat_cb_func kNIMVideoChatSessionTypePeopleStatus) Meeting->>主播:互动直播状态回调(nim_vchat_cb_func kNIMVideoChatSessionTypeLiveState) Meeting->>Meeting:房间发生了错误(nim_vchat_cb_func kNIMVideoChatSessionTypeConnect) Meeting->>Meeting: 结束通话(nim_vchat_end) Meeting->>Meeting: 通话断开(nim_vchat_cb_func kNIMVideoChatSessionTypeConnect)

创建互动直播房间

API介绍

创建一个互动直播房间(后续需要主动调用加入接口进入房间)。其中webrtc标记支持webrtc互通,无需要不要打开。

API原型

参数说明

参数 类型 说明
room_name string 房间名
custom_info string 自定义信息,所有加入房间的成员都会收到此信息
json_extension(C/C++) string Json string 扩展,kNIMVChatWebrtc有效
createRoomInfo(C#) Json C接口中json_extension的封装类,见NIMCreateRoomJsonEx
cb function 回调函数
user_data(C) void* APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!

返回值说明

无返回值

示例

特殊说明

返回错误码中417说明已经存在同名的房间,如果是目标房间议,则可以直接走后面流程加入此房间。如果不是希望创建的目标房间,则需要重新设定房间名后再创建。

加入互动直播房间

API介绍

加入一个互动直播房间,主播必须先进入房间

API原型

参数说明

主播加入必须填写推流地址,打开推流开关。连麦互动者必须打开推流开关。普通成员直接进入。

参数 类型 说明
mode enum 音视频通话类型,见nim_vchat_def.h
room_name string 房间名
json_extension(C/C++) string Json string 扩展,音视频通话的扩展参数设置
joinRoomInfo(C#) object C接口中json_extension的封装类,见NIMJoinRoomJsonEx
cb function 结果回调
user_data(C) void* APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!

其中扩展参数中NIMVChatVideoSplitMode的定义说明见图文介绍;在NIMVChatVideoSplitMode设置为kNRTCChatSplitCustomLayout时可使用自定义布局,说明见布局参数配置介绍

返回值说明

返回一个bool类型值。接口调用成功返回true,否则返回false。失败一般是由于已存在通话,无法重复发起。

示例

离开互动直播房间

API介绍

需要在结束时调用,用于底层挂断和清理数据。

API原型

参数说明

需要带上加入时填写的session_id。

参数 类型 说明
json_extension string Json string 扩展,kNIMVChatSessionId
参数 类型 说明
jsonExtension string Json string 扩展,kNIMVChatSessionId
参数 类型 说明
json_extension string Json string 扩展,kNIMVChatSessionId

返回值说明

无返回值。

示例

用户进出房间通知

API介绍

在连接建立后,如果已有成员在通话中,或新进来的成员都会通过此回调通知。有成员离开也通过此回调,并告诉是正常离开还是超时离开,超时离开代表本地超时未收到对端数据,可能对方网络异常也可能是本地网络异常。

API原型

参数说明

参数 类型 说明
channel_id long 频道id
uid string 对方id
status int 成员状态,离开、加入等
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypePeopleStatus
channel_id int64 频道id
code int 状态码,对应NIMVideoChatSessionStatus
json_extension string Json string 扩展,返回kNIMVChatUid,如果是离开带kNIMVChatStatus对应NIMVideoChatUserLeftType
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理

示例

互动直播状态回调

API介绍

在连接建立后,服务器会定时刷新当前的直播状态,并告知客户端,客户端会收到当前最新的状态,但是有可能丢失过程状态。比如直播发起够快的话,直播的开始连接等状态就会不提示,直接提示推流中。

API原型

参数说明

参数 类型 说明
channel_id long 频道id
code int 无效错误码
status enum 直播状态, 见NIMVChatLiveState
参数 类型 说明
type enum 直播状态,见kNIMVideoChatSessionTypeLiveState
channel_id int64 频道id
code int 无效错误码
json_extension string Json string 扩展,返回kNIMVChatLiveState带kNIMVChatStatus对应NIMVChatLiveStateCode
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理
枚举定义 说明
kNIMVChatLiveStateInitial 500 直播初始状态
kNIMVChatLiveStateLayoutError 501 主播设置定制布局,布局参数错误
kNIMVChatLiveStateStartConnecting 502 开始连接
kNIMVChatLiveStateConnectted 503 连接成功
kNIMVChatLiveStateConnectFail 504 连接失败
kNIMVChatLiveStatePushing 505 推流中
kNIMVChatLiveStatePushFail 506 互动直播推流失败
kNIMVChatLiveStateInnerError 507 内部错误
kNIMVChatLiveStatePeopleLimit 508 人数超出限制

示例

房间发生了错误

API介绍

当房间发生异常,统一返回连接错误信息,和开始时连接成功及连接失败是同一个回调函数。

API原型

参数说明

参数 类型 说明
channel_id long 频道id
code int 状态码见NIMVChatConnectErrorCode
record_file string 服务器录制的音频文件名
video_record_file string 服务器录制的视频文件名
参数 类型 说明
type enum 回调类型kNIMVideoChatSessionTypeConnect
channel_id int64 频道id
code int 错误码NIMVChatConnectErrorCode,200代表连接成功
json_extension string Json string 扩展,如果成功返回 kNIMVChatVideoRecordFile和kNIMVChatRecordFile
user_data void* 注册回调时的APP自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理
枚举定义 说明
kNIMVChatConnectDisconn 0 断开连接
kNIMVChatConnectStartFail 1 启动失败
kNIMVChatConnectTimeout 101 超时
kNIMVChatConnectMeetingModeError 102 会议模式错误
kNIMVChatConnectRtmpModeError 103 非rtmp用户加入rtmp频道
kNIMVChatConnectRtmpNodesError 104 超过频道最多rtmp人数限制
kNIMVChatConnectRtmpHostError 105 已经存在一个主播
kNIMVChatConnectRtmpCreateError 106 需要旁路直播, 但频道创建者非主播
kNIMVChatConnectSuccess 200 成功
kNIMVChatConnectLayoutError 208 主播自定义布局错误
kNIMVChatConnectInvalidParam 400 错误参数
kNIMVChatConnectDesKey 401 密码加密错误
kNIMVChatConnectInvalidRequst 417 错误请求
kNIMVChatConnectServerUnknown 500 服务器内部错误
kNIMVChatConnectLogout 1001 退出
kNIMVChatChannelStartFail 11000 发起失败
kNIMVChatChannelDisconnected 11001 断开连接
kNIMVChatVersionSelfLow 11002 本人SDK版本太低不兼容
kNIMVChatVersionRemoteLow 11003 对方SDK版本太低不兼容

示例