개요 · 범위
치료사(호스트)가 자기 화면을 아동(게스트)에게 실시간 공유하는 기능. 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 |