<p align="center">
<img src="https://raw.githubusercontent.com/hyperb1iss/uchroma/HEAD/docs/public/uchroma-mark.png" alt="UChroma" width="200">
</p>
<h1 align="center">uChroma</h1>
<p align="center">
<strong>리눅스에서 Razer Chroma용 RGB 제어</strong>
</p>
<p align="center">
<img src="https://img.shields.io/badge/Python-3.11+-3776ab?style=for-the-badge&logo=python&logoColor=white" alt="Python">
<img src="https://img.shields.io/badge/GTK4-Frontend-4a86cf?style=for-the-badge&logo=gtk&logoColor=white" alt="GTK4">
<img src="https://img.shields.io/badge/D--Bus-API-e135ff?style=for-the-badge&logo=freedesktoporg&logoColor=white" alt="D-Bus">
<img src="https://img.shields.io/badge/License-LGPL--3.0-50fa7b?style=for-the-badge&logo=gnu&logoColor=white" alt="License">
</p>
The Razer Chroma 라인 주변기기는 내장된 LED 매트릭스나 매크로 키와 같은 화려한 기능을 갖추고 있습니다. 이 프로젝트는 커널 수정(kernel modifications)을 요구하지 않고도 리눅스 환경에서 이러한 기능들에 대한 풍부한 지원을 제공하는 것을 목표로 합니다.
✦ 기능 (What can it do?)
- Razer 키보드, 마우스, 마우스 패드, 노트북, 헤드셋 및 키패드를 지원합니다 — 지원 장치 보기
- 내장 하드웨어 조명 효과 활성화 가능
- LED 매트릭스가 있는 장치를 위한 여러 사용자 지정 효과 포함 (추가 예정)
- 사용자 지정 효과 생성을 위한 풍부한 애니메이션/프레임버퍼 API
- 실시간 LED 매트릭스 미리보기가 가능한 GTK4 프론트엔드
- 노트북용 팬 제어 및 전원 관리 기능
- 무선 장치용 배터리 모니터링
- 낮은 전력 소비에 최적화됨
- 간단한 설치와 설정
- 강력한 커맨드 라인 인터페이스 (CLI)
- D-Bus API
- 100% asyncio-구동 Python, 100% 오픈 소스 (LGPL)
📚 전체 문서 — 사용자 가이드, CLI 레퍼런스, 효과 개발
📦 설치 (Installation)
Ubuntu/Debian (PPA)
sudo add-apt-repository ppa:hyperb1iss/ppa
sudo apt update
sudo apt install uchroma
Arch Linux (AUR)
yay -S uchroma
paru -S uchroma
Fedora
spudo dnf install rpm-build rust cargo maturin python3-devel
rpmbuild -bb packaging/fedora/uchroma.spec
...
PyPI
pipx install uchroma
uv tool install uchroma
소스에서 빌드 (From Source)
UChroma는 Python 3.11 이상을 요구하며, 의존성 관리를 위해 uv를 사용합니다.
git clone https://github.com/hyperbliss/uchroma.git
cd uchroma
...
권한을 변경하거나 장치 또는 커널 HID 드라이버의 동작을 바꿀 수 있는 다른 소프트웨어는 반드시 제거하십시오.
⚡ 사용법 (Usage)
UChroma는 두 가지 주요 실행 파일인 uchromad와 uchroma로 구성됩니다. uchromad 실행 파일은 시스템의 백그라운드 서비스(systemd user service)로 실행되며, 모든 하드웨어 상호 작용을 처리하고, 애니메이션을 실행하며, 기본 설정을 저장하고, 클라이언트가 사용할 여러 D-Bus 서비스를 게시합니다. uchroma 명령어는 발견된 모든 장치에 대한 통일된 인터페이스를 제공합니다. 이 CLI 도구는 하위 명령(subcommand, Git과 유사)을 기반으로 하며, -h 플래그를 전달하여 어느 레벨에서든 도움말을 확인할 수 있습니다.
장치 목록 확인 (Listing devices)
$ uchroma -l
[1532:0210.00]: Blade Pro (Late 2016) (BladeProLate2016 / v0.38)
[1532:0510.01]: Kraken 7.1 V2 (Kylie) (HN1649D04607845 / v1.135)
점(.) 뒤의 숫자는 장치 인덱스입니다. 전체 식별자 또는 단순히 장치 인덱스를 사용하여 -d 플래그로 대상 장치를 선택할 수 있습니다.
장치 상태 덤프 (Dump device state)
$ uchroma -d 0 dump
장치 속성:
...
내장 효과 (Built-in effects)
내장 효과는 하드웨어 자체에서 완전히 실행되며, 지원되는 유형과 옵션은 모델별로 크게 다릅니다.
사용 가능한 효과 목록 확인:
$ uchroma -d 0 fx list
내장 효과 및 인자:
...
효과 활성화:
$ uchroma -d 0 fx fire --color magenta
효과 비활성화:
$ uchroma -d 0 fx disable
밝기 제어 (Brightness control)
장치의 전체 밝기 수준은 0~100의 백분율로 표현됩니다.
현재 밝기 표시:
$ uchroma -d 1 brightness
100.00
밝기 수준 설정:
$ uchroma -d 1 brightness 85
애니메이션 (Animations)
UChroma는 Blade 노트북, BlackWidow 키보드, Mamba 마우스와 같이 라이팅 매트릭스(lighting matrix)를 지원하는 장치에서 사용자 지정 애니메이션을 지원합니다. 여러 개의 애니메이션 렌더러가 포함되어 있으며, 서드파티 모듈에서도 제공될 수 있습니다. 여러 개의 동시 실행되는 (stacked) 애니메이션이 지원되며, 레이어는 알파 블렌딩(alpha-blended)됩니다. 애니메이션은 다른 프레임 속도에서 실행될 수 있으며, 입력 이벤트나 사운드로부터 트리거될 수 있습니다. 현재의 애니메이션 매개변수는 위에서 보여준 "uchroma dump" 명령에서 확인할 수 있습니다.
사용 가능한 애니메이션 렌더러 목록 보기:
$ uchroma -d 0 anim list
사용 가능한 렌더러 및 인자:
...
애니메이션 시작하기:
$ uchroma -d 0 anim add plasma --color_scheme newer
다른 레이어 추가하기:
$ uchroma -d 0 anim add ripples
실행 중인 레이어의 매개변수 수정하기:
$ uchroma -d 0 anim mod 0 --color-scheme emma --fps 10
레이어 제거하기:
$ uchroma -d 0 anim del 1
애니메이션 정지 및 초기화:
🔮 자주 묻는 질문 (Frequently Asked Questions)
장치가 인식되지 않아요!
아직 지원되지 않는 장치가 있다면 몇 가지 옵션이 있습니다. 해당 장치가 새로운 프로토콜을 요구하지 않는 경우, uchroma/server/data 아래의 적절한 YAML 파일에 단순히 추가할 수 있습니다. 특정 모델 추가를 원한다면 Github에 이슈(issue)를 열어주세요. 새 장치에 대한 지원을 추가했다면 풀 리퀘스트(pull request)를 열어주세요!
정말 좋네요, 하드웨어를 기부하거나 개발 자금을 어떻게 마련할 수 있나요?
Razer는 각각 고유한 특징을 가진 많은 장치를 만듭니다. 특정 하드웨어 지원을 보고 싶다면, 저에게 작업할 장치를 보내주시는 것이 가장 좋은 동기 부여 방법입니다. 지속적인 개발에 도움을 주고 싶다면 기부금(donation)을 보내는 것을 고려해 주세요.
사용자 지정 애니메이션은 어떻게 만들 수 있나요?
이 주제에 대한 공식 문서는 곧 공개될 예정이지만, uchroma/fxlib의 번들된 렌더러들을 살펴보는 것만으로도 시작하기에는 충분할 것입니다. 구현체는 반드시 Renderer를 상속받고 init, finish, 그리고 draw 메서드를 구현해야 합니다. 애니메이션 시스템은 프레임버퍼(framebuffer)이며, draw 메서드는 사용자가 지정한 FPS에서 호출됩니다. 불필요한 CPU 사용을 피하기 위해 가능한 한 낮은 FPS를 유지하는 것이 중요합니다! draw 메서드에는 Layer 객체가 전달되는데, 이 객체는 모양을 그리거나 개별 픽셀을 설정하기 위한 기본 요소(primitives)를 제공합니다. 프레임의 버퍼는 Numpy 행렬이며, 원한다면 직접 조작할 수 있습니다. 색상 계산 및 그라디언트/색상 구성표 생성을 위한 함수들은 uchroma.color 모듈에서 찾을 수 있습니다. 사용자 설정 가능한 매개변수에는 Traitlets를 사용합니다.
트리 외부(out-of-tree) 모듈이 인식되게 하려면, 해당 모듈의 setup.py에 효과(effect)에 대한 진입점(entry point)을 선언해야 합니다:
entry_points={
'uchroma.plugins': ['renderer = my.effect.module:MyClass']
}
새로운 렌더러를 구현했고 포함되기를 원한다면 풀 리퀘스트(pull request)를 보내주세요!
Razer Inc와 관련이 있나요?
전혀 그렇지 않지만, 그들이 하드웨어를 트럭 가득 배달해 준다면 기꺼이 받아들일 것입니다 :)
Windows가 지원되나요?
아니요. UChroma는 작동을 위해 UDev 및 기타 Linux 전용 서브시스템에 의존합니다.
매크로 녹화가 지원되나요?
매크로 지원의 기본 구조(skeleton)는 마련되어 있으며, 곧 출시될 버전에서 완성될 예정입니다.
리플 효과(ripple effect)가 제 키 입력과 맞지 않는 것 같아요!
이는 키코드(keycodes)를 LED 매트릭스 좌표에 매핑하는 작업이 필요하며, 장치마다 레이아웃이 크게 다르기 때문입니다. 초기 릴리스에서는 Blade Pro 노트북에 대한 전체 지원이 제공되며, 다른 모델에는 거의 확실하게 잘못된 '일반적인' 매핑이 제공됩니다. 만약 사용하시는 장치에 맞는 적절한 매핑을 만들고 (그리고 이를 기여하고 싶다면!), 도움이 될 간단한 도구를 만들었습니다. 환경 변수에 UCHROMA_DEV=1을 설정한 후, _uchromad_를 실행하고 소스 배포판에서 "scripts/devstuff keys"를 실행해야 합니다. 이 도구는 매트릭스 셀에 불을 밝혀주며, 사용자는 불이 켜진 키를 누르기만 하면 되고, 모든 셀에 대해 반복할 수 있습니다. 새로운 매핑을 만든 후에는 uchroma/server/data 아래의 적절한 YAML 파일에 병합되어야 합니다 (그리고 풀 리퀘스트(pull request)를 보내야 합니다!). 셀 교체 및 재배치 지원도 제공되니, Blade Pro 설정을 참고하여 예시를 확인해 보세요.
비슷한 기능을 가진 다른 프로젝트가 있는데, 왜 이것을 만들었나요?
이 프로젝트는 필요한 코드가 매우 전문적이고 사용자 공간(userspace)에서 완전히 처리할 수 있기 때문에, 다른 프로젝트들이 리눅스 커널에 통합될 가능성이 전혀 없다는 것을 깨닫고 탄생했습니다. 또한 풍부한 애니메이션 지원과 낮은 전력 소비를 원했고, 이는 기존 프로젝트의 많은 부분을 다시 작성해야 했기 때문입니다 (그리고 제 패치들은 진전되지 않고 있었습니다). 초기 사용자 공간 드라이버(user-space driver)를 구현한 후, 저는 계속해서 하드웨어가 리눅스 환경에서 정말 빛나도록 만들기로 결정했습니다. 가장 적합하다고 생각하는 것을 선택하세요!
GUI가 있나요?
네! libadwaita 스타일링이 적용된 GTK4 프런트엔드가 포함되어 있습니다. uchroma-gtk를 실행하여 시작할 수 있습니다. 이 GUI는 실시간 LED 매트릭스 미리보기, 효과 구성 및 레이어 관리를 제공합니다.
기여하는 방법은 무엇인가요?
프로젝트를 포크(fork)하고 변경 사항에 대한 설명을 담아 풀 리퀘스트(pull request)를 보내주세요. 이 프로젝트는 현재 초기 릴리스 단계이므로, 다양한 모델에 걸친 많은 테스트가 필요합니다. 문서화가 부족하며, 더 많은 배포판(distribution) 지원도 목록 상단에 있습니다. 버그를 발견하면 Github에 이슈를 등록해 주세요.
🧪 기반 기술
UChroma에서 사용된 주요 라이브러리:
크레딧
Copyright (C) 2017-2026 Stefanie Jane
Tim Theede와 Terry Cain의 작업에서 영감 받음
이 프로그램은 자유 소프트웨어입니다: 귀하는 이를 무료 소프트웨어 재단(Free Software Foundation)에서 발행한 GNU Lesser General Public License 조건에 따라 재배포 및/또는 수정할 수 있습니다.
본 프로그램은 유용할 것이라는 희망으로 배포되지만, 어떠한 보증도 없으며; 상품성(MERCHANTABILITY) 또는 특정 목적 적합성(FITNESS FOR A PARTICULAR PURPOSE)에 대한 묵시적 보증조차 없습니다. 자세한 내용은 GNU Lesser General Public License를 참조하십시오.
귀하는 본 프로그램과 함께 GNU Lesser General Public License 사본을 받았어야 합니다. 그렇지 않다면, http://www.gnu.org/licenses/를 참조하십시오.
