# Phase 5 音声声掛け制御仕様

## 1. Phase 5の目的

一時track IDに対して再現可能な位置で音声提示またはpseudo promptを行い、その後の振り向き観測を保存する。統計的因果推論は対象外とする。

## 2. システム構成

`TrackEvent + TrackedPerson + TurnFrameResult -> VoicePromptController -> AudioPlayer / VoiceLogger` と接続する。外部pygame型はAudioPlayer内だけで扱う。

## 3. AudioPlayer

pygameを遅延importし、Soundを非同期再生する。disabled/noop、ファイル欠落、初期化・再生失敗はFalseとして継続する。overlapはskip（既定）、restart、allowを選べる。

## 4. VoicePromptController

track別eligibility、prompt実行、response window、反応、最終summaryとイベント重複防止を管理する。

## 5. VoicePromptMode

`prompt`、`control`、`disabled`を独自Enum・文字列で表し、CSVにも同じ値を保存する。

## 6. prompt / control / disabled

promptは音声再生成功時を開始点とする。controlは無音のpseudo promptを同じ開始点として記録する。disabledはcontrollerとvoice CSVを生成しない。

## 7. 声掛け条件

trigger line crossing（既定）、region entry、fixed position、first confirmed trackを選べる。

## 8. trigger_line_crossingの仕様

Phase 2の `trigger_crossed` eventを使用する。一定位置で発生し、実験条件を揃えやすいため既定とする。

## 9. fixed_x_positionの仕様

foot x/yがpixel閾値以上（increasing）または以下（decreasing）で候補となる。one-prompt制約で連続発火を防ぐ。

## 10. 声掛け対象条件

confirmed、領域内、非stale、最低track age、未prompt、未turnを設定に応じて要求する。skip理由もdecision/eventへ残す。

## 11. 重複声掛け防止

既定では同じtrack IDのprompt attemptまたはpseudo prompt後は再実行しない。track IDは個人識別ではなく、ID switch時は別trackになり得る。

## 12. 全体クールダウン

成功promptまたはpseudo promptから既定3秒は別trackへの開始を抑止する。残り時間を画面表示する。

## 13. 反応観測ウィンドウ

開始後3秒以内のweak以上の確定turnをresponseとし、elapsed time差をreaction timeとする。期限超過時はexpired eventを一度出す。

## 14. Phase 4 Turnとの接続

delta最大値、最終level、confirmed時刻をtrack IDで関連付ける。subtleとface appearedは補助情報であり主responseではない。

## 15. response_detected判定

window内の `turn_confirmed` かつweak/medium/strongを必要とする。声掛け後の観測であって因果関係の断定ではない。

## 16. controlモードの解析上の意味

同位置相当からの自然振り向きを観測し、prompt条件との比較開始点を揃える。音声は一切再生しない。

## 17. VoiceLogger CSV仕様

decisions、events、summaryをUTF-8 BOMで保存する。metadataは `ensure_ascii=False` JSON、summaryはtrack ID単位で重複排除する。

## 18. 画面表示

人物付近へwaiting/played/control/failed、左上へmode、prompt数、response数、cooldownを表示する。

## 19. 例外処理

音声欠落・pygame失敗はアプリを停止しない。tracker無効時はVoiceを無効化する。Turn無効時もprompt可能だが分析は `turn_disabled` とする。

## 20. テスト

実音声を鳴らさずmock backend/playerでload、overlap、prompt/control/failure、重複、cooldown、response、expiry、CSV BOM/JSON/dedupを検証する。

## 21. 実機確認手順

音声を `assets/audio/prompt.wav` に置き、promptでライン通過・音量・cooldown・一回制限、controlで無音pseudo event、見る／見ない場合のresponse/expiry、欠落ファイル時の継続を確認する。音声内容・音量・再生機器を固定し、周囲とプライバシーへ配慮する。

## 22. Phase 6への引き継ぎ

track ID、mode、eligibility、prompt/pseudo時刻、window、response、reaction time、response level、最大delta、分析可否・除外理由を安定して提供する。Phase 6は人物状態遷移と実験セッション管理を追加する。