Talk SDK for Cocos2d Lua API接口手册

本页各接口按语法、功能、参数说明、返回值、异步回调介绍；无参数、无返回值或无独立异步完成事件时明确标注。返回类型、回调载荷及线程以本平台封装为准。

API调用说明

添加如下代码： cc.exports.youmetalk = cc.YTalk:create() API的调用可使用“cc.exports.youmetalk:”来直接操作。接口使用的基本流程为初始化->收到初始化成功回调通知->加入语音频道->收到加入频道成功回调通知->使用其它接口->离开语音频道->反初始化，要确保严格按照上述的顺序使用接口。

实现回调

回调经 Cocos 调度器转到游戏主线程。通用事件、成员变化和房间广播按以下方式注册；当前绑定要求固定 4 个回调位置，第二个位置保留空函数即可，不接入 REST。

LUA

local talk = cc.exports.youmetalk
talk.OnEvent = function(event, error, channel, param)
    -- 初始化/进退房等通用结果；音量事件按定义读取 error 数值。
end
local unusedCallback = function(...) end
talk.OnMemberChange = function(channel, memberListJson, isUpdate)
    -- JSON 含 channelid、memchange 数组；每项 userid 和 isJoin。
    -- isUpdate=false 首次查询，true 增量变更。
end
talk.OnBroadcast = function(bc, channel, param1, param2, content)
    -- 按广播类型处理；文本消息由 OnEvent 接收。
end
talk:registerScriptHandler(talk.OnEvent, unusedCallback, talk.OnMemberChange, talk.OnBroadcast)

不要照搬仓库示例的 6 回调注册方式；当前 Lua 绑定只接收 4 个回调，网络/统计/PCM 未向 Lua 转发，不应注册虚构的脚本回调。

初始化

语法

LUA

init(strAppKey, strAPPSecret, serverRegionId, strExtServerRegionName);

功能

初始化语音引擎，做APP验证和资源初始化（只有appkey,appsecret,serverRegionId 都一样时,才可以进行语音互通,改任意一个视为另外一个区服）。

参数说明

strAPPKey：string，从游密后台申请到的 app key, 这个是你们应用程序的唯一标识。

strAPPSecret：string，对应 strAPPKey 的私钥, 这个需要妥善保存，不要暴露给其他人。

serverRegionId：int，设置首选连接服务器的区域码，建议直接使用10001。如果YOUME_RTC_SERVER_REGION定义的区域码不能满足要求，可以把这个参数设为10000，然后通过后面的参数strExtServerRegionName 设置一个自定的区域值（如中国用 "cn" 或者 “ch"表示），然后把这个自定义的区域值同步给游密，我们将通过后台配置映射到最佳区域的服务器。

strExtServerRegionName：string,自定义的扩展的服务器区域名。可为空字符串“”。只有前一个参数serverRegionId设为10000时，此参数才有效（否则都将当空字符串“”处理）。

strAppKey：从游密控制台申请的 AppKey。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_INIT_OK：初始化成功，此后才能加入频道。
YOUME_EVENT_INIT_FAILED：初始化失败，常见原因包括网络或 AppKey/AppSecret 错误。

回调示例：

LUA

--  涉及到的主要回调事件有：
--  OnEvent
--  event: （0） - 表明初始化成功
--  event: （1） - 表明初始化失败，最常见的失败原因是网络错误或者 AppKey-AppSecret 错误

设置服务器区域

语法

LUA

setServerRegion(serverRegionId, strExtRegionName, bAppend);

功能

设置首选连接区域。初始区域通常通过初始化接口参数指定；需要调整时，等待初始化成功后、加入频道前调用。初始化前单独调用区域设置接口不会生效。所有参数及是否支持追加区域按本平台语法传入。

参数说明

serverRegionId：int,如果YOUME_RTC_SERVER_REGION定义的区域码不能满足要求，可以把这个参数设为 10000，然后通过后面的参数strExtServerRegionName 设置一个自定的区域值（如中国用 "cn" 或者 “ch"表示），然后把这个自定义的区域值同步给游密，我们将通过后台配置映射到最佳区域的服务器。

bAppend：true表示添加，false表示替换。

