跳转到主要内容
Sambert

语音合成 Sambert Java SDK

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

前提条件

快速开始

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

非流式调用

提交单个语音合成任务,无需调用回调方法,进行语音合成(无流式输出中间结果),最终一次性获取完整结果。 实例化 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 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) {
    syncAudioDataToFile();
    System.exit(0);
  }
}

单向流式调用

提交单个语音合成任务,通过回调的方式流式输出中间结果,合成结果通过 ResultCallback 中的回调方法流式进行获取。 实例化 SpeechSynthesizer 类,调用 call 方法绑定请求参数和回调接口(ResultCallback)并开始语音合成,通过 ResultCallbackonEvent 方法实时获取合成结果。 语音合成完成后(ResultCallbackonComplete 方法被回调之后),还可以调用 SpeechSynthesizer 类的 getAudioDatagetTimestamps 方法,一次性获取完整的音频和时间戳结果。 以下示例展示了如何使用流式接口调用发音人模型知厨(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 java.util.concurrent.CountDownLatch;

public class Main {
  public static void main(String[] args) {
    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 是 RxJava 2 中的响应式流类,用于处理背压(backpressure)场景下的异步数据流。关于 RxJava 的使用,请参见 RxJava 2 API 文档 以下示例展示了通过 Flowable 对象的 blockingForEach 接口,阻塞式地获取每次流式返回的音频数据和时间戳信息(SpeechSynthesisResult)。 您也可以在 Flowable 的所有流式数据返回完成后,通过 SpeechSynthesizer 类的 getAudioDatagetTimestamps 方法分别获取完整的合成结果和完整的时间戳。
import com.alibaba.dashscope.audio.tts.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.tts.SpeechSynthesizer;
import io.reactivex.Flowable;

public class Main {
  public static void main(String[] args) {
    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.PCMSpeechSynthesisAudioFormat.WAVSpeechSynthesisAudioFormat.MP3。通过 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是否在开启字级别时间戳(enableWordTimestamptrue)的基础上,进一步显示音素级别时间戳。默认不开启。
apiKeyString-用户 API Key。

关键接口

SpeechSynthesizer

SpeechSynthesizer 可以通过 import com.alibaba.dashscope.audio.tts.SpeechSynthesizer; 方式引入。
接口/方法参数返回值描述
public ByteBuffer call(SpeechSynthesisParam param)param:请求参数二进制音频发送待合成文本并获取语音合成结果。该方法阻塞当前线程直到所有结果返回。
public void call(SpeechSynthesisParam param, ResultCallback<SpeechSynthesisResult> callback)param:请求参数;callback:回调接口(ResultCallback)异步开启语音合成任务。任务开启后,服务端会通过回调的方式调用 ResultCallback 实例的方法,将关键流程信息和数据返回给客户端。
public ByteBuffer getAudioData()二进制音频获取完整的二进制音频数据。单向流式调用时,完成回调后(ResultCallbackonComplete 方法被调用之后)可以使用该方法一次性获取完整的音频。
public List<Sentence> getTimestamps()SentenceList 集合获取完整的句子级别时间戳信息(Sentence)。单向流式调用时,完成回调后(ResultCallbackonComplete 方法被调用之后)可以使用该方法一次性获取完整的时间戳。
public String getLastRequestId()当前任务的 request ID获取当前任务的 request ID,在调用 call 开始新任务之后可以使用。
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());
  }
};
接口/方法参数返回值描述
public void onEvent(SpeechSynthesisResult result)result:音频数据和时间戳信息(SpeechSynthesisResult)当服务端返回合成数据时会被回调。
public void onComplete()当所有合成数据全部返回后被回调。
public void onError(Exception e)e:异常信息当调用过程出现异常以及服务返回错误后被回调。

响应结果

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

SpeechSynthesisResult 对象通过回调接口 ResultCallbackonEvent 方法返回,包含增量音频数据和时间戳信息。
接口/方法参数返回值描述
public ByteBuffer getAudioFrame()音频数据获取增量音频片段(流式调用中的分段数据)。
public List<Sentence> getTimestamp()SentenceList 集合获取句子时间戳列表(流式调用中的增量返回)。

句子级别时间戳信息(Sentence

Sentence 对象通过 SpeechSynthesisResult.getTimestamp()SpeechSynthesizer.getTimestamps() 获取。
接口/方法参数返回值描述
public int getBeginTime()毫秒(ms)获取句子开始时间。
public int getEndTime()毫秒(ms)获取句子结束时间。
public List<Word> getWords()WordList 集合获取字级别时间戳列表。

字级别时间戳信息(Word

Word 对象通过 Sentence.getWords() 获取。
接口/方法参数返回值描述
public int getBeginTime()毫秒(ms)获取字开始时间。
public int getEndTime()毫秒(ms)获取字结束时间。
public String getText()字文本获取字文本内容。
public List<Phoneme> getPhonemes()PhonemeList 集合获取音素级别时间戳列表。

音素级别时间戳信息(Phoneme

Phoneme 对象通过 Word.getPhonemes() 获取。
接口/方法参数返回值描述
public int getBeginTime()毫秒(ms)获取音素开始时间。
public int getEndTime()毫秒(ms)获取音素结束时间。
public String getText()音素文本获取音素文本内容(拼音或英文音标)。
public String getTone()声调获取声调信息。英文:0/1/2 分别表示轻音/重音/次重音;拼音:1~5 分别表示一二三四声/轻声。

错误码

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

更多示例

更多示例,请参见 GitHub

常见问题

请参见 GitHub QA

模型列表

默认采样率代表当前模型的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。如知妙音色,默认采样率 16 kHz,使用时可以降采样到 8 kHz,但升采样到 48 kHz 时不会有额外效果提升。
音色model 参数时间戳适用场景特色语言默认采样率
知楠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
语音合成 Sambert Java SDK - 千问 AI 平台