Talk SDK for Cocos2d C++ API接口手册

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

API调用说明

API的调用可使用“IYouMeVoiceEngine::getInstance ()->”来直接操作，接口使用的基本流程为初始化->收到初始化成功回调通知->加入语音频道->收到加入频道成功回调通知->使用其它接口->离开语音频道->反初始化，要确保严格按照上述的顺序使用接口。

实现回调

实现 IYouMeEventCallback，并将回调对象指针作为 init 的第一个参数。对象在 SDK 使用期间保持有效。原生回调不保证在 Cocos/Windows UI 主线程执行，界面操作需投递到主线程。

C++

#include "IYouMeVoiceEngine.h"

class CYMEventCallback : public IYouMeEventCallback {
public:
    void onEvent(YouMeEvent event, YouMeErrorCode error,
                 const char *channel, const char *param) override {
        switch (event) {
        case YOUME_EVENT_INIT_OK:
            // 初始化完成，现在可以加入频道。
            break;
        case YOUME_EVENT_INIT_FAILED:
            // 读取 error，停止后续流程。
            break;
        case YOUME_EVENT_JOIN_OK:
            // 进房完成，现在可以设置音频状态。
            break;
        case YOUME_EVENT_JOIN_FAILED:
            // 处理进房失败。
            break;
        case YOUME_EVENT_LEAVED_ALL:
            // 已退出全部频道。
            break;
        default:
            // 按事件解释 error/param；音量事件会复用 error 为数值。
            break;
        }
    }
};

成员列表、网络检测、音频统计及房间广播使用各自的回调接口对象注册。网络检测、音频统计、房间广播及 PCM 回调的设置，详见本页回调注册与设置；说话状态及本地、远端讲话音量的检测，详见说话及音量检测。

回调注册与设置

本节集中介绍网络检测、音频统计、房间广播及 PCM 数据回调的注册与设置。这些数据通过对应的回调接口对象接收；具体接收方式见各接口的“异步回调”说明。

注册网络检测回调

语法

C++

void setDetectNetworkCallback(IYouMeDetectNetworkCallback *pCallback);

功能

配合 detectNetworkQuality 使用。

strResult 为 JSON，avgRtt 单位毫秒，lossPer 范围 0～1。

传入实现 IYouMeDetectNetworkCallback 的对象，保持对象在使用期间有效；不直接在 SDK 线程操作游戏 UI。

参数说明

pCallback：实现签名所需回调接口的对象，使用期间保持有效；在 SDK 回调线程处理，操作游戏 UI 前切回主线程。

返回值

无（void）。

异步回调

示例与补充说明：

C++

virtual void onDetectNetWorkCompleteCb(bool bNetworkOK, const char *strResult) = 0;

注册音频统计回调

语法

C++

void setAVStatisticNewCallback(IYouMeAVStatisticNewCallback *cb);

功能

按 type 解释 value：音频码率/带宽 Bps，音频丢包率千分比，音频延迟毫秒。

传入实现 IYouMeAVStatisticNewCallback 的对象，保持对象在使用期间有效；不直接在 SDK 线程操作游戏 UI。

参数说明

cb：实现签名所需回调接口的对象，使用期间保持有效；在 SDK 回调线程处理，操作游戏 UI 前切回主线程。

返回值

无（void）。

异步回调

示例与补充说明：

C++

virtual void onAVStatisticNew(YouMeAVStatisticType type, const char *userID, int value, const char *param) = 0;

注册房间广播回调

语法

C++

void setNotifyCallback(IYouMeChannelMsgCallback *cb);

功能

接收抢麦/连麦广播，param1/param2/content 随广播类型变化；普通文本仍通过通用事件 YOUME_EVENT_MESSAGE_NOTIFY 接收。

传入实现 IYouMeChannelMsgCallback 的对象，保持对象在使用期间有效；不直接在 SDK 线程操作游戏 UI。

参数说明

cb：实现签名所需回调接口的对象，使用期间保持有效；在 SDK 回调线程处理，操作游戏 UI 前切回主线程。

返回值

无（void）。

异步回调

示例与补充说明：

C++

virtual void onBroadcast(YouMeBroadcast bc, const char *channel, const char *param1, const char *param2, const char *content) = 0;

设置音频数据回调

语法

C++

YouMeErrorCode setPcmCallbackEnable(IYouMePcmCallback *pcmCallback, int flag, bool bOutputToSpeaker = true, int nOutputSampleRate = 16000, int nOutputChannel = 1);

功能

回调对象实现 IYouMePcmCallback 的 onPcmDataRemote/onPcmDataRecord/onPcmDataMix，分别接收远端、录音和混合数据。

flag 使用状态码页 PCM 标志按位或组合；outputToSpeaker 控制是否继续由 SDK 播放远端声音，采样率和声道使用声明默认值或受支持配置。

指针仅在回调期间有效；跨线程处理先复制数据。

未选中的数据类型不产生对应回调。

参数说明

pcmCallback：实现签名所需回调接口的对象，使用期间保持有效；在 SDK 回调线程处理，操作游戏 UI 前切回主线程。