strExtRegionName：扩展区域名；仅扩展区域类型生效，否则传空字符串。

返回值

无（Lua 返回 nil）。

异步回调

无。本接口不单独返回异步完成通知。

语音频道管理

加入语音频道（单频道）

语法

LUA

joinChannelSingleMode(strUserID, strChannelID, roleType, bCheckRoomExist);

功能

加入语音频道（单频道模式，每个时刻只能在一个语音频道里面）。

参数说明

strUserID：string,全局唯一的用户标识，全局指在当前应用程序的范围内。

strChannelID：string, 全局唯一的频道标识，全局指在当前应用程序的范围内。

roleType：int,用户在语音频道里面的角色，见YouMeUserRole定义。

bCheckRoomExist ：是否检查频道存在时才加入，默认为false: true 当频道存在时加入、不存在时返回错误（多用于观众角色），false 无论频道是否存在都加入频道。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_JOIN_OK：加入频道成功。
YOUME_EVENT_JOIN_FAILED：加入频道失败，按 err 处理原因。

回调示例：

LUA

-- 涉及到的主要回调事件有：
-- OnEvent
-- event:2 - 成功进入语音频道
-- event:3 - 进入语音频道失败，可能原因是网络或服务器有问题，或是bCheckRoomExist为true时频道还未创建

加入语音频道（多频道）

语法

LUA

joinChannelMultiMode(strUserID, strChannelID, roleType, bCheckRoomExist);

功能

加入语音频道（多频道模式，可以同时听多个语音频道的内容，但每个时刻只能对着一个频道讲话）。

参数说明

strUserID：string,全局唯一的用户标识，全局指在当前应用程序的范围内。

strChannelID：string,全局唯一的频道标识，全局指在当前应用程序的范围内。

roleType：int，用户在语音频道里面的角色，见YouMeUserRole定义
bCheckRoomExist ：是否检查频道存在时才加入，默认为false: true 当频道存在时加入、不存在时返回错误（多用于观众角色），false 无论频道是否存在都加入频道。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_JOIN_OK：加入频道成功。
YOUME_EVENT_JOIN_FAILED：加入频道失败，按 err 处理原因。

回调示例：

LUA

-- 涉及到的主要回调事件有：
--  OnEvent
--  event: 2 - 成功进入语音频道
--  event: 3 - 进入语音频道失败，可能原因是网络或服务器有问题，或是bCheckRoomExist为true时频道还未创建

指定讲话频道

语法

LUA

speakToChannel(strChannelID);

功能

多频道模式下，指定当前要讲话的频道。

参数说明

strChannelID：string,全局唯一的频道标识，全局指在当前应用程序的范围内。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_SPEAK_SUCCESS：成功切换到指定讲话频道。
YOUME_EVENT_SPEAK_FAILED：切换失败，按 err 处理网络或服务端等原因。

回调示例：

LUA

-- 涉及到的主要回调事件有：
--  OnEvent
--  event: 8 - 成功切入到指定语音频道
--  event: 9 - 切入指定语音频道失败，可能原因是网络或服务器有问题

退出指定的语音频道

语法

LUA

leaveChannelMultiMode(strChannelID);

功能

多频道模式下，退出指定的语音频道。

参数说明

strChannelID：string,全局唯一的频道标识，全局指在当前应用程序的范围内。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_LEAVED_ONE：已退出指定频道。

回调示例：

LUA

-- 涉及到的主要回调事件有：
--  OnEvent
--  event: 4 - 退出指定语音频道完成

退出所有语音频道

语法

LUA

leaveChannelAll();

功能

退出所有的语音频道（单频道模式下直接调用此函数离开频道即可）。

参数说明

无。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_LEAVED_ALL：已退出全部频道。

回调示例：

LUA

-- 涉及到的主要回调事件有：
--  OnEvent
--  event: 5 - 退出所有语音频道完成

设置白名单用户

语法

LUA

setWhiteUserList(strChannelID, strWhiteUserList);

功能

设置当前用户的语音消息接收白名单，其语音消息只会转发到白名单的用户，不设置该接口则默认转发至频道内所有人。

参数说明

