跳转到主要内容
Sambert

语音合成Sambert Java SDK

本文介绍语音合成Sambert Java SDK的参数和接口细节。

**用户指南:**关于模型介绍和选型建议请参见实时语音合成-CosyVoice /Sambert。 **在线体验:**暂不支持。

接口地址

SDK 的接口地址需在初始化前设置为下方地址。 wss://maas.qianwenaiapi.com/api-ws/v1/inference, 设置方式:
import com.alibaba.dashscope.utils.Constants;

Constants.baseWebsocketApiUrl = "wss://maas.qianwenaiapi.com/api-ws/v1/inference";

前提条件

快速开始

SpeechSynthesizer类提供了非流式调用和单向流式调用的接口。请根据业务场景选择合适的调用方式:
  • 非流式调用:提交文本后,服务端立即处理并返回完整的语音合成结果。整个过程是阻塞式的,客户端需要等待服务端完成处理后才能继续下一步操作。适合短文本合成场景。
  • 单向流式调用:将文本一次发送至服务端并实时接收语音合成结果,不允许将文本分段发送。适用于对实时性要求高的场景。

非流式调用

提交单个语音合成任务,无需调用回调方法,进行语音合成(无流式输出中间结果),最终一次性获取完整结果。
image
实例化SpeechSynthesizer类,调用call方法绑定请求参数,进行合成并获取二进制音频数据。
以下示例展示了如何使用同步接口调用发音人模型知厨(sambert-zhichu-v1),将文案”今天天气怎么样”合成采样率为48kHz,音频格式为wav的音频,并保存到名为output.wav的文件中。
import com.alibaba.dashscope.audio.tts.SpeechSynthesizer;
import com.alibaba.dashscope.audio.tts.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.tts.SpeechSynthesisAudioFormat;
import com.alibaba.dashscope.utils.Constants;

import java.io.*;
import java.nio.ByteBuffer;

