OpenAI Realtime 세션 매니저 — 코드레벨 동작 흐름 P0코드레벨

개요 · 범위

useSessionManager는 브라우저와 OpenAI Realtime API 사이의 WebRTC 세션 1개를 통째로 관리하는 훅이다. 마이크 캡처 → 오디오 가공 → OpenAI 송출, OpenAI 음성 수신 → 스피커 재생, 데이터채널 이벤트(전사·발화 상태) 처리, 끼어들기/침묵/종료까지 담당한다.

아키텍처 한눈에

SDP를 서버로 프록시하는 이유: OPENAI_API_KEY를 브라우저에 노출하지 않기 위해. 클라이언트는 offer SDP만 보내고, Next API 라우트가 키를 붙여 OpenAI에 중계한 뒤 answer SDP를 돌려준다. 세션 instruction/voice/VAD 등 민감·정책 설정도 서버에서 조립된다.

진입점 · 시그니처

훅 옵션 (UseSessionManagerProps, L36–52)

StartSessionParams (L54–67) · 반환값

startSession()는 { dataChannel, outputAudioStream, inputAudioStream }을 반환한다. outputAudioStream이 곧 핑퐁이 음성 스트림이며, 게스트 릴레이가 이를 호스트에게 그대로 add한다.

startSession() 흐름 (L665–978)

1. 1동시성 가드 진입. requestingActivityIdRef로 같은/다른 activity 재요청을 구분(로그만). 실제 무효화는 아래 requestId로 처리.
2. 2세션 파라미터를 ref에 반영. activityRef, turnDetectionRef.interrupt_response, autoFinishConfig, startMent, autoTransition/fallback 활성화.
3. 3RTCPeerConnection 생성(rtcConfigurationRef). WebRTC 모니터링 상태추적·상태감시 시작.
4. 4스피커(audioElement) 준비. createAudioElement()로 <audio autoplay> 생성 + setSinkId로 출력 장치 라우팅. pause/error/playing/ended 리스너로 재생 이상 추적.
5. 5수신 트랙 바인딩. connection.ontrack = e => audioElement.srcObject = e.streams[0] (핑퐁이 음성 재생).
6. 6마이크 스트림 구성. createMediaStream() → 내장 마이크면 volumeAmplifier, 항상 audioProcessingChain 적용 → 각 트랙 enabled=enableMicrophone 후 connection.addTrack. audioProcessingChain.startProcessing() 시작.
7. 7데이터채널 생성. createDataChannel("oai-events") + message/open 리스너. (open 시 isActive=true)
8. 8세션 컨텍스트 조립. avatar/subAvatars/user 조회, voice 결정(avatar.voice || "sage").
9. 9requestId 발급. requestId=`${Date.now()}-${Math.random()}` → tokenRequestIdRef에 저장(최신 요청 식별).
10. 10SDP 협상. createOffer→setLocalDescription → createSession(offer.sdp,...)로 answer SDP 수신.
11. 11최신 요청 검증. tokenRequestIdRef !== requestId면 더 새 요청이 시작된 것 → throw START_FAILED(이 결과 폐기).
12. 12연결 확정. setRemoteDescription(answer) → peerConnectionRef 저장 → audioStream 도착까지 100ms 폴링 대기(isActiveRef && audioStream).
13. 13후속 시작. 볼륨 모니터링·소켓 증폭상태 콜백·STT 폴백·트랙/상태 모니터링 시작. autoTransition이면 AUTO_START_MESSAGE("대화시작") 또는 startMent 송신.

세션 생성 (SDP 프록시) createSession → /api/realtime/call → createCall

클라이언트 createSession()(use-session-manager.ts:1036)은 10초 AbortController 타임아웃으로 /api/realtime/call에 POST한다. 라우트(app/api/realtime/call/route.ts)는 createCall()(lib/openai-create-call.ts)을 호출하고, 여기서 실제 OpenAI 요청·세션 config 조립·재시도가 일어난다.

세션 config 구조 (openai-create-call.ts:84–103)

const sessionConfig = {
  type: "realtime",
  model: resolvedModel,            // 모델 버전 매핑(아래)
  instructions: finalInstruction,  // 변수치환된 프롬프트(prompt/preset/user vars)
  audio: {
    input: {
      transcription: { model: "gpt-4o-transcribe", language: "ko" },
      noise_reduction: { type: inputAudioNoiseReduction },  // 기본 far_field
      turn_detection: turnDetection,
    },
    output: { voice: voice },      // avatar.voice || "sage"
  },
};

모델 버전 매핑 (L27–30, packages/shared constants)

turn_detection (VAD) (L43–59)

