游戏多媒体引擎特殊接口-进阶功能开发指南-文档中心-腾讯云

为方便开发者调试和接入腾讯云游戏多媒体引擎产品 API，这里向您介绍 GME SDK 高级接口。 
通用特殊接口
openid 支持字符串
注意：
此接口在 GME 2.9.3 及以上版本 SDK 生效。
目前 GME SDK 只支持数字以字符串形式传入 SDK，如果需要 openid 支持以字符串形式传入，需要在调用 Init 接口之前调用一次以下接口：
SetAdvanceParams("StringOpenID", "1");
修复打印日志大小
说明：
此接口在 GME 2.8.4 以上版本 SDK 上生效，为了不影响开发者调试，请勿在测试阶段修改日志大小。
在 GME Init 初始化接口前调用此接口，用于修改默认日志文件大小。目前日志文件单个为50m，最多存在3个日志文件。
函数原型
SetAdvanceParams（const char* key, const char* object）
参数
类型
含义
key
const char*
MAX_LOG_FILE_SIZE_MB 和 MAX_LOG_FILE_COUNT，分别代表单个日志的大小和日志的数量。
object
const char*
当key 为 MAX_LOG_FILE_SIZE_MB 时，object 为 Log 文件大小默认值，取值范围（单位M）：5至50；当key 为 MAX_LOG_FILE_COUNT 时，object 为 Log 文件个数默认值，取值范围：1至3。
参数范围：
当输入的 object 超过取值范围上限时，则设置为上限值；当输入的 object 小于取值范围下限时，则设置为下限值。
示例代码
SetAdvanceParams("MAX_LOG_FILE_SIZE_MB", "5");
SetAdvanceParams("MAX_LOG_FILE_COUNT", "1");
音频相关特殊接口
iOS 音频设置接口
此部分接口使用 SetAdvanceParams 接口进行调用，在进房前调用。 调用后影响音频播放效果，需要根据业务需求谨慎调用。
接口原型
[[ITMGContext GetInstance] SetAdvanceParams:keyString value:_value]
参数
含义
keyString
不同的 Key 代表不同的功能
value
 0：代表关闭
