文档中心>游戏多媒体引擎

接入语音消息功能

最近更新时间:2024-10-15 15:11:32

我的收藏
本文介绍如何在微信小游戏项目中接入 GME 实时语音功能,为了方便演示,只提供了基础功能的接入,其他功能的使用请参见 API 文档。
说明:
在微信小游戏的 GMESDK 中,如果只使用语音消息和转文本功能可以不用申请 livepusher 和 liveplayer 权限。

前置条件:

已完成 GME 应用创建,并获取 SDK AppID 和 Key。请参见 服务开通指引
已开通 GME语音消息服务以及转文本服务。请参见 服务开通指引
GME 使用前请对工程进行配置,否则 SDK 不生效。
GME 的接口调用成功后返回值为 AV_OK,数值为 0。
错误码详情可参见 错误码
注意:
语音转文本相关接口有默认频率限制,限额范围内计费方式请参见 计费文档;若需提升接口频率限额或了解超额计费方式,请联系商务或 提交工单咨询
语音消息非流式转文本接口 speechToText():默认单账号限制并发数为10路。
语音消息流式转文本接口 startRecordingWithStreamingRecognition():默认单账号限制并发数为50路。

实时语音合法域名添加

request 域名

https://gme-v2-gz-1256845520.file.myqcloud.com;

https://gme-v2-sh-1256845520.file.myqcloud.com;

https://gme-v2-bj-1256845520.file.myqcloud.com;

https://gme-v2-cd-1256845520.file.myqcloud.com;

https://gme-v2-hk-1256845520.file.myqcloud.com;

https://gme-v2-sg-1256845520.file.myqcloud.com;

https://gme-v2-gz-1256845520.cos.ap-guangzhou.myqcloud.com;

https://gme-v2-bj-1256845520.cos.ap-beijing.myqcloud.com;

https://gme-v2-cd-1256845520.cos.ap-chengdu.myqcloud.com;

https://gme-v2-sh-1256845520.cos.ap-shanghai.myqcloud.com;

https://gme-v2-hk-1256845520.cos.ap-hongkong.myqcloud.com;

https://gme-v2-sg-1256845520.cos.ap-singapore.myqcloud.com;

https://gme-v2-sg-1256845520.cossgp.myqcloud.com;

https://gme-v2-sh-1256845520.cossh.myqcloud.com;

https://gme-v2-gz-1256845520.cosgz.myqcloud.com;

https://gme-v2-cd-1256845520.coscd.myqcloud.com;

https://gme-v2-hk-1256845520.coshk.myqcloud.com;

https://gme-v2-bj-1256845520.cosbj.myqcloud.com;

https://bj.file.myqcloud.com;

https://sh.file.myqcloud.com;

https://gz.file.myqcloud.com;

https://cd.file.myqcloud.com;

https://hk.file.myqcloud.com;

https://sgp.file.myqcloud.com;

https://voice.gmertc.com;

https://gmeconf.qcloud.com;

https://gme-v2-usw-1256845520.cos.na-siliconvalley.myqcloud.com;

https://usw.file.myqcloud.com;

https://voice-intl.gmertc.com;


socket 域名

wss://voice.gmertc.com;

wss://gmeconf.qcloud.com;


接入 SDK

重要步骤

接入 SDK 重要流程如下:

1. 创建 GME 对象
2. 鉴权初始化 PTT
3. 设置 PTT 的回调事件
4. 启动流式语音识别
5. 停止录制

核心接口

接口
接口含义
initPTT
初始化 PTT 的鉴权信息
setTMGDelegate
设置接收回调信息的方法

引用头文件

import GME from "../gme/sdk/gme-wx.js"

获取实例并设置接收回调方法

handleGMEEvent(event) {
switch (event.code) {
//流式转文本完成事件
case "ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORD_COMPLETE":
console.log("ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORD_COMPLETE" ,event)
this.record_path.string = event.data.message.filePath;
this.cos_url.string = event.data.message.downloadUrl
this.translte_text.string = event.data.message.text;
break;
}
}
this.GMEInstance = new GME();
this.GMEInstance.setTMGDelegate((event) => {
this.handleGMEEvent(event);
}
)

初始化 PTT

未初始化前,SDK PTT功能处于未初始化阶段,需要通过接口 Init 初始化 SDK,才可以使用语音消息服务及转文本服务。
let Signature = genTestUserSig(this.editUserID.string);
let config = {
app_id_: this.editAppID.string,//腾讯云注册的appid
open_id_: this.editUserID.string,//用于标识用户的openid
user_sig_: Signature,//鉴权信息
auth_token_: ''//暂无,填空即可
}
this.GMEInstance.initPTT(config)
参数名称
数据类型
含义
app_id_
string
来自 腾讯云控制台 的 GME 服务提供的 AppID,获取请参见 服务开通指引
user_sig_
string
鉴权信息,获取请参见 usersig
open_id_
string
用户名,只允许包含大小写英文字母(a-z、A-Z)、数字(0-9)及下划线和连词符,最大127个字符。注意 GME 不支持同一个 userId 在两台不同的设备上同时进入房间,否则会相互干扰
auth_token_
string
来自 腾讯云控制台 的权限密钥


