.. _py_tts:

16. TTS（文本转语音）
==============================================

本示例演示如何使用 TTS（文本转语音）模块让 PiCrawler 说话。
支持两种引擎：\ **Piper**\ （高质量神经 TTS）和\ **Espeak**\ （轻量级经典 TTS）。
输入任意文本，机器人将朗读出来。

**运行代码**

.. raw:: html

    <run></run>

.. code-block::

    cd ~/picrawler/examples
    sudo python3 16_tts.py

程序运行后，将显示引擎类型和模型。输入任意句子并按 **Enter** —— 机器人将
朗读它。输入 ``quit`` 退出，或按\ **Ctrl+C**\ 。

**代码**

.. note::
    您可以**修改/重置/复制/运行/停止**\ 以下代码。但在此之前，您需要进入源代码
    路径，如 ``picrawler\examples``。修改代码后，可以直接运行以查看效果。

.. raw:: html

    <run></run>

.. code-block:: python

    #!/usr/bin/env python3
    from robot_hat.tts import Piper, Espeak

    # 使用 robot_hat TTS 模块的文本转语音演示
    # 按 Ctrl+C 退出

    # 设置 USE_PIPER=True 使用高质量神经 TTS（Piper），False 使用 Espeak
    USE_PIPER = True

    # Piper 模型："en_US-ryan-low"（英语），"zh_CN-huayan-x_low"（中文）
    TTS_MODEL = "zh_CN-huayan-x_low"

    def main():
        print("=== PiCrawler 文本转语音演示 ===")

        if USE_PIPER:
            print(f"引擎：Piper ({TTS_MODEL})")
            tts = Piper(model=TTS_MODEL)
        else:
            print("引擎：Espeak")
            tts = Espeak()

        print("输入要朗读的文本，或输入 'quit' 退出")
        print()

        try:
            while True:
                text = input("要朗读的文本：").strip()
                if text.lower() == 'quit':
                    break
                if text:
                    print(f"正在朗读：{text}")
                    tts.say(text)
        except KeyboardInterrupt:
            print("\n正在退出...")

    if __name__ == "__main__":
        main()


**工作原理**

#. 两种可用的 TTS 引擎

   .. code-block:: python

      from robot_hat.tts import Piper, Espeak

   ``robot_hat`` 包提供两种 TTS 引擎：

   - **Piper**\ ：基于神经网络的引擎，产生自然、高质量的语音。需要语音模型文件。
   - **Espeak**\ ：轻量级、基于规则的引擎，在最小资源下运行。

#. 选择引擎和模型

   .. code-block:: python

      USE_PIPER = True
      TTS_MODEL = "zh_CN-huayan-x_low"

   将 ``USE_PIPER`` 设为 ``True`` 使用 Piper，或设为 ``False`` 使用 Espeak。
   使用 Piper 时，``TTS_MODEL`` 选择语音。常用模型：

   - ``"en_US-ryan-low"`` — 美式英语男声
   - ``"zh_CN-huayan-x_low"`` — 中文女声

#. 创建 TTS 实例

   .. code-block:: python

      if USE_PIPER:
          tts = Piper(model=TTS_MODEL)
      else:
          tts = Espeak()

   根据 ``USE_PIPER`` 标志，实例化相应的引擎。两个引擎共享相同的 ``say()``
   接口，因此切换引擎不需要其他代码更改。

#. 输入循环

   .. code-block:: python

      while True:
          text = input("要朗读的文本：").strip()
          if text.lower() == 'quit':
              break
          if text:
              print(f"正在朗读：{text}")
              tts.say(text)

   程序提示您输入文本：

   - 输入任意句子并按 **Enter** 让机器人朗读。
   - 输入 ``quit`` 退出循环。
   - 随时按 **Ctrl+C** 中断。

#. 与 STT 的对比

   本课是 :ref:`py_stt` 的配套内容。STT（语音识别）和 TTS（语音合成）
   共同构成 PiCrawler 语音接口的输入和输出部分。