在线语音合成Android SDK文档

文档修订记录

文档版本号	修订日期	修订原因
V1.0	2022.8.30	创建文档
V1.1	2023.10.23	优化文档

概述

TTS模块主要是文字转语音的功能，目前支持返回音频链接、二进制音频流。

权限声明

网络权限 - 使用过程中，会有wss请求、网络状态检测

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" /> 

存储权限 - 使用过程中，会写入日志文件（debug）、保存音频文件，请在清单中指定以下内容。

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />   
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!-- android10 以上需要额外添加-->
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

在android10及以上需要在application标签下添加如下配置

<application android:requestLegacyExternalStorage="true">

配置文件

需要在 turing_config.json 中添加 tts 节点

{
  "authorization": {
    "apikey": "您的apikey",
    "secret": "您的secret"
  },
  "ability": {
    "tts": {
      "tone": "huiting",
      "format": "MP3_16_16",
      "speed": 5,
      "volume": 3,
      "pitch": 5,
      "arousal": 6
    }
  }
}

接口说明

public interface TuringTtsInterface {
    /**
     * TTS合成音频链接，使用全局配置文件Turing_config.json中的参数，需配置tts参数
     *
     * @param text        需要转语音的文字
     * @param isAssignTts 是否使用配置文件中的tts参数
     * @param listener    回调接口
     * @return 你输入的字符串会被切割为SparseArray<String>
     */
    SparseArray<String> actionTts(String text, boolean isAssignTts, TuringOSClientListener listener);

    /**
     * TTS合成音频链接
     *
     * @param text             需要转语音的文字
     * @param listener         回调接口
     * @param ttsRequestConfig tts请求参数，如设置为空，则使用Turing_config.json中的tts配置，如没有tts配置，则使用默认值
     * @return 你输入的字符串会被切割为SparseArray<String>
     */
    SparseArray<String> actionTts(String text, TtsRequestConfig ttsRequestConfig, TuringOSClientListener listener);

    /**
     * TTS合成并播放，使用全局配置文件Turing_config.json中的参数，需配置tts参数
     *
     * @param text                       需要转语音的文字
     * @param isAssignTts                是否指定tts参数 ，参数配置在Turing_config.json中
     * @param listener                   回调接口
     * @param turingOSClientPlayListener 音频播放回调接口
     * @return
     */
    SparseArray<String> actionTtsPlay(String text, boolean isAssignTts, TuringOSClientListener listener,
                                      TuringOSClientPlayListener turingOSClientPlayListener);

    /**
     * TTS合成并播放
     *
     * @param text                       需要转语音的文字
     * @param ttsRequestConfig           tts请求参数，如设置为空，则使用Turing_config.json中的tts配置，如没有tts配置，则使用默认值
     * @param listener                   回调接口
     * @param turingOSClientPlayListener 音频播放回调接口
     * @return
     */
    SparseArray<String> actionTtsPlay(String text, TtsRequestConfig ttsRequestConfig, TuringOSClientListener listener,
                                      TuringOSClientPlayListener turingOSClientPlayListener);

    /**
     * TTS合成文件，使用全局配置文件Turing_config.json中的参数，需配置tts参数
     *
     * @param text        需要转语音的文字
     * @param filePath    合成之后的文件的文件父路径
     * @param isAssignTts 是否指定tts参数 ，参数配置在Turing_config.json中
     * @param listener    回调接口
     * @return
     */
    public SparseArray<String> actionTtsToUri(String text,
                                              String filePath,
                                              boolean isAssignTts,
                                              TuringOSClientListener listener);

    /**
     * TTS合成文件
     *
     * @param text             需要转语音的文字
     * @param filePath         合成之后的文件的文件父路径
     * @param ttsRequestConfig tts请求参数，如设置为空，则使用Turing_config.json中的tts配置，如没有tts配置，则使用默认值
     * @param listener         回调接口，onSuccess中的extension参数是具体的tts路径
     * @return
     */
    public SparseArray<String> actionTtsToUri(String text,
                                              String filePath,
                                              TtsRequestConfig ttsRequestConfig,
                                              TuringOSClientListener listener);

    /**
     * 停止播放
     */
    boolean stopPlay();

    /**
     * 暂停播放
     */
    boolean pausePlay();

    /**
     * 继续播放
     */
    boolean resumePlay();

    /**
     * 是否正在播放
     */
    boolean isPlaying();

    /**
     * 资源释放
     */
    void release();
}

使用说明

功能描述

