全部产品
阿里云办公

Java SDK 1.0

更新时间:2018-12-10 10:59:13

本文档为智能语音交互1.0,新用户请使用智能语音交互2.0

功能介绍

语音Java SDK提供提供将文本转为普通话语音的语音合成功能。

获取appkey

获取appkey

SDK下载地址

语音合成JavaSDK

压缩包内为Java Demo工程,SDK jar包在src/main/java/resources/目录下,用户需要在IDE中操作将jar包导入。

  • IDEA 中的操作方法为在jar包上右键,选”Add as library…”。
  • Eclipse中的操作方法为在工程上右键,选“Build Path”->“Add Library…”。

示例说明

SDK调用顺序

  1. 创建一个NlsClient的实例并调用init()方法来初始化客户端。

  2. 提取语音数据并创建语音合成请求,至少填写appKey及需要合成的语音内容。创建一个NlsListener的实现类。

  3. 创建一个文件用于保存合成的语音数据。调用NlsClient的createNlsFuture(第2步中的listener实例作为入参之一,用来处理返回结果)方法获取future,通过future的read方法来读取从服务端返回的语音数据,并保存到创建的文件中,并在listener的回调方法中返回是否成功。

  4. 读取完服务端返回的合成语音数据后,调用await等待服务端返回确认结果。

  5. 如有多个合成需要,重复步骤2-4。

  6. 调用NlsClient的close()方法来关闭客户端并释放资源。

SDK调用注意事项

  1. NlsClient创建一次可以重复使用,每次创建消耗性能

  2. NlsClient使用了netty的框架,创建时比较消耗时间和资源,但创建之后可以重复利用。建议调用程序将NlsClient的创建和关闭与程序本身的生命周期结合。

  3. 每一次调用语音合成请求时注入的NlsListener只对本次语音合成的生命周期负责。

  4. 每次调用createNlsFuture(NlsRequest req, com.alibaba.idst.nls.event.NlsListener listener)方法做语音合成时,注入的listener只对本次合成起作用。其他的语音合成进程不会触发该listener。

  5. NlsRequest里面的语音格式请与要保存的语音文件的格式保持一致。目前SDK支持pcm、wav、mp3。

  6. sdk只会根据该格式来合成语音数据。

  7. NlsListener的实现类里面,处理返回结果的代码尽量耗时剪短,最好不要涉及I/O操作。

  8. NlsListener的实现类中的处理方法是在NlsClient的语音合成线程中调用的,太长的操作时间导致线程不能及时释放会影响其他合成进程的顺利进行,同时也会影响整个程序的loading。I/O操作应该禁止在该实现类中出现,最好使用触发的方式将操作转移到其他线程中去进行。

  9. 并发或多线程支持,如果需要在您的应用支持多个并发请求,请不要重复创建NlsClient对象。正确的做法是构建不同的NlsRequest对象,同时创建不同的NlsListener,并传入NlsRequest对象。这样就可以并发不同请求并且拿到正确的相应的结果。

重要接口说明

com.alibaba.idst.nls.NlsClient


语音sdk对外暴露的类,调用程序通过调用该类的init()、close()、createNlsFuture()等方法来打开、关闭或发送语音数据。

初始化NlsClient

