OpenStreamHub는 Cooler Master MasterHUB를 macOS에서 제어하기 위한 비공식 데스크톱 앱과 Rust SDK, 진단 도구 모음이다. 공식 Windows 앱의 기기 제어·프로필·디스플레이·동작을 구현하는 것을 목표로 하지만 기능 호환은 아직 완전하지 않으며, 실제 하드웨어 검증도 한 대의 장비에 한정돼 있다.
이 프로젝트는 MasterHUB만 지원하며 Cooler Master와 제휴하거나 회사의 승인을 받은 제품이 아니다. 기능 비교 기준은 저장소에 기록된 분석을 토대로 한 공식 MasterHUB 소프트웨어 1.0.0.113이다. 구현 여부와 실제 기기 검증 여부는 따로 관리한다. 현재 상태는 Windows 앱을 완전히 대체할 수 있다고 검증된 단계가 아니다.
기능과 하드웨어 지원 현황
공식 Windows 앱과 비교한 OpenStreamHub의 구현 및 검증 상태는 다음과 같다.
| 기능 | macOS 구현 및 검증 상태 |
|---|---|
| 키패드·노브·다이얼 입력 | 구현했으며 하드웨어에서 테스트했다. 제한 사항은 모듈 지원 현황을 참조한다. |
| 두 개의 롤러 입력 | 디코더는 구현했다. 캡처를 통해 Windows 입력은 확인했지만 macOS에서는 보고가 들어오지 않아 해결되지 않았다. |
| 5개 페이더 입력 | 구현했으며 하드웨어에서 5개 페이더 모두 테스트했다. 값은 아래쪽 0에서 위쪽 100까지다. 값의 흔들림과 마이크 볼륨 동작은 아직 확인하지 않았다. |
| 프로필·바인딩·키패드 폴더 | 중첩 폴더, 뒤로 이동, 프로필 전환을 포함해 구현했다. 하드웨어에서 폴더 화면 다시 그리기를 테스트했다. |
| 키 이미지·애니메이션 | 키별 정적 이미지와 애니메이션 시퀀스를 구현했다. 정적 이미지는 하드웨어에서 테스트했으며 애니메이션 재생은 하드웨어 승인 테스트가 남아 있다. |
| 다이얼 디스플레이·기능 전환 | 이미지 업로드, 기능 레이블, 시계, CPU 표시를 구현하고 하드웨어에서 테스트했다. 디스플레이 전체 기능은 아직 동등하지 않다. |
| 볼륨·음소거·단축키·텍스트·앱·URL·미디어 제어 | 구현했지만 실행 여부와 macOS 권한 확인은 동작별로 다르다. 동작 목록을 참조한다. |
| 다중 동작·키 매크로 녹음 | 다중 동작 시퀀스와 키 매크로 녹음기를 구현했다. 녹음기는 실제 하드웨어 세션에서 확인해야 한다. |
| 카운트다운 타이머 | 알림과 소리를 포함해 구현했다. 남은 시간은 키에 표시되지 않는다. |
| OBS Studio 동작 | 일부를 구현했고 가짜 서버를 대상으로 테스트했다. 실제 OBS 검증과 나머지 동작 구현은 남아 있다. |
| Twitch·Discord·Streamlabs 및 앱별 통합 | 동등한 통합 기능은 구현하지 않았다. 일부 단축키는 수동으로 지정할 수 있다. |
공식 .mhz 프로필 가져오기·내보내기 | 호환성 보고서를 제공하고 실행 전에 검토하는 가져오기를 구현했다. 실제 내보내기 호환성은 아직 검증되지 않았고 .mhz 내보내기는 없다. 자체 형식인 JSON 가져오기·내보내기는 구현했다. |
| 조명·밝기 | 베이스·노브·페이더 조명 페이지와 다이얼 화면의 백라이트·색상 설정이 있다. 프로필 실행 중에도 사용할 수 있다. 다이얼 화면의 프로필별 밝기와 키 화면 밝기(키의 소프트웨어 디밍)는 하드웨어에서 테스트했다. 앱의 베이스·노브·페이더 조명은 추가 하드웨어 확인이 필요하다. |
| 펌웨어 업데이트 | 지원하지 않는다. |
| 절전·복귀·재연결 | 세션 처리를 구현했고 다이얼의 드라이런 재연결을 테스트했다. 절전·복귀와 다른 수명 주기 경로는 하드웨어 검증이 남아 있다. |
OpenStreamHub에는 Windows 기능 호환성의 일부는 아니지만 드라이런 동작 미리보기, 원시 데이터 캡처와 오프라인 재생, 로컬 진단 번들, 현재 포커스된 앱에 따른 선택적 프로필 규칙도 포함된다. 자세한 구현 항목과 남은 작업은 기능 호환성 추적표에서 확인할 수 있다. 이 문서의 일부 항목은 이전 구현 단계를 설명하므로, 이후 기기 테스트는 하드웨어 테스트 결과에서 확인해야 한다.
실제 기기에서 확인한 결과도 장비 하나에서 얻었다. 디코더나 편집기가 구현됐다는 사실만으로 하드웨어 호환성이 확인되는 것은 아니다.
| 모듈 | 확인된 결과와 한계 |
|---|---|
| 15키 IPS 키패드 · M4315 | 누름·뗌 입력, 키 이미지, 중첩 폴더 화면 다시 그리기, 뒤로 이동을 하드웨어에서 테스트했다. 물리 키 대응은 일부 위치에서 확인했다. |
| 3노브 모듈 · M003K | 기본 모드에서 회전과 누름을 테스트했고, 위쪽 노브 하나의 물리적 대응을 확인했다. |
| IPS 다이얼 · M131E | 회전, 누름, 디스플레이 화면, 이미지 업로드, 백라이트, 색상을 테스트했다. 앱의 드라이런 재연결도 테스트했다. |
| 2롤러 스크롤 모듈 · M032LE | Windows 캡처로 두 롤러가 모두 입력을 보낸다는 점을 확인했다. macOS 리더는 여전히 입력 보고를 받지 못해 조사가 진행 중이다. |
| 5페이더 모듈 · M005S | 디코더와 편집기를 구현했지만 검증에 쓸 실제 모듈이 없어 물리 기기 테스트는 하지 못했다. |
| 베이스 · M0064 | 장치를 발견해 기록했다. 관찰된 보고는 일정한 하트비트뿐이다. |
절전·복귀 복구, 일부 수명 주기 경로, 실제 OBS 동작은 추가 검증이 필요하다. 구체적인 테스트와 한계는 하드웨어 테스트 결과, 공식 Windows 앱과의 차이는 기능 호환성 추적표에서 볼 수 있다.
설치와 시작
최신 릴리스 페이지에서 최신 버전과 릴리스 노트, 다운로드 파일을 받을 수 있다. Mac에 맞는 .dmg를 고른다. Apple Silicon Mac은 aarch64, Intel Mac은 x86_64 파일을 사용하며 SHA256SUMS.txt에서 SHA-256 값을 확인한다. 파일을 열고 OpenStreamHub를 Applications 폴더로 옮긴다. macOS 12.3 이상이 필요하다.
앱은 서명과 공증을 받지 않았다. 서명에는 유료 Apple Developer 계정이 필요하지만 이 프로젝트는 무료로 운영되는 독립 프로젝트다. 따라서 처음 실행할 때 macOS가 경고를 표시한다. 앱은 오픈소스이므로 코드를 확인하거나 직접 빌드할 수 있다. 방법은 빠른 시작 안내에 있다.
처음 실행했을 때 macOS가 앱을 확인할 수 없다며 열지 않으면 다음과 같이 진행한다.
- 앱을 한 번 연다. macOS가 확인할 수 없다는 메시지를 표시하고 앱을 열지 않는다.
- 시스템 설정 → 개인정보 보호 및 보안으로 이동해 OpenStreamHub 관련 메시지를 찾고 ‘그래도 열기’를 선택한 뒤 확인한다.
macOS 14 이하에서는 앱을 오른쪽 클릭한 뒤 ‘열기’를 선택해도 된다. 터미널을 사용하려면 다음 명령으로 다운로드 표시를 제거할 수 있다.
xattr -dr com.apple.quarantine /Applications/OpenStreamHub.app
동작에 처음 필요한 시점에 macOS가 권한을 요청한다. 시스템 설정 → 개인정보 보호 및 보안에서 OpenStreamHub를 허용해야 한다. 앱의 설정 → 권한 화면에서는 부여된 권한을 확인하고 해당 설정 화면을 열 수 있다.
| 권한 | 필요한 기능 |
|---|---|
| 손쉬운 사용 | 다른 앱에 보내는 키보드 단축키, 텍스트, 실행 취소·다시 실행, 미디어 키 |
| 자동화 | 동작에서 시스템 이벤트와 미디어 플레이어(Music, Spotify) 제어 |
| 입력 모니터링 | 모듈 입력 읽기와 키 녹음기 |
설정 → 시작에서 로그인할 때 앱을 실행하도록 지정하고, 앱이 열릴 때마다 권한을 확인하도록 설정할 수 있다. 권한을 확인할 때는 해당 설정 화면으로 이동하는 짧은 안내가 표시된다. 프로필은 Mac에 로컬로 저장된다.
앱은 자동 업데이트하지 않는다. 설정 → 업데이트에서 새 버전이 있는지 확인한 뒤 기존 버전 위에 설치해야 한다. 서명되지 않은 앱이므로 업데이트 후 macOS가 권한을 다시 허용하라고 요청할 수 있다.
소스에서 빌드하려면 macOS 12.3 이상, Node.js 22.12 이상, Rust 1.97 이상, Xcode 명령줄 도구가 필요하다.
git clone git@github.com:goniszewski/OpenStreamHub.git
cd OpenStreamHub/apps/open-stream-hub
npm ci
npm run desktop
desktop 명령은 앱을 시작하기 전에 Rust 서비스 사이드카를 빌드한다. 앱을 시작한 뒤에는 다음 순서로 사용할 수 있다.
- MasterHUB를 연결하고 모듈을 선택한다.
- 프로필을 만들거나 편집하고 각 컨트롤에 동작을 지정한다.
- 드라이런을 시작해 입력과 실행 예정 동작을 살펴본다.
- 실제 동작을 실행할 준비가 되면 Execute를 선택하고 확인한다.
설정 → OpenStreamHub가 디스플레이 제어 → App을 선택한 상태에서 키패드 또는 다이얼 프로필을 실행하면 소프트웨어 모드가 켜지고 디스플레이를 제어한다. 세션을 중지하면 내장 애니메이션으로 돌아간다. ‘내장 애니메이션’을 선택하면 해당 모듈을 자체 모드로 둔다. 이 모드에서는 모듈 입력을 사용할 수 없다.
로컬 디버그 앱 번들을 만들 때는 다음 명령을 실행한다.
npm run desktop:build
개발 세부 정보는 데스크톱 앱 안내, 번들링과 서명은 빌드 안내를 참조한다. 서명과 공증은 릴리스 작업으로 남아 있다.
개인정보와 문서
OpenStreamHub에는 원격 측정, 분석, 자동 충돌 보고, 계정, 클라우드 동기화 기능이 없다. 프로필, 설정, 이미지, 진단 번들은 로컬에 저장한다. 진단 번들은 사용자가 요청할 때 만들며 공유 여부도 사용자가 결정한다. 민감한 항목은 기본적으로 가린다.
선택 기능인 OBS 통합은 같은 Mac에 있는 OBS에만 연결하며, 사용자가 켜기 전에는 비활성 상태다. 비밀번호는 메모리에만 저장하므로 앱을 다시 실행한 뒤 다시 입력해야 한다. 설정한 동작을 실행하면 앱이나 웹 주소를 열 수 있다.
앱은 자체적으로 원격 서비스에 접속하지 않는다. 설정 → 업데이트의 ‘업데이트 확인’ 버튼은 GitHub에 최신 릴리스를 요청한다. 이 익명 요청에는 앱 이름과 버전만 전송된다. 선택 사항인 실행 시 일일 확인은 기본적으로 꺼져 있다. 앱이 직접 파일을 다운로드하거나 설치하는 일은 없다. 소스 빌드 과정에서는 npm과 crates.io에서 의존성을 다운로드한다. 로컬 진단에 담기는 정보는 진단 번들 안내에서 확인할 수 있다.
문서에는 데스크톱 앱, 동작 목록, 프로필 및 바인딩 서비스, 구현 상태, 키패드 폴더, 하드웨어 테스트 결과, 다이얼 기능, 프로토콜 근거 자료, 공식 프로필 가져오기, Windows 기능 호환성 추적표, 포커스된 앱 규칙, macOS 로드맵, 진단 및 재생, 세션 수명 주기, 디스플레이 동기화, 릴리스 절차가 제공된다. 예제 프로필로는 macOS 컨트롤, 전체 모듈, 키패드 폴더, 다이얼 기능이 있다. 전체 예제는 프로필 예제 디렉터리에서 볼 수 있다.
개발과 라이선스
저장소는 앱, 서비스, SDK를 함께 관리해 프로토콜과 프로필을 연계해 개발할 수 있도록 구성됐다. Rust 크레이트는 기존 cooltek-sdk 이름을 유지한다.
| 경로 | 내용 |
|---|---|
apps/open-stream-hub/ | Tauri 데스크톱 앱과 React 인터페이스 |
crates/ | Rust SDK, 바인딩 서비스, 명령줄 도구 |
examples/ | 예제 프로그램과 프로필 |
docs/ | 사용자 안내, 프로토콜 조사, 검증 기록 |
저장소 루트에서 Rust 작업 공간을 빌드하고 검사하려면 다음 명령을 사용한다.
cargo build --workspace
cargo fmt --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
데스크톱 프런트엔드는 다음 명령으로 검사한다.
cd apps/open-stream-hub
npm run check
npm test
npm run build
앱의 Rust 백엔드는 별도 작업 공간이다. 관련 내용은 데스크톱 검증 명령에 있다. SDK나 서비스를 바꾼 뒤에는 npm run sidecar로 사이드카를 다시 빌드한다.
다른 Rust 프로젝트에서 SDK를 사용하려면 다음 의존성을 추가한다.
[dependencies]
cooltek-sdk = { git = "https://github.com/goniszewski/OpenStreamHub" }
기여를 환영한다. 변경 범위를 좁게 유지하고 관련 테스트와 문서를 추가하며 Conventional Commits를 사용하도록 안내한다. 하드웨어 변경에서는 합성 테스트와 실제 기기 관찰을 구분해야 한다.
OpenStreamHub는 projectzero7의 CoolTEK SDK를 기반으로 한다. 독립적으로 유지 관리되는 이 프로젝트는 원래의 이력과 라이선스를 보존하면서 자체 MasterHUB 앱과 macOS 지원을 개발한다. 프로젝트의 역공학·개발·테스트 과정에는 생성형 AI 도구가 사용됐다. 유지 관리자는 모든 변경을 검토하고 테스트한다고 밝힌다. 실제 기기에서 시험한 동작만 하드웨어 동작으로 주장하며, 기록은 하드웨어 테스트 결과에 남긴다.
라이선스는 MIT 또는 Apache-2.0 중 선택할 수 있는 이중 라이선스다. 별도 표기가 없는 한 기여분에도 같은 조건이 적용된다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요