strChannelID：要设置的频道(兼容多频道模式，单频道模式下传入当前频道即可)。

strWhiteUserList：白名单用户列表, 以|分隔，如：User1|User2|User3；表示语音消息只发送到User1,User2,User3. "all"表示转发至频道内所有人；设置为自己表示不转发至任何用户。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_SET_WHITE_USER_LIST_OK：白名单设置完成；存在异常用户时 err 可为 YOUME_ERROR_WHITE_SOMEUSER_ABNORMAL。
YOUME_EVENT_SET_WHITE_USER_LIST_FAILED：设置失败。

回调示例：

LUA

-- 涉及到的主要回调事件有：
--  OnEvent
--  event: 62 - 成功在指定语音频道设置白名单，有异常用户会返回错误码-501
--  event: 63 - 在指定语音频道设置白名单失败，可能原因是网络或服务器有问题

设置黑名单用户

语法

LUA

setListenOtherVoice(strUserID, on);

功能

设置指定用户的语音接收黑名单状态，控制本机是否接收该用户的语音。

参数说明

strUserID：要设置黑名单状态的用户 ID。

on：false 将指定用户加入语音接收黑名单，屏蔽该用户的语音；true 将其移出黑名单，恢复接收其语音。

返回值

int，如果成功返回0，否则返回错误码，请参考YouMeErrorCode类型定义。

异步回调

没有本次设置的独立完成事件。相关屏蔽状态通知使用 YOUME_EVENT_LISTEN_OTHER_ON / YOUME_EVENT_LISTEN_OTHER_OFF，按通用事件定义处理。

回调示例：

LUA

--  涉及到的主要回调事件有(被控制方收到)：
--  OnEvent
--  event: 27 - 取消屏蔽某人语音
--  event: 28 - 屏蔽某人语音

设置用户角色

语法

LUA

setUserRole(role);

功能

仅支持单频道，进房成功后切换当前用户角色。

参数说明

role：用户角色，使用本平台角色类型/常量，不能传无效角色。

返回值

角色为整数，返回错误码；角色变化事件 77 的错误码字段携带角色值。

异步回调

通过注册的 OnEvent 函数接收 YOUME_EVENT_IDENTITY_MODIFY；错误字段携带角色值，应按本平台角色类型解释，不作为错误码。

获取用户角色

语法

LUA

getUserRole();

功能

获取用户角色（getUserRole）。

参数说明

无。

返回值

同步返回本平台用户角色枚举/角色值，不是错误码。仅支持单频道，应在进房成功后查询。

异步回调

无。本接口不单独返回异步完成通知。

加入语音频道

语法

LUA

joinChannel(userID, channelID, role, singleMode, checkRoomExist);

功能

当前统一入口，用户、频道、角色、单频道模式、检查房间存在共 5 个业务参数。

singleMode 为 true 是单频道，false 是多频道；检查参数为 true 时仅加入已存在房间。

旧 joinChannelSingleMode/joinChannelMultiMode 仍有绑定，可继续用于兼容。

参数说明

userID：用户 ID，在当前应用内唯一。

channelID：频道 ID，在当前应用内唯一。

role：用户角色，使用本平台角色类型/常量，不能传无效角色。

singleMode：true 为单频道，加入时退出其他频道；false 为多频道，可用指定讲话频道接口选择讲话目标。

checkRoomExist：true 只加入已存在的频道；false 允许加入尚未存在的频道。

返回值

返回错误码，成功受理后等待 OnEvent 的进房成功/失败事件。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_JOIN_OK：加入频道成功。
YOUME_EVENT_JOIN_FAILED：加入频道失败，按 err 处理原因。

退出指定频道

语法

LUA

leaveChannel(channelID);

功能

原 leaveChannelMultiMode 兼容别名仍有效。

参数说明

channelID：频道 ID，在当前应用内唯一。

返回值

退出指定频道，返回错误码；成功后等待离房结果事件。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_LEAVED_ONE：已退出指定频道。

查询频道用户列表

语法

LUA

getChannelUserList(strChannelID, maxCount, notifyMemChange);

功能