flag：PCM 数据类型标志，远端、录音、混合类型按位或组合；定义见本平台状态码页。

bOutputToSpeaker：true 使用扬声器，false 使用听筒。

nOutputSampleRate：输出 PCM 采样率（Hz），使用 SDK 支持的配置。

nOutputChannel：输出 PCM 声道数，使用 SDK 支持的配置。

返回值

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

异步回调

回调参数为声道数、采样率、每采样字节数、数据指针及数据字节数。

回调派发配置

设置事件优先级

语法

C++

YouMeErrorCode setEventCallbackPriority(YouMeEvent event, YouMeMessagePriority priority);

功能

设置事件优先级（setEventCallbackPriority）。

参数说明

event：要设置/查询派发优先级的通用事件类型。

priority：派发优先级，使用本平台优先级枚举。

返回值

初始化成功后设置通用事件的优先级，priority 为 MsgPriority_Low/Middle/High，返回错误码；不改变事件含义或初始化/进房的等待要求。

异步回调

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

获取事件优先级

语法

C++

YouMeMessagePriority getEventCallbackPriority(YouMeEvent event);

功能

获取事件优先级（getEventCallbackPriority）。

参数说明

event：要设置/查询派发优先级的通用事件类型。

返回值

返回本平台事件优先级枚举；未初始化时返回默认中优先级，不能据此判断初始化状态。

异步回调

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

初始化

语法

C++

YouMeErrorCode init(IYouMeEventCallback *pEventCallback, const char *pAPPKey, const char *pAPPSecret, YOUME_RTC_SERVER_REGION serverRegionId, const char *pExtServerRegionName);

功能

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

pEventCallback：实现 IYouMeEventCallback 的回调对象指针，在回调使用期间保持有效。

参数说明

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

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

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

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

pEventCallback：实现签名所需回调接口的对象，使用期间保持有效；在 SDK 回调线程处理，操作游戏 UI 前切回主线程。

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

pAPPSecret：对应 AppKey 的 AppSecret。

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

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

回调示例：

C++

//涉及到的主要回调事件有：
// YOUME_EVENT_INIT_OK  - 表明初始化成功
// YOUME_EVENT_INIT_FAILED - 表明初始化失败，最常见的失败原因是网络错误或者 AppKey-AppSecret 错误
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

设置服务器区域

语法

C++

void setServerRegion(YOUME_RTC_SERVER_REGION regionId, const char *extRegionName, bool bAppend);

功能

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

参数说明

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

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

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

regionId：首选服务器区域。

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

返回值

无（void）。

异步回调

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

语音频道管理

加入语音频道

语法

C++

YouMeErrorCode joinChannel(const char *pUserID, const char *pChannelID, YouMeUserRole_t eUserRole, bool bSingleMode = false, bool bCheckRoomExist = false);

功能

初始化成功后加入频道。

用户 ID 在应用内唯一，频道 ID 用于区分语音房间；角色决定讲话及播放战歌等权限。

eUserRole 使用 YouMeUserRole_t 枚举；省略 bSingleMode 时默认是多频道。

bSingleMode 为 true：单频道，加入时自动退出原频道；false：多频道，可同时收听多个频道，通过 speakToChannel指定讲话频道。
bCheckRoomExist 为 true：仅加入已存在的房间；false：房间不存在时也允许加入。

参数说明

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

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

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

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

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

返回值

返回成功仅表示请求受理，等待 YOUME_EVENT_JOIN_OK / YOUME_EVENT_JOIN_FAILED 后再继续。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

指定讲话频道

语法

C++

YouMeErrorCode speakToChannel (const char* strChannelID);

功能

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

参数说明

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

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

回调示例：

C++

//涉及到的主要回调事件有：
//YOUME_EVENT_SPEAK_SUCCESS - 成功切入到指定语音频道
//YOUME_EVENT_SPEAK_FAILED - 切入指定语音频道失败，可能原因是网络或服务器有问题
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

退出指定的语音频道

语法

C++

YouMeErrorCode leaveChannel (const char* strChannelID);

功能

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

参数说明

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

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_LEAVED_ONE：已退出指定频道。

回调示例：

C++

//涉及到的主要回调事件有：
//YOUME_EVENT_LEAVED_ONE - 成功退出指定语音频道
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

退出所有语音频道

语法

C++

YouMeErrorCode leaveChannelAll ();

功能

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

参数说明

无。

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_LEAVED_ALL：已退出全部频道。

回调示例：

C++

//涉及到的主要回调事件有：
//YOUME_EVENT_LEAVED_ALL - 成功退出所有语音频道
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

设置白名单用户

语法

C++

YouMeErrorCode setWhiteUserList (const char* strChannelID, const char* strWhiteUserList);

功能

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

参数说明

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

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

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

回调示例：

C++

//涉及到的主要回调事件有：
//YOUME_EVENT_SET_WHITE_USER_LIST_OK - 成功在指定语音频道设置白名单，有异常用户会返回错误码YOUME_ERROR_WHITE_SOMEUSER_ABNORMAL
//YOUME_EVENT_SET_WHITE_USER_LIST_FAILED - 在指定语音频道设置白名单失败，可能原因是网络或服务器有问题
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

