keymapper

설치 방법

• winget (Windows): winget install –id houmain.keymapper –exact 명령으로 설치할 수 있습니다. 또는 winget install keymapper, choco install keymapper도 사용 가능합니다.
• Windows 수동 설치: 최신 릴리스 페이지에서 설치 관리자 또는 포터블 빌드를 다운로드합니다. 설치 관리자는 작업 스케줄러에 logon 시작을 등록하고, 포터블 빌드는 keymapper.exe와 keymapperd.exe를 직접 실행합니다.
• Linux: 최신 릴리스 페이지에서 사전 빌드 패키지를 다운로드하거나 Arch Linux의 경우 AUR에서 설치합니다.
• MacOS: Karabiner의 가상 HID 장치 드라이버를 먼저 설치한 뒤, Homebrew 탭(brew tap houmain/tap)에서 brew install –HEAD keymapper로 빌드 및 설치합니다.

기본 사용 절차

1. 설정 파일 keymapper.conf를 작성합니다. 각 줄은 입력 표현식과 출력 표현식을 >> 로 구분하며, 예: CapsLock >> Backspace, Control{Q} >> Alt{F4} 와 같습니다.
2. Linux에서는 sudo systemctl start keymapperd로 서비스를 시작한 뒤 keymapper -u로 클라이언트를 실행해 설정 변경 시 자동 리로드를 활성화합니다.
3. MacOS에서는 sudo keymapper-launchd add로 launchd 데몬/에이전트를 등록합니다.
4. Windows에서는 트레이 아이콘 메뉴의 “Configuration” 항목으로 설정 파일을 열어 편집할 수 있습니다.
5. 긴급 종료가 필요한 경우 Shift+Escape+K 조합으로 keymapperd를 종료할 수 있습니다.

활용 예시

• QWERTY와 다른 키 배열 사용: Z >> Y, Y >> Z로 키 위치를 교환하고 [stage] 블록으로 후속 매핑을 연결할 수 있습니다.
• 특정 애플리케이션에서 단축키 변경: [title = “Visual Studio”] 같은 컨텍스트 블록 안에서 build >> (Shift Control){B}로 빌드 단축키를 재정의합니다.
• 입력 시점에 따라 다른 출력: Meta{C} >> Meta{R} ^ “cmd” Enter 형태로 키 누름과 떼림 시점에 출력을 분리할 수 있습니다.
• 가상 키로 상태 전환: ScrollLock >> Virtual1, Escape >> !Virtual1, Virtual1{A} >> B 형태로 가상 키를 토글해 매핑 조건으로 활용할 수 있습니다.
• 환경 변숫값에 따른 매핑 활성화: [getenv[“HOSTNAME”] = “LaptopMum”] 같은 블록으로 특정 환경에서만 동작하는 매핑을 구성합니다.

제한 및 확인 사항

• 설정 파일은 대소문자를 구분합니다. 키 이름은 대문자로 시작하므로 추상 명령 이름은 소문자로 시작하는 것이 권장됩니다.
• Wayland에서는 프로세스 경로 정보가 제공되지 않을 수 있으며, 권한이 높은 프로세스에서도 마찬가지입니다. MacOS에서는 창 제목 정보를 사용할 수 없습니다.
• Windows의 device/device-id 컨텍스트 필터는 가상 장치 드라이버(Interception) 설치가 필요합니다. Interception은 장치 연결 해제 시 장치가 동작을 멈출 수 있는 알려진 버그가 있으므로, 장치 필터링이 꼭 필요한 경우에만 설치하는 것이 권장됩니다.
• 포터블 Windows 빌드에서 keymapperd.exe를 관리자 권한 없이 실행하면 Windows 키 매핑이 안정적이지 않고, 작업 관리자와 같이 관리자 권한으로 실행 중인 애플리케이션은 매핑되지 않습니다.
• 문자열 리터럴의 키보드 레이아웃은 설정 파일 로드 시점에 평가되어 런타임 중 키보드 레이아웃 전환은 지원되지 않습니다.
• 출력 지연 시 해당 시간 동안 입력 처리가 중단됩니다. 비동기 키 입출력은 keymapperctl의 –press, –wait, –release를 조합해 구현해야 합니다.
• 라이선스는 GNU GPLv3이며, 어떠한 보증도 제공되지 않습니다.