查询频道当前的用户列表， 并设置是否获取频道用户进出的通知（OnMemberChange）。（必须自己在频道中）

参数说明

strChannelID：string,频道ID。

maxCount：int,想要获取的最大人数。-1表示获取全部列表。

notifyMemChange：其他用户进出房间时，是否要收到通知。（设置为true，自己所在频道有人进出都会有对应回调产生，反之false就没有对应回调）

返回值

返回整数错误码，YOUME_SUCCESS 表示本次调用成功；其他值表示失败，参见错误码定义。

异步回调

通过已注册的 OnMemberChange(channel, memberJson, update) 回调接收列表及变更，update 区分首次与增量。

LUA

-- strChannel:string,频道ID
-- memchanges:对象数组，查询获得的用户列表，或变更列表。
-- 每一个数组的数据，包含userID和isJoin两个字段
onMemberChange(  strChannel,  memchanges )

首次查询用户列表时，假设当前房间内用户数是curCount， 1、当传入的maxCount >= curCount时： OnMemberChange回调一次，返回房间内所有curCount个用户。 2、当传入的maxCount < curCount时，OnMemberChange回调两次：第一次返回maxCount个用户；第二次返回其余curCount-maxCount个用户。 3、当传入的maxCount = -1时，OnMemberChange回调两次：第一次只返回一个用户(按照用户id排序的最小值)；第二次返回房间内剩余的curCount-1个用户。

把人踢出房间

语法

LUA

kickOtherFromChannel(userID, channelID, lastTime);

功能

把人踢出房间。

参数说明

userID：被踢的用户ID。

channelID：从哪个房间踢出（自己需要在房间）。

lastTime：踢出后，多长时间内不允许再次进入（单位：秒）。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_KICK_RESULT：踢人方收到操作结果，param 为被踢者 ID。
YOUME_EVENT_KICK_NOTIFY：被踢方收到通知并退出频道；param 携带踢人者 ID、原因及被禁时长。

回调示例：

LUA

--  涉及到的主要回调事件有：
--  OnEvent
--  event: 64 - 踢人方收到，发送消息的结果回调，param为被踢者ID
--  event: 65 - 被踢方收到，被踢通知，会自动退出所在频道。param: （踢人者ID，被踢原因，被禁时间）

设备状态管理

切换语音输出设备

语法

LUA

setOutputToSpeaker(bOutputToSpeaker);

功能

默认输出到扬声器，在加入房间成功后设置。（iOS受系统限制，如果已释放麦克风则无法切换到听筒；Android需要在app的AndroidManifest文件中添加android.permission.MODIFY_AUDIO_SETTINGS权限）

参数说明

bOutputToSpeaker ：true——输出到扬声器，false——输出到听筒。

返回值

int，如果成功返回0，否则返回错误码，请参考YouMeErrorCode类型定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_SWITCH_OUTPUT：语音输出设备切换结果，按 err 判断。

设置扬声器状态

语法

LUA

setSpeakerMute(mute);

功能

设置本机扬声器静音状态，加入频道成功后配置；设备状态异步生效。

参数说明

mute:true——关闭扬声器，false——开启扬声器。

返回值

无（Lua 返回 nil）。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_LOCAL_SPEAKER_ON：本机扬声器开启状态通知，按 err 判断结果。
YOUME_EVENT_LOCAL_SPEAKER_OFF：本机扬声器关闭状态通知，按 err 判断结果。

获取扬声器状态

语法

LUA

getSpeakerMute();

功能

同步读取 SDK 当前设备静音状态配置。设备开关异步生效，设置后立即查询不代表硬件已完成切换。

参数说明

无。

返回值

true 表示设备静音/关闭，false 表示开启。读取 SDK 当前状态，不保证硬件已完成切换。

异步回调

无。本接口不单独返回异步完成通知。

设置麦克风状态

语法

LUA

setMicrophoneMute(mute);

功能

设置本机麦克风静音状态，加入频道成功后配置；设备状态异步生效。

参数说明

mute:true——关闭麦克风，false——开启麦克风。

返回值

无（Lua 返回 nil）。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_LOCAL_MIC_ON：本机麦克风开启状态通知，按 err 判断结果。
YOUME_EVENT_LOCAL_MIC_OFF：本机麦克风关闭状态通知，按 err 判断结果。

