The speech synthesis service generates a timestamp for each word in a sentence, indicating when that word is spoken in the audio stream. This feature is also called phoneme boundary detection for each word.
Use timestamps to drive time-synchronized UI behaviors, such as:
Video subtitles: display and dismiss subtitle text in sync with audio playback.
Virtual speakers: trigger lip-sync animations or word-highlighting effects as each word is spoken.
Notice: This feature is only available for speakers that support phoneme boundary detection for each word.
Enable the timestamp feature
Set the enable_subtitle request parameter to true when you initiate a synthesis request from the client.
The following example uses the Java SDK:
// Enable timestamps. Disabled by default.
synthesizer.addCustomedParam("enable_subtitle", true);Server response
When enable_subtitle is true, the server returns a MetaInfo event that contains a subtitles array in the payload.
`subtitles` parameters
| Parameter | Type | Description | Use case |
|---|---|---|---|
text | String | The word as read aloud (pronunciation-based, not the original text character). | Do not use this field for on-screen display. Render subtitles from the original input text instead (see Usage notes). |
begin_time | Integer | The start timestamp of the word in the synthesized audio, in milliseconds. | Use to trigger subtitle display or start a word-highlight effect. |
end_time | Integer | The end timestamp of the word in the synthesized audio, in milliseconds. | Use to dismiss the subtitle or end the highlight effect. |
Usage notes
Use the original text for on-screen display. The
textfield reflects how the original text is read aloud (pronunciation-based), not the source characters. Render subtitles from the original input text, and usebegin_timeandend_timeonly to control display timing.Derive sentence-level timestamps from word-level data. If you use this feature to generate video subtitles, you can obtain the start and end timestamps of each sentence based on the returned response.
Sample output
{
"header": {
"message_id": "05450bf69c53413f8d88aed1ee60****",
"task_id": "640bc797bb684bd6960185651307****",
"namespace": "SpeechSynthesizer",
"name": "MetaInfo",
"status": 20000000,
"status_message": "GATEWAY|SUCCESS|Success."
},
"payload": {
"subtitles": [
{
"text": "xx",
"begin_time": 130,
"end_time": 260
},
{
"text": "xx",
"begin_time": 260,
"end_time": 370
}
]
}
}