아키텍처 시각화 · 2026-11-19 · 기준 PPI develop 658debb9

아동 측 WebRTC 릴레이 구조 — LiveKit · mediasoup 두 SFU

마지막 업데이트 2026-11-19

대상: 아동 기기의 업링크 부담, 모니터·녹음 음성 끊김 원인, 네이티브 앱 전환 시 영향을 판단하려는 개발자

아동 브라우저는 원격 WebRTC 서버 두 곳에 동시에 연결된다. LiveKit SFU는 AI(핑퐁이)와의 대화용이고, mediasoup SFU는 치료사·모니터·녹음 서버로 수업 미디어를 보내는 용도다. 두 SFU는 서로 연결되어 있지 않다.

그래서 AI 음성은 아동 기기가 LiveKit에서 받은 것을 mediasoup으로 다시 올려 보낸다(릴레이). 마이크도 LiveKit과 mediasoup으로 두 번 올라간다. 모니터와 녹음 서버가 듣는 AI 음성은 전부 아동 기기의 업링크에 달려 있다.

1. 한 장 구조도

LiveKit 경로 (AI 대화)mediasoup 경로 (수업 중계)아동 기기 릴레이 구간

두 SFU는 서로를 모른다. 둘을 잇는 유일한 지점이 아동 브라우저이고, 이 문서에서 말하는 "릴레이"는 아동 기기 안에서 LiveKit 수신 트랙을 mediasoup 송신 트랙으로 다시 올리는 구간이다.

2. 트랙별 경로

트랙아동 → LiveKitLiveKit → 아동아동 → mediasoupmediasoup에서 받는 쪽
아동 마이크✓ publishTrack(localAudioTrack, {dtx:false}) (livekit-client-session.ts:4190)—✓ mic-audio (처리된 relayStream)모니터, 녹음 서버
AI 음성—✓ Agent의 TTS를 subscribe (onRemoteAudioStream → setAiAudioStream, use-ai-session.ts:2385)✓ ai-audio (복제해서 재송출)모니터, 녹음 서버(replaceAiConsumer)
카메라——✓ camera-video (단일 레이어, simulcast 없음)모니터

모니터는 LiveKit 방에 들어가지 않는다. 그래서 모니터 수가 늘어도 LiveKit 방의 참가자 수는 늘지 않는다. 대신 모니터와 녹음이 듣는 AI 음성은 아동 기기의 수신·재송출 상태에 전적으로 의존한다.

Realtime·TTS 런타임에서는 LiveKit 대신 OpenAI Realtime과 직접 RTCPeerConnection을 맺는다(use-ai-session.ts:1908). 이때도 원격 연결은 두 곳(OpenAI + mediasoup)이고, AI 음성 릴레이 구조는 같다.

3. 마이크 분기 상세

  1. 원본 마이크 획득: localMedia.audioStream을 AI 세션에 externalMicStream으로 넘긴다(use-guest-page-session.ts:534).
  2. LiveKit 송출: LiveKit 런타임은 SDK의 LocalAudioTrack에 오디오 처리기(setProcessor)를 붙여 publish한다.
  3. 처리된 트랙 분기: 처리기가 만든 트랙을 onProcessedMicrophoneStream으로 돌려주면, createRecordingMicRelayArtifacts가 relayStream을 만든다(mic-relay-stream.ts, use-ai-session.ts:2119).
  4. mediasoup 송출: micStream: aiSession.guestMicStream ?? localMedia.audioStream으로 relayStream을 우선 쓰고, 없으면 원본 마이크를 쓴다(use-guest-page-session.ts:1093). 치료사가 음소거하면 micEnabled: !isHostRelayMuted로 꺼진다.

즉 모니터·녹음이 듣는 아동 목소리는 AI가 들은 것과 같은 처리 체인을 거친 소리다. 같은 소리가 두 번, 서로 다른 연결로 인코딩되어 올라간다.

4. 이 구조의 영향

영향설명
아동 업링크 부담업로드: 마이크(LiveKit) + 마이크(mediasoup) + AI 음성(mediasoup) + 카메라(mediasoup). 오디오는 Opus라 수십 kbps 수준이지만 연결 두 개의 ICE·DTLS·RTCP 오버헤드와 인코더 부하가 더해진다. 업링크가 약한 회선에서 가장 먼저 무너지는 곳이다.
모니터·녹음 음성이 아동 회선에 의존아동 업링크나 mediasoup 경로만 막히면 AI와의 대화는 정상인데 모니터와 녹음에서는 AI 음성이 끊긴다. 반대로 LiveKit만 끊기면 대화는 멈췄는데 모니터 영상은 정상이다.
AI 음성 품질·지연Agent → LiveKit → 아동 디코딩 → 재인코딩 → mediasoup → 모니터. 인코딩 손실이 한 번 더 생기고 지연이 늘어난다. 아동 기기의 지터버퍼 상태도 그대로 전달된다.
아동 기기 CPU·오디오 자원WebRTC 연결 2개, 오디오 인코더 3개(LiveKit 마이크, mediasoup 마이크, AI 음성), 비디오 인코더 1개. iOS는 덕킹 회피용 기기 내부 loopback 연결까지 더해진다(webrtc-audio-loopback.ts).
진단 난이도증상이 어느 연결에서 나왔는지에 따라 원인 분석 경로가 달라진다. ICE_DIAGNOSTIC_SUMMARY의 source(LiveKit / mediasoup)로 먼저 구분해야 한다.

5. 장애 시나리오별 증상

어디가 끊겼나아동이 겪는 것치료사·모니터가 보는 것녹음
LiveKit만AI가 대답하지 않음영상·아동 목소리 정상, AI 음성 없음AI 음성 없음
mediasoup만AI 대화 정상영상·소리 모두 멈춤 ("연결 불안정")끊김
아동 업링크 전체 약화AI가 늦게 듣거나 못 들음영상 화질 하락 → 소리 끊김끊김 가능
아동 기기 AI 음성 재생 정지AI 무음AI 무음 (같은 트랙을 복제해서 올리므로)AI 무음

마지막 행이 릴레이 구조의 특징이다. 아동 기기 안의 수신 문제가 모니터와 녹음에도 그대로 복제되므로, "모니터에서 AI 무음"만으로는 Agent 문제인지 아동 기기 문제인지 구분할 수 없다.

6. 개선 방향과 네이티브 앱과의 관계

릴레이를 없애는 후보

네이티브 앱으로 바꾸면?

순서: 릴레이 제거 → (가능하면) 마이크 중복 제거 → 네이티브·하이브리드 검토. 릴레이 제거는 웹에서 바로 업링크를 줄이는 개선이면서, 아동 앱이 LiveKit 하나만 다루게 만들어 네이티브 전환의 가장 큰 위험(mediasoup 네이티브 연동)을 없애는 선행 조건이다.

근거와 검증 범위

관련 PPI 문서