获取麦克风状态

语法

LUA

getMicrophoneMute();

功能

同步读取 SDK 当前设备静音状态配置。设备开关异步生效，设置后立即查询不代表硬件已完成切换。

参数说明

无。

返回值

true 表示设备静音/关闭，false 表示开启。读取 SDK 当前状态，不保证硬件已完成切换。

异步回调

无。本接口不单独返回异步完成通知。

设置是否通知别人麦克风和扬声器的开关

语法

LUA

setAutoSendStatus(bAutoSend);

功能

设置是否通知别人,自己麦克风和扬声器的开关状态。（建议进入频道后调用，设置后其他当前在同一个频道的用户可以获取该用户的麦克风和扬声器的开关状态。对应回调事件 YouMeEvent.YOUME_EVENT_OTHERS_MIC_ON, YouMeEvent.YOUME_EVENT_OTHERS_MIC_OFF, YouMeEvent.YOUME_EVENT_OTHERS_SPEAKER_ON, YouMeEvent.YOUME_EVENT_OTHERS_SPEAKER_OFF, 事件对应具体详细请参考状态码。）

参数说明

bAutoSend:true——通知，false——不通知。

相关回调

LUA

--  涉及到的主要回调事件有(房间里的其他人会收到)：
--  OnEvent
--  event: 16 - 其他用户麦克风打开
--  event: 17 - 其他用户麦克风关闭
--  event: 18 - 其他用户扬声器打开
--  event: 19 - 其他用户扬声器关闭

返回值

无（Lua 返回 nil）。

异步回调

设置本身没有独立完成事件；开启后同频道其他用户可接收 YOUME_EVENT_OTHERS_MIC_ON/OFF、YOUME_EVENT_OTHERS_SPEAKER_ON/OFF 状态通知。

设置扬声器音量增益

语法

LUA

setVolume(volume);

功能

设置扬声器音量增益，实际扬声器音量 = 扬声器音量增益 x 系统音量；百分比 100 对应乘法系数 1。

参数说明

volume：扬声器音量增益，0～100（百分比），100 对应乘法系数 1；实际扬声器音量 = 扬声器音量增益 x 系统音量。

返回值

无（Lua 返回 nil）。

异步回调

无。本接口不单独返回异步完成通知。

获取扬声器音量增益

语法

LUA

getVolume();

功能

获取 SDK 当前扬声器音量增益。实际扬声器音量 = 扬声器音量增益 x 系统音量；100% 增益对应乘法系数 1。

参数说明

无。

返回值

返回 SDK 当前扬声器音量增益，范围 0～100（百分比），不是实际扬声器音量。

异步回调

无。本接口不单独返回异步完成通知。

控制他人麦克风

语法

LUA

setOtherMicMute(strUserID, mute);

功能

控制他人的麦克风状态（也就是关闭或者开启他人的麦克风）。

参数说明

strUserID：string,要控制的用户ID

mute：是否静音。true:静音别人的麦克风，false：开启别人的麦克风

返回值

int，如果成功返回0，否则返回错误码，请参考YouMeErrorCode类型定义。

相关回调

LUA

--  涉及到的主要回调事件有(被控制方收到)：
--  OnEvent
--  event: 23 - 麦克风被其他用户打开
--  event: 24 - 麦克风被其他用户关闭

异步回调

没有调用方的独立完成事件；被控制端通过通用事件 YOUME_EVENT_MIC_CTR_ON / YOUME_EVENT_MIC_CTR_OFF 接收麦克风控制通知。

控制他人扬声器

语法

LUA

setOtherSpeakerMute(strUserID, mute);

功能

控制他人的扬声器状态（也就是关闭或者开启他人的扬声器）。

参数说明

strUserID：string,要控制的用户ID。

mute：是否静音。true:静音别人的扬声器，false：开启别人的扬声器。

返回值

int，如果成功返回0，否则返回错误码，请参考YouMeErrorCode类型定义。

相关回调

LUA