• tts合成时，如果文本大于500个字符，会将文本按最大500个字符分割成一个数组，分别将数组的每一条数据合成一个tts，接口返回的结果就是分割的文本数组

支持的所有方式：

• TTS合成并返回音频链接：输入目标文本，合成TTS链接，需要自行播放tts链接
• TTS合成并播放音频：输入目标文本，合成流式TTS，播放流式音频
• TTS合成本地音频文件：输入目标文本，合成本地TTS音频文件

接口类型：

• 类型一：全局使用turing_config中的配置参数，需要在 turing_config.json 中添加 tts节点，节点字段见《接入指南说明文档》配置文件参数说明。可使用TuringConfig.setConfigData设置全局配置参数，此参数在使用到配置文件的接口全局生效，适用于不频繁修改参数场景
• 类型二：不使用 turing_config.json 中的配置，使用入参带TtsRequestConfig 的接口，此参数仅调用时生效，适用于频繁修改参数场景。

实例化

val turingTts:TuringTtsInterface = TuringTts.getInstance(this)

一、TTS合成本地音频文件

方法一：TTS合成音频链接，使用全局配置文件Turing_config.json中的参数，需配置tts参数

val tts = TuringConfig.getInstance(this).configData.ability.tts
tts.speed = 10
turingTts.actionTts(text, true, object : TuringOSClientListener{
    override fun onResult(
        code: Int,
        result: String?,
        responBean: BaseResp?,
        extension: String?
    ) {
        if (responBean?.nlpResponse != null && responBean.nlpResponse
                .results != null
        ) {
            val resultsBeanList: List<BaseResp.NlpResponse.ResultsBean> =
                responBean.getNlpResponse().getResults()
            val valuesBean: BaseResp.NlpResponse.ResultsBean.ValuesBean =
                resultsBeanList[0].getValues()
            if (valuesBean != null) {
                if (valuesBean.getTtsUrl() != null) {
                    val url: String = valuesBean.getTtsUrl().get(0)
                    if (!TextUtils.isEmpty(url)) {
                        addPlayUrl(url)
                    }
                }
            }
        }
        mUIHandler.postRunnable(Runnable {
            result?.let {
                resultList.add(it)
            }
            resultAdapter!!.updateList(resultList)
            resultRecycleview.smoothScrollToPosition(resultList.size - 1)
        })
    }

    override fun onError(code: Int, msg: String?) {
        Log.e(TAG, "onError code: $code  msg: $msg")
    }
})

方法二：TTS合成音频链接，使用局部生效参数

val ttsConfig = TtsRequestConfig.Builder().speed(10).build()
turingTts.actionTts(text, ttsConfig, turingOSClientListener)

TuringOSClientListener接口的onResult方法说明，ttsUrl为合成目标文字的音频链接。

返回示例：

{
    "code":200,
    "globalId":"98412556156000000",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":50101
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "ttsUrl":[
                        "http://turing-iot.oss-cn-beijing.aliyuncs.com/tts/tts-0b6c2dd6687a4c8cb73a3ca49ed9b3ca-ef856c768eb2495bafce0fd01eeade93.mp3"
                    ],
                    "text":"北京今天天气怎么样?"
                }
            }
        ]
    }
}

二、TTS合成并播放音频

• 该方式请求TTS后会在TuringOSClientListener中回调请求日志，并在TuringOSClientPlayListener中回调播放信息。
• 该方法时请求后直接播放音频，不需要单独的开启播放的操作。所针对一些合成并播放的场景可以使用该方式；
• 该方式不支持设置TtsRequestConfig的format参数。

方法一：TTS合成音频链接，使用全局配置文件Turing_config.json中的参数，需配置tts参数

val tts = TuringConfig.getInstance(this).configData.ability.tts
tts.speed = 10
turingTts.actionTtsPlay(text, true, object : TuringOSClientListener {
            override fun onResult(
                code: Int,
                result: String?,
                responBean: BaseResp?,
                extension: String?
            ) {
                if (responBean != null && responBean.nlpResponse != null && responBean.nlpResponse.results != null) {
                    val resultsBeanList = responBean.nlpResponse.results
                    val valuesBean = resultsBeanList[0].values
                    if (valuesBean != null) {
                        if (valuesBean.ttsUrl != null) {
                            val url = valuesBean.ttsUrl[0]
                            if (!TextUtils.isEmpty(url)) {
                            }
                        }
                    }
                }
                mUIHandler.postRunnable {
                    resultList.add(result!!)
                    resultAdapter!!.updateList(resultList)
                    resultRecycleview.smoothScrollToPosition(resultList.size - 1)
                }
            }

            override fun onError(code: Int, msg: String) {
                Log.e(TAG, "onError code: $code  msg: $msg")
            }
        }, object : TuringOSClientPlayListener {
            override fun onPlayStart(text: String?) {
                Log.e(TAG, "onPlayStart text:")
            }

            override fun onPlayError(message: String?) {
                Log.e(TAG, "onPlayError")
            }

            override fun onPlayComplete() {
                Log.e(TAG, "onPlayComplete")
            }

            override fun onPlayPaused() {
                Log.e(TAG, "onPlayPaused")
            }

            override fun onPlayResumed() {
                Log.e(TAG, "onPlayResumed")
            }
        })

