Imported from sato-susumu/susumu_asr (AGENTS.md). Install upstream with npx skills add sato-susumu/susumu_asr. Copyright stays with the author.

AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

プロジェクト概要

ROS2上で動作する音声認識パッケージ。VAD（音声区間検出）→ ウェイクワード検出 → ASR（音声認識）のパイプラインをマルチスレッドで実装し、長時間安定動作を目的とする。

ビルドとテスト

# ビルド
cd ~/ros2_ws
colcon build --packages-select susumu_asr
source install/setup.bash

# テスト（全件）
pytest test/

# コードスタイルチェック（コミット前に必ず実行）
python -m pytest test/test_flake8.py -v

# 単一テスト実行
python -m pytest test/test_asr.py::test_1 -v

test_copyright.py は @pytest.mark.skip で意図的にスキップされている。

アーキテクチャ

データフロー

AudioRecorder → VADPlugin → WakewordPlugin → audio_queue → ASR → result_queue → SusumuAsrNode
(MicAudioRecorder / WavAudioRecorder)

SpeechRecognitionSystem の状態機械

IDLE
  → [VAD_START] → BUFFERING
      VAD音声をバッファに蓄積しながら WakewordPlugin にフレームを渡す
  → [WAKEWORD_DETECTED] → IN_SPEECH
      VADの silence_threshold を延長（8秒）、バッファ先頭から ASR に送信開始
  → [VAD_END in BUFFERING] → IDLE
      ウェイクワード未検出のまま発話終了 → 音声を捨てる
  → [VAD_END in IN_SPEECH] → IDLE
      ASR に STOP 送信
  → [ASR final result in IN_SPEECH] → IDLE
      ASR が自律的に発話終了を検出した場合（AmiVoice等）も STOP 送信して IDLE へ

主要クラス

プラグイン組み合わせ

ウェイクワード検出（livekit_wakeword / openwakeword）は廃止予定。詳細は susumu_asr/legacy/wakeword.md を参照。

スレッド構成

• VADスレッド（メインスレッド内ループ）: フレームを読み取り、VAD → Wakeword → ASRへ通す
• ASRスレッド（asr.run()）: audio_queue からコマンド（start/audio/stop/stop_all）を受け取って認識処理
• Google ASR内部スレッド（_streaming_recognize_loop）: ストリーミングAPIのレスポンスを非同期処理

キュー通信プロトコル

audio_queue に渡すメッセージ形式：(ASRCommand, data: bytes)

• (ASRCommand.START, timestamp_bytes) — 発話開始
• (ASRCommand.AUDIO, pcm_bytes) — 音声データ
• (ASRCommand.STOP, timestamp_bytes) — 発話終了
• (ASRCommand.STOP_ALL, timestamp_bytes) — シャットダウン

result_queue から返るメッセージ形式：ASRResult(is_final, text, start, end)（end は partial では None）

/stt_event イベント一覧

ROS2ノード（susumu_asr/susumu_asr_node.py）

SusumuAsrNode.__init__ でVAD・Wakeword・ASR・録音の各モジュールを組み立て、system.start() を別スレッドで起動する。認識イベントは on_asr_event コールバック経由で受け取り、以下のトピックに配信する。

音声設定の定数

constants.py で定義。変更する場合はここを編集する。

• SAMPLE_RATE = 16000 — WAVファイル入力時もこのレートを強制チェック
• FRAME_LENGTH_MS = 30 — PyAudioのread_frame_sizeと連動
• AUDIO_FRAME_SAMPLES = 512 — Silero VAD が要求する最小サンプル数

プラグイン固有のしきい値（VAD検出感度・タイムアウト等）は launch ファイルまたは --ros-args のパラメータで上書きする。

デバッグモード

debug=True で起動すると ./debug/ ディレクトリに以下を出力：

• {timestamp}_audio_full.wav — 全音声
• speech_{timestamp}.wav — 認識セッション単位の音声
• {timestamp}_label.txt — ラベル（タブ区切り：start, end, label）。vad_speech（区間）、ww_detected（点）、ASR認識結果（区間）、[P] テキスト（発話ごと最初のpartial、点）、[F] テキスト（final、点）
• {timestamp}_log.txt — 全ログのファイル出力
• {timestamp}_waveform.png — 波形画像

AmiVoice ユーザー辞書（profileWords）

amivoice.profile_words パラメータで毎セッション送信される。フォーマットは AmiVoice ACP 公式仕様に準拠：

• 1単語: 表記 読み（スペース区切り）
• 複数単語: 表記1 読み1|表記2 読み2（| 区切り）
• 例: ヘイ、マイクロフト へいまいくろふと|今日 きょう

環境変数