--  涉及到的主要回调事件有(被控制方收到)：
--  OnEvent
--  event: 25 - 扬声器被其他用户打开
--  event: 26 - 扬声器被其他用户关闭

异步回调

没有调用方的独立完成事件；被控制端通过通用事件 YOUME_EVENT_SPEAKER_CTR_ON / YOUME_EVENT_SPEAKER_CTR_OFF 接收扬声器控制通知。

设置当麦克风静音时，是否释放麦克风设备

语法

LUA

setReleaseMicWhenMute(enabled);

功能

设置当麦克风静音时，是否释放麦克风设备（需要在初始化成功后，加入房间之前调用）

参数说明

enabled： true--当麦克风静音时，释放麦克风设备，此时允许第三方模块使用麦克风设备录音。在Android和iOS上，语音由通话音轨切换到媒体音轨，回归到双声道高音质输出体验（如果媒体音量和通话音量不同时切换会产生音量变大变小的感觉）；false--不管麦克风是否静音，麦克风设备都会被占用。

返回值

返回整数错误码，YOUME_SUCCESS 表示本次调用成功；其他值表示失败，参见错误码定义。

异步回调

无。本接口不单独返回异步完成通知。

设置插入耳机时，是否自动退出系统通话模式

语法

LUA

setExitCommModeWhenHeadsetPlugin(enabled);

功能

设置插入耳机时，是否自动退出系统通话模式(禁用手机系统硬件信号前处理)。系统提供的前处理效果包括回声消除、自动增益等，有助于抑制战歌等回声噪音，减少系统资源消耗，对Windows系统无效。默认为false，在初始化之后、加入房间之前调用。

参数说明

enabled： true--当插入耳机时，自动禁用系统硬件信号前处理，拔出时还原；false--插拔耳机不做处理。

返回值

成功返回YOUME_SUCCESS，其它返回值请参考YouMeErrorCode类型定义。

异步回调

无。本接口不单独返回异步完成通知。

说话及音量检测

设置语音检测

语法

LUA

setVadCallbackEnabled(bEnabled);

功能

设置是否开启语音检测回调，开启后频道内有人正在讲话与结束讲话都会发起相应回调通知。（需要游密后台配置开启，该状态值在加入房间成功后设置才有效，并且需要频道内所有用户都设置才生效。）

参数说明

bEnabled:true——打开，false——关闭。

返回值

无（Lua 返回 nil）。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_OTHERS_VOICE_ON：其他用户进入讲话状态。
YOUME_EVENT_OTHERS_VOICE_OFF：其他用户进入静默状态。

回调示例：

LUA

-- 主要回调事件：
--  OnEvent
--  event: 20 - 其他用户进入讲话状态
--  event: 21 - 其他用户进入静默状态

设置本地讲话音量级别回调

语法

LUA

setMicLevelCallback(maxLevel);

功能

设置是否开启监听自己讲话音量回调, 并设置相应的参数。

参数说明

maxLevel:音量最大时对应的级别，需大于1，最大可设100。根据实际需要设置小于100的值可以减少回调的次数（注意设置较高的值可能会产生大量回调，特别在Unity上会影响其它事件到达，一般建议不超过30）。比如你只在UI上呈现10级的音量变化，那就设10就可以了。设 0 表示关闭回调。

返回值

int，如果成功则返回0，其他返回值请参考YouMeErrorCode类型定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_MY_MIC_LEVEL：本机讲话音量级别；读取错误字段的整数业务数值读取音量值，不按错误码判断。

通话管理

暂停通话

语法

LUA

pauseChannel();

功能

暂停通话，释放对麦克风等设备资源的占用。当需要用第三方模块临时录音时，可调用这个接口。

参数说明

无。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_PAUSED：暂停语音频道完成。

回调示例：

LUA

-- 主要回调事件：
--  OnEvent
--  event: 6 - 暂停语音频道完成

恢复通话

语法

LUA

resumeChannel();

功能

恢复通话，调用PauseChannel暂停通话后，可调用这个接口恢复通话。（恢复通话后的麦克风的状态是和重新恢复通话时的角色相关，不一定与PauseChannel暂停通话时的麦克风状态一致）

参数说明

无。

返回值

