TextToSpeech QML Type

TextToSpeech 类型可访问文本转语音引擎。更多...

Import Statement: import QtTextToSpeech

所有成员列表（包括继承的成员）

属性

engine : string
engineCapabilities : enumeration (since 6.6)
engineParameters : map
locale : locale
pitch : double
rate : double
state : enumeration
voice : voice
volume : double

信号

aboutToSynthesize(number id) (since 6.6)
void errorOccurred(enumeration reason, string errorString)
sayingWord(string word, int id, int start, int length) (since 6.6)

方法

list<string> availableEngines()
list<voice> availableLocales()
list<voice> availableVoices()
int enqueue(string utterance) (since 6.6)
enumeration errorReason()
string errorString()
list<voice> findVoices(map criteria) (since 6.6)
void pause(BoundaryHint boundaryHint)
void resume()
void say(string text)
void stop(BoundaryHint boundaryHint)

详细说明

使用 `say()` 开始向默认音频设备朗读文本，并使用 `stop()`、`pause()` 和 `resume()` 来控制文本的朗读。

    TextToSpeech {
        id: tts
        volume: volumeSlider.value
        pitch: pitchSlider.value
        rate: rateSlider.value
    ...

        RowLayout {
            Button {
                text: qsTr("Speak")
                enabled: [TextToSpeech.Paused, TextToSpeech.Ready].includes(tts.state)
                onClicked: {
                    let voices = tts.availableVoices()
                    tts.voice = voices[voicesComboBox.currentIndex]
                    tts.say(input.text)
                }
            }
            Button {
                text: qsTr("Pause")
                enabled: tts.state == TextToSpeech.Speaking
                onClicked: tts.pause()
                visible: tts.engineCapabilities & TextToSpeech.Capabilities.PauseResume
            }
            Button {
                text: qsTr("Resume")
                enabled: tts.state == TextToSpeech.Paused
                onClicked: tts.resume()
                visible: tts.engineCapabilities & TextToSpeech.Capabilities.PauseResume
            }
    ...

若要将文本合成到 PCM 数据中以便进行后续处理，请使用 synthesize()。

要设置语音，请按如下方式使用VoiceSelector 附加属性：

TextToSpeech {
    VoiceSelector.locale: Qt.locale("en_UK")
    VoiceSelector.gender: Voice.Male
}

系统将使用第一个满足所有指定条件的语音。如果没有语音满足所有条件，则语音不会改变。

或者，可使用findVoices() 获取匹配的语音列表，或使用availableVoices() 获取支持当前区域设置的语音列表。通过调用availableLocales()，将locale 属性设置为与输入文本语言及所需语音输出的口音高度匹配的选项。在大多数平台上，这将更改可用语音列表。随后，在voice 属性中选用其中一种可用语音。

并非所有引擎都支持全部功能。请使用 engineCapabilities() 函数测试哪些功能可用，并据此调整该类型的使用方式。

注意： 引擎支持哪些区域设置和语音通常取决于操作系统的配置。例如，在 macOS 上，最终用户可以通过“系统偏好设置”中的“辅助功能”面板安装语音。

属性文档

engine : string

用于文本转语音合成的引擎。

更改引擎会停止当前的语音播放。

在大多数平台上，更换引擎会更新available locales 和available voices 中的列表。

engineCapabilities : enumeration `[since 6.6]`

该属性保存了当前引擎所实现的功能。

该属性自 Qt 6.6 起引入。

另请参阅 engine 和QTextToSpeech::Capability 。

engineParameters : map

该属性存储特定于引擎的参数。

另请参阅 engine 。

locale : locale

该属性存储当前正在使用的区域设置。

默认情况下，使用系统区域设置。

另请参阅 voice 。

pitch : double

该属性用于控制语音音高，取值范围为 -1.0 到 1.0。

默认值为 0.0，表示正常语音音高。

rate : double

该属性存储当前的语速，取值范围为 -1.0 到 1.0。

默认值为 0.0，表示正常的语速。

state : enumeration

该属性保存语音合成器的当前状态。

        onStateChanged: updateStateLabel(state)

        function updateStateLabel(state)
        {
            switch (state) {
                case TextToSpeech.Ready:
                    statusLabel.text = qsTr("Ready")
                    break
                case TextToSpeech.Speaking:
                    statusLabel.text = qsTr("Speaking")
                    break
                case TextToSpeech.Paused:
                    statusLabel.text = qsTr("Paused...")
                    break
                case TextToSpeech.Error:
                    statusLabel.text = qsTr("Error!")
                    break
            }
        }

另请参阅 QTextToSpeech::State 、say()、stop() 以及pause()。

voice : voice

该属性用于指定语音合成所使用的声音。

该语音必须是引擎支持的voices available 之一。

在某些平台上，设置语音会更改其他语音属性，例如locale 、pitch 等。这些更改会触发信号的发出。

volume : double

该属性存储当前音量值，取值范围为 0.0 到 1.0。

默认值为平台的默认音量。

Signal 文档

`[since 6.6]` aboutToSynthesize(number id)

该信号在引擎开始为id 合成语音音频之前发出。应用程序可以利用此信号对voice 的属性进行最后时刻的修改，或跟踪通过enqueue() 入队文本的处理过程。

注意： 对应的处理程序 是onAboutToSynthesize 。

该信号在 Qt 6.6 中引入。

另请参阅 enqueue() 和voice 。

void errorOccurred(enumeration reason, string errorString)

当发生错误且state 已被设置为TextToSpeech.Error 时，会发出此信号。reason 参数指定错误类型，而errorString 则提供可供人类阅读的错误描述。

注意： 对应的处理程序 为onErrorOccurred 。

另请参阅 state 、errorReason() 和errorString()。

`[since 6.6]` sayingWord(string word, int id, int start, int length)

当word （即语句id 中由start 和length 所指代的文本片段）被播放到音频设备时，会触发此信号。

注意：此 信号要求引擎具备WordByWordProgress 功能。

以下代码会突出显示在TextArea input 中被读出的单词：

        onSayingWord: (word, id, start, length)=> {
            input.select(start, start + length)
        }

注意： 相应的处理程序 是onSayingWord 。

该信号在 Qt 6.6 中引入。

另请参阅 QTextToSpeech::Capability 和say()。

方法文档

list<string> availableEngines()

包含支持的文本转语音引擎插件列表。

list<voice> availableLocales()

包含当前engine 所支持的区域设置列表。

list<voice> availableVoices()

存储了当前locale 可用的语音列表。

`[since 6.6]` int enqueue(string utterance)

将utterance 添加到待朗读文本的队列中，并开始朗读。

如果引擎的state 当前为Ready ，则会立即朗读utterance 。否则，引擎将在完成当前文本的朗读后，开始朗读utterance 。

每次引擎处理队列中的下一个文本条目时，都会触发aboutToSynthesize() 信号。这使得应用程序能够跟踪进度，并对语音属性进行最后一刻的调整。

调用stop() 将清空队列。

该方法在 Qt 6.6 中引入。

另请参阅 say()、stop() 和aboutToSynthesize()。

enumeration errorReason()

返回引擎报告错误的原因。

另请参阅 QTextToSpeech::ErrorReason 。

string errorString()

返回当前引擎的错误消息。

`[since 6.6]` list<voice> findVoices(map criteria)

返回符合所有指定criteria 的语音列表。

criteria 是一个从语音属性名称到属性值的映射，支持以下搜索条件的组合：

let daniel = tts.findVoices({
    "name": "Daniel"
})
let maleEnglish = tts.findVoices({
    "gender": Voice.Male,
    "language": Qt.locale('en')
})

该方法在 Qt 6.6 中引入。

另请参阅 VoiceSelector 。

void pause(BoundaryHint boundaryHint)

暂停当前在boundaryHint 处的语音播放。

boundaryHint 是否被遵守，取决于engine 。

另请参阅 resume()、QTextToSpeech::BoundaryHint 以及PauseResume 。

void resume()

在调用pause() 之后恢复发言。

另请参阅 pause()。

void say(string text)

开始合成text 。

此函数将异步开始语音合成，并将文本读入默认音频输出设备。

        RowLayout {
            Button {
                text: qsTr("Speak")
                enabled: [TextToSpeech.Paused, TextToSpeech.Ready].includes(tts.state)
                onClicked: {
                    let voices = tts.availableVoices()
                    tts.voice = voices[voicesComboBox.currentIndex]
                    tts.say(input.text)
                }
            }

注意： 在开始朗读新合成的文本之前，所有正在进行的朗读都会被停止。

可通过state 属性获取当前状态，一旦开始朗读，该属性将设置为QTextToSpeech::Speaking 。朗读完成后，state 将被设置为QTextToSpeech::Ready 。

另请参阅 stop()、pause() 和resume()。

void stop(BoundaryHint boundaryHint)

在boundaryHint 处停止当前读取，并清空待处理文本队列。

无法恢复读取操作。是否遵守boundaryHint 取决于引擎。

另请参阅 say()、enqueue()、pause() 以及QTextToSpeech::BoundaryHint 。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.

TextToSpeech QML Type

属性

信号

方法

详细说明

属性文档

engine : string

engineCapabilities : enumeration [since 6.6]

engineParameters : map

locale : locale

pitch : double

rate : double

state : enumeration

voice : voice

volume : double

Signal 文档

[since 6.6] aboutToSynthesize(number id)

void errorOccurred(enumeration reason, string errorString)

[since 6.6] sayingWord(string word, int id, int start, int length)

方法文档

list<string> availableEngines()

list<voice> availableLocales()

list<voice> availableVoices()

[since 6.6] int enqueue(string utterance)

enumeration errorReason()

string errorString()

[since 6.6] list<voice> findVoices(map criteria)

void pause(BoundaryHint boundaryHint)

void resume()

void say(string text)

void stop(BoundaryHint boundaryHint)

engineCapabilities : enumeration `[since 6.6]`

`[since 6.6]` aboutToSynthesize(number id)

`[since 6.6]` sayingWord(string word, int id, int start, int length)

`[since 6.6]` int enqueue(string utterance)

`[since 6.6]` list<voice> findVoices(map criteria)