미니캐스트 시작하기
미니캐스트(MiniCast)는 강의, 라이브 코딩, 화상회의, 스트리밍 녹화 시 마우스와 키보드 입력을 즉시 시각화해 주는 Electron 기반 데스크톱 앱입니다.
다중 모니터를 자동 인식하고 원하는 한 모니터에만 키 입력을 띄울 수 있으며, 커서 하이라이트와 키 표시를 세밀하게 커스터마이즈할 수 있습니다.
현재 동작 중인 핵심 모듈: 커서 하이라이트 / 키 입력 표시 / 다중 모니터 오버레이
추가 예정: 캔버스 드로잉, 클릭 이펙트 강화, 단축키 토글, 자동 업데이트 등
설치
Windows (Portable)
- Releases 페이지에서
MiniCast.exe(무설치) 또는MiniCast.msi(설치형) 다운로드 - 무설치: 원하는 폴더에 두고 바로 실행 (설치 과정 X) 설치형(MSI): 설치 진행 후 바탕화면에서 실행
- 실행 후 트레이(시스템 트레이) 아이콘이 생성되며 Controller 창이 표시됩니다.
macOS (준비 중)
DMG 패키징 및 코드 서명 예정. 현재는 개발 환경에서만 실행 가능.
개발 환경에서 실행 (공통)
bash
git clone https://github.com/andongmin94/mini-cast.git
cd mini-cast/packages
npm install
npm run app # React Dev + Electron 함께 실행화면 구성 개요
| 요소 | 설명 |
|---|---|
| Controller (메인 창) | 설정을 변경하는 UI. 커서 / 키보드 탭 제공, 상단 커스텀 타이틀바, 하단 광고 영역 |
| Overlay 창 | 모니터마다 1개씩 투명창. 입력 시각화만 담당 (클릭 통과) |
| Splash | 초기 2초 로딩 중 표시 (윈도우 생성/포트 결정) |
| Tray (Windows) | 빠른 접근 및 최소화 상태 관리 (미니마이즈/닫기와 별도) |
오버레이는 항상 위(alwaysOnTop) + 마우스 이벤트 무시(setIgnoreMouseEvents) 설정으로,
실제 작업/프레젠테이션을 방해하지 않습니다.
빠른 시작 (기본 흐름)
- 앱 실행 → Splash → Controller 표시
- 자동으로 모든 모니터에 Overlay 창 생성
- 기본 설정 상태 (커서/키 표시 ON)
- Controller 에서 즉시 설정 수정 → Overlay 실시간 반영
- 창 닫기(X) 시 Windows: 종료 / macOS: 숨김 처리 (추후 동작 커스터마이즈 가능)
주요 설정 요약
| 구분 | 설정 | 설명 | 기본값 |
|---|---|---|---|
| 커서 | 칠 색상 / 칠 투명 | 내부 원 색상 / 투명도 | #0064FF / 0.5 |
| 커서 | 획 색상 / 획 투명 | 클릭 시 테두리 색상 / 투명도 | #202632 / 0.5 |
| 커서 | 칠 크기 | 원 지름(px) | 30 |
| 커서 | 획 크기 | 클릭 시 stroke 굵기 | 3 |
| 커서 | 커서 활성화 | 하이라이트 토글 | ON |
| 키 | 키보드 활성화 | 키 표시 토글 | ON |
| 키 | 활성 모니터 | 키 표시 대상 모니터 index | 0 |
| 키 | 지속 시간 | 표시 유지 ms | 2000 |
| 키 | 폰트 크기 | px 단위 | 16 |
| 키 | 배경 색상 / 투명 | 키박스 배경 / 투명도 | #000000 / 0.5 |
| 키 | 폰트 색상 | 텍스트 색 | #FFFFFF |
| 키 | 표시 위치 | 4방 코너 중 선택 | bottom-right |
실제 저장 시 앱 내부에서는 RGBA 로 변환되어 영구 저장(electron-store).
키 입력 처리 로직 핵심
- 전역 후킹:
node-global-key-listener - 조합키 (Ctrl, Shift, Alt, Meta) + 일반 키
- 단일 알파벳 반복 입력(스팸) 최소화를 위한 타임스탬프/조합 비교
- 표시 유지 시간 경과 후 자동 제거
다중 모니터 동작
- 실행 시
screen.getAllDisplays()로 전체 디스플레이 수만큼 Overlay 생성 - 디스플레이 추가/제거 이벤트(
display-added/display-removed) → 재생성 - 키 입력은 모든 Overlay 로 브로드캐스트하되, 표시 여부는 각 Overlay 가 자신의 id 와
keyDisplayMonitor비교하여 결정
설정이 반영되지 않을 때
| 증상 | 점검 | 해결 |
|---|---|---|
| 키 표시 안 됨 | 키보드 활성화 스위치 ON? | ON 후 재시도 |
| 특정 모니터에만 키 표시 필요 | 활성 모니터 index 올바른가? | 드롭다운에서 재선택 |
| 커서 원 안 보임 | 커서 활성화 OFF? 투명도 1.0? | 활성화 ON / 투명도 낮추기 |
| 앱 중복 실행 | 이미 인스턴스 존재? | 기존 인스턴스 포커스됨 (싱글 락) |
성능 & 최적화 팁
- 마우스 폴링 8ms → CPU 사용량 문제시 16~24ms 로 옵션화 예정
- 대형 4K 다중 모니터 구성에서 투명 레이어가 많을 경우 GPU 점유 모니터링 권장
- 반투명 배경 수가 많으면 (다수 키 연타) 배경/폰트 대비를 조절하여 가독성 유지
향후 확장 (로드맵 요약)
| 범주 | 계획 |
|---|---|
| 캔버스 | 펜/레이저/사각형/스팟라이트 모드 |
| 효과 | 클릭 파동, 커서 애니메이션, 테마 프리셋 |
| UX | 글로벌 토글 단축키, 트레이 컨텍스트 메뉴 확장 |
| 배포 | macOS DMG / 자동 업데이트 / 버전 동기화 스크립트 |
| i18n | 한국어/영어 다국어 지원 |
FAQ (초안)
Q. 보안 경고(키보드 후킹) 가 나옵니다.
A. 전역 입력 후킹 라이브러리 사용으로 OS/백신이 민감하게 반응할 수 있습니다. 키 입력은 로컬에서만 처리하며 외부 전송하지 않습니다.
Q. 키 입력이 일부 앱에서 누락됩니다.
A. 관리자 권한이 필요한 환경일 수 있습니다. (추후 Elevation 안내 추가 예정)
Q. 설정 초기화는?
A. 하단 리셋 버튼 → Alert 확인 → 기본값 복원.
문제 제보
아래에 있는 Gmail로 문의하기로 재현 단계와 스크린샷을 남겨주세요.