返回整数错误码，YOUME_SUCCESS 表示请求已受理；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_RESUMED：恢复语音频道完成。

回调示例：

LUA

-- 主要回调事件：
--  OnEvent
--  event: 7 - 恢复语音频道完成

战歌管理

播放战歌

语法

LUA

playBackgroundMusic(strFilePath, bRepeat);

功能

播放指定的音乐文件。播放的音乐将会通过扬声器输出，并和语音混合后发送给接收方。这个功能必须进入频道传入身份为主播/指挥才能使用。建议使用mp3格式的文件，目前wav、flac格式的文件不支持。（windows程序目前只支持win32程序，win64程序暂不支持）

参数说明

strFilePath：音乐文件的路径。

bRepeat：是否重复播放，true——重复播放，false——只播放一次就停止播放。

返回值

返回整数错误码，YOUME_SUCCESS 表示本次调用成功；其他值表示失败，参见错误码定义。

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_BGM_STOPPED：战歌播放结束。
YOUME_EVENT_BGM_FAILED：战歌播放失败。

回调示例：

LUA

-- 主要回调事件：
--  OnEvent
--  event: 13 - 通知战歌播放结束
--  event: 14 - 通知战歌播放失败

停止播放战歌

语法

LUA

stopBackgroundMusic();

功能

停止播放当前正在播放的战歌。这是一个同步调用接口，函数返回时，音乐播放也就停止了。

参数说明

无。

返回值

int，如果成功返回0，表明成功停止了音乐播放流程；否则返回错误码，请参考YouMeErrorCode类型定义。

异步回调

无。本接口不单独返回异步完成通知。

设置战歌播放音量

语法

LUA

setBackgroundMusicVolume(vol);

功能

设定战歌的音量。这个接口用于调整战歌和语音之间的相对音量，使得战歌和语音混合听起来协调。这是一个同步调用接口。

参数说明

vol:int,战歌的音量，范围 [0-100]。

返回值

int，如果成功（表明成功设置了战歌的音量）返回0，否则返回错误码，具体请参考YouMeErrorCode类型定义。

异步回调

无。本接口不单独返回异步完成通知。

设置监听

语法

LUA

setHeadsetMonitorOn(micEnabled, bgmEnabled);

功能

设置是否用耳机监听本机的麦克风声音或战歌。这是一个同步调用接口，进入频道时使用主播/指挥身份才能使用。

参数说明

micEnabled:是否监听麦克风 true 监听，false 不监听。

bgmEnabled:是否监听战歌 true 监听，false 不监听。

返回值

无（Lua 返回 nil）。

异步回调

无。本接口不单独返回异步完成通知。

设置混响音效

语法

LUA

setReverbEnabled(bEnabled);

功能

设置是否开启混响音效，这个主要对主播/指挥有用。

参数说明

bEnabled:true——打开，false——关闭。

返回值

无（Lua 返回 nil）。

异步回调

无。本接口不单独返回异步完成通知。

变声音调

获取变声音调

语法

LUA

getSoundtouchPitchSemiTones();

功能

获取变声音调（增值服务，需要后台配置开启）。

参数说明

无。

返回值

返回当前变声音调值，范围 -12～+12。

异步回调

无。本接口不单独返回异步完成通知。

设置变声音调

语法

LUA

setSoundtouchPitchSemiTones(fPitchSemiTones);

功能

设置变声音调（增值服务，需要后台配置开启），需在进入房间成功后调用，仅对当前房间有效，退出房间时重置为0。目前该接口在windows中只支持win32。

参数说明

fPitchSemiTones:变声音调的值，范围[-12 ~ +12]。

返回值

int，如果成功则返回0，其他返回值请参考YouMeErrorCode类型定义。

异步回调

无。本接口不单独返回异步完成通知。

广播消息

语法

LUA

sendMessage(channelID, content);

功能

在语音频道内，广播一个文本消息。

参数说明

channelID：频道ID（自己需要进入这个频道）。

content：要广播的文本内容。

返回值

返回负值表示错误码，非负值为 requestID。应保存 requestID 用于关联发送结果，不能只与 YOUME_SUCCESS 比较；

异步回调

