오디오 분석 에이전트 — 통합 코드 레벨 문서

마지막 업데이트 2026-09-12

한눈에 보는 파이프라인

등장 인물 (모듈 맵)

0. 데이터 모델 — 무엇이 흐르는가

먼저 두 타입만 머리에 넣으면 전체가 읽힌다. apps/web/types/db/audio-analysis-agent.types.ts

// 운영자가 등록하는 에이전트 정의 (DynamoDB chatPreset 테이블에 저장)
interface AudioAnalysisAgent {
  userId: string;        // 파티션 키 = "AUDIO_ANALYSIS_AGENT" (AUDIO_ANALYSIS_AGENT_KEY)
  id: string;
  name: string;
  provider: "gemini" | "openai" | "qwen";
  model: string;         // 예: gpt-4o-audio-preview, gemini-2.5-flash, qwen3.5-omni-flash
  systemPrompt: string;  // {핑퐁이발화} 변수 사용 가능
  nTurns: number;       // 분석에 포함할 최근 아동 발화 턴 수 (1~5)
  order?: number;
}

// LLM이 돌려주는 분석 결과 (JSON)
interface TurnAnalysisResult {
  probability: "high" | "medium" | "low";  // 오인식 가능성
  reason: string;            // 판단 사유 (한국어)
  transcript?: string;       // 오디오에서 실제로 들린 내용
  heardContent?: string;     // AI가 인식한 내용
  estimatedActual?: string;  // 실제 발화 추정
  error?: string;
}

1. 관리 UI — 에이전트 만들고 "내 브라우저에서" 켜기

운영자 화면은 components/sections/audio-analysis-agents-section.tsx:204. CRUD는 entities/audio-analysis-agent/model/use-audio-analysis-agents.ts 훅이 /api/audio-analysis-agents(목록·생성), /api/audio-analysis-agents/[id](수정·삭제)를 호출한다.

활성화는 DB가 아니라 localStorage

중요한 포인트 — 어느 에이전트를 쓸지는 서버에 저장되지 않는다. audio-analysis-agents-section.tsx:282 handleActivate()가 localStorage["ppi_active_analysis_agent_id"] 한 칸만 토글한다(토글식, 같은 걸 누르면 해제).

const LS_ACTIVE_AGENT = "ppi_active_analysis_agent_id";
const handleActivate = (id) => {
  const newId = activeAgentId === id ? "" : id;  // 다시 누르면 OFF
  newId ? localStorage.setItem(LS_ACTIVE_AGENT, newId)
        : localStorage.removeItem(LS_ACTIVE_AGENT);
};

nTurns 시각화 — 분석 대상 아동 발화 기준 최근 N개 오디오 턴

audio-analysis-agents-section.tsx:80 TurnPreview는 분석 대상 아동 발화로 끝나는 최근 n개 오디오 턴을 보여준다. 새 핑퐁 응답은 분석을 트리거할 뿐 합본 범위에는 포함되지 않는다.

예) nTurns=2 · 분석 대상 = 아동 답변

이때 실제 LLM과 audio_analysis 합본 WAV에 들어가는 오디오는 핑퐁 질문 Blob → 아동 답변 Blob 2개다. {핑퐁이발화} 변수도 새 응답이 아니라 아동 답변 직전의 핑퐁 질문으로 치환된다.

2. 런타임 진입점 — 어디서 켜지나

같은 3개 훅을 V1 호스트와 V2 세션카드가 동일하게 엮는다.

// host.tsx:558 — 3개 훅이 데이터로 연결된다
const { getRecentBlobs } = useGuestAudioCapture({ remoteVideoRef, isPeerTalking: sessionRelay.isPeerTalking });

const { logAnalysis } = useAudioAnalysisLogger(  // userId/lessonIndex/activityId 컨텍스트
  selectedUserId && selectedLessonIndex ? { userId, lessonIndex, getActivityId } : null);

const { analysisResults } = useTurnAnalysis({
  agents: audioAnalysisAgents,        // 활성 후보 목록(localStorage로 1개 선택)
  getRecentBlobs,                     // ← 단계 1이 제공
  chatLogs,                           // ← 단계 2의 입력
  isSessionActive: sessionRelay.isActive,
  onResult: (_logId, result) => { setAnalysisAlert(...) },  // ← 단계 4 (V1만)
  onLogData: logAnalysis,             // ← 단계 5
});

3. 단계 ① 오디오 캡처 — role/time 기반 턴 Blob 링버퍼

hooks/use-guest-audio-capture.ts. 핵심은 핑퐁이와 아동 발화를 모두 TurnAudioBlob으로 기록하되, 최종 합본에는 실제 녹음 Blob이 매칭된 턴만 넣는 것이다.