语音消息服务及转文本服务

说明
转文本服务分录音文件极速转文本以及语音消息流式转文本。
使用语音消息服务不需要进入实时语音房间。
语音消息最大录制时长默认为58秒,最短不能小于1秒。

语音消息服务使用流程





转文本服务使用流程





流式语音识别

语音消息及转文字相关接口

接口
接口含义
startRecordingWithStreamingRecognition
启动流式录音
stopRecording
停止录音

启动流式语音识别

此接口用于启动流式语音识别,同时在回调中会有实时的语音转文字返回,可以指定语言进行识别,也可以将语音中识别到的信息翻译成指定的语言返回。停止录音调用 停止录制停止录制以后可以在回调中获取录制好的文件和转文本结果以及文件时长。

接口原型

startRecordingWithStreamingRecognition(source_language , translate_language);
参数
类型
含义
speechLanguage
String
识别成指定文字的语言参数,参数请参见 语言参数参考列表
translateLanguage
String
填入与 speechLanguage 相同的值

示例代码

this.GMEInstance.startRecordingWithStreamingRecognition("cmn-Hans-CN" , "cmn-Hans-CN");
handleGMEEvent(event) {
switch (event.code) {
//接收出现错误的情况
case "ERROR":
console.log("Error" , event)
break;
//接收语音转文本中的转文本结果
case "ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORDING":
console.log("ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORDING" , event)
this.translte_text.string = event.data.message.text;
break;
//录制结束接收录音文件,下载cos_url,以及所有的转文本结果
case "ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORD_COMPLETE":
console.log("ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORD_COMPLETE" ,event)
this.record_path.string = event.data.message.filePath;
this.cos_url.string = event.data.message.downloadUrl
this.translte_text.string = event.data.message.text;
break;
}
}
注意:
翻译会收取额外费用,请参见 购买指南

流式语音识别的回调

启动流式语音识别后,需要通过在 ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORD_COMPLETE 或者 ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORDING 通知中监听回调消息,事件消息分为以下两个:
ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORD_COMPLETE 是在停止录制并完成识别后才返回文字,相当于一段话说完才会返回识别的文字。
ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORDING 是在录音过程中就会实时返回识别到的文字,相当于边说话边返回识别到的文字。
根据需求在 OnEvent 通知中对相应事件消息进行判断。传递的参数包含以下四个信息。
消息名称
含义
text
语音转文字识别的文本
filePath
录音存放的本地地址
downloadUrl
录音在后台的 url 地址,录音在服务器存放90天
注意
监听 ITMG_MAIN_EVNET_TYPE_PTT_STREAMRECORDING 消息时,file_id 为空。

错误码

错误码
含义
处理方式
32775
流式语音转文本失败,但是录音成功
调用 UploadRecordedFile 接口上传录音,再调用 SpeechToText 接口进行语音转文字操作
32777
流式语音转文本失败,但是录音成功,上传成功
返回的信息中有上传成功的后台 url 地址,调用 SpeechToText 接口进行语音转文字操作
32786
流式语音转文本失败
在流式录制状态当中,请等待流式录制接口执行结果返回
32787
转文本成功,文本翻译服务未开通
需要在控制台开通文本翻译服务
32788
转文本成功,文本翻译语言参数不支持
重新检查传入参数
如果出现 4098 错误码,请参见 常见问题文档 进行解决。

语音消息录制

录制的流程为:录音 > 停止录音 > 录音回调返回 > 启动下一次录音。

语音消息及转文字相关接口

接口
接口含义
startRecording
启动录音
pauseRecording
暂停录音
resumeRecording
恢复录音
stopRecording
停止录音
cancelRecording
取消录音

启动录音

此接口用于启动录音。

接口原型

startRecord()

示例代码

this.GMEInstance.startRecording();
handleGMEEvent(event) {
switch (event.code) {
//接收出现错误的情况
case "ERROR":
console.log("Error" , event)
break;
//接收录制好的本地文件路径
case "ITMG_MAIN_EVNET_TYPE_PTT_RECORD_COMPLETE":
console.log("ITMG_MAIN_EVNET_TYPE_PTT_RECORD_COMPLETE" ,event)
this.record_path.string = event.data.message.filePath;
break;
}
}

停止录音

此接口用于停止录音。此接口为异步接口,停止录音后会有录音完成回调,成功之后录音文件才可用。

