마지막 업데이트 2026-10-23
기존 진행자 웹을 Electron 창에 그대로 띄우고, 웹에서 일어난 이벤트(수업 진입·종료)를 앱에 전달해 앱 창 화면 녹화를 자동으로 시작·종료합니다. 녹화 로직은 이미 있는 /monitor-recorder를 재사용하고, 앱은 “화면 선택”과 “창 수명”만 대신 맡습니다.
getDisplayMedia·setSinkId·MediaRecorder(webm)·팝업+BroadcastChannel은 macOS WKWebView(Tauri·Wails)에서 동작이 보장되지 않습니다. 웹 쪽 변경은 브리지 어댑터 1개 + 이벤트 발행 지점 몇 곳 + 녹화 화면 선택 분기로 작고, 일반 브라우저 동작은 그대로 유지됩니다.
확인2026-10-23 PPI checkout(PPI-1376 브랜치) 정적 확인 · 추정Electron 동작 중 PoC로 검증이 필요한 항목 · 신규아직 존재하지 않는 제안 파일·API
진행자 페이지(/monitor-dashboard/[group], /monitor-dashboard/[group]/[roomId], /monitor-recorder/[group])가 실제로 쓰는 API를 기준으로 판단했습니다.
| API | 사용 위치 확인 | Electron | Tauri (Mac WKWebView / Win WebView2) |
|---|---|---|---|
| WebRTC · mediasoup · Socket.io | 모니터 전반 | ✅ | ✅ |
getDisplayMedia + displaySurface === "browser" 검사 | features/monitor-recording/model/use-video-crop-recorder.ts | ⚠️ 앱에서는 탭이 아니라 창이 잡힘 → 분기 필요 | ❌ |
MediaRecorder (vp9/opus webm) | features/monitor-recording/model/chunk-recorder.ts | ✅ | ⚠️ Mac은 mp4 위주 |
setSinkId | shared/ui/meet-video.tsx 외 | ✅ | ⚠️ Mac 불안정 |
window.open 팝업 + BroadcastChannel | features/monitor-recording/model/use-monitor-recording-beacon.ts | ✅ (setWindowOpenHandler로 같은 session 창 생성) | ⚠️ 팝업 직접 구현 |
iron-session 쿠키 (sameSite: lax, prod secure) | lib/session-options.ts | ✅ 원격 https URL 로드 시 그대로 | ✅ |
앱이 커지는 비용(설치본 약 100MB 이상)은 있지만, 웹과 같은 Chromium 엔진이라 “브라우저에서 되던 것이 앱에서도 된다”는 전제를 지킬 수 있다는 점이 결정적입니다.
window.ppiApp이 있을 때만 앱 경로를 탑니다. 없으면 지금과 같은 버튼·탭 선택 녹화를 그대로 씁니다.nodeIntegration: false, contextIsolation: true, sandbox: true. preload는 타입이 정해진 함수 몇 개만 노출하고, main은 보낸 쪽 origin을 검사합니다.version·capabilities로 협상해 오래된 앱에서도 웹이 깨지지 않게 합니다.┌──────────────────────── ppi-monitor-app (Electron) ────────────────────────┐
│ main process │
│ ├ windows.ts 메인 창(진행자 웹) · 녹화 창(숨김) 생성·수명 관리 │
│ ├ bridge.ts ipcMain: 웹 이벤트 수신 → origin 검사 → 정책 실행 │
│ ├ capture.ts setDisplayMediaRequestHandler → 메인 창 소스 자동 지정 │
│ ├ permissions.ts 미디어·화면 권한: PPI origin만 허용, macOS TCC 상태 확인 │
│ ├ navigation.ts 허용 origin 밖 이동 차단, 외부 링크 → shell.openExternal │
│ ├ tray.ts 녹화 상태 표시(●REC), 수동 중지, 종료 │
│ └ updater.ts electron-updater (stage별 채널) │
│ preload contextBridge → window.ppiApp { version, emit, on, … } │
└───────────────┬───────────────────────────────────────────┬─────────────────┘
│ 메인 창 (BrowserWindow, partition A) │ 녹화 창 (hidden, 같은 partition A)
▼ ▼
https://<ppi>/monitor-dashboard/{group} https://<ppi>/monitor-recorder/{group}?recordingId=…
├ 수업 진입·종료 → ppiApp.emit(…) ├ getDisplayMedia → (앱이 메인 창 소스 지정)
└ useMonitorRecordingBeacon ├ 카드 영역 크롭 영상 + 아동별 오디오
└ BroadcastChannel ◀──────────────────────┘ └ 업로드(presigned PUT → S3)
/monitor-recorder 그대로입니다. 앱이 하는 일은 ① 그 창을 숨김·백그라운드 무제한으로 띄우고 ② 화면 선택 창 없이 메인 창을 캡처 대상으로 넘기는 것뿐입니다. 아동별 오디오 믹싱, 크롭, 업로드 로직은 중복 구현하지 않습니다.ppi-monitor-app/
├ src/
│ ├ main/ index.ts · windows.ts · bridge.ts · capture.ts
│ │ permissions.ts · navigation.ts · tray.ts · updater.ts · config.ts
│ ├ preload/ index.ts # contextBridge 노출
│ └ shared/ bridge-contract.ts # 이벤트 이름·payload 타입·version
├ build/ entitlements.mac.plist · icons
├ electron-builder.yml # dmg(Mac) · nsis(Win) · publish(S3)
└ package.json # electron-vite + electron-builder
빌드 도구는 electron-vite(개발)와 electron-builder(패키징·서명·업데이트)를 제안합니다. Electron Forge도 가능하지만 S3 기반 자동 업데이트·공증 설정 예시가 electron-builder 쪽이 많습니다.
// window.ppiApp — 앱에서만 존재. 브라우저에서는 undefined
interface PpiAppBridge {
version: 1;
capabilities: Array<"auto-capture" | "recording-control" | "tray">;
emit<E extends WebToAppEvent["type"]>(type: E, payload: PayloadOf<E>): void;
on<E extends AppToWebEvent["type"]>(type: E, cb: (p: PayloadOf<E>) => void): () => void;
}
type WebToAppEvent =
| { type: "monitor:group-opened"; payload: { groupId: string } }
| { type: "monitor:room-opened"; payload: { groupId: string; roomId: string } }
| { type: "lesson:started"; payload: { groupId: string; roomId: string } }
| { type: "lesson:completed"; payload: MonitorLessonCompletion } // 기존 타입 재사용
| { type: "lesson:all-ended"; payload: { groupId: string } }
| { type: "recording:state"; payload: { recordingId: string; state: RecState } };
type AppToWebEvent =
| { type: "recording:stop-request"; payload: { reason: "user" | "app-quit" | "tcc-denied" } }
| { type: "app:capture-insets"; payload: { top: number; left: number; scale: number } };
lesson:completed payload는 기존 MonitorLessonCompletion과 같습니다. 현재 shared/lib/monitor-lesson-completion-channel.ts의 publishMonitorLessonCompletion이 BroadcastChannel로 보내는 지점에서 앱으로도 함께 보내면 됩니다. 확인event.senderFrame.url의 origin을 허용 목록(stage별 PPI 도메인)과 비교하고, payload를 다시 검증합니다(웹의 parseMonitorLessonCompletion과 같은 규칙).apps/web/shared/lib/desktop-bridge/ 신규)에 두고 앱 저장소가 복사합니다. 버전이 바뀌면 version을 올리고, 웹은 capabilities에 있는 기능만 사용합니다.| 파일 | 변경 |
|---|---|
shared/lib/desktop-bridge/ | getDesktopBridge()(없으면 null), 타입, emitToDesktop() no-op 래퍼 |
app/monitor-dashboard/[group]/page.tsx | 진입 시 monitor:group-opened |
app/monitor-dashboard/[group]/[roomId]/page.tsx | 진입 시 monitor:room-opened |
shared/lib/monitor-lesson-completion-channel.ts | BroadcastChannel 발행과 함께 lesson:completed |
features/monitor-recording/model/use-monitor-recording-beacon.ts | 앱이면 정책에 따라 openRecorder를 자동 호출(버튼 없이) |
features/monitor-recording/model/use-video-crop-recorder.ts | 앱이면 displaySurface !== "browser" 거부를 건너뛰고 app:capture-insets로 크롭 좌표 보정 |
① 진행자 로그인 → 메인 창에서 /monitor-dashboard/{group}
② 웹: 시작 조건 충족(정책: §08) → openRecorder() → window.open(/monitor-recorder/…)
③ main: setWindowOpenHandler가 /monitor-recorder 를 가로챔
→ BrowserWindow({ show:false, webPreferences:{ partition:A,
backgroundThrottling:false, autoplayPolicy:"no-user-gesture-required" } })
④ 녹화 창: getDisplayMedia() 호출
→ main: session.setDisplayMediaRequestHandler
desktopCapturer.getSources({types:["window"]})
에서 mainWindow.getMediaSourceId() 와 같은 소스를 callback({ video })
→ 선택 창 없이 메인 창 영상 트랙 획득
⑤ 녹화 창: 기존 로직 그대로 — 크롭 영상 + room별 아동 오디오(mediasoup 수신) 녹화
→ recording:state 를 앱에 보고 → 트레이 ●REC 표시
⑥ 종료: lesson:all-ended / 30분 한도 / 트레이 중지 / 앱 종료 요청
→ 녹화 창이 finalize·업로드 → recording:state=done → main이 녹화 창 닫음
not-browser-tab으로 거부됩니다. 앱에서는 선택 단계 자체가 없습니다.AudioContext는 지금 클릭 핸들러 안에서 만들어야 합니다(use-monitor-recording-session.ts:480 주석). 앱은 autoplayPolicy로 이 제약을 풉니다.backgroundThrottling: false로 canvas 크롭 타이머가 느려지지 않습니다.window.open("", name)으로 핸들을 다시 찾는 우회가 단순해집니다(main이 창을 recordingId로 관리).setDisplayMediaRequestHandler가 불리는지 확인되지 않았습니다. 막히면 대안: 녹화 창에서 getUserMedia({ video: { mandatory: { chromeMediaSource: "desktop", chromeMediaSourceId } } })로 받습니다(웹에 분기 1개 추가).useSystemPicker는 쓰지 않음 — 켜면 macOS 시스템 선택 창이 우선되어 handler가 호출되지 않습니다.getContentBounds()와 getBounds()의 차이와 배율을 app:capture-insets로 보내 크롭을 보정합니다.| 항목 | 설계 |
|---|---|
| 렌더러 격리 | contextIsolation·sandbox on, nodeIntegration off. preload는 emit/on/version/capabilities만 노출 |
| 이벤트 출처 | main에서 senderFrame.url origin 허용 목록 검사. 허용 외 origin(외부 링크·채널톡 등)의 이벤트는 무시 |
| 탐색 제한 | will-navigate로 PPI origin 밖 이동 차단. _blank·채널톡 링크는 shell.openExternal로 기본 브라우저에서 열기 |
| 미디어 권한 | setPermissionRequestHandler/setPermissionCheckHandler: PPI origin의 media·display-capture만 허용 |
| macOS TCC | Info.plist NSMicrophoneUsageDescription·NSCameraUsageDescription, Hardened Runtime entitlements. 화면 기록 권한은 systemPreferences.getMediaAccessStatus("screen")로 확인하고, 미허용이면 설정 화면 안내(허용 후 앱 재시작 필요) |
| 녹화 고지 | 아동 화면·음성이 녹화되므로 트레이·창 제목에 ●REC 상시 표시. 자동 시작이라도 진행자가 녹화 중임을 항상 알 수 있어야 함 |
config.ts로 고정합니다. 개발 빌드에서만 URL 변경 메뉴를 둡니다.before-quit는 recording:stop-request를 보내고 업로드가 끝날 때까지 종료를 보류합니다(확인 대화상자 제공).trackEvent에 appVersion을 붙입니다. 앱/브라우저 사용자 구분과 버전별 장애 추적용입니다.| 질문 | 선택지 | 제안 |
|---|---|---|
| 자동 녹화 시작 시점 | 그룹 페이지 진입 / 첫 아동 접속 / 진행자 수업 시작 | 첫 아동 접속(빈 화면 녹화 방지). 페이지 진입은 녹화 창 준비(오디오 연결)만 |
| 종료 시점 | 모든 아동 수업 종료 / 30분 한도 / 수동 | 셋 다. 기존 “모든 아동 수업 종료 시 녹화 종료 안내”를 앱에서는 자동 종료로 |
포커스뷰([roomId]) 이동 시 | 녹화 유지 / 분할 | 유지(창 단위 캡처라 화면 전환도 그대로 기록) |
| 브라우저 녹화 경로 | 유지 / 앱 전용 | 당분간 유지. 앱에서는 버튼을 숨겨 중복 녹화 방지 |
| 지원 OS 최소 버전 | — | 채택하는 Electron 버전의 지원 범위에 맞춤(진행자 장비 조사 필요) |
| 설치·배포 대상 | 사내 배포 / 기관 배포 | 미정 — 서명·업데이트 채널 설계에 영향 |
| 단계 | 범위 | 완료 기준 |
|---|---|---|
| P0 셸 | 저장소 생성, 메인 창 로드, 권한·탐색 제한, 외부 링크 | Mac·Win에서 로그인 유지, 카드뷰·포커스뷰 영상·음성·출력 장치 선택 정상 |
| P1 브리지 | preload·bridge·계약, 웹 어댑터(no-op), 이벤트 발행 지점 | 앱에서 이벤트 수신 로그 확인, 브라우저 동작 변화 없음(기존 테스트 통과) |
| P2 캡처 PoC | 숨김 녹화 창, 자동 소스 지정, 크롭 보정 | 클릭·선택 창 없이 녹화 시작, 카드 경계 정확, 가려짐·창 크기 변경 시 유지 |
| P3 자동 정책 | 시작·종료 정책, 트레이 ●REC, 종료 가드 | 수업 1회 전체가 사람 조작 없이 녹화·업로드, 앱 종료 시 유실 없음 |
| P4 배포 | 서명·공증·인스톨러·자동 업데이트 | 깨끗한 Mac·Win에서 설치→TCC 허용→업데이트까지 통과 |
PPI 웹 변경은 repository 규칙에 따라 brainstorming 설계 승인 → code-quality-guardian baseline → 구현 → guardian-gate 리뷰 순서로 진행합니다.
ppi-monitor-app은 진행자 웹(/monitor-dashboard)을 Electron BrowserWindow로 로드하는 얇은 셸이다. Tauri는 macOS WKWebView에서 getDisplayMedia·setSinkId·webm MediaRecorder가 보장되지 않아 제외했다. 웹↔앱은 preload contextBridge의 window.ppiApp(version·capabilities·emit·on)으로 연결하고 main이 senderFrame origin을 검사한다.
자동 녹화는 기존 /monitor-recorder 페이지를 재사용한다. setWindowOpenHandler로 녹화 팝업을 숨김 창(같은 partition, backgroundThrottling false, autoplay 허용)으로 만들고, setDisplayMediaRequestHandler에서 desktopCapturer의 메인 창 소스(mainWindow.getMediaSourceId)를 자동 지정한다. 웹은 앱일 때 use-video-crop-recorder의 displaySurface==="browser" 검사를 건너뛰고 app:capture-insets로 크롭 좌표를 보정한다. 사용자 동작 없는 getDisplayMedia 허용 여부는 미검증이며, 막히면 chromeMediaSource desktop getUserMedia로 대체한다.
미확정 정책: 시작 시점(제안: 첫 아동 접속), 종료(모든 아동 종료·30분·수동), 브라우저 녹화 경로 유지 여부, 최소 OS, 배포 대상. 단계 P0 셸 → P1 브리지 → P2 캡처 PoC → P3 자동 정책 → P4 서명·업데이트. 2026-10-23 설계 제안, 구현 전.