.. _py_stt:

15. STT（语音转文本）
==============================================

本示例演示如何在 PiCrawler 上使用 STT（语音转文本）模块。
机器人通过板载麦克风听取您的声音，并实时将其转换为文本。

**运行代码**

.. raw:: html

    <run></run>

.. code-block::

    cd ~/picrawler/examples
    sudo python3 15_stt.py

程序运行后，您将看到语言设置和提示符。机器人开始监听 — 对着麦克风说话，
识别的文本将打印到终端。

如果未检测到语音，将显示 ``(no speech detected)``。按 **Ctrl+C** 退出。

**准备工作**

请确保已完成：

* :ref:`install_all_modules` — 安装 ``robot-hat``、``vilib``、``picrawler``
  模块，然后运行脚本 ``i2samp.sh``。

**代码**

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

.. raw:: html

    <run></run>

.. code-block:: python

    #!/usr/bin/env python3
    from robot_hat.stt import STT

    # 使用 sunfounder_voice_assistant STT 模块的语音识别演示
    # 按 Ctrl+C 退出

    # 配置语言："en-us"、"zh-cn" 等
    LANGUAGE = "zh-cn"

    def main():
        print("=== PiCrawler 语音转文本演示 ===")
        print(f"语言：{LANGUAGE}")
        print("按 Ctrl+C 退出")
        print()

        stt = STT(language=LANGUAGE)

        try:
            while True:
                print("正在监听...（现在说话）")
                text = stt.listen()
                if text:
                    print(f">>> {text}")
                else:
                    print("（未检测到语音）")
        except KeyboardInterrupt:
            print("\n正在退出...")

    if __name__ == "__main__":
        main()


**工作原理**

#. 导入 STT 模块

   .. code-block:: python

      from robot_hat.stt import STT

   ``STT`` 类是 ``robot_hat`` 包的一部分。它处理所有底层的音频捕获和语音
   识别处理。

#. 设置语言

   .. code-block:: python

      LANGUAGE = "zh-cn"

   ``LANGUAGE`` 变量配置识别语言。您可以根据需要将其更改为其他支持的代码，
   如 ``"en-us"``\ （英语）。

#. 创建 STT 实例

   .. code-block:: python

      stt = STT(language=LANGUAGE)

   这将创建一个针对所选语言配置的 STT 对象。该对象初始化麦克风和语音识别
   引擎。

#. 监听循环

   .. code-block:: python

      while True:
          print("正在监听...（现在说话）")
          text = stt.listen()
          if text:
              print(f">>> {text}")
          else:
              print("（未检测到语音）")

   程序运行一个无限循环，每次迭代：

   - 提示用户说话。
   - 调用 ``stt.listen()``，该函数会阻塞，直到检测并处理语音。
   - 将识别的文本作为字符串返回，如果未理解任何内容则返回 ``None``。
   - 将结果打印到终端。

#. 优雅退出

   .. code-block:: python

      except KeyboardInterrupt:
          print("\n正在退出...")

   按 **Ctrl+C** 会触发 ``KeyboardInterrupt``，捕获后打印退出消息并干净地
   终止程序。