• syncCapture("user", isUserSpeaking, userStream) — 아동 발화 구간을 녹음한다.
• syncCapture("assistant", isAiSpeaking, aiStream) — 핑퐁이 발화 구간을 녹음한다. Realtime은 OpenAI WebRTC ontrack stream, TTS/Typecast는 TtsPlayer.stream이 같은 aiAudioStream으로 들어온다.
• MediaRecorder 종료 시 { role, blob, startedAt, endedAt }를 FIFO로 보관한다.
• getRecentBlobs(n, chatLogs, targetLogId)는 로그 턴과 녹음 Blob을 role/time 기준으로 매칭한다.

// 한 턴 녹음이 끝날 때 role/time 메타와 함께 보관
turnAudioBlobsRef.current = [
  ...turnAudioBlobsRef.current,
  { role, blob, startedAt, endedAt: Date.now() },
].slice(-Math.max(maxTurns * 3, maxTurns));

4. 단계 ② 턴 감지 & 중복 제거 — TurnAnalysisCore

가장 머리를 써야 하는 부분. 순수 로직은 React와 분리되어 hooks/turn-analysis-core.ts에 클래스로 있고(테스트는 turn-analysis-core.test.ts), use-turn-analysis.ts가 타이머·fetch 같은 부수효과를 주입한다.

입력: 채팅 로그를 흘려넣는다

use-turn-analysis.ts:113 effect가 chatLogs를 core.ingest()로 전달한다. turn-analysis-core.ts:45 ingest()는 seenIds로 처음 보는 로그만 골라 누적하고, 역할별로 분기한다.

두 가지 트리거

// :77 — assistant 도착 = 직전 아동 발화에 핑퐁이가 응답한 순간
private handleAssistant(assistantLog) {
  for (const [, p] of this.pending) this.deps.clearTimer(p.handle); // 무응답 폴백 취소
  this.pending.clear();
  // 내부 히스토리를 역방향으로 훑어 직전 user 1개를 찾음
  for (let i = assistantIdx - 1; i >= 0; i--) {
    if (this.allLogs[i].role === "user") {
      const previousPingpongSpeech = this.findPreviousAssistantMessage(i);
      this.emit({ userLogId, transcribedText, pingpongSpeech: previousPingpongSpeech ?? assistantLog.message, trigger: "assistant" });
      return;
    }
  }
}

중복 방지의 두 집합: seenIds vs targeted

★ 스텝 전환 중복 알림 버그 수정 (핵심 함정)

use-turn-analysis.ts:113~125의 effect 분기가 의도적으로 미묘하다.

if (chatLogs.length === 0) { core.reset(); return; }  // 게스트 접속 종료 등에만 상태 초기화
if (!isSessionActive) return;                  // 스텝 전환으로 잠깐 inactive → 누적/dedup 상태 유지
core.ingest(chatLogs.map(...));

5. 단계 ③ 분석 요청 — analyze() → 서버

코어가 타깃을 onTarget으로 올리면 use-turn-analysis.ts:61 analyze()가 실행된다.

1. :62 getActiveAgentId()로 활성 에이전트 선택 — 없으면 즉시 return.
2. :64 getRecentBlobs(agent.nTurns, chatLogs, target.userLogId)로 분석 대상 user 기준 최근 n턴 오디오를 요청 — 기대 턴 수만큼 실제 Blob이 없으면 return.
3. :69 Blob들을 blobToBase64로 변환해 POST /api/audio-analysis/analyze 호출.
4. :87~89 응답 result를 analysisResults Map에 저장 → onResult(단계 4)와 onLogData(단계 5) 콜백 호출.
5. :90 실패 시 probability:"medium" 에러 result를 만들어 그래도 결과를 흘린다.

분석 서버 분리 — web은 프록시만 한다 PPI-1224

app/api/audio-analysis/analyze/route.ts는 더 이상 provider를 호출하지 않는다. withAuthMember로 인증만 하고 AUDIO_ANALYSIS_SERVICE_ORIGIN의 POST /internal/analyze로 body를 스트림 전달하는 얇은 프록시다(x-internal-api-key 헤더, 16MB 상한, 기본 35초 timeout → 504 AUDIO_ANALYSIS_TIMEOUT, 설정 누락·연결 실패는 502 AUDIO_ANALYSIS_SERVICE_UNAVAILABLE).

실제 분석은 독립 서비스 apps/audio-analysis(express, 기본 포트 3101)에서 돈다. OOM 진단을 위해 /metrics와 30초 주기 memory_heartbeat 로그를 노출한다. provider 분기는 src/analyze.ts, 호출·timeout·메트릭은 src/provider.ts가 담당한다. 공통으로 substitutePrompt()가 {핑퐁이발화}를 실제 발화로 치환한다 analyze.ts:42.

응답 text를 JSON.parse → TurnAnalysisResult로 만들어 { result, resolvedSystemPrompt, textPrompt }를 돌려준다(프롬프트도 같이 반환 → 로그에 남기기 위함).

6. 단계 ④ 결과 표시 (V1 호스트)

