ha-voice

Home Assistant 音声コントロール

Assist パイプライン、カスタムインテント、ウェイクワード、音声処理、音声サテライトを設定し、ローカル音声コントロールを実現します。

クイックスタート

Assist パイプラインの設定

# configuration.yaml
assist_pipeline:
  pipelines:
    - language: en
      name: Default Pipeline
      stt_engine: faster_whisper  # Local STT
      tts_engine: tts.piper       # Local TTS
      conversation_engine: conversation.home_assistant
      wake_word_entity: binary_sensor.wake_word

重要な理由： パイプラインは、すべてのコンポーネント（STT、TTS、インテント、会話エージェント）を1つの音声ワークフローに接続します。

カスタムインテントの作成

# custom_sentences/en/turn_on.yaml
language: en
version: 1

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on the [area] {name:list}"
          - "turn on {name:list}"
          - "[please] activate {name:list}"
        lists:
          name: light_names

lists:
  light_names:
    - "bedroom light"
    - "kitchen overhead"
    - "living room"

重要な理由： カスタムの文パターンを使うと、自宅に合わせた自然な音声コマンドを設定できます。

テキスト読み上げ（TTS）の設定

ローカルオプション - Piper：

tts:
  - platform: piper
    language: en_GB
    voice: jenny_dioco

クラウドオプション - OpenAI：

tts:
  - platform: tts
    service: google_translate_say  # or openai, google cloud
    language: en

重要な理由： TTS は音声でフィードバックを返します。ローカルオプションなら、クラウドへの依存はありません。

音声認識（STT）の設定

ローカルオプション - Faster Whisper：

stt:
  - platform: faster_whisper
    language: en

クラウドオプション - Google Cloud Speech：

stt:
  - platform: google_cloud
    language_code: en-US

重要な理由： STT は音声コマンドをテキストに変換します。ローカルオプションならプライバシーを確保できます。

重要なルール

✅ 必ず行うこと

• ✅ インテントの設定には custom_sentences/ ディレクトリを使用します（非推奨の sentences/ は使用しません）
• ✅ デプロイ前に Assist 開発者ツールでインテントをテストします
• ✅ スロットベースのエンティティ照合には {name:list} 構文を使用します
• ✅ 同じパイプラインで STT と TTS の両方のエンジンを設定します
• ✅ パイプラインで有効にする前に、ウェイクワードエンティティが存在することを確認します
• ✅ 音声コマンドを見つけやすいよう、インテントの一覧を文書化します

❌ 絶対にしないこと

• ❌ 文パターンにエンティティ ID をハードコードしないでください（リストとスロットを使用します）
• ❌ カスタム sentences/ YAML ファイルで version: 1 を忘れないでください
• ❌ 古い sentences/ ディレクトリと新しい custom_sentences/ を混在させないでください（custom_sentences/ のみを使用します）
• ❌ ディスク容量が十分でない状態で Piper TTS を有効にしないでください（モデルのサイズは100 MB以上です）
• ❌ すべてのスロットにワイルドカード {query} を使用しないでください（インテントが曖昧になります）
• ❌ Assist 開発者ツールでのテストを省略しないでください

よくある間違い

❌ 誤り - エンティティ ID のハードコード：

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on light.bedroom"
          - "turn on light.kitchen"

✅ 正しい - スロットリストの使用：

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on [the] {name:list}"
        lists:
          name: light_names

lists:
  light_names:
    - "bedroom"
    - "kitchen"

理由： リストは動的であり、Home Assistant のエンティティからプログラムで生成できます。

文パターンの構文

スロット

名前付きスロットはリストの値に一致します：

sentences:
  - "turn on {name:list}"  # Matches list value, captures as 'name' slot

リスト

リスト照合によってスロットの値を指定します：

lists:
  room:
    - "bedroom"
    - "kitchen"
    - "living room"

省略可能なグループ

角括弧で囲むと、その単語を省略可能にできます：

sentences:
  - "[please] turn on the {name:list}"
  - "activate [the] {device:list}"

ワイルドカード

ワイルドカードスロットは任意のテキストを取得します：

