文档

实时语音是用于实现游戏房间内多人实时语音功能的服务。基础库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 调用结果（错误原因）

← qq.getLocation →