.. note::

    こんにちは、SunFounderのRaspberry Pi & Arduino & ESP32愛好家コミュニティへようこそ！Facebook上でRaspberry Pi、Arduino、ESP32についてもっと深く掘り下げ、他の愛好家と交流しましょう。

    **参加する理由は？**

    - **エキスパートサポート**：コミュニティやチームの助けを借りて、販売後の問題や技術的な課題を解決します。
    - **学び＆共有**：ヒントやチュートリアルを交換してスキルを向上させましょう。
    - **独占的なプレビュー**：新製品の発表や先行プレビューに早期アクセスしましょう。
    - **特別割引**：最新製品の独占割引をお楽しみください。
    - **祭りのプロモーションとギフト**：ギフトや祝日のプロモーションに参加しましょう。

    👉 私たちと一緒に探索し、創造する準備はできていますか？[|link_sf_facebook|]をクリックして今すぐ参加しましょう！

.. _ai_voice_assistant_car:

21. AI音声アシスタントカー
===========================

このレッスンでは、PiCar-Xを **AI搭載の移動型音声アシスタント** に変身させます。  
ロボットはあなたの声で起動し、話した内容を認識し、感情をこめて話し返し、  
さらに動き・ジェスチャー・ライトでその「気持ち」を表現します。

以下を使って、**完全インタラクティブな音声アシスタントカー** を構築します：

* **LLM** - 大規模言語モデル（OpenAI GPT または Doubao）  
* **STT** - Speech-to-Text（音声→テキスト）  
* **TTS** - Text-to-Speech（テキスト→音声）  
* **センサー + アクション** - 超音波センサー、カメラ、内蔵の表現アクション

----

始める前に
----------------

以下を完了していることを確認してください：

* :ref:`install_all_modules` — ``robot-hat``、 ``vilib``、 ``picar-x`` モジュールをインストールし、その後スクリプト ``i2samp.sh`` を実行します。
* :ref:`test_piper` — **Piper TTS** の対応言語を確認。  
* :ref:`test_vosk` — **Vosk STT** の対応言語を確認。  
* :ref:`py_online_llm` — このステップは **非常に重要** です：  
  **OpenAI** または **Doubao**、その他サポートされているLLMの **APIキー** を取得します。

以下がすでに準備できている必要があります：

* PiCar-Xに接続された **マイク** と **スピーカー**  
* ``secret.py`` に保存された **有効なAPIキー**  
* 安定したネットワーク接続（**有線接続** 推奨）

----

サンプルの実行
---------------

両方の言語バージョンは同じディレクトリにあります：

.. code-block:: bash

   cd ~/picar-x/example

**英語版** （OpenAI GPT、英語の指示）：

.. code-block:: bash

   sudo python3 21.voice_active_car_gpt.py

* LLM: ``OpenAI GPT-4o-mini``  
* TTS: ``en_US-ryan-low`` (Piper)  
* STT: Vosk (``en-us``)

起動ワード：

.. code-block::

   "Hey buddy"

---

**中国語版** （Doubao、中国語の指示）：

.. code-block:: bash

   sudo python3 21.voice_active_car_doubao_cn.py

* LLM: ``Doubao-seed-1-6-250615``  
* TTS: ``zh_CN-huayan-x_low`` (Piper)  
* STT: Vosk (``cn``)

起動ワード：

.. code-block::

   "你好 滴滴"

.. note::

   **起動ワード** および **ロボット名** はコード内で変更可能です：  
   ``NAME = "Buddy"`` または ``NAME = "滴滴"``  
   ``WAKE_WORD = ["hey buddy"]`` または ``WAKE_WORD = ["你好 滴滴"]``

----

何が起こるのか
-----------------

このサンプルを正常に実行すると：

* ロボットは **起動ワードを待機** します（例：「Hey Buddy」／「你好 滴滴」）。  
* 起動ワードを聞くと：

  * LEDが **点滅** し、そのまま点灯します。  
  * ロボットが **元気よく挨拶** します。

* 続いて、ロボットは **あなたの声をリアルタイムで聞き取り** ます。  
* 発話内容を認識すると、次の処理を行います：

  * あなたの音声を **LLM** （OpenAI または Doubao）に送信。  
  * 処理中に **LEDを点滅** させながら「思考」します。  
  * **TTS音声** で応答します。  
  * **対応するアクション** （例：うなずく、回転する、喜ぶ）を実行します。

* もしあなたがロボットに近づきすぎた場合、超音波センサーが：

  * 安全のため、自動で **後退** します。  
  * 現在のラウンドを中断し、警告の応答を行います。

**対話の例**

.. code-block:: text

   You: Hey Buddy
   Robot: Hi there!

   You: Turn left and look around.
   Robot: Roger that, turning my head left like a curious cat!
   ACTIONS: turn_left, look_left

----

他のLLMまたはTTSへの切り替え
------------------------------

LLM・TTS・STT言語は、わずかなコード変更で簡単に切り替えることができます：

* サポートされているLLM：

  * OpenAI
  * Doubao
  * Deepseek
  * Gemini
  * Qwen
  * Grok