设置黑名单用户

语法

C++

YouMeErrorCode setListenOtherVoice (const char* userID,bool on);

功能

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

参数说明

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

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

返回值

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

异步回调

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

设置用户角色

语法

C++

YouMeErrorCode setUserRole(YouMeUserRole_t eUserRole);

功能

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

参数说明

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

返回值

角色影响讲话与播放战歌权限；先检查同步返回值。

异步回调

通过 IYouMeEventCallback::onEvent 接收 YOUME_EVENT_IDENTITY_MODIFY；错误字段携带角色值，应按本平台角色类型解释，不作为错误码。

获取用户角色

语法

C++

YouMeUserRole_t getUserRole();

功能

获取用户角色（getUserRole）。

参数说明

无。

返回值

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

异步回调

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

设置频道收听黑名单

语法

C++

YouMeErrorCode blockChannels(const char *channelList);

功能

多频道模式下设置不收听的频道；每次覆盖完整黑名单。

以竖线分隔的完整频道 ID 字符串，例如 "team1|team2"；空字符串清空黑名单。

参数说明

channelList：完整的频道收听黑名单；以 | 分隔频道 ID，空字符串清空。

返回值

返回成功后处理 YOUME_EVENT_BLOCK_CHANNELS（80）事件。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_BLOCK_CHANNELS：频道黑名单设置结果；err=YOUME_SUCCESS 表示成功，其他值按错误码处理。

查询是否在频道

语法

C++

bool isInChannel(const char *pChannelID);
bool isInChannel();

功能

无参数重载查询是否在任意频道，有参数重载查询指定频道。

参数说明

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

返回值

同步返回 bool。

异步回调

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

查询频道用户列表

语法

C++

YouMeErrorCode getChannelUserList( const char*  channelID, int maxCount, bool notifyMemChange );

功能

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

参数说明

channelID：频道ID。

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

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

返回值

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

异步回调

通过 IYouMeEventCallback::onMemberChange(channel, listMemberChange, bUpdate) 接收，bUpdate=false 为首次查询，true 为增量。

C++

//IYouMeMemberChangeCallback
// channel:频道ID
// memberChangeJsonStr:查询获得的用户列表，或变更列表
// bUpdate: false为第一次查询，true为增量通知
void onMemberChange( const char* channel, const char* memberChangeJsonStr, bool bUpdate ){
    // memberChangeJsonStr 数据格式：
    // {"channelid":"123","memchange":[{"isJoin":true,"userid":"u541"},{"isJoin":true,"userid":"u948"}]}
}

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

示例与补充说明：

C++

void setMemberChangeCallback( IYouMeMemberChangeCallback* cb );

把人踢出房间

语法

C++

YouMeErrorCode kickOtherFromChannel( const char* pUserID, const char* pChannelID, int lastTime );

功能

把人踢出房间。

参数说明

pUserID：被踢的用户ID。

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

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

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

回调示例：

C++

//IYouMeEventCallback
//event:YOUME_EVENT_KICK_RESULT: 踢人方收到，发送消息的结果回调，param为被踢者ID
//event:YOUME_EVENT_KICK_NOTIFY: 被踢方收到，被踢通知，会自动退出所在频道。param: （踢人者ID，被踢原因，被禁时间）
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

范围语音

加入范围语音频道

语法

C++

YouMeErrorCode joinRangeAudioChannel(const char *pUserID, const char *pChannelID, YouMeUserRole_t eUserRole, bool bSingleMode = false, bool bCheckRoomExist = false, float length = 5000.0, float width = 5000.0, float height = 5000.0, float radius = 50.0);

功能

“范围语音”让玩家只收听周围一定范围内的成员声音。初始化成功后加入范围语音频道，尺寸、坐标和半径使用一致的游戏坐标单位。已有频道忽略本次地图尺寸设置。

参数说明

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

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

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

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

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

length：地图 x 轴尺寸，正数，与位置坐标使用相同单位；已有频道忽略本次尺寸设置。

width：地图 y 轴尺寸，正数，与位置坐标使用相同单位；已有频道忽略本次尺寸设置。

height：地图 z 轴尺寸，正数，与位置坐标使用相同单位；已有频道忽略本次尺寸设置。

radius：收听半径，必须大于 0；按切比雪夫距离计算。

原生 C++ 的地图尺寸默认各为 5000（对应坐标范围 [-2500, 2500]），半径默认 50；可选参数按上述声明省略。

返回值

返回成功后等待进房成功/失败事件。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_JOIN_OK：加入范围语音频道成功，此后可更新位置。
YOUME_EVENT_JOIN_FAILED：加入失败。

更新位置和收听半径

语法

C++

YouMeErrorCode updateRangeAudioPosition(const char *pChannelID, float x, float y, float z, float radius);

功能

更新当前范围频道内的位置 x/y/z 及收听半径 radius；坐标单位与加入时地图一致，radius 必须大于 0。

按切比雪夫距离判断范围，即三个坐标轴距离的最大值。