1：代表开启
Key
不同的 Key 代表不同的功能，参数 Key 可填写的字段如下：
OptionMixWithOthers
混音选项。开启后可以把后台播放的音乐与前台通话语音同时播放。
OptionDuckOthers
压低背景音。在 OptionMixWithOthers 开启的情况下，如果开启此功能，则开启扬声器播放语音时，将会压低其他后台背景声音。
ReleaseAudioFoucus
释放音频焦点。
如果开启，退房之后将会释放音频焦点，系统恢复后台其他音频相关应用。例如 QQ 音乐。
如果关闭，退房之后将不会恢复其他音频相关应用。
检查 iPhone 静音键是否开启
说明：
此接口在 GME 2.8.4 以上版本 SDK 上生效。
调用接口检查 iPhone 手机静音功能是否开启。
接口原型
CheckDeviceMuteState();
返回值
返回值为 0 代表关闭物理静音键，返回值为 1 代表打开物理静音键。
设置 Android 蓝牙设备使用媒体音量
说明：
此接口在 GME 2.8.4 以上版本 SDK 上生效。
调用此接口后蓝牙耳机使用媒体音量，需要在进房前调用。如果您的用户经常反馈如下问题：
蓝牙耳机在开关麦的时候漏声音。
Android 设备在已连接蓝牙耳机的情况下，切换连接状态后出现声音从扬声器播放。
可以在业务层的设置界面设计一个开关，当用户反馈类似问题，建议客户打开开关，业务层在进房前设置蓝牙耳机使用媒体音量。
调用情况
音量类型影响
采集音频方式
调用前
通话音量
从耳机对用户说话声音进行采集。
调用后
媒体音量
从手机麦克风对用户说话声音进行采集，如果用户离手机麦克风比较远，可能造成采集到的音量很小，影响通话。
SetAdvanceParams(“BluetoothUseMedia”, “1”);
设置最大混音路数
使用 SetRecvMixStreamCount 接口可以设置最高混音路数，在进房前调用。 各平台均有此接口，下面以 PC 端为例。
virtual int SetRecvMixStreamCount(int nCount) = 0;
参数说明
参数
含义
nCount
混音路数，最大为20
开关 3A 效果
通过此接口，可对 3A 效果（AEC、AGC、ANS）进行开关，默认为 3A 效果都开启。
警告：
非特殊情况，无需调用此接口开关 3A 效果，以免影响音质。
示例代码
C++
ITMGContextGetInstance()->SetAdvanceParams("AECFlag", "1")；
ITMGContextGetInstance()->SetAdvanceParams("AECFlag", "0")；
ITMGContextGetInstance()->SetAdvanceParams("ANSFlag", "1")；
ITMGContextGetInstance()->SetAdvanceParams("ANSFlag", "0")；
ITMGContextGetInstance()->SetAdvanceParams("AGCFlag", "1")；
ITMGContextGetInstance()->SetAdvanceParams("AGCFlag", "0")；
参数
类型
含义
keyString
String
AECFlag：代表 AEC 功能开关。
ANSFlag：代表 ANS 功能开关。
AGCFlag：代表 AGC 功能开关。
value
String
"1"：代表开。
"0"：代表关。
设置房间音频类型
进房前使用 SetForceUseMediaVol ，可以让流畅音质房间或者标准音质房间使用媒体音量。
警告：
非特殊情况，无需调用此接口，以免影响音质。
接口原型
[[ITMGContext GetInstance] SetAdvanceParams:SetForceUseMediaVol value:1]
value
不同的 value 代表不同的功能，具体如下：
0：房间类型1与2的语音房间都还原为开麦克风后音量为通话音量。
1：房间类型1的语音房间开麦克风后为媒体音量（原为通话音量）。
2：房间类型2的语音房间开麦克风后为媒体音量（原为通话音量）。
获取房间内成员说话音量
调用 TrackingVolume 接口之后，监听 TIMGContext.ITMG_MAIN_EVENT_TYPE.ITMG_MAIN_EVENT_TYPE_USER_VOLUMES 事件，里面的键值对为 uin-volume，通过此接口可以根据房间内某 uin 说话的音量强度画出相应的能量柱状图。
如果不再获取，请调用 StopTrackingVolume 接口。
//TMGAudioCtrl
public int TrackingVolume(float fTrackingTimeS)
public int StopTrackingVolume();
参数
类型
含义
fTrackingTimeS
Float
监听的秒数，建议设置为 0.5f
音文同传相关接口
文本翻译接口
调用此接口，可以将一段文本进行翻译，例如将一段中文翻译成英文。调用接口后通过回调返回翻译结果。此处以 C++ 接口为例。
函数原型
virtual int TranslateText(const char* text, const char* sourceLanguage, const char* translateLanguage) = 0;
参数
类型
含义
text
const char*
待翻译的文本，不可为空，最大长度5000字符
sourceLanguage
const char*
指定待翻译文本的语言，可为空，后台自动检测语音
translateLanguage
const char*
指定文本翻译后的语言，不可为空，以英文逗号作为间隔，例如"cmn-Hans-CN,en-GB"、"cmn-Hans-CN"
语言参数请参见 语言参数列表。
接口回调
参数
类型
含义
code
Int
错误码，0代表成功，其他返回请参考 错误码 进行解决
targetText
jason(Unity 中返回 String 格式)
翻译后的目标文本，例如     {"target_text":[{"target_language_code":"cmn-Hans-CN","target_text":"我是中国人"},{"target_language_code":"de-DE","target_text":"Ich bin Chinese"}]}
Unity 工程示例代码
1. 添加监听。
ITMGContext.GetInstance().GetPttCtrl().OnTranslateTextComplete+= OnTranslateTextComplete;
2. 调用接口。
private void OnTranslateTextBtn()
{
  mTargetText.text = "";
 int ret = ITMGContext.GetInstance().GetPttCtrl().TranslateText(mSourceText. text, mSourceLanguageText.text, mTargetLanguageText.text);
 if (0 != ret)
 {
      mTargetText.text = "Invalid Atgument";
 }
}
3. 处理回调。
void OnTranslateTextComplete(int code, string targetText)
{
 if (0 == code)
 {
     mTargetText.text = targetText;
 }
 else
 {
     mTargetText.text = String.Format(
         "Translate Text Error, Error Code:{0}", code);
 }
}
4. 取消监听。
ITMGContext.GetInstance().GetPttCtrl().OnTranslateTextComplete-= OnTranslateTextComplete;
文本转语音接口
调用此接口，可以将一段文本转成对应的一段语音，调用接口后，通过回调返回语音 fileid，通过下载语音接口进行下载此语音。此处以 C++ 接口为例。
注意：
此接口仅对白名单用户开放，且只在SDK 291版本上才能使用。若您有需求，请 提交工单 联系工作人员申请服务。
函数原型
virtual int TextToSpeech(const char* text, const char* voiceName,const char* languageCode, float speakingRate) = 0;
参数
类型
含义
text
const char*
原始文本，不可为空，最大长度5000字符
voiceName
const char*
声音类型，提供英语及普通话的示例，如需其他语言请 提交工单 咨询
languageCode
const char*
指定目标语言。不可为空
speakingRate
Float
音频语速，取值范围 [0.6-1.5]，1代表正常速度
voiceName 说明如下：
声音类型
性别
语言
cmn-CN-Standard-A
女声
普通话
cmn-CN-Standard-B
男声
普通话
en-US-Neural2-A
女声
英语
en-US-Neural2-B
男声
英语
语言参数请参见 语言参数列表。
接口回调
参数
类型
含义
code
Int
错误码，0代表成功，其他返回请参考 错误码 进行解决
isCos
Bool
文件是否上传到 COS
fileID
String
文件 ID，提供下载接口入参，可以通过 DownloadRecordedFile 接口下载音频
Unity 工程示例代码
1. 添加监听。
ITMGContext.GetInstance().GetPttCtrl().OnTextToSpeechComplete += new QAVTextToSpeechCallback(TextToSpeechComplate);
2. 调用接口。
void OnTextToSpeech()
{
 float fSpeakingRate;
 if (!float.TryParse(mSpeakingRate.text, out fSpeakingRate))
 {
     mReturnData.text = "SpeakingRate invalid";
      return;
 }
﻿
 int iRet = ITMGContext.GetInstance().GetPttCtrl().TextToSpeech(
     mSouceText.text, mVoiceName.text,
     mLanguageCode.text, fSpeakingRate);
﻿
 Debug.Log(string.Format("TextToSpeech Code:{0}", iRet));
﻿
 if (0 != iRet)
 {
     mReturnData.text = string.Format("TextToSpeech Error, errorCode:{0}", iRet);
     return;
 }
}
3. 处理回调。
void TextToSpeechComplate(int code, bool isCos, string fileID)
{
 Debug.Log(string.Format("TextToSpeechComplate Code:{0}", code));
﻿
 if (0 != code)
 {
     mReturnData.text = string.Format("TextToSpeech Error, errorCode:{0}", code);
     return;
 }
﻿
 mReturnData.text = string.Format("code:{0}\\r\\nisCos:{1}\\r\\nfileID:{2}", code, isCos, fileID);
 mDownloadUrl.text = fileID;
}
4. 取消监听。
ITMGContext.GetInstance().GetPttCtrl().OnTextToSpeechComplete -= new QAVTextToSpeechCallback(TextToSpeechComplate);
临时热词接口
通过该接口设置临时热词表，在调用转文本接口前调用此接口，对接下来的转文本调用生效。如果无需临时热词功能，请在参数 object 中填入“”，用于清空热词表。
临时热词表只对中文生效，如果此次调用转文本功能使用了临时热词表，则在控制台上传的热词表此次调用不生效。
接口原型
int SetAdvanceParams(const char* key, const char* object);
接口参数
参数
类型
含义
key
const char*
请填入 "SetPTTHotWorldList"
object
const char*
传入要设置的热词列表。传"" 清空上次设置的热词。
单个热词规则：“热词|权重”，不超过30个字符(最多10个汉字)，权重1-10。1代表权重最低，10代表权重最高。
热词列表：多个热词之间用英文逗号分割，最多128个热词，参数示例："腾讯云|10"、"语音识别|5,ASR|10"。
示例代码
ITMGContext.GetInstance().SetAdvanceParams("SetPTTHotWorldList", "会敢去采|10,塌下来又怎样|2,何来罪恶|2,自在喝奶咖|7,几成痴|10,");
﻿