public class Main {
    public static void syncAudioDataToFile() {
        SpeechSynthesizer synthesizer = new SpeechSynthesizer();
        SpeechSynthesisParam param = SpeechSynthesisParam.builder()
                // 若没有将API Key配置到环境变量中,需将下面这行代码注释放开,并将apiKey替换为自己的API Key
                // .apiKey("yourApikey")
                .model("sambert-zhichu-v1")
                .text("今天天气怎么样")
                .sampleRate(48000)
                .format(SpeechSynthesisAudioFormat.WAV)
                .build();

        File file = new File("output.wav");
        // 提交同步合成任务,获取完整的音频数据
        ByteBuffer audio = synthesizer.call(param);
        try (FileOutputStream fos = new FileOutputStream(file)) {
            fos.write(audio.array());
            System.out.println("synthesis done!");
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

    public static void main(String[] args) {
        Constants.baseWebsocketApiUrl = "wss://maas.qianwenaiapi.com/api-ws/v1/inference";
        syncAudioDataToFile();
        System.exit(0);
    }
}

单向流式调用

提交单个语音合成任务,通过回调的方式流式输出中间结果,合成结果通过ResultCallback中的回调方法流式进行获取。
image
实例化SpeechSynthesizer类,调用call方法绑定请求参数和回调接口(ResultCallback)并开始语音合成,通过回调接口(ResultCallback)的onEvent方法实时获取合成结果。 语音合成完成后(回调接口(ResultCallback)的onComplete方法被回调之后),还可以调用SpeechSynthesizer类的getAudioData和getTimestamps方法,一次性获取完整的音频和时间戳结果。
以下示例展示了如何使用流式接口调用发音人模型知厨(sambert-zhichu-v1)将文案”今天天气怎么样”合成采样率为48kHz,默认音频格式(wav)的流式音频,并获取对应时间戳。
import com.alibaba.dashscope.audio.tts.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.tts.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;

import java.util.concurrent.CountDownLatch;

public class Main {
    public static void main(String[] args) {
        Constants.baseWebsocketApiUrl = "wss://maas.qianwenaiapi.com/api-ws/v1/inference";
        CountDownLatch latch = new CountDownLatch(1);
        SpeechSynthesizer synthesizer = new SpeechSynthesizer();
        SpeechSynthesisParam param = SpeechSynthesisParam.builder()
                // 若没有将API Key配置到环境变量中,需将下面这行代码注释放开,并将apiKey替换为自己的API Key
                // .apiKey("yourApikey")
                .model("sambert-zhichu-v1")
                .text("今天天气怎么样")
                .sampleRate(48000)
                .enableWordTimestamp(true)
                .enablePhonemeTimestamp(true)
                .build();

        class ReactCallback extends ResultCallback<SpeechSynthesisResult> {
            @Override
            public void onEvent(SpeechSynthesisResult result) {
                if (result.getAudioFrame() != null) {
                    // do something with the audio frame
                    System.out.println("audio result length: " + result.getAudioFrame().array().length);
                }
                if (result.getTimestamp() != null) {
                    // do something with the timestamp
                    System.out.println("timestamp: " + result.getTimestamp());
                }
            }

            @Override
            public void onComplete() {
                // do something when the synthesis is done
                System.out.println("onComplete!");
                latch.countDown();
            }

            @Override
            public void onError(Exception e) {
                // do something when an error occurs
                System.out.println("onError:" + e);
                latch.countDown();
            }
        }

        synthesizer.call(param, new ReactCallback());
        try {
            latch.await();
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        }
        System.exit(0);
    }
}

通过Flowable调用

Flowable是一个用于工作流和业务流程管理的开源框架,它基于Apache 2.0许可证发布。关于Flowable的使用,请参见Flowable API详情。
以下示例展示了通过Flowable对象的blockingForEach接口,阻塞式地获取每次流式返回的音频数据和时间戳信息(SpeechSynthesisResult)。您也可以在Flowable的所有流式数据返回完成后,通过SpeechSynthesizer类的getAudioData和getTimestamps方法分别获取完整的合成结果和完整的时间戳。
import com.alibaba.dashscope.audio.tts.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.tts.SpeechSynthesizer;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.Flowable;

public class Main {
    public static void main(String[] args) {
        Constants.baseWebsocketApiUrl = "wss://maas.qianwenaiapi.com/api-ws/v1/inference";
        SpeechSynthesizer synthesizer = new SpeechSynthesizer();
        SpeechSynthesisParam param = SpeechSynthesisParam.builder()
                // 若没有将API Key配置到环境变量中,需将下面这行代码注释放开,并将apiKey替换为自己的API Key
                // .apiKey("yourApikey")
                .model("sambert-zhichu-v1")
                .text("今天天气怎么样")
                .sampleRate(48000)
                .enableWordTimestamp(true)
                .build();

        Flowable<SpeechSynthesisResult> flowable = synthesizer.streamCall(param);
        flowable.blockingForEach(
                msg -> {
                    if (msg.getAudioFrame() != null) {
                        // do something with the audio frame
                        System.out.println("getAudioFrame");
                    }
                    if (msg.getTimestamp() != null) {
                        // do something with the timestamp
                        System.out.println("getTimestamp");
                    }
                }
        );
        System.exit(0);
    }
}

高并发调用

对象池配置、并发调用完整示例及异常处理请参见语音合成高并发最佳实践。

请求参数

通过SpeechSynthesisParam的链式方法配置模型、待合成文本等参数。配置完成的对象传入SpeechSynthesizer类的call方法中使用。
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
                .model("sambert-zhichu-v1")
                .text("今天天气怎么样")
                .sampleRate(48000)
                .enableWordTimestamp(true)
                .build();
参数类型默认值是否必须说明
modelString-是指定用于语音合成的音色模型名,完整列表请参见模型列表。
textString-是指定待合成文本,要求采用UTF-8编码且不能为空。 最高字符限制:1万字符。 > 字符计算规则:1个汉字、1个英文字母、1个标点或1个句子中间空格均算作1个字符。 支持SSML格式。SSML标记语言的使用请参见SSML标记语言介绍。
formatenumWAV否指定合成音频的编码格式,支持下列格式:
  • SpeechSynthesisAudioFormat.PCM
  • SpeechSynthesisAudioFormat.WAV
  • SpeechSynthesisAudioFormat.MP3
SpeechSynthesisAudioFormat通过“import com.alibaba.dashscope.audio.tts.SpeechSynthesisAudioFormat;”的方式引入。
sampleRateint16000否指定合成音频的采样率(单位:Hz),建议使用模型默认采样率(参见模型列表),如果不匹配,服务会进行必要的升降采样处理。
volumeint50否指定合成音频的音量,取值范围是0~100。
ratefloat1.0否指定合成音频的语速,取值范围:0.5~2。
  • 0.5:表示默认语速的0.5倍速。
  • 1:表示默认语速。默认语速是指模型默认输出的合成语速,语速会因发音人不同而略有不同。约每秒钟4个字。
  • 2:表示默认语速的2倍速。
pitchfloat1.0否指定合成音频的语调,取值范围:0.5~2。
enableWordTimestampbooleanfalse否是否开启字级别时间戳。默认不开启。
enablePhonemeTimestampbooleanfalse否是否在开启字级别时间戳(enableWordTimestamp为true)的基础上,进一步显示音素级别时间戳。默认不开启。
apiKeyString-否用户API Key。

关键接口

SpeechSynthesizer类

SpeechSynthesizer可以通过“import com.alibaba.dashscope.audio.tts.SpeechSynthesizer;”方式引入。它的关键接口如下:
接口/方法参数返回值描述
示例 1 请参见表格下方param:请求参数二进制音频发送待合成文本并获取语音合成结果。该方法阻塞当前线程直到所有结果返回。
示例 2 请参见表格下方无异步开启语音合成任务。 任务开启后,服务端会通过回调的方式调用ResultCallback实例的方法,将关键流程信息和数据返回给客户端。
示例 3 请参见表格下方无二进制音频获取完整的二进制音频数据。 单向流式调用时,完成回调后(ResultCallback的onComplete方法被调用之后)可以使用该方法一次性获取完整的音频。
示例 4 请参见表格下方无句子级别时间戳信息(Sentence)的List集合获取完整的句子级别时间戳信息(Sentence)。 单向流式调用时,完成回调后(ResultCallback的onComplete方法被调用之后)可以使用该方法一次性获取完整的时间戳。
示例 5 请参见表格下方无当前任务的request ID获取当前任务的request ID,在调用call开始新任务之后可以使用。
示例 6 请参见表格下方无当前任务首包延迟获取当前任务的首包延迟,任务结束后使用。
示例 1(接口/方法):
public ByteBuffer call(SpeechSynthesisParam param)
示例 2(接口/方法):
public void call(SpeechSynthesisParam param, ResultCallback<SpeechSynthesisResult> callback)
示例 3(接口/方法):
public ByteBuffer getAudioData()
示例 4(接口/方法):
public List<Sentence> getTimestamps()
示例 5(接口/方法):
public String getLastRequestId()
示例 6(接口/方法):
public long getFirstPackageDelay()

回调接口(ResultCallback)

单向流式调用时,通过回调接口ResultCallback获取合成结果。
ResultCallback<SpeechSynthesisResult> callback = new ResultCallback<SpeechSynthesisResult>() {
    @Override
    public void onEvent(SpeechSynthesisResult result) {
        System.out.println("RequestId为:" + result.getRequestId());
        // 在此实现处理语音合成结果的逻辑
    }

    @Override
    public void onComplete() {
        System.out.println("任务完成");
    }

    @Override
    public void onError(Exception e) {
        System.out.println("任务失败:" + e.getMessage());
    }
};
接口/方法参数返回值描述
示例 1 请参见表格下方result:音频数据和时间戳信息(SpeechSynthesisResult)无当服务端返回合成数据时会被回调。
示例 2 请参见表格下方无无当所有合成数据全部返回后被回调。
示例 3 请参见表格下方e:异常信息无当调用过程出现异常以及服务返回错误后被回调。
示例 1(接口/方法):
public void onEvent(SpeechSynthesisResult result)
示例 2(接口/方法):
public void onComplete()
示例 3(接口/方法):
public void onError(Exception e)

响应结果

非流式调用:响应结果为二进制音频数据。 单向流式调用:响应结果为音频数据和时间戳信息(SpeechSynthesisResult)。

音频数据和时间戳信息(SpeechSynthesisResult)

SpeechSynthesisResult封装了语音合成结果,常用的接口为getAudioFrame和getTimestamp。
接口/方法参数返回值描述
示例 1 请参见表格下方无二进制音频数据返回一个流式合成片段的增量二进制音频数据,可能为空。
示例 2 请参见表格下方无句子级别时间戳信息(Sentence)的List集合批量获取句子级别时间戳信息,可能为空。
示例 1(接口/方法):
public ByteBuffer getAudioFrame()
示例 2(接口/方法):
public List<Sentence> getTimestamp()

句子级别时间戳信息(Sentence)

Sentence封装了句子级别时间戳信息。
接口/方法参数返回值描述
示例 1 请参见表格下方无句子开始时间,单位为ms返回句子开始时间。
示例 2 请参见表格下方无句子结束时间,单位为ms返回句子结束时间。
示例 3 请参见表格下方无字级别时间戳信息(Word)的List集合批量获取字级别时间戳信息,可能为空。
示例 1(接口/方法):
public int getBeginTime()
示例 2(接口/方法):
public int getEndTime()
示例 3(接口/方法):
public List<Word> getWords()

字级别时间戳信息(Word)

Word封装了字级别时间戳信息。
接口/方法参数返回值描述
示例 1 请参见表格下方无词开始时间,单位为ms返回词开始时间。
示例 2 请参见表格下方无词结束时间,单位为ms返回词结束时间。
示例 3 请参见表格下方无文本信息返回文本信息。
示例 4 请参见表格下方无音素级别时间戳信息(Phoneme)的List集合批量获取音素级别时间戳信息,可能为空。
示例 1(接口/方法):
public int getBeginTime()
示例 2(接口/方法):
public int getEndTime()
示例 3(接口/方法):
public String getText()
示例 4(接口/方法):
public List<Phoneme> getPhonemes()

音素级别时间戳信息(Phoneme)

Phoneme封装了音素级别时间戳信息。
接口/方法参数返回值描述
示例 1 请参见表格下方无音素开始时间,单位为ms返回音素开始时间。
示例 2 请参见表格下方无音素结束时间,单位为ms返回音素结束时间。
示例 3 请参见表格下方无文本信息返回文本信息。
示例 4 请参见表格下方无音调返回音调。
  • 英文中,0、1、2分别代表轻音、重音和次重音。
  • 拼音中,1、2、3、4、5分别代表一声、二声、三声、四声和轻声。
示例 1(接口/方法):
public int getBeginTime()
示例 2(接口/方法):
public int getEndTime()
示例 3(接口/方法):
public String getText()
示例 4(接口/方法):
public String getTone()

错误码

在使用API过程中,如果调用失败并返回错误信息,请参见错误码进行解决。

更多示例

更多示例,请参见GitHub。

常见问题

请参见GitHub QA。

模型列表

默认采样率代表当前模型的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。如知妙音色,默认采样率16 kHz,使用时可以降采样到8 kHz,但升采样到48 kHz时不会有额外效果提升。
音色音频试听(右键保存音频)model参数时间戳支持适用场景特色语言默认采样率(Hz)
知楠sambert-zhinan-v1是通用场景广告男声中文+英文48k
知琪sambert-zhiqi-v1是通用场景温柔女声中文+英文48k
知厨sambert-zhichu-v1是新闻播报舌尖男声中文+英文48k
知德sambert-zhide-v1是新闻播报新闻男声中文+英文48k
知佳sambert-zhijia-v1是新闻播报标准女声中文+英文48k
知茹sambert-zhiru-v1是新闻播报新闻女声中文+英文48k
知倩sambert-zhiqian-v1是配音解说、新闻播报资讯女声中文+英文48k
知祥sambert-zhixiang-v1是配音解说磁性男声中文+英文48k
知薇sambert-zhiwei-v1是阅读产品简介萝莉女声中文+英文48k
知浩sambert-zhihao-v1是通用场景咨询男声中文+英文16k
知婧sambert-zhijing-v1是通用场景严厉女声中文+英文16k
知茗sambert-zhiming-v1是通用场景诙谐男声中文+英文16k
知墨sambert-zhimo-v1是通用场景情感男声中文+英文16k
知娜sambert-zhina-v1是通用场景浙普女声中文+英文16k
知树sambert-zhishu-v1是通用场景资讯男声中文+英文16k
知莎sambert-zhistella-v1是通用场景知性女声中文+英文16k
知婷sambert-zhiting-v1是通用场景电台女声中文+英文16k
知笑sambert-zhixiao-v1是通用场景资讯女声中文+英文16k
知雅sambert-zhiya-v1是通用场景严厉女声中文+英文16k
知晔sambert-zhiye-v1是通用场景青年男声中文+英文16k
知颖sambert-zhiying-v1是通用场景软萌童声中文+英文16k
知媛sambert-zhiyuan-v1是通用场景知心姐姐中文+英文16k
知悦sambert-zhiyue-v1是客服温柔女声中文+英文16k
知柜sambert-zhigui-v1是阅读产品简介直播女声中文+英文16k
知硕sambert-zhishuo-v1是数字人自然男声中文+英文16k
知妙(多情感)sambert-zhimiao-emo-v1是阅读产品简介、数字人、直播多种情感女声中文+英文16k
知猫sambert-zhimao-v1是阅读产品简介、配音解说、数字人、直播直播女声中文+英文16k
知伦sambert-zhilun-v1是配音解说悬疑解说中文+英文16k
知飞sambert-zhifei-v1是配音解说激昂解说中文+英文16k
知达sambert-zhida-v1是新闻播报标准男声中文+英文16k
Camilasambert-camila-v1否通用场景西班牙语女声西班牙语16k
Perlasambert-perla-v1否通用场景意大利语女声意大利语16k
Indahsambert-indah-v1否通用场景印尼语女声印尼语16k
Clarasambert-clara-v1否通用场景法语女声法语16k
Hannasambert-hanna-v1否通用场景德语女声德语16k
Bethsambert-beth-v1是通用场景咨询女声美式英文16k
Bettysambert-betty-v1是通用场景客服女声美式英文16k
Callysambert-cally-v1是通用场景自然女声美式英文16k
Cindysambert-cindy-v1是通用场景对话女声美式英文16k
Evasambert-eva-v1是通用场景陪伴女声美式英文16k
Donnasambert-donna-v1是通用场景教育女声美式英文16k
Briansambert-brian-v1是通用场景客服男声美式英文16k
Waansambert-waan-v1否通用场景泰语女声泰语16k