sentences:
  - "remind me {reminder:text}"  # Captures any text as 'reminder'
  - "set a timer for {duration:text}"

組み合わせパターンの例

intents:
  TurnOn:
    data:
      - sentences:
          - "[please] [turn on | switch on | activate] [the] {area} {name:list}"
          - "[please] turn on {name:list}"
          - "activate {name:list} [in the] {room:list}"
        lists:
          name: light_names
          room: room_names

  Reminder:
    data:
      - sentences:
          - "remind me {reminder:text}"
          - "[please] [create | set] a reminder [for me] [to] {reminder:text}"

lists:
  light_names:
    - "bedroom light"
    - "kitchen overhead"
    - "living room lamps"
  room_names:
    - "bedroom"
    - "kitchen"
    - "living room"

重要な理由： 柔軟なパターンを使うと、インテント認識の精度を保ちながら、自然な言い回しに対応できます。

組み込みインテントのリファレンス

Home Assistant には、次のデフォルトインテントが用意されています。

ナビゲーションインテント

• HassTurnOn / HassTurnOff - デバイスを制御します
• HassToggle - スイッチ／ライトを切り替えます
• HassOpenCover / HassCloseCover - カバーを制御します
• HassSetClimate - 空調を制御します（暖房／冷房）

情報インテント

• HassGetState - エンティティの状態を取得します
• HassGetHistory - オートメーションの履歴を照会します

ホームコントロールインテント

• HassArmAlarm / HassDisarmAlarm - アラームを設定／解除します
• HassLockDoor / HassUnlockDoor - ロックを制御します

カスタムインテント

新しいインテントブロックを定義すると、custom_sentences/ に追加のインテントを作成できます：

intents:
  CustomIntentName:
    data:
      - sentences: [...]

ウェイクワードの設定

openWakeWord（ローカル）

conversation:
  engine: openai

# Enable openWakeWord
binary_sensor:
  - platform: openwakeword
    models:
      - alexa    # "Alexa, help"
      - hey_google  # "Hey Google, ..."
      - hey_siri

Porcupine（ローカル、有料）

binary_sensor:
  - platform: porcupine
    access_key: !secret porcupine_key
    keywords:
      - hey_home_assistant

音声サテライトのセットアップ

ハードウェア要件

• マイク： INMP441（I2S デジタル）または同等品
• スピーカー： MAX98357A アンプまたは同等品
• ボード： ESP32-S3。ESP32-S3-BOX-3 を推奨
• 接続： Wi-Fi が必要です

ESPHome 音声アシスタントの設定

# ESPHome device
packages:
  voice_assistant: !include packages/voice_assistant.yaml

# Or inline configuration:
i2s_audio:
  i2s_lrclk_pin: GPIO33
  i2s_bclk_pin: GPIO34
  i2s_mclk_pin: GPIO32

microphone:
  - platform: i2s_audio
    id: mic
    adc_type: external
    i2s_din_pin: GPIO35
    pdm: false

speaker:
  - platform: i2s_audio
    id: speaker
    dac_type: external
    i2s_dout_pin: GPIO36
    mode: mono

voice_assistant:
  microphone: mic
  speaker: speaker
  noise_suppression_level: 2
  auto_gain: 80dB
  volume_multiplier: 0.8

重要な理由： 音声サテライトを使うと、ローカル処理で複数の部屋に Assist を拡張できます。

音声処理の設定

言語サポート

完全サポート（20以上の言語）： en、de、fr、it、es、nl、pl、pt、ru、sv、tr、uk、zh、ja、ko など

部分サポート（40以上の言語）： STT／TTS の対応状況に差がある地域別の言語バリエーションや追加言語

コミュニティサポート（80以上の言語）： コミュニティが提供する文テンプレート

言語設定：

assist_pipeline:
  pipelines:
    - language: de  # German
      name: Deutsche Pipeline
      tts_engine: tts.piper  # Set voice per language

パフォーマンスの調整

STT（Faster Whisper）：

stt:
  - platform: faster_whisper
    language: en
    model: base  # tiny, base, small, medium, large
    acceleration: gpu  # CPU or GPU

