Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.




  • Enable TTS in the Godot editor for your project

  • 向系统查询可用语音列表

  • 存储你想要使用的语音 ID

By default, the Godot project-level setting for text-to-speech is disabled, to avoid unnecessary overhead. To enable it:

  • Go to Project > Project Settings

  • Make sure the Advanced Settings toggle is enabled

  • Click on Audio > General

  • Ensure the Text to Speech option is checked

  • Restart Godot if prompted to do so.

Text-to-speech uses a specific voice. Depending on the user's system, they might have multiple voices installed. Once you have the voice ID, you can use it to speak some text:

# One-time steps.
# Pick a voice. Here, we arbitrarily pick the first English voice.
var voices = DisplayServer.tts_get_voices_for_language("en")
var voice_id = voices[0]

# Say "Hello, world!".
DisplayServer.tts_speak("Hello, world!", voice_id)

# Say a longer sentence, and then interrupt it.
# Note that this method is asynchronous: execution proceeds to the next line immediately,
# before the voice finishes speaking.
var long_message = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur"
DisplayServer.tts_speak(long_message, voice_id)

# Immediately stop the current text mid-sentence and say goodbye instead.
DisplayServer.tts_speak("Goodbye!", voice_id)


Godot 包含了文本转语音功能,可以在 DisplayServer 类中找到。

Godot 的文本转语音功能依赖于系统库。Windows 和 macOS 上默认安装了这些库,但并不是所有 Linux 发行版都有安装。如果这些库不存在,那么文本转语音功能就无法正常工作,此时 tts_get_voices() 返回的列表为空,表示没有可用的语音。

Both Godot users on Linux and end-users on Linux running Godot games need to ensure that their system includes the system libraries for text-to-speech to work. Please consult the table below or your own distribution's documentation to determine what libraries you need to install.


Arch Linux

pacman -S speech-dispatcher festival espeakup


If you get the error Invalid get index '0' (on base: 'PackedStringArray'). for the line var voice_id = voices[0], check if there are any items in voices. If not:

  • All users: make sure you enabled Text to Speech in project settings

  • Linux users: ensure you installed the system-specific libraries for text to speech


就盲人玩家的理想游玩体验而言,文本转语音的最佳实践是将输出发送到玩家的屏幕阅读器。这样可以保留用户设定的语言、语速、音调等选择,还可以实现一些高级功能,例如允许玩家在文本中快进和快退。目前,Godot 还没有提供这种级别的集成。

考虑到 Godot 文本转语音 API 目前的状态,最佳实践包括:

  • 开发游戏时启用文本转语音,确保读音正确

  • 允许玩家控制使用哪种语音,对选择进行存储/持久化,能够在后续游玩时使用

  • 允许玩家控制发言的速率,对选择进行存储/持久化,能够在后续游玩时使用



  • 调用 tts_speaktts_stop 时会有延迟。实际延迟的时间会根据操作系统和机器的配置而有所不同。在 Android 和 Web 平台尤为明显,因为部分语音基于 Web 服务,播放的实际时间取决于服务器负载、网络延迟等因素。

  • 非英语文本需要安装并使用正确语音后才能正常工作。在 Windows 上,可以按照这篇文章的内容来启用额外语言的语音。

  • 元音变音等非 ASCII 字符的正确发音需要选择正确的语音。

  • 盲人玩家使用的屏幕阅读器有很多种,包括 JAWS、NVDA、VoiceOver、Narrator 等。

  • Windows 文本转语音 API 的性能通常比其他系统中对应的 API 要好(例如 tts_stop 后跟 tts_speak 能够立即朗读新消息)。