调用情况	音量类型影响	采集音频方式
调用前	通话音量	从耳机对用户说话声音进行采集。
调用后	媒体音量	从手机麦克风对用户说话声音进行采集，如果用户离手机麦克风比较远，可能造成采集到的音量很小，影响通话。

参数	类型	含义
key	const char*	MAX_LOG_FILE_SIZE_MB 和 MAX_LOG_FILE_COUNT，分别代表单个日志的大小和日志的数量。
object	const char*	当key 为 MAX_LOG_FILE_SIZE_MB 时，object 为 Log 文件大小默认值，取值范围（单位M）：5至50；当key 为 MAX_LOG_FILE_COUNT 时，object 为 Log 文件个数默认值，取值范围：1至3。

参数	含义
keyString	不同的 Key 代表不同的功能
value	0：代表关闭 1：代表开启

声音类型	性别	语言
cmn-CN-Standard-A	女声	普通话
cmn-CN-Standard-B	男声	普通话
en-US-Neural2-A	女声	英语
en-US-Neural2-B	男声	英语

特殊接口

本页目录：

通用特殊接口

openid 支持字符串

修复打印日志大小

函数原型

示例代码

音频相关特殊接口

iOS 音频设置接口

接口原型

Key

检查 iPhone 静音键是否开启

接口原型

返回值

设置 Android 蓝牙设备使用媒体音量

设置最大混音路数

开关 3A 效果

示例代码

设置房间音频类型

接口原型

value

获取房间内成员说话音量

音文同传相关接口

文本翻译接口

函数原型

接口回调

Unity 工程示例代码

文本转语音接口

函数原型

接口回调

Unity 工程示例代码

临时热词接口

接口原型

接口参数

示例代码