화면 공유 (host→guest) — 코드레벨 동작 흐름

개요 · 범위

치료사(호스트)가 자기 화면을 아동(게스트)에게 실시간 공유하는 기능. getDisplayMedia로 화면을 캡처해 V1 P2P(#11, connectionId="screen-share")로 전송한다.

host 전용 시작: 시작은 호스트만(role==="host"). 게스트는 수신 전용. 시그널링은 소켓, 미디어는 useWebRTC P2P(#11)를 그대로 재사용.

핸드셰이크 시퀀스

[호스트] startScreenShare → getDisplayMedia(video 제약, audio) → emit host-screen-share-start2 [게스트] handleHostScreenShareStart → webRTC.connect() → emit guest-screen-share-ready [호스트] handleGuestScreenShareReady → webRTC.connect() → addTrack(video/audio) [게스트] useWebRTC.onTrackReceived → 화면 렌더 [종료] 호스트 stopScreenShare → emit host-screen-share-stop2 → 게스트 webRTC.disconnect()

"게스트 준비 후 트랙 추가" 순서: 호스트가 stream을 먼저 잡아두고(start2), 게스트가 P2P 연결을 깔고 ready를 보내야(ready) 호스트가 트랙을 add한다. 게스트 준비 전 add하면 트랙이 유실될 수 있다.

캡처 · 해상도 제약 startScreenShare L75–152

getDisplayMedia({video: VIDEO_CONSTRAINTS, audio: true}) — 오디오 포함 시도(브라우저 미지원이면 영상만 진행, 경고).
고해상도 다운스케일: 캡처 width > 1280이면 applyConstraints(LOW_RESOLUTION_CONSTRAINTS)로 낮춤(아동 기기/대역폭 보호).
오디오 트랙 enabled는 isAudioEnabled 토글로 제어.

트랙 추가 · 자동 종료 handleGuestScreenShareReady L241

게스트 ready 수신 → webRTC.connect() → stream의 video/audio 트랙을 webRTC.addTrack(P2P 송신, onnegotiationneeded #11).
브라우저 "공유 중지" 연동: video track.onended(사용자가 브라우저 UI에서 공유 중지) → stopScreenShare() 자동 호출.
종료: 호스트 stop → cleanup(트랙 stop) + host-screen-share-stop2 → 게스트 webRTC.disconnect().

함정 · 주의

준비 후 add 순서 준수: start2 → guest ready → addTrack. 순서를 줄이면(게스트 미준비 시 add) 화면이 안 뜸.
connectionId="screen-share" 격리: 세션 릴레이(session-audio)·미디어(host-audio)와 같은 useWebRTC지만 connectionId가 달라 시그널링이 분리. connectionId 누락 시 다른 P2P와 이벤트 교차(#11).
오디오 미지원 브라우저: getDisplayMedia audio가 없을 수 있음 → 영상만 진행. includeAudio 기대 시 분기 필요.
고해상도 부하: 1280 초과는 다운스케일하지만, 아동 기기 동시 디코드 부하 고려(영상 끊김 bug와 동일 맥락).
track.onended 자동 종료: 브라우저 UI 공유 중지와 앱 stop이 둘 다 cleanup을 부른다 — 중복 호출 idempotency 확인.

파일 · 라인 레퍼런스

파일/심볼	역할
use-screen-share.ts (startScreenShare L75, handleGuestScreenShareReady L241)	화면 공유 본체
use-web-rtc.ts (connectionId screen-share)	P2P 전송(#11)
components/sections/share-screen.tsx	화면 공유 UI

화면 공유 (host→guest) — 코드레벨 동작 흐름 P2코드레벨