4.2 KiB
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は人物状態遷移と実験セッション管理を追加する。