方法二：TTS合成音频链接，使用局部生效参数

val ttsConfig = TtsRequestConfig.Builder().speed(10).build()
turingTts.actionTtsPlay(text, ttsConfig, turingOSClientListener,turingOSClientPlayListener)

播放状态控制

停止播放：

turingTts.actionStopPlay();

暂停播放：

turingTts.actionPausePlay();

继续播放：

turingTts.actionResumePlay(); 

注意：以上播放控制的方法对语音聊天模块同样有效，所以尽可能明确设备正在处理播放的模块。

返回示例：

{
    "code":200,
    "globalId":"130611147397245001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":50101
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "ttsStreamId":"fb6b658e88194dbfab969f829348097f",
                    "text":"佩奇(Peppa Pig)（英文配音：海莉·博德，中文配音：陈奕雯） 佩奇是一只非常可爱的小猪，她和她的妈妈、爸爸以及弟弟乔治生活在一起。她和弟弟一样很喜欢恐龙，尤其是马门溪龙。 她最喜欢跳泥坑，"
                }
            }
        ]
    }
}

使用该方式时语音合成成功会在onResult返回合成信息，若目标文字过长时，会分段返回结果，调用开始后直接播放音频。

三、TTS合成本地音频文件

• 该方式请求TTS后会在TuringOSClientListener的onResult中回调合成的文件路径，具体值为extension值。
• 该方式中TtsRequestConfig不应为空，并且需要设置format参数；
• 该方式需要传入合成文件的存储路径，例如：String filePath = “/storage/emulated/0/turingos/tts/”，合成结果为：/storage/emulated/0/turingos/tts/WAV_16_16_20200630172821.wav；
• 合成文件名规则：WAV_16_16_20200630172821.wav，格式+日期+对应格式的文件后缀，文件格式应为ttsRequestConfig中的format参数的值；
• 当目标文字过长时，从开始请求到合成完成回调结果需要一定的延时。

方法一：使用全局配置turing_config.json参数

turingTts.actionTtsToUri(text,"/sdcard/turingos/",true,object:TuringOSClientListener{
    override fun onResult(
        code: Int,
        result: String?,
        baseResp: BaseResp?,
        extension: String?
    ) {
        if (code==200&&extension!=null){
            Log.d(TAG,"tts合成结束，path:$extension")
        }
        Log.d(TAG,"code:$code extension:$extension")
        Log.d(TAG, "onResult result:$result")
    }

    override fun onError(code: Int, msg: String?) {
        Log.d(TAG,"onError code:"+code)
    }

})

方法二：使用TtsRequestConfig参数

val ttsRequestConfigBuilder = TtsRequestConfig.Builder();
    ttsRequestConfigBuilder.pitch(pitch + 1)
            .speed(speed + 1)
            .volume(volume + 1)
            .arousal(arousal + 1)
            //需要指定tts合成的格式
            .format("WAV_16_16")
            .tone(voiveTone);
val ttsRequestConfig = ttsRequestConfigBuilder.build();
val path = SdkInitializer.getFilePath() + "tts/";
turingTts.actionTtsToUri(text, path, ttsRequestConfig, object:TuringOSClientListener{
            override fun onResult(
                code: Int,
                result: String?,
                baseResp: BaseResp?,
                extension: String?
            ) {
                if (code==200&&extension!=null){
                    Log.d(TAG,"tts合成结束，path:$extension")
                }
                Log.d(TAG,"code:$code extension:$extension")
                Log.d(TAG, "onResult result:$result")
            }

            override fun onError(code: Int, msg: String?) {
                Log.d(TAG,"onError code:"+code)
            }

        });

区分中英文配置

如果需要单独设置英文tts配置，可在配置文件中增加与tts同级的enTts对象，字段跟tts一致

方法一：使用全局配置文件Turing_config.json

