[TOC]
# **语音消息**
## 概述
本小节介绍语音消息API相关内容，独立的语音消息业务仅参考此小节即可。
## 错误码
| 类型 | 值 |
| --- | --- |
| SUCCESSED | 0 ：成功 |
| ENGINE_ERROR | 1：语音引擎出错 |
| DOWNLOADING | 2：下载出错 |
| AUTH_ERROR | 3：鉴权出错 |
| APPID_FORMAT_ERROR | 4：appid格式错误 |
| FILE_PATH_ERROR | 5：文件路径错误 |
| FILE_REPEAT_ERROR | 6：重复打开或创建文件 |
| ENVIRONMENT_ERROR | 7：环境配置错误 |
| FILE_UNRELEASE_ERROR | 8：文件未释放 |
| TIME_OUT | 9：超时 |
## CreateLarkMsgEngine 创建语音消息引擎
**语音消息引擎创建**
1.接口说明
使用服务前，获取语音消息引擎对象，返回语音消息引擎对象。
2.函数原型
~~~
public static ILarkMsgEngine CreateLarkMsgEngine();
~~~
3.示例代码
~~~
larkMsgEngine = LarkMsgEngineFactory.CreateLarkMsgEngine();
~~~
## Init 初始化语音消息引擎
**语音消息引擎初始化**
1.接口说明
初始化语音引擎，需在创建引擎之后，调用其他服务之前。
2.函数原型
~~~
ErrorCode Init(string appID, string appKey, string userID);
~~~
3.示例代码
`larkMsgEngine.Init("testid", "testkey", "user");`
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| appID | string | Lark平台注册分配的APPID |
| appKey | string | Lark平台注册分配的APPKEY |
| userID | string | 玩家唯一的身份标识 |
4.返回
正确返回SUCCESSED，错误返回错误码ENGINE_ERROR、APPID_FORMAT_ERROR、ENVIRONMENT_ERROR。
## StartRecording 开始录音
**录音到文件**
1.接口说明
开始录音到指定路径，形成录音文件，限制单个语音消息文件录音时间为2分钟，超过2分钟的数据不予录音到文件内，录音完成后请调用StopRecording停止录音。
2.函数原型
`ErrorCode StartRecording(string path);`
3.示例代码
~~~
larkMsgEngine.StartRecording(uppath);
~~~
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| uppath | string | 录音产生的文件的路径 |
4.返回
正确返回SUCCESSED，错误返回错误码FILE_PATH_ERROR、FILE_REPEAT_ERROR、ENGINE_ERROR。
## StopRecording 停止录音
**停止录音**
1.接口说明
停止录音，并关闭录音文件。
2.函数原型
~~~
ErrorCode StopRecording();
~~~
3.示例代码
~~~
larkMsgEngine.StartRecording();
~~~
4.返回
正确返回SUCCESSED，错误返回错误码ENGINE_ERROR。
## StartPlayRecordedFile 播放录音文件
**播放录音文件，即语音消息**
1.接口说明
从指定路径获取录音文件，并播放。当文件没有播放完成再次点击播放会从文件开始处重播，通过StopPlayRecordedFile停止播放，或者直至播完回调PlayRecordFileCompletehandler。
2.函数原型
~~~
ErrorCode StartPlayRecordedFile(string downloadFilePath);
~~~
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| downloadFilePath | string | 待播放的录音文件的路径 |
3.示例代码
~~~
larkMsgEngine.StartPlayRecordedFile(downpath);
~~~
4.返回
正确返回SUCCESSED，错误返回错误码ENGINE_ERROR。
## StopPlayRecordedFile 停止播放
**停止播放录音文件**
1.接口说明
停止播放录音文件，并关闭文件，如果重复关闭，内部没有可关闭的文件，返回ENGINE_ERROR。
2.函数原型
~~~
ErrorCode StopPlayRecordedFile();
~~~
3.示例代码
~~~
larkMsgEngine.StopPlayRecordedFile();
~~~
4.返回
正确返回SUCCESSED，错误返回错误码ENGINE_ERROR。
## DownLoadRecordFile 下载录音文件
**下载录音文件，即消息语音**
1.接口说明
根据服务器提供的fileid下载录音文件，到指定路径。
2.函数原型
~~~
ErrorCode DownLoadRecordFile(string fileID, string downloadFilePath, int msTimeout);
~~~
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| fileID | string | 服务器返回的唯一标识文件id |
| downloadFilePath | string | 下载文件到指定路径 |
| msTimeout | string | 超时设置，单位毫秒，未正确设值时，将使用默认30s |
3.示例代码
~~~
larkMsgEngine.DownLoadRecordFile(g_fileID, downpath, 1000);
~~~
4.返回
正确返回SUCCESSED。
## UploadRecordedFile 上传录音文件
**上传录音文件，即消息语音**
1.接口说明
将指定路径的录音文件上传至服务器。
2.函数原型
~~~
ErrorCode UploadRecordedFile(string filePath, int msTimeout);
~~~
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| filePath | string | 文件路径 |
| msTimeout | string | 超时设置，单位毫秒，未正确设值时，将使用默认30s |
3.示例代码
~~~
larkMsgEngine.UploadRecordedFile(g_fileID, 1000);
~~~
4.返回
正确返回SUCCESSED。
## Poll 轮询
**轮询任务**
1.接口说明
轮询任务队列，完成上传、下载、读、写等异步任务管理。
2.函数原型
~~~
ErrorCode Poll();
~~~
3.示例代码
~~~
larkMsgEngine.Poll();
~~~
4.返回
正确返回SUCCESSED。
## EnginePause 语音引擎暂停
**暂停语音引擎**
1.接口说明
当客户端切后台，需要调用语音引擎暂停，如果有录音和播放，都将被暂停。
2.函数原型
~~~
ErrorCode EnginePause();
~~~
3.示例代码
~~~
larkMsgEngine.EnginePause();
~~~
4.返回
正确返回SUCCESSED，错误返回ENGINE_ERROR。
## EngineResume 语音引擎恢复
**恢复语音引擎**
1.接口说明
当客户端切后台后转回应用，需要调用语音引擎恢复，如果有被暂停的录音或者播放，将会重新恢复继续。
2.函数原型
~~~
ErrorCode EngineResume();
~~~
3.示例代码
~~~
larkMsgEngine.EngineResume();
~~~
4.返回
正确返回SUCCESSED，错误返回ENGINE_ERROR。
## ApplyMessageKeyCompleteHandler 应用key完成
**应用key完成事件**
1.接口说明
应用key完成回调事件。
2.函数原型
~~~
public delegate void ApplyMessageKeyCompleteHandler(ErrorCode code);
event ApplyMessageKeyCompleteHandler ApplyMessageKeyCompleteHandlerEvent;
~~~
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| code | ErrorCode | 错误码 |
3.示例代码
~~~
larkMsgEngine.ApplyMessageKeyCompleteHandlerEvent += ApplyMessageKeyCompleteHandler;
void ApplyMessageKeyCompleteHandler(ErrorCode code) {
Debug.Log("ApplyMessageKeyCompleteHandler ret: " + code);
}
~~~
4.返回
无。
## UploadReccordFileCompletehandler 上传完成
**上传完成事件**
1.接口说明
上传完成回调事件。
2.函数原型
~~~
public delegate void UploadReccordFileCompletehandler(ErrorCode code, string filePath, string fileID);
event UploadReccordFileCompletehandler UploadReccordFileCompletehandlerEvent;
~~~
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| code | ErrorCode | 错误码 |
| filePath | string | 带上传文件路径 |
| fileID | string | 服务器分配的文件id |
3.示例代码
~~~
larkMsgEngine.UploadReccordFileCompletehandlerEvent += UploadReccordFileCompletehandler;
void UploadReccordFileCompletehandler(ErrorCode code, string filePath, string fileID) {
Debug.Log("UploadReccordFileCompletehandler ret: " + code);
g_fileID = fileID;
}
~~~
4.返回
无。
## DownloadRecordFileCompletehandler 下载完成
**下载完成事件**
1.接口说明
下载完成回调事件。
2.函数原型
~~~
public delegate void DownloadRecordFileCompletehandler(ErrorCode code, string filePath, string fileID);
event DownloadRecordFileCompletehandler DownloadRecordFileCompletehandlerEvent;
~~~
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| code | ErrorCode | 错误码 |
| filePath | string | 下载文件到该路径 |
| fileID | string | 服务器分配的文件id |
3.示例代码
~~~
larkMsgEngine.DownloadRecordFileCompletehandlerEvent += DownloadRecordFileCompletehandler;
void DownloadRecordFileCompletehandler(ErrorCode code, string filePath, string fileID) {
Debug.Log("DownloadRecordFileCompletehandler ret: " + code);
if (fileID == g_fileID) {
larkMsgEngine.StartPlayRecordedFile(filePath);
}
}
~~~
4.返回
无。
## PlayRecordFilCompletehandler 播放完成
**播放完成事件**
1.接口说明
播放完成回调事件。
2.函数原型
~~~
public delegate void PlayRecordFilCompletehandler(ErrorCode code, string filePath);
event PlayRecordFilCompletehandler PlayRecordFilCompletehandlerEvent;
~~~
* 参数说明：
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| code | ErrorCode | 错误码 |
| filePath | string | 播放文件的路径 |
3.示例代码
~~~
larkMsgEngine.PlayRecordFilCompletehandlerEvent += PlayRecordFilCompletehandler;
void PlayRecordFilCompletehandler(ErrorCode code, string filePath) {
Debug.Log("PlayRecordFilCompletehandler ret: " + code + " file is " + filePath);
}
~~~
4.返回
无。
## SetSpeakerVolume 设置语音音量
**音量控制**
1.接口说明
控制语音消息的音量，不改变系统音量，设置范围[0,100]。
2.函数原型
~~~
ErrorCode SetSpeakerVolume(int volume);
~~~
3.示例代码
~~~
larkMsgEngine.SetSpeakerVolume(volume);
~~~
4.返回
错误范围错误码，成功返回SUCCESSED。
## GetSpeakerLevel 获取音量
**获取音量**
1.接口说明
获取音量值，即默认或设置的语音音量值，范围[0,100]
2.函数原型
~~~
int GetSpeakerLevel();
~~~
3.示例代码
~~~
larkMsgEngine.GetSpeakerLevel();
~~~
4.返回
语音消息音量值。
## Destroy 销毁引擎
**销毁引擎**
1.接口说明
调用引擎销毁，将关闭语音消息引擎，释放资源。
2.函数原型
~~~
void Destroy();
~~~
3.示例代码
~~~
larkMsgEngine.Destroy();
~~~
4.返回
无。