收听距离使用切比雪夫距离 d=max(|x1-x2|,|y1-y2|,|z1-z2|)，不是欧氏距离；radius 必须大于 0，不能传 0 作为默认值。

参数说明

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

x：当前位置 x 坐标。

y：当前位置 y 坐标。

z：当前位置 z 坐标。

radius：收听半径，必须大于 0；按切比雪夫距离计算。

返回值

仅用于范围频道，在普通频道调用返回范围房间类型错误；先检查同步返回错误码。

异步回调

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

设备状态管理

切换语音输出设备

语法

C++

YouMeErrorCode setOutputToSpeaker (bool bOutputToSpeaker);

功能

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

参数说明

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

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

设置扬声器状态

语法

C++

void setSpeakerMute (bool mute);

功能

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

参数说明

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

返回值

无（void）。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

获取扬声器状态

语法

C++

bool getSpeakerMute();

功能

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

参数说明

无。

返回值

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

异步回调

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

设置麦克风状态

语法

C++

void setMicrophoneMute (bool mute);

功能

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

参数说明

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

返回值

无（void）。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

获取麦克风状态

语法

C++

bool getMicrophoneMute ();

功能

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

参数说明

无。

返回值

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

异步回调

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

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

语法

C++

void setAutoSendStatus( bool 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 不通知。

返回值

无（void）。

异步回调

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

设置扬声器音量增益

语法

C++

void setVolume(const unsigned int &uiVolume);

功能

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

参数说明

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

返回值

无（void）。

异步回调

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

获取扬声器音量增益

语法

C++

unsigned int getVolume();

功能

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

参数说明

无。

返回值

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

异步回调

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

设置房间内某成员音量

语法

C++

YouMeErrorCode setUserVolume(const char *userID, const unsigned int &uiVolume);

功能

设置房间内某成员的说话音量大小，仅在本端生效；本端退出频道时失效，被调节成员进出频道可保持有效。

参数说明

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

uiVolume：成员音量，0～300，100 为正常值，0 为无声；只影响本端收听。

返回值

userID 为目标成员 ID，音量范围 0～300，100 为正常值；返回平台错误码。

异步回调

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

设置麦克风音量增益

语法

C++

void setMicVolume(const unsigned int &uiVolume);

功能

设置麦克风音量增益，0 为无声，100 为正常值，大于 100 为增益、小于 100 为减益；过度放大可能失真。

参数说明

uiVolume：麦克风音量增益，0～1000，100 为正常值，0 为无声；过度放大可能失真。

返回值

无（void）。

异步回调

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

获取麦克风音量增益

语法

C++

unsigned int getMicVolume();

功能

获取麦克风音量增益配置，不是实时讲话音量；实时讲话音量通过相应的音量回调获取。

参数说明

无。

返回值

返回当前麦克风音量增益，范围 0～1000，100 为正常值，不是实时说话音量。

异步回调

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

控制他人麦克风

语法

C++

YouMeErrorCode setOtherMicMute (const char* pUserID,bool mute);

功能

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

参数说明

pUserID：要控制的用户ID。

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

返回值

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

异步回调

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

控制他人扬声器

语法

C++

YouMeErrorCode setOtherSpeakerMute (const char* pUserID,bool mute);

功能

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

参数说明

pUserID：要控制的用户ID。

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

返回值

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

异步回调

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

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

语法

C++

YouMeErrorCode setReleaseMicWhenMute(bool enabled);

功能

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

参数说明

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

返回值

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

异步回调

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

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

语法

C++

YouMeErrorCode setExitCommModeWhenHeadsetPlugin(bool enabled);

功能

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

参数说明

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

返回值

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

异步回调

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

释放麦克风

语法

C++

bool releaseMicSync();

功能

调用后完成麦克风释放，只是为了方便使用 IM 的录音接口时切换麦克风使用权。

参数说明

无。

返回值

返回true，表示释放成功，可以认为只要在占用麦克风的状态肯定能释放成功。

异步回调

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

恢复麦克风录音状态

语法

C++

bool resumeMicSync();

功能

调用后恢复麦克风到释放前的状态，只是为了方便使用 IM 的录音接口时切换麦克风使用权。

参数说明

无。

返回值

返回true，表示恢复成功，可以认为只要在释放的状态，肯定可以恢复成功。

异步回调

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

说话及音量检测

设置语音检测

语法

C++

YouMeErrorCode setVadCallbackEnabled(bool enabled);

功能

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

参数说明

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

enabled：true 开启本项功能，false 关闭。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

回调示例：

C++

//主要回调事件：
//YOUME_EVENT_OTHERS_VOICE_ON - 其他用户进入讲话状态
//YOUME_EVENT_OTHERS_VOICE_OFF - 其他用户进入静默状态
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

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

语法

C++

YouMeErrorCode setMicLevelCallback(int maxLevel);

功能

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

参数说明

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

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

设置远端讲话音量级别回调

语法

C++

YouMeErrorCode setFarendVoiceLevelCallback(int maxLevel, int maxMixedLevel);

功能

maxLevel 为单个远端用户音量量化级别，maxMixedLevel 为混合音量量化级别，设置 0 关闭相应回调。

参数说明

maxLevel：音量最大时对应的量化级别，0 关闭回调，开启时大于 1、最大 100，一般建议不超过 30。

maxMixedLevel：远端混合音量的最大量化级别，0 关闭，开启时大于 1、最大 100。

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收 YOUME_EVENT_FAREND_VOICE_LEVEL。错误字段携带音量级别；单个用户通知的 param 为用户 ID，混合音量通知的 param 为空。

通话控制

暂停通话

语法

C++

YouMeErrorCode pauseChannel(YouMePauseReason reason = YOUME_PAUSE_REASON_UNKNOWN);

功能

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

参数说明

reason：暂停/恢复通话原因，使用本平台对应枚举；默认值按语法声明。

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_PAUSED：暂停语音频道完成。

回调示例：

C++

//主要回调事件：
//YOUME_EVENT_PAUSED - 暂停语音频道完成
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

可选 reason 使用对应暂停/恢复原因枚举，默认 UNKNOWN；原有无参数调用仍有效。

恢复通话

语法

C++

YouMeErrorCode resumeChannel(YouMeResumeReason reason = YOUME_RESUME_REASON_UNKNOWN);

功能

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

参数说明

reason：暂停/恢复通话原因，使用本平台对应枚举；默认值按语法声明。

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_RESUMED：恢复语音频道完成。

回调示例：

C++

//主要回调事件：
//YOUME_EVENT_RESUMED - 恢复语音频道完成
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

可选 reason 使用对应暂停/恢复原因枚举，默认 UNKNOWN；原有无参数调用仍有效。

抢麦连麦

抢麦相关设置

语法

C++

YouMeErrorCode setGrabMicOption(const char* pChannelID, int mode, int maxAllowCount, int maxTalkTime, unsigned int voteTime);

功能

抢麦相关设置（抢麦活动发起前调用此接口进行设置）。

参数说明

pChannelID：抢麦活动的频道id。

mode：抢麦模式（1:先到先得模式；2:按权重分配模式）。先到先得模式中，抢麦活动会持续，用户可以继续抢其他用户释放的麦。

maxAllowCount：允许能抢到麦的最大人数（要大于0）。

maxTalkTime：允许抢到麦后使用麦的最大时间（单位：秒，要大于0）。

voteTime：抢麦仲裁时间（单位：秒，要大于0），过了X秒后服务器将进行仲裁谁最终获得麦（仅在按权重分配模式下有效）。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

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

发起抢麦活动

语法

C++

YouMeErrorCode startGrabMicAction(const char* pChannelID, const char* pContent);

功能

发起抢麦活动。接口需要加入房间后再调用。

参数说明

pChannelID：抢麦活动的频道id。

pContent：游戏传入的上下文内容，通知回调会传回此内容（目前只支持纯文本格式）。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_GRABMIC_START_OK：发起抢麦活动成功。
YOUME_EVENT_GRABMIC_START_FAILED：发起失败。
YOUME_EVENT_GRABMIC_NOTIFY_START：频道内的抢麦活动开始通知。

停止抢麦活动

语法

C++

YouMeErrorCode stopGrabMicAction(const char* pChannelID, const char* pContent);

功能

停止抢麦活动

参数说明

pChannelID：抢麦活动的频道id。

pContent：游戏传入的上下文内容，通知回调会传回此内容（目前只支持纯文本格式）。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_GRABMIC_STOP_OK：停止抢麦活动成功。
YOUME_EVENT_GRABMIC_STOP_FAILED：停止失败。
YOUME_EVENT_GRABMIC_NOTIFY_STOP：频道内的抢麦活动结束通知。

发起抢麦请求

语法

C++

YouMeErrorCode requestGrabMic(const char* pChannelID, int score, bool isAutoOpenMic, const char* pContent);

功能

发起抢麦请求

参数说明

pChannelID：抢麦的频道id。

score：积分（权重分配模式下有效，游戏根据自己实际情况设置）。

isAutoOpenMic：抢麦成功后是否自动开启麦克风权限。

pContent：游戏传入的上下文内容，通知回调会传回此内容（目前只支持纯文本格式）。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_GRABMIC_REQUEST_OK：抢麦成功，可以讲话。
YOUME_EVENT_GRABMIC_REQUEST_FAILED：抢麦失败。
YOUME_EVENT_GRABMIC_REQUEST_WAIT：进入等待队列，仅权重模式产生。
YOUME_EVENT_GRABMIC_ENDMIC：因使用时长到期或其他原因不再占用麦。

释放抢到的麦

语法

C++

YouMeErrorCode releaseGrabMic(const char* pChannelID);

功能

释放抢到的麦。

参数说明

pChannelID：抢麦的频道id。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_GRABMIC_RELEASE_OK：释放麦成功。
YOUME_EVENT_GRABMIC_RELEASE_FAILED：释放麦失败。

连麦相关设置

语法

C++

YouMeErrorCode setInviteMicOption(const char* pChannelID, int waitTimeout, int maxTalkTime);

功能

连麦相关设置（角色是频道的管理者或者主播时调用此接口进行频道内的连麦设置）。

参数说明

pChannelID：连麦的频道id。

waitTimeout：等待对方响应超时时间（秒）。

maxTalkTime：最大通话时间（秒）。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_INVITEMIC_SETOPT_OK：连麦设置成功。
YOUME_EVENT_INVITEMIC_SETOPT_FAILED：连麦设置失败。

发起连麦请求

语法

C++

YouMeErrorCode requestInviteMic(const char* pChannelID, const char* pUserID, const char* pContent);

功能

发起与某人的连麦请求（主动呼叫）。支持跨频道发起连麦。

参数说明

pUserID：被叫方的用户id。

pContent：游戏传入的上下文内容，通知回调会传回此内容（目前只支持纯文本格式）。

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

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_INVITEMIC_REQUEST_OK：请求已发出，仍需等待对方回应。
YOUME_EVENT_INVITEMIC_REQUEST_FAILED：请求失败。
YOUME_EVENT_INVITEMIC_NOTIFY_ANSWER：对方回应同意、拒绝或超时。
YOUME_EVENT_INVITEMIC_CAN_TALK：双方可以通话。

回应连麦请求

语法

C++

YouMeErrorCode responseInviteMic(const char* pUserID, bool isAccept, const char* pContent);

功能

对连麦请求做出回应（被动应答）。

参数说明

pUserID：主叫方的用户id。

isAccept：是否同意连麦。

pContent：游戏传入的上下文内容，通知回调会传回此内容（目前只支持纯文本格式）。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_INVITEMIC_RESPONSE_OK：回应请求处理成功；err=YOUME_ERROR_INVITEMIC_REJECT 表示拒绝。
YOUME_EVENT_INVITEMIC_RESPONSE_FAILED：回应请求处理失败。
YOUME_EVENT_INVITEMIC_CAN_TALK：对方被接受后，双方可以通话。

停止连麦

语法

C++

YouMeErrorCode stopInviteMic();

功能

停止连麦。

参数说明

无。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_INVITEMIC_STOP_OK：停止连麦成功。
YOUME_EVENT_INVITEMIC_STOP_FAILED：停止连麦失败。
YOUME_EVENT_INVITEMIC_CANNOT_TALK：双方已不能继续连麦通话。
YOUME_EVENT_INVITEMIC_NOTIFY_CANCEL：对方结束连麦或连麦时长到期的通知。

战歌管理

播放战歌

语法

C++

YouMeErrorCode playBackgroundMusic (const char* pFilePath, bool bRepeat);

功能

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

参数说明

pFilePath：音乐文件的路径。

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

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

回调示例：

C++

//主要回调事件：
//YOUME_EVENT_BGM_STOPPED - 通知战歌播放结束
//YOUME_EVENT_BGM_FAILED - 通知战歌播放失败
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

停止播放战歌

语法

C++

YouMeErrorCode stopBackgroundMusic();

功能

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

参数说明

无。

返回值

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

异步回调

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

设置战歌播放音量

语法

C++

YouMeErrorCode setBackgroundMusicVolume(int vol);

功能

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

参数说明

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

返回值

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

异步回调

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

获取战歌总时长

语法

C++

long long getBgmDuration();

功能

获取战歌总时长（getBgmDuration）。

参数说明

无。

返回值

同步返回战歌总时长，单位毫秒。

异步回调

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

获取战歌播放进度

语法

C++

long long getBgmProgress();

功能

获取战歌播放进度（getBgmProgress）。

参数说明

无。

返回值

同步返回战歌当前播放进度，单位毫秒。

异步回调

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

设置战歌播放进度

语法

C++

void setBgmProgress(const long long uiProgress);

功能

将当前战歌跳转到指定毫秒位置；在战歌已加载的情况下使用，范围不超过总时长。

参数说明

uiProgress：战歌播放进度，单位毫秒。

返回值

无（void）。

异步回调

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

查询战歌播放状态

语法

C++

bool isBackgroundMusicPlaying();

功能

查询战歌播放状态（isBackgroundMusicPlaying）。

参数说明

无。

返回值

同步返回战歌是否正在播放，true 为播放中。

异步回调

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

语音举报

语音举报功能需要联系游密开通。流程：初始化成功 → 加入频道成功 → 各端调用 setReportInfo 配置本机最近语音缓存 → 用户 A 调用 reportUserAudio 举报用户 B → 用户 B 收到信令后上传本地最近 nTimeSec 秒语音（不超过 60 秒）。

配置举报音频缓存

语法

C++

YouMeErrorCode setReportInfo(int nTimeSec, const char *language);

功能

初始化成功后配置本机缓存时长及语言，进房后按业务设置。

nTimeSec 单位秒，范围 0～60，超出范围按 60 秒处理；language 为 ISO 639 语言代码。

用于被举报时上报，此接口不直接发起举报。

参数说明

nTimeSec：最近音频缓存时长（秒），范围 0～60，超出范围按 60 秒处理。

language：ISO 639 语言代码。

返回值

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

异步回调

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

举报房间内用户

语法

C++

YouMeErrorCode reportUserAudio(const char *reportUserID, const char *roomID, const char *customData);

功能

reportUserID 为非空的被举报用户 ID，roomID 为其所在房间；单频道传空表示本房间，多频道传空表示第一次加入的房间。

customData 为透传业务字符串。

按事件错误码和参数处理结果。

参数说明

reportUserID：非空的被举报用户 ID。

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

customData：透传的业务自定义字符串。

返回值

返回成功仅表示受理；举报者处理 YOUME_EVENT_SEND_REPORT_REQ_ACK，被举报端处理 YOUME_EVENT_REPORT_AUDIO_SERVER_NOTIFY，禁言通知为 YOUME_EVENT_REPORT_AUDIO_MASK_NOTIFY。

异步回调

通过 IYouMeEventCallback::onEvent 接收：

YOUME_EVENT_SEND_REPORT_REQ_ACK：举报者收到的发送举报请求响应。
YOUME_EVENT_REPORT_AUDIO_SERVER_NOTIFY：被举报端收到的音频上报服务器结果。
YOUME_EVENT_REPORT_AUDIO_MASK_NOTIFY：被禁言通知。

监听（耳返）

用于在本机耳机中监听自己的麦克风声音或战歌，并调节麦克风监听音量。监听音量设置作用于本机监听效果。

设置监听

语法

C++

YouMeErrorCode setHeadsetMonitorOn(bool micEnabled, bool bgmEnabled = true);

功能

设置是否用耳机监听自己的声音或战歌，这是一个同步调用接口。这个功能必须进入频道传入身份为主播/指挥才能使用。

参数说明

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

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

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

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

设置监听麦克风音量

语法

C++

YouMeErrorCode setMicbypassVolume(int vol);

功能

此为本机监听音量，不是发送给房间成员的麦克风音量增益。

参数说明

vol：音量，范围 0～100，与扬声器音量增益分别设置。

返回值

设置监听时麦克风音量，范围 0～100，返回错误码。

异步回调

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

获取监听麦克风音量

语法

C++

int getMicbypassVolume();

功能

获取监听麦克风音量（getMicbypassVolume）。

参数说明

无。

返回值

返回监听麦克风音量，范围 0～100。

异步回调

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

混响音效

设置混响音效

语法

C++

YouMeErrorCode setReverbEnabled(bool enabled);

功能

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

参数说明

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

enabled：true 开启本项功能，false 关闭。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

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

设置混响音效类型

语法

C++

YouMeErrorCode setAudioEffectType(unsigned int effectType);

功能

具体参见混响音效类型定义。

参数说明

effectType：混响音效类型；具体数值见本平台状态码页的混响音效类型定义。

具体参见混响音效类型定义。

返回值

设置混响音效类型，参数传整数类型值，返回平台错误码。

异步回调

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

变声音调

获取变声音调

语法

C++

float getSoundtouchPitchSemiTones ();

功能

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

参数说明

无。

返回值

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

异步回调

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

设置变声音调

语法

C++

YouMeErrorCode setSoundtouchPitchSemiTones (float fPitchSemiTones);

功能

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

参数说明

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

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

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

广播消息

语法

C++

YouMeErrorCode  sendMessage( const char* pChannelID,  const char* pContent, int* requestID );

功能

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

参数说明

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

pContent：要广播的文本内容。

requestID：用于标识消息的ID。

返回值

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

异步回调

通过 IYouMeEventCallback::onEvent 接收：

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

回调示例：

发送方会收到YOUME_EVENT_SEND_MESSAGE_RESULT回调，通知发送消息的结果。频道内其他人收到YOUME_EVENT_MESSAGE_NOTIFY回调，通知消息内容。

C++

//IYouMeEventCallback
//event:YOUME_EVENT_SEND_MESSAGE_RESULT: 发送消息的结果回调，param为requestID的字符串
//event:YOUME_EVENT_MESSAGE_NOTIFY:频道内其他人收到消息的通知。param为文本内容
void onEvent(const YouMeEvent event, const YouMeErrorCode error, const char * channel, const char * param) ;

设置时间戳

设置录音时间戳

语法

C++

void setRecordingTimeMs(unsigned int timeMs);

功能

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

参数说明

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

返回值

无（void）。

异步回调

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

设置播放时间戳

语法

C++

void setPlayingTimeMs(unsigned int timeMs);

功能

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

参数说明

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

返回值

无（void）。

异步回调

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

移动网络设置

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

语法

C++

void setUseMobileNetworkEnabled (bool bEnabled);

功能

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

参数说明

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

返回值

无（void）。

异步回调

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

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

语法

C++

bool getUseMobileNetworkEnabled () ;

功能

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

参数说明

无。

返回值

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

异步回调

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

网络质量检测

语法

C++

YouMeErrorCode detectNetworkQuality(int nDetectTime, int nOverTime, int nInterval, int nPackSize);

功能

开始网络质量检测。如之前的检测还在进行中，再次调用该接口将返回YOUME_ERROR_FREQUENCY_TOO_HIGH = -701(检测频率过快)的返回值。

终止检测网络质量。终止后将不会收到onDetectNetWorkComplete回调。如未在进行网络质量检测就调用该接口将返回YOUME_ERROR_FREQUENCY_TOO_HIGH = -701的返回值。

网络质量检测回调。

参数说明

nDetectTime：发包检测时长，单位为秒，建议3秒，范围(0,100]。

nOverTime：检测终止时长，单位为秒，建议4秒，范围(0,110]。

nInterval：发包间隔，单位毫秒，建议20毫秒，范围[20,30000]，发包间隔不能超过检测时长或终止时长。

nPackSize：发包大小，单位字节，建议300字节，范围[64,1400]。

bNetworkOK：网络是否可用（目前如果lossPer<=0.2并且avgRtt<400，就认为网络是可用的，并且这两个阈值将支持服务器动态下发控制）。

strResult：检测的结果值，以json格式返回，目前会返回avgRtt（平均往返延迟，整型，单位毫秒）和lossPer（丢包率，浮点型，范围0.0~1.0）。json格式示例：{"avgRtt":39,"lossPer":0}。

返回值

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

异步回调

通过 setDetectNetworkCallback 注册的 IYouMeDetectNetworkCallback::onDetectNetWorkCompleteCb 接收。检测结果包含 avgRtt（毫秒）和 lossPer（0～1）。

示例与补充说明：

C++

YouMeErrorCode stopDetectNetworkQuality();

C++

void onDetectNetWorkCompleteCb(bool bNetworkOK, const char* strResult);

版本与日志

获取 SDK 版本

语法

C++

int getSDKVersion();

功能

获取 SDK 版本（getSDKVersion）。

参数说明

无。

返回值

返回压缩整数 SDK 版本号。

异步回调

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

上传 SDK 日志

语法

C++

YouMeErrorCode uploadLog(const char *userID, int timeout, IYouMeUploadLogCallback *callback, int msCdProgress);

功能

异步上传日志，用于问题诊断。

需已初始化且已退出所有频道；同一时刻只能进行一次上传。

userID 非空，timeout 为超时秒数（0 表示无超时），msCdProgress 为回调最小间隔毫秒数（0 表示不限制频率）。

等待回调结束后再 unInit。

参数说明

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

timeout：超时秒数，0 表示不设置超时。

callback：实现签名所需回调接口的对象，使用期间保持有效；在 SDK 回调线程处理，操作游戏 UI 前切回主线程。

msCdProgress：进度回调最小间隔，单位毫秒；0 不限制回调频率。

返回值

同步返回成功仅表示开始上传；progress=100 且 errcode=YOUME_SUCCESS 才表示完成。

异步回调

通过 IYouMeUploadLogCallback::onUploadProgress(progress, errcode, msg) 接收进度，progress=100 且 errcode=YOUME_SUCCESS 才表示完成。SDK 保持初始化状态直到上传完成；不要发起后立即 unInit。

终止日志上传

语法

C++

YouMeErrorCode abortUploadLog();

功能

终止日志上传（abortUploadLog）。

参数说明

无。

返回值

同步终止当前日志上传，返回错误码。

异步回调

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

反初始化

语法

C++

YouMeErrorCode unInit ();

功能

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

参数说明

无。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

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

变声相关文档

需要配合游密变声管理模块文档使用。

设置变声是否可用

语法

YouMeErrorCode SetMagicVoiceEnable(bool enabled);

功能

设置变声是否可用。

参数说明

enabled：设置变声是否可用，开启后会略微增大声音延迟。

返回值

如果成功则返回YOUME_SUCCESS，其它具体参见YouMeErrorCode类型定义。

异步回调

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

文档目录

Talk SDK for Cocos2d C++ API接口手册

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

API调用说明

实现回调

回调注册与设置

注册网络检测回调

注册音频统计回调

注册房间广播回调

设置音频数据回调

回调派发配置

设置事件优先级

获取事件优先级

初始化

设置服务器区域

语音频道管理

加入语音频道

指定讲话频道

退出指定的语音频道

退出所有语音频道

设置白名单用户

设置黑名单用户

设置用户角色

获取用户角色

设置频道收听黑名单

查询是否在频道

查询频道用户列表

把人踢出房间

范围语音

加入范围语音频道

更新位置和收听半径

设备状态管理

切换语音输出设备

设置扬声器状态

获取扬声器状态

设置麦克风状态

获取麦克风状态

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

设置扬声器音量增益

获取扬声器音量增益

设置房间内某成员音量

设置麦克风音量增益

获取麦克风音量增益

控制他人麦克风

控制他人扬声器

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

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

释放麦克风

恢复麦克风录音状态

说话及音量检测

设置语音检测

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

设置远端讲话音量级别回调

通话控制

暂停通话

恢复通话

抢麦连麦

抢麦相关设置

发起抢麦活动

停止抢麦活动

发起抢麦请求

释放抢到的麦

连麦相关设置

发起连麦请求

回应连麦请求

停止连麦

战歌管理

播放战歌

停止播放战歌

设置战歌播放音量

获取战歌总时长

获取战歌播放进度

设置战歌播放进度

查询战歌播放状态

语音举报

配置举报音频缓存

举报房间内用户

监听（耳返）

设置监听

设置监听麦克风音量