mediasoup 클라이언트 (producer/consumer·simulcast) — 코드레벨 동작 흐름 P1코드레벨

개요 · 범위

V2(SFU) 클라이언트의 미디어 송수신을 담당하는 mediasoup-client 래퍼 훅 3종. 게스트는 producer로 카메라/마이크/AI 음성을 SFU에 올리고, 모니터(카드뷰/포커스뷰)는 consumer로 받아 본다. 서버측은 #2 SFU 서버.

Device 초기화 use-mediasoup-device.ts:29–48

const device = new Device();
await device.load({ routerRtpCapabilities: rtpCapabilities });  // JOIN_ROOM 응답의 rtpCapabilities

JOIN_ROOM(#2) 콜백으로 받은 router의 rtpCapabilities로 Device를 로드해야 send/recv transport·produce/consume가 가능. 이후 createSendTransport/createRecvTransport는 서버 CREATE_TRANSPORT로 transportOptions를 받아 생성.

송출(Producer) use-mediasoup-producer.ts

1. 1Device load → createSendTransport. transport connect 이벤트 → 서버 CONNECT_TRANSPORT, produce 이벤트 → 서버 PRODUCE(producerId 반환).
2. 2스트림별 transport.produce({track, appData}):

카메라 simulcast 인코딩 L415–419

encodings: [
  { maxBitrate: 100000, scaleResolutionDownBy: 4 },  // L0 저화질(≈180p 썸네일)
  { maxBitrate: 300000, scaleResolutionDownBy: 2 },  // L1 중화질(≈360p)
  { maxBitrate: 900000 },                          // L2 고화질(원본 ≈720p)
]

재연결: sendTransport connectionstatechange="disconnected" → MAX_RECONNECT_ATTEMPTS까지 지연 재시도. getStats로 RTT/대역폭/패킷손실 주기 수집(모니터링).

수신(Consumer) use-mediasoup-consumer.ts

1. 1Device load → createRecvTransport.
2. 2새 producer 통지(NEW_PRODUCER) 또는 JOIN_ROOM의 existingProducers → consume(producerId): 서버 CONSUME로 consumerOptions 수신 → recvTransport.consume(options) → RESUME_CONSUMER.
3. 3consume 직후 기본 spatialLayer 0(L304) — 저화질 썸네일로 시작(대역폭 절약).
4. 4track을 appData.type별로 peerStream에 분리 저장: videoStream / audioStream(mic) / aiAudioStream(AI). 각각 new MediaStream([consumer.track]).
5. 5consumer-closed 통지 시 해당 track 제거(카드뷰 정확한 cleanup).

레이어 전환 setConsumerLayer L717 / video-expansion

setConsumerLayer(peerId, spatialLayer)  →  emit SET_CONSUMER_LAYERS

포커스뷰/확대 시 use-video-expansion이 setConsumerLayer(peerId, 2)로 고화질(L2) 요청. 축소하면 다시 저레이어로. 즉 "보이는 것만 고화질"로 끌어올리는 selective forwarding.

재연결 · 트랙 교체

• recvTransport 재생성(recreateRecvTransport): 기존 peerStream 트랙 stop 후 새 transport로 재consume.
• 같은 type 트랙 교체: 재consume 시 같은 appData.type의 기존 트랙을 먼저 stop·remove한 뒤 새 트랙 추가(재연결 시 중복 트랙 방지).
• producer측도 transport disconnect 시 재연결(위).

함정 · 주의

• consume는 항상 paused→resume + 기본 layer 0: resume 누락 또는 layer 미상향 시 "썸네일만 보이고 확대해도 흐림". 확대 경로(video-expansion)가 layer 2를 올려야 선명.
• appData.type이 트랙 구분의 전부: camera-video/mic-audio/ai-audio. type 누락/오타 시 스트림이 엉뚱한 버킷(videoStream/audioStream/aiAudioStream)에 들어감.
• 트랙 clone(producer): 카메라는 clone해서 produce → 원본 로컬 스트림에 영향 없음. clone stop 누락 시 누수.
• simulcast 송신 부하는 아동 기기: 3레이어 인코딩이 약한 기기에 부담 → 끊김. 필요 시 high 레이어 비활성 검토(bug 문서).
• 재연결 트랙 교체 가드: 같은 type 트랙 정리 없이 add하면 유령 트랙으로 화면/소리 중복.

파일 · 라인 레퍼런스

관련 문서

• 코드레벨 문서화 로드맵 (#10 본 문서)
• SFU 서버 (#2, 서버측 짝)
• 아동측 영상·오디오 끊김 — simulcast 계획
• 카드뷰 세션 변천사