在ability下，添加与tts字段同级别的enTts，参数与tts一致，如下：

{
  "authorization": {
    "apikey": "您的apikey",
    "secret": "您的secret"
  },
  "ability": {
    "tts": {
      "tone": "huiting",
      "format": "MP3_16_16",
      "speed": 5,
      "volume": 3,
      "pitch": 5,
      "arousal": 6
    },
    "enTts": {
      "tone": "huiting",
      "format": "MP3_16_16",
      "speed": 5,
      "volume": 3,
      "pitch": 5,
      "arousal": 6
    }
  }
}

方法二：使用TtsRequestConfig

en开头是英文参数，否则是中英混合参数，如需设置英文参数，还需设置setEnConfig(true)，如下：

val ttsConfig = TtsRequestConfig.Builder().setEnConfig(true).enSpeed(10).enPitch(6).build()

参数说明

输入参数

TtsRequestConfig、tts

参数	类型	是否必须	取值范围	说明
tone	String	No	-	默认"小雪"，2023年09月13日前创建的机器人，默认音色为zhiwa，其他音色请联系商务
format	String	No	-	输出格式，默认MP3_16_16，参见“format参数说明-item”
speed	Int	No	1~9	语速设置，取值范围1~9，默认为5
volume	Int	No	1~9	音量设置，取值范围1~9，默认为5
pitch	Int	No	1~9	语调设置，取值范围1~9，默认为5
arousal	Int	No	1~9	语音波动，取值范围1~9，默认为5
ext	Map	No	tts#ext参数说明	附加参数

tts#ext参数说明

字段	类型	必填	说明
xunFeiTone	String	使用讯飞音色必填	讯飞音色参数，使用此参数时，tts#tone需要设置为“xunfei”
bdVoice	String	使用字节音色必填	参考字节文档【voice】
bdVoiceType	String	使用字节音色必填	参考字节文档【voice_type】
bdStyleName	String	非必填	参考字节文档【style_name】

tone参数说明

名称	说明	性别
zhiwa	图灵智娃	中英混合男童
aq	图灵阿Q	中英混合女童
huiting	图灵慧听	中英混合成年女声

xunFeiTone参数说明

名称	说明	性别
x3_xiaozhong	小忠	中文男
x3_xiaoguo	小果	中文女
x2_engam_ryan	Ryan	英文男
x2_engam_lindsay	lindsay	英文女

format参数说明

item	Model
AMR_NB	amr-8khz-16bit
MP3_16_16	mp3-16khz-16kpbs
MP3_16_24	mp3-16khz-24kpbs
MP3_16_64	mp3-16khz-64kpbs
WAV_16_16	wav-16khz-16bit
PCM_16_16	pcm-16khz-16bit
PCM_8_16	pcm-8khz-16bit
OPUS_16_16	opus-16khz-16bit

参数优先级说明

• TTS音色有特殊需求和定制，可以联系图灵商务；
• 当不设置TTS音色以及音量等参数时，默认使用图灵平台云端配置的默认参数；若设置参数与图灵平台云端配置参数不一致时，会导致合成音频无法播放。
• 另外每一次请求设置的参数只对该次有效，下一次请求如果不设置参数，将使用图灵平台云端配置的默认参数；
• 可以联系图灵技术支持通过云端配置音色音量等参数，请求时可以省略TtsRequestConfig参数。

回调接口

TuringOSClientListener

详细说明见《语音对话接入文档》

输出参数

BaseResp说明

参数	类型	说明
code	int	请求响应Code，具体可参考Code说明
message	String	请求响应的消息描述
nlpResponse	NlpResponse（Object）

• 当code=200表示识别成功；
• 其他code表示识别异常，参考Code说明。

NlpResponse

参数	类型	说明
intent	Intent（Object）	语义理解结果的实体内容
results	List（Object）	语义理解结果的提示语和播放内容集合

NlpResponse-Intent

参数	类型	说明
code	Intent（Object）	此次请求命中的技能Code TT合成模块固定返回50101

NlpResponse-List-Results

参数	类型	说明
groupType	int	组类型(普通接入可忽略该参数): 0为独立输出; 大于0时可能包含同组相关内容
resultType	String	输出类型： 当 resultType=text 时：表示文本 TTS合成场景固定返回text
values	Values（Object）	输出内容（必会包含 resultType 对应的 key， 其他会根据具体应用场景进行字段扩充）

NlpResponse-List-Results-Values

参数	类型	说明
ttsUrl	String[]	文字合成语音的音频链接
text	String	合成目标，即输入的文字