* :ref:`test_piper` — **Piper TTS** の対応言語を確認。  
* :ref:`test_vosk` — **Vosk STT** の対応言語を確認。

切り替えるには、コードの初期化部分を以下のように変更します：

.. code-block:: python

   from picarx.llm import Gemini as LLM
   llm = LLM(api_key="YOUR_KEY", model="gemini-pro")

   # モデルと言語の設定
   TTS_MODEL = "en_US-ryan-low"
   STT_LANGUAGE = "en-us"

----

アクション & サウンド リファレンス
-----------------------------------

以下は、LLM が ``ACTIONS:`` 行の後に返すことができる **アクションキーワード** と、それがロボットで何を行うかの一覧です。

.. list-table::
   :header-rows: 1
   :widths: 20 55 25

   * - **アクション**
     - **動作内容（per preset_actions.py）**
     - **効果 / メモ**
   * - ``shake head``
     - カメラのパン角を左右に素早く振りながら振幅を減らし、最後に中央へ戻す。
     - 「ノー」のジェスチャー；車輪は停止したまま。
   * - ``nod``
     - カメラのチルトを上下に2回動かし、中央へ戻す。
     - 「イエス」のジェスチャー；車輪は停止したまま。
   * - ``wave hands``
     - カメラを傾けた後、ハンドルを左右に2回（±25°）振って中央へ戻す。
     - おどけた「手を振る」動作（操舵サーボを“腕”として使用）。
   * - ``resist``
     - 軽いチルト；左右（ステア±15°、パン±15°）を3回交互に繰り返し、停止後センターに戻す。
     - 「拒否」や防御の動き。
   * - ``act cute``
     - 頭を下げ、前後に小刻みに移動（モーターパルス短時間）してリセット。
     - ぴょんぴょんした「かわいい」動き。
   * - ``rub hands``
     - ステアを小さく（±6°）5回振ってリセット。
     - 「手をこすり合わせる」ような動作。
   * - ``think``
     - なめらかに右パン＋下チルト＋右ステア→少しホールド→考えるようなポーズ→リセット。
     - 単一の「考える」アニメーション。
   * - ``twist body``
     - 前進→停止→左パン・左ステア→後退→右パン・右ステア、これを3サイクル。
     - 体を「ひねる」ような動き。
   * - ``celebrate``
     - チルトアップ→右側で2回パン・ステアのフラリッシュ→左側も2回→中央へ。
     - お祝い風の華やかな動き。
   * - ``depressed``
     - チルトを下方向に角度と間隔を変えながら何度か動かし、長い間をおいてリセット。
     - 「悲しい」姿勢のシーケンス。

移動 & ユーティリティ
~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 22 58 20

   * - **アクション**
     - **動作内容**
     - **メモ**
   * - ``forward``
     - 低速で約1秒間前進して停止。
     - ``forward(car)`` （速度5%、1秒）で実装。
   * - ``backward``
     - 低速で約1秒間後退して停止。
     - ``backward(car)`` （速度5%、1秒）で実装。

サウンドエフェクト
~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 24 56 20

   * - **サウンド**
     - **動作内容**
     - **メモ**
   * - ``honking``
     - ``car-double-horn.wav`` を非同期で再生（音量約100）。
     - ``Music.sound_play_threading`` でトリガー。
   * - ``start engine``
     - ``car-start-engine.wav`` を非同期で再生（音量約50）。
     - 起動／準備の合図。

センサーによる自動トリガー
~~~~~~~~~~~~~~~~~~~~~~~~~~

* **超音波近接センサー**  

  * トリガー：距離 < 10 cm  
  * 副作用：自動 ``backward`` + このラウンドの画像処理を無効化  
  * 注入メッセージ： ``<<<Ultrasonic sense too close: {distance}cm>>>``

ライフサイクルフック（LEDインジケーター）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ``before_listen`` → 2回点滅（リスニング準備）  
* ``before_think`` → 点滅（思考中）  
* ``before_say`` → LED点灯（発話中）  
* ``after_say`` → アクション待機 → LED消灯  
* ``on_stop`` → アクション停止、デバイスクローズ

----

トラブルシューティング
-----------------------------

* **ロボットが起動ワードに反応しない**

  * マイクが動作しているか確認してください。  
  * ``WAKE_ENABLE = True`` になっていることを確認。  
  * 発音に合うように起動ワードを調整します。

* **スピーカーから音が出ない**
 
  * TTSモデルの設定を確認。  
  * Piper または Espeak を手動でテスト。  
  * スピーカーの接続と音量をチェック。

* **APIキーのエラーまたはタイムアウト**
 
  * ``secret.py`` のキーを確認。  
  * ネットワーク接続を確認。  
  * 使用している LLM がサポート対象か確認。

* **Picar-X が動作・アクションしない**
 
  * アクション名が ``actions_dict`` と一致しているか確認。  
  * モーターおよびサーボの配線を確認。

* **超音波センサーが予期せず作動し続ける**
  
  * センサーの取り付け高さと角度を確認。  
  * コード内の ``TOO_CLOSE`` 距離しきい値を調整。