接口原型

stopRecording()

示例代码

this.GMEInstance.stopRecording();

启动录音的回调

启动录音的结果会通过回调返回。
停止录音调用 StopRecording。停止录音后才有启动录音的回调。
参数
类型
含义
filePath
String
录制的存放地址,必须是可以访问到的路径,不可将 fileid 作为路径

错误码

在回调里,通过 ERROR 事件来接收错误信息
错误码值
原因
建议方案
4097
参数为空
检查代码中接口参数是否正确
4098
初始化错误
检查设备是否被占用,或者权限是否正常,是否初始化正常
4099
正在录制中
确保在正确的时机使用 SDK 录制功能
4100
没有采集到音频数据
检查麦克风设备是否正常
4102
麦克风未授权错误
使用 SDK 需要麦克风权限,添加权限请参考对应引擎或平台的 SDK 工程配置文档
4103
录音时间太短错误
首先,限制录音时长的单位为毫秒,检查参数是否正确;其次,录音时长要1000毫秒以上才能成功录制
4104
没有启动录音操作
检查是否已经调用启动录音接口

取消录音

调用此接口取消录音。取消之后没有回调

接口原型

cancelRecord()

示例代码

this.GMEInstance.cancelRecord();

语音消息上传、下载及播放

接口
接口含义
uploadRecordedFile
上传语音文件
downloadRecordedFile
下载语音文件
playRecordedFile
播放语音
stopPlayFile
停止播放语音

上传语音文件

此接口用于上传语音文件。

接口原型

uploadRecordedFile(file_path)
参数
类型
含义
file_path
String
上传的语音路径,此路径为本地路径

示例代码

this.GMEInstance.uploadRecordedFile(filePath);

上传语音完成的回调

上传语音完成后,事件消息为 ITMG_MAIN_EVNET_TYPE_PTT_UPLOAD_COMPLETE, 在 OnEvent 函数中对事件消息进行判断。 传递的参数包含三个信息,result,file_path 和 file_id。
参数
类型
含义
code
int
当 code 为0时,录制完成
message
String
文件的 url 路径

错误码

如果出现错误需要在ERROR事件里监听
错误码值
原因
建议方案
8193
上传文件时,文件访问错误
确保文件存在,文件路径的合法性
8194
签名校验失败错误
检查鉴权密钥是否正确,检查是否有初始化离线语音
8195
网络错误
检查设备网络是否可以正常访问外网环境
8196
获取上传参数过程中网络失败
检查鉴权是否正确,检查设备网络是否可以正常访问外网环境
8197
获取上传参数过程中回包数据为空
检查鉴权是否正确,检查设备网络是否可以正常访问外网环境
8198
获取上传参数过程中回包解包失败
检查鉴权是否正确,检查设备网络是否可以正常访问外网环境
8200
没有设置 appinfo
检查 apply 接口是否有调用,或者入参是否为空

示例代码

handleGMEEvent(event) {
switch (event.code) {
//接收出现错误的情况
case "ERROR":
console.log("Error" , event)
break;
//接收录制好的本地文件路径
case "ITMG_MAIN_EVNET_TYPE_PTT_UPLOAD_COMPLETE":
console.log("ITMG_MAIN_EVNET_TYPE_PTT_UPLOAD_COMPLETE" ,event)
this.cos_url.string = event.data.message;
break;
}
}

下载语音文件

此接口用于下载语音文件。

接口原型

downloadRecordedFile(cos_url , file_path)
参数
类型
含义
cos_url
String
文件的 url 路径
file_path
String
文件的本地保存路径

下载语音文件完成回调

下载语音完成后,事件消息为 ITMG_MAIN_EVNET_TYPE_PTT_DOWNLOAD_COMPLETE, 在 OnEvent 函数中对事件消息进行判断。 传递的参数包含三个信息,result、file_path 和 file_id。
参数
类型
含义
code
int
当 code 为0时,下载完成
message
String
下载完成的地址

错误码

出现错误可在ERROR事件里监听
错误码值
原因
建议方案
12289
下载文件时,文件访问错误
检查文件路径是否合法
12290
签名校验失败
检查鉴权密钥是否正确,检查是否有初始化离线语音
12291
网络存储系统异常
服务器获取语音文件失败,检查接口参数 fileid 是否正确,检查网络是否正常,检查 COS 文件存不存在
12292
服务器文件系统错误
检查设备网络是否可以正常访问外网环境,检查服务器上是否有此文件
12293
获取下载参数过程中,HTTP 网络失败
检查设备网络是否可以正常访问外网环境
12294
获取下载参数过程中,回包数据为空
检查设备网络是否可以正常访问外网环境
12295
获取下载参数过程中,回包解包失败
检查设备网络是否可以正常访问外网环境
12297
没有设置 appinfo
检查鉴权密钥是否正确,检查是否有初始化离线语音

