오디오 분석 에이전트 (오인식 감지·자동 정정) — 코드레벨 동작 흐름 & 이슈 분석 가이드

한 장 요약 (전체 흐름)

0. 증상 → 의심 코드 지점 디버깅 맵

이슈 수정 시 여기서 시작. 모든 경로는 apps/web/ 기준.

1. 구성 요소 지도

배선(사용처) — 파이프라인이 실제로 조립되는 곳

2. 에이전트 설정 계층 — 무엇을 어떻게 분석할지

에이전트는 "어느 LLM에게(provider/model), 어떤 지시로(systemPrompt), 최근 몇 턴을(nTurns) 들려줄지"의 프리셋이다. 여러 개를 만들어 두고 전역으로 1개만 활성화한다.

3. 오디오 캡처 — 발화 구간만 role별로 녹음

hooks/use-guest-audio-capture.ts. 아동(user)과 핑퐁이(assistant)를 독립된 MediaRecorder 2대로, 발화 신호가 켜진 구간만 녹음한다. 발화 신호의 출처는 배선부 — 카드뷰 기준 monitorSession.isSpeaking/isAiSpeaking session-card.tsx:648-649.

4. 턴 완료 감지 — TurnAnalysisCore 상태 머신

hooks/turn-analysis-core.ts. React 무의존 순수 클래스(단위 테스트 있음 — 로직 수정 시 turn-analysis-core.test.ts 먼저). 전사 로그 스트림에서 "분석할 아동 턴"을 뽑는다.

hooks/turn-analysis-core.ts:80-99 — assistant 트리거의 두 가지 함정private handleAssistant(assistantLog: CoreLog): void {
  // ① assistant 도착 → 대기 중인 "모든" user 폴백 취소 — 연속 user 발화 후 응답이 오면
  //    마지막 user 턴만 분석되고 앞의 user 턴들은 폴백까지 취소돼 영영 분석 안 됨
  for (const [, p] of this.pending) this.deps.clearTimer(p.handle);
  this.pending.clear();
  // ② 역방향 첫 user 턴 1개만 emit — pingpongSpeech는 "이 assistant 발화"로 고정
  const assistantIdx = this.allLogs.indexOf(assistantLog);
  for (let i = assistantIdx - 1; i >= 0; i--) {
    if (this.allLogs[i].role === "user") { this.emit({ ... }); return; }
  }
}

5. blob 선별과 대기 — 로그 턴 ↔ 녹음 blob 매칭

getRecentBlobs(nTurns, chatLogs, targetLogId) use-guest-audio-capture.ts:199-253 → 매칭 로직은 turn-audio-selection.ts.

1. 오디오 턴 필터 turn-audio-selection.ts:32-34, 88-97: type === "audio" 또는 "stt_verified"인 user/assistant 턴만. stt_verified가 raw audio 로그를 가리키면(relatedToLogId) 중복 제거, raw가 없으면 대체 기준.
2. target까지 자르기 :98-109: targetLogId 위치까지의 턴 중 마지막 n개가 기대 목록. target이 stt_verified면 raw audio id로 해석(:101-106).
3. 근접도 매칭 :63-85: role 동일 + 미사용 blob 중, blob 구간 중앙시각이 로그 timestamp에 가장 가까운 것. minStartedAt 단조 증가로 시간 역행 매칭 차단(:83).

6. 분석 요청 파이프라인 — WAV 변환과 provider 분기

analyze() use-turn-analysis.ts:63-116 → POST /api/audio-analysis/analyze route.ts:42-296.

hooks/use-turn-analysis.ts:71-78 — 형식 결정 지점 (400 이슈의 진원지)// OpenAI(wav/mp3)·Gemini(wav/mp3/ogg/flac/aac/aiff) 모두 webm 미지원 → 전송 전 턴별 WAV 변환.
// "전 턴 성공 시에만" wav — 하나라도 실패하면 형식 혼용을 피해 원본(webm) 그대로 폴백 → 서버 400
const wavBlobs = await Promise.all(blobs.map((b) => audioBlobToWav(b)));
const allWav = wavBlobs.every((b): b is Blob => b !== null);
const sendBlobs = allWav ? wavBlobs : blobs;
const mimeType = allWav ? "audio/wav" : blobs[0]?.type || "audio/webm";

• {핑퐁이발화} 치환: route.ts:19-21 — assistant 트리거면 핑퐁이 응답 발화, no-response면 "(무응답)".
• 지연·상태 메트릭: observeExternalOperationDuration("audio_analysis_request", provider, status) :124-142, 242-260 → Grafana에서 provider별 지연 분리 가능.
• 서버 오류는 전부 502/400 + 로거 채널 AUDIO_ANALYSIS_ANALYZE. 클라이언트는 이를 probability:"medium" + error 결과로 변환(use-turn-analysis.ts:105-112) — 알림에는 뜨되 자동 정정은 차단(!result.error 가드).
• nTurns는 서버에서 _nTurns로 받고 실사용 안 함(route.ts:57) — 실제 턴 수는 audioBase64.length가 결정. 턴 수 관련 이슈는 클라이언트 선별(§5)만 보면 된다.

7. 결과 소비 3갈래

① 모니터 알림 session-card.tsx:666-680 / monitor-dashboard page.tsx:1025-1039

onResult → 결과 JSON의 non-empty 필드를 줄 단위로 펼쳐 AlertType.AUDIO_MISRECOGNITION("오디오 오인식 감지", shared/types/index.ts:58) 알림 추가. priority: NONE이라 조용한 정보성 알림이다.

② 자동 정정 주입 (correction injection) session-card.tsx:682-688

기본 템플릿(types:43-47)은 "인식된 발화(잘못 들음) vs 실제 발화"를 명시하고 '소리 내어 말하지 말고 다음 발화에 반영만 하라'고 지시한다. 설정은 전역 단일 레코드라 모든 수업에 일괄 적용 (기본 off, types:49-52).

③ 로그 영속화 use-audio-analysis-logger.ts:27-107

세션 로그 페이지(components/pages/session-log.tsx:160)는 buildAudioAnalysisMap으로 분석 로그를 관련 턴 아래 병합 표시하고, /api/audio-analysis-logs/download-url로 분석에 실제 쓰인 오디오를 재생할 수 있다 — "LLM이 뭘 듣고 이렇게 판정했나" 사후 검증용.

8. 설계 결정·엣지 케이스 모음

수정 시 체크리스트

• 배선 3곳 동시 확인: 카드뷰 session-card.tsx · 포커스뷰 monitor-dashboard page.tsx · (레거시) host.tsx — 로직 수정이 한쪽에만 반영되면 뷰별 동작 차이 사이드 이펙트.
• TurnAnalysisCore 수정 → 단위 테스트 먼저: hooks/turn-analysis-core.test.ts가 트리거·dedup·폴백 시나리오를 커버한다.
• probability 계약 유지: 에이전트 프롬프트·자동 정정 게이트·알림이 모두 "high"/"medium"/"low" 문자열에 의존.
• 실기기 검증 전 커밋 금지 영역: 오디오 캡처(§3)·정정 주입(§7-②)은 브라우저/실세션 검증이 필요한 영역 — 로컬 적용 후 검증 완료 시 커밋.