아키텍처 시각화 · 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. 한 장 구조도
두 SFU는 서로를 모른다. 둘을 잇는 유일한 지점이 아동 브라우저이고, 이 문서에서 말하는 "릴레이"는 아동 기기 안에서 LiveKit 수신 트랙을 mediasoup 송신 트랙으로 다시 올리는 구간이다.
2. 트랙별 경로
| 트랙 | 아동 → LiveKit | LiveKit → 아동 | 아동 → mediasoup | mediasoup에서 받는 쪽 |
|---|---|---|---|---|
| 아동 마이크 | ✓ 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. 마이크 분기 상세
- 원본 마이크 획득:
localMedia.audioStream을 AI 세션에externalMicStream으로 넘긴다(use-guest-page-session.ts:534). - LiveKit 송출: LiveKit 런타임은 SDK의
LocalAudioTrack에 오디오 처리기(setProcessor)를 붙여 publish한다. - 처리된 트랙 분기: 처리기가 만든 트랙을
onProcessedMicrophoneStream으로 돌려주면,createRecordingMicRelayArtifacts가 relayStream을 만든다(mic-relay-stream.ts,use-ai-session.ts:2119). - 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을 직접 구독: 모니터가 LiveKit 방에 수신 전용으로 들어가 AI 음성을 받는다. 아동 업링크에서
ai-audio가 빠지고, 모니터 AI 음성이 아동 회선과 무관해진다. 대신 모니터 쪽에 LiveKit 연결이 추가되고, LiveKit 방 참가자 수가 모니터 수만큼 는다. - 서버 측 브리지: 서버에서 LiveKit 트랙을 mediasoup으로 넘긴다(LiveKit Egress·서버 참가자, 또는 Agent가 직접 mediasoup에 송출). 모니터 코드는 그대로 두고 아동 기기 부담만 줄인다. 서버 구현·운영 비용이 늘어난다.
- 녹음 경로 함께 이전 필요: 녹음 서버도 mediasoup의
ai-audio·mic-audio를 소비한다(media-handlers.ts:154,session-relay-handlers.ts:1392). 릴레이를 없애려면 녹음의 AI 음성 공급원도 함께 바꿔야 한다. - 마이크 중복 업로드 제거: 모니터·녹음이 아동 마이크를 LiveKit에서 받으면 mediasoup
mic-audio도 뺄 수 있다. 이 경우 mediasoup에는 카메라만 남는다.
네이티브 앱으로 바꾸면?
- 대역폭·연결 수·재인코딩: 구조가 같으면 그대로다. 네트워크 이점은 없다.
- CPU·전력·저전력 모드: 일부 이점이 있다(하드웨어 인코더 선택, Web Audio·rAF 제약 제거).
- 오히려 어려워짐: 브라우저에서는 LiveKit 수신 트랙을 mediasoup
produce()에 넘기기만 하면 되지만, 네이티브에서는 오디오 프레임을 꺼내 커스텀 소스로 넣어야 한다. LiveKit SDK와 libmediasoupclient가 각자 libwebrtc를 포함해 한 앱에서 충돌할 위험도 크다. WebView + 네이티브 LiveKit 하이브리드에서는 네이티브 AI 음성을 WebView의 mediasoup으로 넘길 표준 방법이 없다.
순서: 릴레이 제거 → (가능하면) 마이크 중복 제거 → 네이티브·하이브리드 검토. 릴레이 제거는 웹에서 바로 업링크를 줄이는 개선이면서, 아동 앱이 LiveKit 하나만 다루게 만들어 네이티브 전환의 가장 큰 위험(mediasoup 네이티브 연동)을 없애는 선행 조건이다.
근거와 검증 범위
- PPI
develop658debb9 기준 코드:apps/web/entities/guest-page-session/model/use-guest-page-session.ts(516, 534, 1086~1095),apps/web/hooks/mediasoup/use-mediasoup-producer.ts(749, 834, 945),apps/web/entities/guest-session/model/use-ai-session.ts(1908, 2119, 2385),apps/web/entities/guest-session/lib/mic-relay-stream.ts,apps/web/lib/voice-agent/livekit-client-session.ts(4190~4202),apps/web/hooks/mediasoup/use-mediasoup-consumer.ts(789~872),apps/socket/src/sfu-socket/handlers/media-handlers.ts(154),apps/socket/src/sfu-socket/handlers/session-relay-handlers.ts(1392). - 게스트 페이지 세션 훅에서는 mediasoup consumer를 찾지 못했다. 치료사 화면 공유를 아동이 받는 경로는 이 문서 범위에서 확인하지 않았다.
- 트랙별 실제 비트레이트와 업링크 점유율은 측정하지 않았다. 개선 후보의 비용·효과는 설계 검토 전 단계의 추정이다.
관련 PPI 문서
- LiveKit 음성 에이전트 흐름 & 두 SFU 구조 (시각화): 세션 발급·dispatch·두 SFU 브리지의 전체 흐름(2026-08 기준).
- Typecast TTS → LiveKit Agent → 게스트 → 모니터 오디오 흐름: AI 음성이 Agent에서 모니터까지 가는 경로.
- 녹음 파이프라인 — mediasoup · ffmpeg · ogg · S3: 릴레이된 트랙을 소비하는 녹음 경로.
- 아동 화면 모바일 제공 방식 비교 — 웹 · PWA · 하이브리드 · 네이티브: 네이티브 전환 검토와 네트워크 개선 방향.
- PPI 업링크 stall 웹 대처방안: 아동 업링크 저하 대응.