Java SDK

Synthesize speech

The sample obtains a token, initializes a client, and synthesizes 16 kHz WAV audio with the siyue voice. It saves the audio to a temporary file, measures first-packet latency, and checks for synthesis failures, timeouts, and file write errors.

import com.alibaba.nls.client.AccessToken;
import com.alibaba.nls.client.protocol.NlsClient;
import com.alibaba.nls.client.protocol.OutputFormatEnum;
import com.alibaba.nls.client.protocol.SampleRateEnum;
import com.alibaba.nls.client.protocol.tts.SpeechSynthesizer;
import com.alibaba.nls.client.protocol.tts.SpeechSynthesizerListener;
import com.alibaba.nls.client.protocol.tts.SpeechSynthesizerResponse;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.ByteBuffer;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.TimeoutException;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicReference;

public class SpeechSynthesizerDemo {
    private static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.trim().isEmpty()) {
            throw new IllegalArgumentException("Missing environment variable: " + name);
        }
        return value;
    }

    public static void main(String[] args) throws Exception {
        String appKey = requireEnv("NLS_APP_KEY");
        String accessKeyId = requireEnv("ALIYUN_AK_ID");
        String accessKeySecret = requireEnv("ALIYUN_AK_SECRET");
        AccessToken accessToken = new AccessToken(accessKeyId, accessKeySecret);
        accessToken.apply();
        if (accessToken.getToken() == null || accessToken.getToken().isEmpty()) {
            throw new IllegalStateException("Failed to obtain an NLS token");
        }

        NlsClient client = new NlsClient("wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1", accessToken.getToken());
        try {
            Path output = Files.createTempFile("tts-", ".wav");
            try (OutputStream audio = Files.newOutputStream(output)) {
                AtomicBoolean completed = new AtomicBoolean(false);
                AtomicBoolean firstPacket = new AtomicBoolean(true);
                AtomicReference<Exception> failure = new AtomicReference<>();
                final long[] startedAt = new long[1];
                SpeechSynthesizerListener listener = new SpeechSynthesizerListener() {
                    @Override
                    public void onMessage(ByteBuffer message) {
                        if (firstPacket.compareAndSet(true, false)) {
                            long elapsedMs = (System.nanoTime() - startedAt[0]) / 1_000_000;
                            System.out.println("First packet latency (ms): " + elapsedMs);
                        }
                        byte[] bytes = new byte[message.remaining()];
                        message.get(bytes);
                        try {
                            audio.write(bytes);
                        } catch (IOException e) {
                            failure.compareAndSet(null, e);
                        }
                    }

                    @Override
                    public void onComplete(SpeechSynthesizerResponse response) {
                        if (response.getStatus() == 20000000) {
                            completed.set(true);
                            System.out.println("Synthesis completed, task_id: " + response.getTaskId());
                        } else {
                            onFail(response);
                        }
                    }

                    @Override
                    public void onFail(SpeechSynthesizerResponse response) {
                        failure.compareAndSet(null, new IOException(
                            "task_id=" + response.getTaskId() + ", status=" + response.getStatus()
                            + ", status_text=" + response.getStatusText()));
                    }

                    @Override
                    public void onMetaInfo(SpeechSynthesizerResponse response) {
                        System.out.println("Subtitles: " + response.getObject("subtitles"));
                    }
                };

                SpeechSynthesizer synthesizer = new SpeechSynthesizer(client, listener);
                try {
                    synthesizer.setAppKey(appKey);
                    synthesizer.setVoice("siyue");
                    synthesizer.setFormat(OutputFormatEnum.WAV);
                    synthesizer.setSampleRate(SampleRateEnum.SAMPLE_RATE_16K);
                    synthesizer.setVolume(50);
                    synthesizer.setSpeechRate(0);
                    synthesizer.setPitchRate(0);
                    synthesizer.setText("Hello world. Welcome to the speech synthesis service.");
                    synthesizer.addCustomedParam("enable_subtitle", false);

                    startedAt[0] = System.nanoTime();
                    synthesizer.start();
                    synthesizer.waitForComplete(30_000L);
                    if (failure.get() != null) {
                        throw failure.get();
                    }
                    if (!completed.get()) {
                        throw new TimeoutException("Synthesis did not complete within 30 seconds");
                    }
                } finally {
                    synthesizer.close();
                }
            }
            System.out.println("Audio file: " + output.toAbsolutePath());
        } finally {
            client.shutdown();
        }
    }
}

On success, the program prints Synthesis completed and the audio file path. Open the generated WAV file to check its content. If an exception occurs, the temporary file may be incomplete and must not be used as a successful synthesis result.

The sample waits up to 30 seconds. This is an application setting, not a service latency guarantee. For low-latency playback, play audio as it arrives in onMessage. Streaming playback does not change the input text length limit.

For an application on an ECS instance in the Shanghai region that requires internal access, select an applicable internal endpoint from the speech synthesis service endpoints. Do not use a public endpoint as an internal endpoint.

Key interfaces

Obtain a token, create a client and synthesis object, set the parameters, start the task, process callbacks, and release resources.

FAQ

<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20170516</version>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.2</version>
</dependency>