目录

Text to Speech (1077+)

This document describes only the definition of APIs. For details about how and when to call these APIs, please refer to Text to Speech.

API Declaration

Add the following configuration to the features attribute in the manifest.json file:

{"name": "service.ml.tts"}

Module Import

Add the following configuration to the script element on the page where the API will be called:

import mltts from '@service.ml.tts'

Or

var mltts = require("@service.ml.tts ")

Application Scope

Item

Description

Applicable devices

Mobile phones and tablets

Applicable regions

Global

Definition

API

Description

mltts.speak(OBJECT)

Starts text to speech (TTS).

mltts.stop()

Stops TTS.

mltts.pausePlay()

Pauses playback.

mltts.resumePlay()

Resumes playback.

[h2]mltts.speak(OBJECT) (1077+)

Description

Starts speech recognition and obtains the recognition result from the callback.

Parameters

Parameter

Type

Mandatory

Description

appId

string

Yes

ID of a created quick app. For details, please refer to Obtaining an App ID.

apiKey

string

Yes

API key of a created quick app. For details, please refer to Obtaining the API Key (Credential).

You need to set and keep your API key properly. For details, please refer to Notes on Using Cloud Authentication Information.

language

string

No

Text language. For details, please refer to Supported Speaker List.

speaker

string

No

Speaker. For details, please refer to Supported Speaker List.

speed

number

No

Playback speed. The value range is [0,5].

The value 1.0 indicates the normal speed. A higher value means to speed up a video, and a lower value means to slow down a video. For example, 0.5 indicates half of the normal speed, and 1.5 indicates 1.5 times faster than the normal speed.

If this parameter is not set, the default value will be used.

volume

number

No

Sound volume. The value range is [0,2].

The value 1.0 indicates the normal volume. A higher value means to increase the volume, and a lower value means to decrease the volume. For example, 0.5 indicates half of the normal volume, and 1.5 indicates 1.5 times higher than the normal volume.

If this parameter is not set, the default value will be used.

queueMode

number

No

Task queuing mode. The default value is 0.

  • 0: serial execution mode. If playback is going on, a new TTS task is added to the queue for execution in sequence; if playback pauses, the new task is added to the queue for execution in sequence when playback resumes; if there is no playback, the new task is executed immediately.
  • 1: clearing mode. The ongoing TTS task and playback are stopped immediately, all TTS tasks in the queue are cleared, and the current TTS task is executed immediately for playback.

sourceText

string

Yes

Text information to be processed. The value can contain up to 500 characters.

callback(eventName,taskId,…data)

function

Yes

Callback method, which is called back for multiple times. Two or more parameters will be returned. The first parameter specifies the event name. For details, please refer to eventName parameters, the second parameter indicates the TTS task ID, and other parameters can be set based on the service requirements.

fail(errMsg, errCode)

function

Optional

Callback method, which is called after an error occurs.

eventName parameters

Event

Trigger Condition

onWarn

The alarm is handled without affecting service logic.

  • data[0] mlTtsWarn: alarm data
  • mlTtsWarn.warnId: alarm ID
  • mlTtsWarn.warnMsg: alarm description

onRangeStart

The mapping between the currently played segment and text is processed.

  • data[0] start: start position of an audio segment in the input text
  • data[1] end: end position of the audio segment in the input text (excluded)

onPlayStart

Called back when playback starts. (This event needs to be tracked when an internal player is used.)

onPlayResume

Called back when playback resumes. (This event needs to be tracked when an internal player is used.)

onPlayPause

Called back when playback pauses. (This event needs to be tracked when an internal player is used.)

onPlayStop

Called back when playback stops. (This event needs to be tracked when an internal player is used.)

onSynthesisStart

Called back when TTS starts. (This event needs to be tracked when playback is not performed using an internal player and you only need to focus on TTS data.)

onSynthesisEnd

Called back when TTS ends. (This event needs to be tracked when playback is not performed using an internal player and you only need to focus on TTS data.)

Returns

Parameter

Type

Description

eventName

String

Name of a callback event.

taskId

String

ID of a TTS task.

...data

0 or a set of parameters

The value can be 0 or a set of parameters, depending on the value of eventName.

Result codes returned by fail

Result Code

Description

Suggestion

11305

Audio playback error.

-

11306

Authentication failure.

Use valid authentication parameters.

11301

Invalid parameter.

Use valid parameters.

11303

Insufficient balance.

Check your account.

11398

Internal error.

-

11302

Network connection exception.

Check the network connection status.

11304

TTS failed.

-

11399

Unknown error.

-

Returns

For multiple callbacks, the return value depends on the value of the first parameter eventName.

Sample code

mltts.speak({ // Start TTS.
    appId: "App ID that you have applied for.", // String, mandatory.
    apiKey: "API key that you have applied for.", // String, mandatory. This is parameter is set for authentication.
    language: "", // String, optional. This parameter specifies the language. The options are zh-Hans, en-US, fr-FR, and es-ES. The default value is zh-Hans.
    speaker: "", // String, optional. This parameter specifies the voice. The options are Female-zh, Female-en, Male-zh, Male-en, fr-FR-st-1, and es-ES-st-1. The default value is Female-zh.
    speed: 1, // Number, optional. This parameter specifies the playback speed. The default value is 1. 
    volume: 1, // Number, optional. This parameter specifies the playback speed. The default value is 1.
    queueMode: 0, // Number, optional. This parameter specifies the queuing mode. The options are 0 (serial execution) and 1 (clearing). The default value is 0.
    sourceText: "This is a test.", // String. This parameter specifies text information to be converted. The value can contain up to 500 characters.
    callback: (eventName, taskId, ...data) => { // Callback method. One or more parameters are returned. The first parameter is the event name (eventName). Other parameters depend on the service.
    console.log(eventName, taskId, ...data);
    switch (eventName) {
        case 'onWarn': // Alarm handling without affecting service logic.
        let mlTtsWarn = data[0]; // JSON format. mlTtsWarn.warnId: alarm ID; mlTtsWarn.warnMsg: alarm message.
        break;
        case 'onRangeStart': // Process the mapping between the currently played segment and text.
        let start = data[0]; // Start position of an audio segment in the input text.
        let end = data[1]; // End position of the audio segment in the input text (excluded).
        break;
        case ' onPlayStart': // Called back when playback starts.

        break;
        case ' onPlayResume': // Called back when playback resumes.

        break;

        case 'onPlayPause': // Called back when playback pauses.

        break;
        case 'onPlayStop': // Called back when playback stops.

        break;
        case 'onSynthesisStart': // Called back when TTS starts.

        break;
        case 'onSynthesisEnd': // Called back when TTS ends.

        break;

        }
    },
    fail: (errMsg, errCode) => {  // Callback upon failure.
        console.log("error:", errMsg);
    },
});

[h2]mltts.stop() (1077+)

Description

Stops TTS.

Sample code

mltts.stop(); // Stop TTS.

[h2]mltts.pausePlay() (1077+)

Description

Pauses playback.

Sample code

mltts.pausePlay(); // Pause playback.

[h2]mltts.resumePlay() (1077+)

Description

Resumes playback.

Sample code

mltts.resumePlay(); // Resume playback.