TTS（Piper）：

tts:
  - platform: piper
    voice: en_GB-jenny
    rate: 11025  # Audio sample rate
    volume_normalize: true

会話エージェントの統合

組み込みエージェント：

conversation:
  engine: home_assistant

OpenAI エージェント：

conversation:
  engine: openai
  api_key: !secret openai_api_key
  model: gpt-4

カスタム会話エージェント：

conversation:
  engine: custom
  module: custom_components.my_agent

よく使われるインテントパターン

デバイス制御パターン

intents:
  TurnOn:
    data:
      - sentences:
          - "turn on [the] {name:list}"
          - "[please] activate {name:list}"
        lists:
          name: light_names

空調制御パターン

intents:
  SetClimate:
    data:
      - sentences:
          - "set [the] {room:list} [thermostat] to {temp:number} degrees"
          - "make it {temp:number} in [the] {room:list}"
        lists:
          room: room_names

クエリパターン

intents:
  GetState:
    data:
      - sentences:
          - "what is the temperature [in the] {room:list}"
          - "is [the] {name:list} on"
        lists:
          room: room_names
          name: device_names

開発者ツールでのテスト

1. Developer Tools → Assist に移動します
2. テスト文「turn on the bedroom light」を入力します
3. 次の点を確認します：
   • ✅ インテントが正しく一致する
   • ✅ スロットが適切に抽出される
   • ✅ 音声が再生される（TTS を設定している場合）
4. 一致しない場合は、次の方法でデバッグします：
   • 文のパターンを確認する
   • リストの値を確認する
   • スロット名を確認する

トラブルシューティング

インテントが認識されない

症状： 音声コマンドがどのインテントにも一致しません

解決策：

# Check custom_sentences directory structure
ls -R config/custom_sentences/

# Verify YAML syntax
cat config/custom_sentences/en/custom.yaml

# Test in Assist Developer Tools with exact phrase
# Adjust sentence patterns to match expected phrasing

TTS／STT エンジンが動作しない

症状： Assist で「Engine not available」エラーが表示されます

解決策：

# Verify engine is configured
service: tts.piper  # Must exist

# Check dependencies installed
pip install piper-tts  # for Piper
pip install faster-whisper  # for Whisper

# Restart Home Assistant to load engines

ウェイクワードが反応しない

症状： ノイズがあるにもかかわらず、バイナリセンサーがオフのままです

解決策：

# Verify entity_id is correct
service: homeassistant.update_entity
target:
  entity_id: binary_sensor.wake_word

# Check binary sensor configuration
# Review noise levels and model sensitivity
# Test microphone separately

音声サテライトの接続に関する問題

症状： ESP32 が WiFi または Assist パイプラインから切断されます

解決策：

# Check WiFi signal strength in ESPHome logs
# Reduce WiFi distance or add access point
# Update ESPHome firmware
esphome run voice_assistant.yaml --upload-speed 115200

依存関係

必須

コンポーネント	バージョン	用途
Home Assistant	2024.1+	Assist プラットフォーム
Faster Whisper	0.5+	ローカル STT エンジン
Piper TTS	1.0+	ローカル TTS エンジン

任意

コンポーネント	バージョン	用途
OpenWakeWord	0.3+	ウェイクワードの検出
Porcupine	Latest	プレミアムなウェイクワード
ESPHome	2024.1+	音声サテライトデバイス

公式ドキュメント

• Home Assistant の音声制御
• Assist パイプラインの設定
• インテント認識ガイド
• 会話統合

セットアップチェックリスト

音声コマンドを使用する前に、次の点を確認してください：

• STT、TTS、会話エンジンを設定した Assist パイプライン
• インテント定義を含む custom_sentences/en/ ディレクトリが作成されている
• Assist の開発者ツールで文のパターンをテスト済み
• ウェイクワードエンティティが存在する（ウェイクワードを使用する場合）
• マイクとスピーカーが動作している（開発者ツールでテスト）
• インテントのリストに正しいエンティティの別名が含まれている
• 言語設定が構成と一致している
• すべての YAML 構文が有効である（タブを使わず、適切にインデントされている）