public void init((boolean sslMode, int port)

  • 说明 初始化NlsClient,创建好websocket client factory
  • 参数

    • sslMode 是否采用ssl模式,一般设置为true
    • port 端口号,一般为443
  • 返回值 null

设置服务器地址

public void setHost(String host)

  • 说明 设置服务器地址
  • 参数

  • 返回值 null

实例化NlsFuture请求

public NlsFuture createNlsFuture(NlsRequest req, com.alibaba.idst.nls.event.NlsListener listener)

  • 说明 实例化NlsFuture请求,传入请求和监听器
  • 参数

    • req 请求对象
    • listener 回调数据的监听器
  • 返回值 future

关闭NlsClient

public void close()

  • 说明 关闭websocket client factory,释放资源
  • 参数

    null

  • 返回值 null

com.alibaba.idst.nls.event.NlsListener


合成结果状态回调

void onMessageReceived(NlsEvent e);

  • 说明 合成结果状态回调
  • 参数

    • NlsEvent Nls服务结果的对象 合成结果状态在e.getResponse()中
  • 返回值 null

合成失败回调

void onOperationFailed(NlsEvent e);

  • 说明 合成失败回调
  • 参数

    • NlsEvent Nls服务结果的对象 错误信息在e.getErrorMessage()中
  • 返回值 null

socket 连接关闭的回调

void onChannelClosed(NlsEvent e);

  • 说明 socket 连接关闭的回调
  • 参数

    • NlsEvent Nls服务结果的对象
  • 返回值 null

com.alibaba.idst.nls.protocol.NlsRequest


语音合成的请求封装对象。调用程序需要至少在请求对象里设定好调用者的appKey以便后台服务能正确合成语音。

初始化Nls 请求:NlsRequest mNlsRequest = new NlsRequest(proto)

public void setAppKey(String app_key)

  • 说明 设置应用的appkey,appkey需要先申请再使用。
  • 参数
    • app_key
  • 返回值 null

public void authorize(String id, String secret)

  • 说明 数加认证模块,所有的请求都必须通过authorize方法认证通过,才可以使用。 id和secret需要申请获取。
  • 参数
    • id id。
    • secret 对应密钥。
  • 返回值 null

public void setTtsRequest(String tts_text)

  • 说明 TTS 服务调用接口,传入文本,返回语音结果
  • 参数
    • tts_text 用户输入的文本请求
  • 返回值 null

public void setTtsRequest(String tts_text, String sample_rate)

  • 说明 TTS 服务调用接口,传入文本,返回语音结果
  • 参数
    • tts_text 用户输入的文本请求
    • sample_rate 返回语音采样率 支持8k,16k等
  • 返回值 null

public void setTtsVoice(String voiceName)

  • 说明 设置tts返回发音人,有两个选项 xiaoyun(女声)、xiaogang(男声)。
  • 参数
    • voiceName xiaoyun/xiaogang
  • 返回值 null

public void setTtsNus(int nus)

  • 说明 nus模式选择,0为参数,1为拼接(电话客户场景请选0)

    参数是指最终合成语音的时候是通过一组参数生成的语音数据,拼接的意思是通过拼接原始的录音数据得到语音数据

  • 参数
    • nus 取值范围0或1,默认1
  • 返回值 null

public void setTtsEncodeType(String encodeType)

  • 说明 设置tts返回语音的格式类型,目前支持pcm、wav、alaw、mp3。
  • 参数
    • encodeType 类型
  • 返回值 null

public void setTtsSpeechRate(String speechRate)

  • 说明 语速,默认输入为0,阈值-500~500,从慢到快。
  • 参数
    • speechRate 语速
  • 返回值 null

public void setTtsVolume(String volume)

  • 说明 音量大小默认50,阈值0-100。
  • 参数
    • volume 音量
  • 返回值 null

public void setTtsBackgroundMusic(int id)

  • 说明 设置开启背景音乐
  • 参数
    • id 音乐id 0,1
  • 返回值 null

public void setTtsPitchRate(int pitchRate)

  • 说明 设置tts发音语调,-500非常低沉,500非常高亢
  • 参数
    • pitchRate 调整语调,-500~500
  • 返回值 null

com.alibaba.idst.nls.internal.protocol.NlsRequestProto


NlsRequest对象初始化时需要注入的参数。

public void setApp_id(String app_id)

  • 设置application_id.

public void setApp_user_id(String app_user_id)

  • 设置app_user_id.

com.alibaba.idst.nls.NlsFuture


NlsFuture是具体操作语音的对象类,语音数据的发送/接收都通过这个类进行操作。

public byte[] read()

  • 说明 TTS(文本转语音)时,输出语音流
  • 参数
  • 返回值 byte[]

public boolean await(int timeout)

  • 说明 请求超时时间
  • 参数
    • timeout 请求发送出去后,等待服务端结果返回的超时时间,单位ms
  • 返回值 true false

com.alibaba.idst.nls.protocol.NlsResponse


语音合成的返回结果封装对象。返回结果告知语音合成是否成功,语音合成是否已经结束。

  • 说明 TTS(文本转对话)的状态等文本的提升结果,语音结果通过future.read()获取
  • 参数
    • null
  • 返回值 String

错误码

状态 status_code CloseFrame状态码 HTTP语义
成功 200 1000 成功处理
请求格式有误 400 4400 错误请求
需要鉴权信息 401 4401 请求要求身份验证
鉴权失败 403 4403 服务器拒绝请求
超出最大并发量 429 4429 太多请求
请求超时 408 4408 处理请求超时
处理出错 500 4500 服务器内部错误
服务不可用 503 4503 服务不可用

完整示例

  1. package com.demo;
  2. import com.alibaba.idst.nls.protocol.NlsResponse;
  3. import com.alibaba.idst.nls.NlsClient;
  4. import com.alibaba.idst.nls.NlsFuture;
  5. import com.alibaba.idst.nls.event.NlsEvent;
  6. import com.alibaba.idst.nls.event.NlsListener;
  7. import com.alibaba.idst.nls.protocol.NlsRequest;
  8. public class TTSDemo implements NlsListener {
  9. private NlsClient client = new NlsClient();
  10. public TTSDemo() {
  11. System.out.println("init Nls client...");
  12. // 初始化NlsClient
  13. client.init();
  14. }
  15. public void shutDown() {
  16. System.out.println("close NLS client");
  17. // 关闭客户端并释放资源
  18. client.close();
  19. System.out.println("demo done");
  20. }
  21. public void startTTS() {
  22. File file = new File("tts.wav");
  23. if(!file.exists()) {
  24. try {
  25. file.createNewFile();
  26. } catch (Exception e) {
  27. e.printStackTrace();
  28. }
  29. }
  30. NlsRequest req = new NlsRequest();
  31. String appkey = "nls-service";
  32. req.setAppKey(appkey); // 设置语音文件格式
  33. req.setTtsRequest(tts_text); //传入测试文本,返回语音结果
  34. req.setTtsEncodeType("wav");//返回语音数据格式,支持pcm、wav、alaw、mp3
  35. req.setTtsVolume(30); //音量大小默认50,阈值0-100
  36. req.setTtsSpeechRate(0); //语速,阈值-500~500
  37. req.setTtsBackgroundMusic(1);//背景音乐编号
  38. req.authorize("", ""); // 请替换为用户申请到的Access Key ID和Access Key Secret
  39. try {
  40. FileOutputStream fileOutputStream = new FileOutputStream(file);
  41. NlsFuture future = client.createNlsFuture(req, this); // 实例化请求,传入请求和监听器
  42. int total_len = 0;
  43. byte[] data ;
  44. while((data = future.read()) != null) {
  45. fileOutputStream.write(data, 0, data.length);
  46. total_len += data.length;
  47. System.out.println("tts length " + data.length);
  48. }
  49. fileOutputStream.close();
  50. System.out.println("tts audio file size is :" + total_len);
  51. future.await(10000); // 设置服务端结果返回的超时时间
  52. } catch (Exception e) {
  53. e.printStackTrace();
  54. }
  55. }
  56. @Override
  57. public void onMessageReceived(NlsEvent e) {
  58. NlsResponse response = e.getResponse();
  59. String result = "";
  60. int statusCode = response.getStatus_code();
  61. if (response.getTts_ret() != null) {
  62. result += "\nget tts result: statusCode=[" + statusCode + "], " + response.getTts_ret();
  63. }
  64. if (result != null) {
  65. System.out.println(result);
  66. }
  67. else {
  68. System.out.println(response.jsonResults.toString());
  69. }
  70. }
  71. @Override
  72. public void onOperationFailed(NlsEvent e) {
  73. //合成失败的回调
  74. System.out.print("on operation failed: ");
  75. System.out.println(e.getErrorMessage());
  76. }
  77. @Override
  78. public void onChannelClosed(NlsEvent e) {
  79. //socket 连接关闭的回调
  80. System.out.println("on websocket closed.");
  81. }
  82. /**
  83. * @param args
  84. */
  85. public static void main(String[] args) {
  86. TTSDemo ttsDemo = new TTSDemo();
  87. ttsDemo.startTTS();
  88. ttsDemo.shutDown();
  89. }
  90. }