示例代码

handleGMEEvent(event) {
switch (event.code) {
//接收出现错误的情况
case "ERROR":
console.log("Error" , event)
break;
//下载完成事件
case "ITMG_MAIN_EVNET_TYPE_PTT_DOWNLOAD_COMPLETE":
console.log("ITMG_MAIN_EVNET_TYPE_PTT_DOWNLOAD_COMPLETE" ,event)
this.cos_url.string = event.data.message;
break;
}
}

播放语音

此接口用于播放语音。

接口原型

playRecordedFile(file_path)
参数
类型
含义
file_path
String
本地语音文件的路径

错误码

错误码值
原因
建议方案
20485
播放未开始
确保文件存在,文件路径的合法性

示例代码

this.GMEInstance.playRecordedFile(this.record_path.string);

播放语音的回调

播放语音的回调,事件消息为 ITMG_MAIN_EVNET_TYPE_PTT_PLAY_COMPLETE, 在 回调函数中对事件消息进行判断。 传递的参数包含两个信息,一个是 result,另一个是 file_path。
参数
类型
含义
code
int
当 code 为0时,播放完成
message
String
播放结束的信息

错误码

出现错误可在ERROR事件里监听
错误码值
原因
建议方案
20481
初始化错误
检查设备是否被占用,或者权限是否正常,是否初始化正常
20482
正在播放中,试图打断并播放下一个失败了(正常是可以打断的)
检查代码逻辑是否正确
20483
参数为空
检查代码中接口参数是否正确
20484
内部错误
初始化播放器错误,解码失败等问题产生此错误码,需要结合日志定位问题

示例代码

handleGMEEvent(event) {
switch (event.code) {
//接收出现错误的情况
case "ERROR":
console.log("Error" , event)
break;
//播放完成事件
case "ITMG_MAIN_EVNET_TYPE_PTT_PLAY_COMPLETE":
console.info("ITMG_MAIN_EVNET_TYPE_PTT_PLAY_COMPLETE" , event)
break;
}
}

停止播放语音

此接口用于停止播放语音。停止播放语音也会有播放完成的回调。

接口原型

stopPlayFile()

示例代码

this.GMEInstance.stopPlayFile();

将指定的语音文件翻译成文字(指定语言)

此接口可以指定语言进行识别,也可以将语音中识别到的信息翻译成指定的语言返回。
注意
翻译会收取额外费用,请参见 购买指南

接口原型

speechToText(file_id , source_language ,translate_language)
参数
类型
含义
file_id
String
语音文件 url,录音在服务器存放90天
source_language
String
识别出指定文字的语言参数,参数参见 语言参数参考列表
translate_language
const char*
翻译成指定文字的语言参数,参数参见 言参数参考列表

示例代码

this.GMEInstance.speechToText(this.cos_url.string , "cmn-Hans-CN" , "cmn-Hans-CN")

识别回调

将指定的语音文件识别成文字的回调,事件消息为 ITMG_MAIN_EVNET_TYPE_PTT_TRANSLATOR_COMPLETE, 在 OnEvent 函数中对事件消息进行判断。 传递的参数包含三个信息,code和 text,其中 text 为识别的文本。
参数
类型
含义
code
int
当 code 为0时,录制完成
text
String
转换的文本结果

错误码

出现错误可以在ERROR事件里监听
错误码值
原因
建议方案
32769
内部错误
分析日志,获取后台返回给客户端的真正错误码,并联系后台同事协助解决
32770
网络失败
检查设备网络是否可以正常访问外网环境
32772
回包解包失败
分析日志,获取后台返回给客户端的真正错误码,并联系后台同事协助解决
32774
没有设置 appinfo
检查鉴权密钥是否正确,检查是否有初始化离线语音
32776
authbuffer 校验失败
检查 authbuffer 是否正确
32784
语音转文本参数错误
检查代码中接口参数 fileid 是否为空
32785
语音转文本翻译返回错误
离线语音后台错误,请分析日志,获取后台返回给客户端的真正错误码,并联系后台同事协助解决
32787
转文本成功,文本翻译服务未开通
需要在控制台开通文本翻译服务
32788
转文本成功,文本翻译语言参数不支持
重新检查传入参数

示例代码

handleGMEEvent(event) {
switch (event.code) {
//接收出现错误的情况
case "ERROR":
console.log("Error" , event)
break;
//转文本完成
case "ITMG_MAIN_EVNET_TYPE_PTT_TRANSLATOR_COMPLETE":
console.log("ITMG_MAIN_EVNET_TYPE_PTT_TRANSLATOR_COMPLETE" ,event)
this.translte_text.string = event.data.message.text;
break;
}
}