通过注册的 OnEvent 函数接收：

YOUME_EVENT_SEND_MESSAGE_RESULT：发送结果，param 为回传 requestID。
YOUME_EVENT_MESSAGE_NOTIFY：频道内其他用户收到文本消息，param 为 content 内容。

回调示例：

LUA

--  涉及到的主要回调事件有：
--  OnEvent
--  event: 60 - 发送消息的结果，param为requestID的字符串
--  event: 61 - 频道内其他人收到消息的通知。param为文本内容

设置时间戳

设置录音时间戳

语法

LUA

setRecordingTimeMs(timeMs);

功能

设置当前录音的时间戳。当通过录游戏脚本进行直播时，要保证观众端音画同步，在主播端需要进行时间对齐。这个接口设置的就是当前游戏画面录制已经进行到哪个时间点了。

参数说明

timeMs:unsigned int, 当前游戏画面对应的时间点，单位为毫秒。

返回值

无（Lua 返回 nil）。

异步回调

无。本接口不单独返回异步完成通知。

设置播放时间戳

语法

LUA

setPlayingTimeMs(timeMs);

功能

设置当前声音播放的时间戳。当通过录游戏脚本进行直播时，要保证观众端音画同步，游戏画面的播放需要和声音播放进行时间对齐。这个接口设置的就是当前游戏画面播放已经进行到哪个时间点了。

参数说明

timeMs:unsigned int,当前游戏画面播放对应的时间点，单位为毫秒。

返回值

无（Lua 返回 nil）。

异步回调

无。本接口不单独返回异步完成通知。

移动网络设置

设置是否允许使用移动网络

语法

LUA

setUseMobileNetworkEnabled(bEnabled);

功能

设置是否允许使用移动网络。在WIFI和移动网络都可用的情况下会优先使用WIFI，在没有WIFI的情况下，如果设置允许使用移动网络，那么会使用移动网络进行语音通信，否则通信会失败。该接口需要在初始化后，加入房间前设置。

参数说明

bEnabled:true——允许使用移动网络，false——禁止使用移动网络。

返回值

无（Lua 返回 nil）。

异步回调

无。本接口不单独返回异步完成通知。

获取是否允许使用移动网络

语法

LUA

getUseMobileNetworkEnabled();

功能

获取是否允许SDK在没有WIFI的情况使用移动网络进行语音通信。

参数说明

无。

返回值

true——允许使用移动网络，false——禁止使用移动网络，默认情况下允许使用移动网络。

异步回调

无。本接口不单独返回异步完成通知。

反初始化

语法

LUA

unInit();

功能

反初始化引擎，可在退出游戏时调用，以释放SDK所有资源。

参数说明

无。

返回值

int，如果成功则返回0，其他返回值请参考YouMeErrorCode类型定义。

异步回调

无。本接口不单独返回异步完成通知。

文档目录

Talk SDK for Cocos2d Lua API接口手册

相关异步/同步处理方法介绍

API调用说明

实现回调

初始化

设置服务器区域

语音频道管理

加入语音频道（单频道）

加入语音频道（多频道）

指定讲话频道

退出指定的语音频道

退出所有语音频道

设置白名单用户

设置黑名单用户

设置用户角色

获取用户角色

加入语音频道

退出指定频道

查询频道用户列表

把人踢出房间

设备状态管理

切换语音输出设备

设置扬声器状态

获取扬声器状态

设置麦克风状态

获取麦克风状态

设置是否通知别人麦克风和扬声器的开关

设置扬声器音量增益

获取扬声器音量增益

控制他人麦克风

控制他人扬声器

设置当麦克风静音时，是否释放麦克风设备

设置插入耳机时，是否自动退出系统通话模式

说话及音量检测

设置语音检测

设置本地讲话音量级别回调

通话管理

暂停通话

恢复通话

战歌管理

播放战歌

停止播放战歌

设置战歌播放音量

设置监听

设置混响音效

变声音调

获取变声音调

设置变声音调

广播消息

设置时间戳

设置录音时间戳

设置播放时间戳

移动网络设置

设置是否允许使用移动网络

获取是否允许使用移动网络

反初始化