• 기본: server_vad · threshold 0.35 · prefix_padding 500ms · silence_duration silenceDurationMs ?? 2000 · create_response true · interrupt_response false
• activity.semanticVad가 "none"이 아니면 → semantic_vad로 교체(eagerness=low|medium|high|auto). server_vad의 threshold/padding/silence는 무시되고 create/interrupt만 승계.

재시도 · 타임아웃

오디오 파이프라인

입력(마이크 → OpenAI) createMediaStream, L996–1034

• audioDeviceIdOrStream이 이미 MediaStream이면 getUserMedia 생략(외부에서 준비한 스트림 사용).
• 증폭기는 내장(built-in) 마이크일 때만 적용(!audioInputDevice || isBuiltInDevice(...)). 오디오 처리 체인은 항상 적용(초기화가 startProcessing 전제).
• 상세는 별도 문서 → 로드맵 #7(오디오 처리 체인), #17(볼륨 증폭기).

출력(OpenAI → 스피커)

• connection.ontrack의 event.streams[0]을 audioElement.srcObject로 연결. 같은 스트림이 outputAudioStream으로 반환되어 릴레이/립싱크/노이즈가드가 공유한다.
• 출력 장치 선택은 createAudioElement의 setSinkId(미지원 브라우저는 무시).

데이터채널 이벤트 처리 handleDataChannelMessage, L332–522

파생 상태 · 끼어들기 제어

발화 상태

• isPeerTalking(핑퐁이): output_audio_buffer.started/stopped로 직접 토글.
• isUserTalking(아동): isInputAudioBufferPlaying || sttFallback.isPlaying || isTextareaTyping 합성(L1254).

마이크 입력 게이팅 (L1233–1237)

// 세 조건이 모두 만족해야 마이크 트랙 enabled
audioInputEnabled = microphoneEnabled && !autoFinishSilence && !interruptBlocked;

응답 취소 cancelResponse, L230

response.cancel + output_audio_buffer.clear 두 메시지를 전송. sendMessage에서 핑퐁이 발화 중 텍스트 입력 시, after-child-speech 자동종료 시 호출된다.

침묵 타이머 · WebRTC 연결 처리

• 15초 무음 타이머(startSilenceTimer, L319): 세션 활성+입력 가능 상태에서 발화가 없으면 15초 뒤 onNoGuestAudio(). speech/output 이벤트마다 해제·재설정.
• 연결 상태(handleWebRTCConnectionStateChange, L160): disconnected→즉시 onWebRTCDisconnected() + 5초 타이머 후 onWebRTCFailed(). failed→즉시 onWebRTCFailed(). connected→타이머 해제.

종료 (stopSession) 정리 순서 L592–663

1. dataChannel 리스너 제거 + close
2. peerConnection close
3. mediaStream 트랙 stop
4. audioElement 정리(srcObject 트랙 stop, 리스너 제거)
5. 각종 ref/타이머 초기화 + webrtcMonitoring 중지(closed 송출)
6. sttFallback·volumeAmplifier·audioProcessingChain·autoFinish 정리
7. isActive=false, requestId/requestingActivityId 리셋(재시도 허용)

통합 서브 훅 (별도 문서 예정)

함정 · 주의

• ref ↔ state 이중화: 콜백/이벤트 핸들러가 최신 값을 봐야 해 거의 모든 제어값이 state + ref 쌍으로 존재(isActive/isActiveRef, audioInputEnabled/audioInputEnabledRef 등). 수정 시 양쪽 동기화 필수.
• noise_reduction은 초기 far_field 고정: createSession 호출부(L1057)가 "far_field"를 하드코딩 전송. 런타임 변경은 updateInputAudioNoiseReduction/toggleNoiseReduction의 session.update로만.
• audioStream 폴링 대기: ontrack 도착 전까지 100ms 간격 폴링. ontrack이 끝내 안 오면 무한 대기 가능(상위 타임아웃/연결실패 콜백에 의존).
• V1/V2 분기: 본 훅은 V1·prompt-test 전용. V2는 use-ai-session.ts. 동일 버그를 두 곳에 각각 고쳐야 할 수 있음.
• 최신요청 무효화: 같은 activity 빠른 재시작 시 tokenRequestIdRef로 이전 응답을 폐기. 이 가드를 건드리면 race로 유령 세션이 생길 수 있음.

파일 · 라인 레퍼런스

관련 문서

• 코드레벨 문서화 로드맵 (#1 본 문서)
• OpenAI Realtime 세션 시작 실패 원인 분석
• gpt-realtime WebRTC 정적 노이즈 원인 분석
• 아바타 RMS 립싱크 코드레벨 동작흐름 (outputAudioStream 소비처)