host.tsx:578 onResult가 probability를 높음 🔴 / 중간 🟡 / 낮음 🟢 라벨로 바꾸고, 사유·전사·추정 발화를 줄글로 모아 setAnalysisAlert(...) 모달을 띄운다. 결과 Map(analysisResults)은 자식 컴포넌트로도 내려간다(host.tsx:1521).

7. 단계 ⑤ 영속화 — S3 + audio_analysis 세션 로그

onLogData = hooks/use-audio-analysis-logger.ts logAnalysis(). 두 군데에 나눠 저장한다.

• 오디오 → S3: :38 n턴 Blob을 combineAudioBlobsToWav()로 단일 WAV로 remux해, POST /api/audio-analysis-logs/upload-url로 presigned URL 발급(:7 최대 20MB) → 그 URL에 PUT. 키 구조는 lib/s3.ts {stage}/audio-analysis/{userId}/{logId}.{ext}.
• 메타+결과 → 세션 로그: :73 POST /api/session-logs에 role:"system", type:"audio_analysis", message(agentName·provider·model·nTurns·프롬프트·result JSON), 그리고 audioAnalysisS3Key를 저장.

// :61 — message에 분석 전모를 JSON으로 직렬화해 세션 로그 한 줄에 담는다
const message = JSON.stringify({
  agentName, provider, model, nTurns,
  systemPrompt: data.resolvedSystemPrompt,  textPrompt: data.textPrompt,
  blobCount: data.blobs.length,             result: data.result,
});

세션 로그 타입은 types/db/session-log.types.ts:26에 "audio_analysis"로, 오디오 키는 :82 audioAnalysisS3Key?로 추가돼 있다(최근 "세션 로그 전용 컬럼" 작업).

세션 로그 뷰어에서 보기

components/pages/session-log.tsx:546 "오디오 분석" 컬럼이 type === "audio_analysis" 행을 렌더한다 — 에이전트 배지, result 필드 나열, 프롬프트 <details>, 그리고 audioAnalysisS3Key가 있으면 🎵 재생 / 다운로드 버튼. 재생·다운로드는 :347 / :362에서 POST /api/audio-analysis-logs/download-url로 presigned 조회 URL을 받아 쓴다.

8. 2026-06-23 nTurns 합본 WAV 수정 기록

문제 증상은 nTurns=2인데 세션 로그의 합본 WAV가 아동 턴만 2개 들어가거나, 반대로 핑퐁 1턴만 들어가는 것이었다. 근본 원인은 실제 오디오 Blob이 있는 턴과 transcript/STT 보정 턴을 구별하는 기준이 불완전했던 것이다.

// turn-audio-selection.ts — stt_verified는 raw audio와 중복되지 않게 해석
const rawAudioIds = new Set(chatLogs
  .filter((log) => isAudioRole(log.role) && log.type === "audio")
  .map((log) => log.id));

const audioTurns = chatLogs.filter((log) => {
  if (!isAudioTurn(log)) return false;
  return !(log.type === "stt_verified" && log.relatedToLogId && rawAudioIds.has(log.relatedToLogId));
});

전체 시퀀스 (한 턴 기준)

코드 맵 — 파일별 역할 한눈에

읽을 때 주의할 함정 5가지

• 활성 에이전트는 localStorage — 서버 상태가 아니라 진행자 브라우저 1칸. 다른 PC/탭과 공유되지 않는다.
• 버퍼는 실제 Blob 기준 — getRecentBlobs(n, chatLogs, targetLogId)은 transcript만 보고 저장하지 않는다. role/time 기준으로 실제 녹음 Blob이 n개 모두 매칭되어야 한다.
• 리셋 조건 — 스텝 전환(isSessionActive=false)에는 리셋하지 않는다. chatLogs가 0일 때만. (중복 알림 버그의 원인이자 수정점)
• 너무 짧은 발화 스킵 — 공백 제거 후 2자 미만이면 분석을 건너뛰되 targeted에 기록해 다시 시도하지 않는다.
• V2엔 모달이 없다 — 세션카드는 onResult 미연결. 결과는 세션 로그에서만 확인. (2026-06-30 bb04ee93 갱신: 모달 표시용 연결은 여전히 없지만, 오인식 정정 자동 주입 목적으로는 session-card·monitor-dashboard의 onResult가 처음 연결됨 → PR 리뷰 문서)

통합된 이전 문서

아래 두 문서는 이 문서로 통합되었다. 기존 URL 호환을 위해 얇은 안내 페이지로 남긴다.

• 오디오-분석-에이전트-구현-기존구조-영향-분석.html — 기존 구조 변경/사이드 이펙트 내용은 이 문서의 데이터 모델, 런타임 진입점, 2026-06-23 수정 기록에 흡수.
• 오디오-분석-에이전트-및-아동-알림.html — 초기 기능 설명과 아동 알림 개요는 관련 도메인 문서(아동-알림-프리셋-생성관리-및-개별-토글.html) 및 이 문서에 분리 반영.