实时语音是用于实现游戏房间内多人实时语音功能的服务。基础库1.5.1开始支持。

调用流程

所有调用通过前端接口完成。开发者仅需提供房间唯一标识,即可加入到指定的房间。传入相同唯一标识的用户,会进到相同的语音房间。为了保证前端传入的 groupId 可信,qq.joinVoIPChat 接口要求传入签名。详见 签名算法。

前端接口

  • 创建/加入房间:qq.joinVoIPChat
  • 离开房间:qq.exitVoIPChat
  • 更新房间麦克风/耳机静音设置:qq.updateVoIPChatMuteConfig
  • 监听房间成员变化:qq.onVoIPChatMembersChanged
  • 监听房间成员通话状态变化:qq.onVoIPChatSpeakersChanged
  • 监听通话中断:qq.onVoIPChatInterrupted

签名算法

生成签名需要小游戏传入四个参数:

参数名 说明
appId 小游戏的 appId
groupId 游戏房间的唯一标识,由游戏自己保证唯一
nonceStr 随机字符串,长度应小于 128
timeStamp 生成这个随机字符串的 UNIX 时间戳(精确到秒)

签名算法为:

signature = hmac_sha256([appId, groupId, nonceStr, timeStamp].sort().join(''), sessionKey)

具体来说,这个算法分为几个步骤:

  • 对 appId groupId nonceStr timeStamp 四个值表示成字符串形式,按照字典序排序;
  • 将排好序的四个字符串拼接在一起;
  • 使用 session_key 作为 key,使用 hmac_sha256 算法对 2 中的结果字符串做计算,所得结果即为 signature

示例:

appId = 'wx20afc706a711eefc'

groupId = '1559129713_672975982'

nonceStr = '8AP6DT9ybtniUJfb'

timeStamp = '1559129714'

session_key = 'gDyVgzwa0mFz9uUP7M6GQQ=='

str = [appId, groupId, nonceStr, timeStamp].sort().join('') = '1559129713_67297598215591297148AP6DT9ybtniUJfbwx20afc706a711eefc'

signature = hmac_sha256('1559129713_67297598215591297148AP6DT9ybtniUJfbwx20afc706a711eefc', sessionKey) = 'b002b824688dd8593a6079e11d8c5e8734fbcb39a6d5906eb347bfbcad79c617'

joinVoIPChat

qq.joinVoIPChat(Object object)

加入 (创建) 实时语音通话

参数

Object object

属性 类型 默认值 必填 说明
signature String 签名,用于验证小游戏的身份
nonceStr String 验证所需的随机字符串
timeStamp Number 验证所需的时间戳
groupId String 小游戏内此房间/群聊的 ID。同一时刻传入相同 groupId 的用户会进入到同个实时语音房间。
muteConfig Object 静音设置
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

object.muteConfig 的结构

属性 类型 默认值 必填 说明
muteMicrophone Boolean 0 是否静音麦克风
muteEarphone Boolean 0 是否静音耳机

object.sucess 回调函数

参数

Object res

属性 类型 说明
openIdList Array<String> 在此通话中的成员 openId 名单
errCode Number 错误码
errMsg String 调用结果

错误

错误码 错误信息 说明
-1 系统内部错误
-2 录音设备被占用,可能是当前正在使用QQ内语音通话或系统通话
-3 重复调用或重复进房
1 进入语音房超时

exitVoIPChat

qq.exitVoIPChat(Object object)

退出(销毁)实时语音通话

参数

Object object

属性 类型 默认值 必填 说明
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

updateVoIPChatMuteConfig

qq.updateVoIPChatMuteConfig(Object object)

更新实时语音静音设置

参数

Object object

属性 类型 默认值 必填 说明
muteConfig Object 静音设置
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

object.muteConfig 的结构

属性 类型 默认值 必填 说明
muteMicrophone Boolean 0 是否静音麦克风
muteEarphone Boolean 0 是否静音耳机

onVoIPChatMembersChanged

qq.onVoIPChatMembersChanged(function callback)

监听实时语音通话成员在线状态变化事件。有成员加入/退出通话时触发回调

参数

function callback

实时语音通话成员在线状态变化事件的回调函数

参数

Object res

属性 类型 说明
openIdList Array<String> 还在实时语音通话中的成员 openId 名单
errCode Number 错误码
errMsg String 调用结果

onVoIPChatSpeakersChanged

qq.onVoIPChatSpeakersChanged(function callback)

监听实时语音通话成员通话状态变化事件。有成员开始/停止说话时触发回调

参数

function callback

实时语音通话成员通话状态变化事件的回调函数

参数

Object res

属性 类型 说明
openIdList Array<String> 还在实时语音通话中的成员 openId 名单
errCode Number 错误码
errMsg String 调用结果(错误原因)

onVoIPChatInterrupted

qq.onVoIPChatInterrupted(function callback)

监听被动断开实时语音通话事件。包括小游戏切入后端时断开

参数

function callback

被动断开实时语音通话事件的回调函数

参数

Object res

属性 类型 说明
errCode Number 错误码
errMsg String 调用结果(错误原因)