Python SDK

Prerequisites

• Obtain the AppKey and token required for authentication. For more information, see Manage projects and Obtain a token using an SDK.

• To connect using an SDK, you must first download and install it. For more information, see QuickStart.

Download and install

1. Download the Python SDK.

You can obtain the Python SDK from Github or download streamInputTts-github-python.

2. Install SDK dependencies.

Go to the root directory of the SDK and run the following command to install the dependencies:

python -m pip install -r requirements.txt

3. Install the SDK.

After the dependencies are installed, run the following command to install the SDK:

python -m pip install .

3. After the installation is complete, import the SDK using the following code.

# -*- coding: utf-8 -*-
import nls

Key interfaces

• startStreamInputTts: Establishes a WebSocket connection with the server and is used to set callbacks and parameters.

  You can set enable_aigc_tag, aigc_propagator, and aigc_propagate_id using the ex parameter.

  """
  Starts a long text synthesis task and synchronously receives confirmation from the server-side.
  
  Parameters:
  -----------
  text: str
      UTF-8 text. SSML is supported.
  voice: str
      The voice for text-to-speech. Default value: longxiaochun.
  aformat: str
      The binary format of the audio. Supported formats: 'pcm', 'wav', and 'mp3'. Default value: 'pcm'.
  sample_rate: int
      The audio sampling rate. Default value: 24000. Supported values: 8000, 11025, 16000, 22050, 24000, 32000, 44100, and 48000.
  volume: int
      The audio volume. The value ranges from 0 to 100. Default value: 50.
  speech_rate: int
      The speech rate. The value ranges from -500 to 500. Default value: 0.
  pitch_rate: int
      The pitch of the voice. The value ranges from -500 to 500. Default value: 0.
  ex: dict
      A dictionary that is merged into the 'payload' field in the request.
  """
  def startTts(
      self,
      text,
      voice="longxiaochun",
      aformat="pcm",
      sample_rate=24000,
      volume=50,
      speech_rate=0,
      pitch_rate=0,
      ex:dict=None,
  )

• waitForComplete: Blocks the current process until speech synthesis is complete, and then disconnects the WebSocket connection from the server.

  """
  Waits for the speech synthesis to complete.
  """
  def waitForComplete(self)

• Callback function descriptions

  Python callback functions are configured as parameters when an object is created. The following table describes the parameters.

  Parameter	Description
  on_data	A callback function that is invoked when synthetic data is available. This function receives two arguments: The binary audio data in the format specified by the aformat parameter of the start method. User-defined parameters The user-defined parameter is the value returned in the callback_args field described below.
  on_sentence_begin	A callback function that is invoked when a SentenceBegin event is received. This function receives two arguments: A string in JSON format. User-defined parameter The user-defined parameter is the content returned in the `callback_args` field.
  on_sentence_synthesis	A reserved interface for timestamps. CosyVoice does not support timestamps. You do not need to process this.
  on_sentence_end	A reserved interface for timestamps. CosyVoice does not support timestamps. You do not need to process this.
  on_complete	A reserved interface for timestamps. CosyVoice does not support timestamps. You do not need to process this.
  on_error	When an error occurs in the SDK or the cloud, the following two parameters are passed to the callback: A string in JSON format. User-defined parameter The user-defined parameter is the value of the callback_args field described below.
  on_close	A callback function that is invoked when the connection to the server is closed. This function receives the user-defined arguments that are provided in the callback_args parameter.

Example

The following Python code example shows how to request speech synthesis with SSML text, play the synthesized audio, and save the audio file.

# coding=utf-8
#
# Installation instructions for pyaudio:
# APPLE Mac OS X
#   brew install portaudio
#   pip install pyaudio
# Debian/Ubuntu
#   sudo apt-get install python-pyaudio python3-pyaudio
#   or
#   pip install pyaudio
# CentOS
#   sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# Microsoft Windows
#   python -m pip install pyaudio

import nls
import time

# Enable log output.
nls.enableTrace(False)

# Save the audio to a file.
SAVE_TO_FILE = True
# Play the audio in real time using a player. A sound card is required. If you run the code on a server, disable this feature.
PLAY_REALTIME_RESULT = True
if PLAY_REALTIME_RESULT:
    import pyaudio

if __name__ == "__main__":
    if SAVE_TO_FILE:
        file = open("output.wav", "wb")
    if PLAY_REALTIME_RESULT:
        player = pyaudio.PyAudio()
        stream = player.open(
            format=pyaudio.paInt16, channels=1, rate=24000, output=True
        )

    # Create an SDK instance.
    # Configure callback functions.
    def test_on_data(data, *args):
        if SAVE_TO_FILE:
            file.write(data)
        if PLAY_REALTIME_RESULT:
            stream.write(data)

    def test_on_message(message, *args):
        print("on message=>{}".format(message))

    def test_on_close(*args):
        print("on_close: args=>{}".format(args))

    def test_on_error(message, *args):
        print("on_error message=>{} args=>{}".format(message, args))

    sdk = nls.NlsStreamInputTtsSynthesizer(
        # The large model voices are available only in the China (Beijing) region. You must change the URL to the endpoint of the China (Beijing) region.
        url="wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1",
        token="your-token",
        appkey="your-appkey",
        on_data=test_on_data,
        on_sentence_begin=test_on_message,
        on_sentence_synthesis=test_on_message,
        on_sentence_end=test_on_message,
        on_completed=test_on_message,
        on_error=test_on_error,
        on_close=test_on_close,
        callback_args=[],
    )

    # Send a text message.
    sdk.startTts(
        text='''<speak bgm="http://nls.alicdn.com/bgm/2.wav">How is the weather today</speak>''',
        voice="longxiaochun_v2",       # The voice for speech synthesis.
        aformat="wav",              # The format of the synthesized audio.
        sample_rate=24000,          # The sampling rate of the synthesized audio.
        volume=50,                  # The volume of the synthesized audio.
        speech_rate=0,              # The speech rate of the synthesized audio.
        pitch_rate=0,               # The pitch of the synthesized audio.
    )
    sdk.waitForComplete()
    print('finished, task_id: {}'.format(sdk.get_last_task_id()))
    if SAVE_TO_FILE:
        file.close()
    if PLAY_REALTIME_RESULT:
        stream.stop_stream()
        stream.close()
        player.terminate()

Common SDK error codes

For more information about error codes, see Error code reference.