[Economi] Moonlight 스트리밍 중 단축키와 창 모드 교차 작업 — 검증된 키 목록과 "포커스 함정"
초록
스트리밍 화면과 로컬 데스크톱을 오가는 교차 작업을 위한 Moonlight 6.1.0 단축키 전체 목록(설치 버전과 동일한 소스 태그로 검증), 캡처 해제 후 포커스가 옮겨져 단축키가 도달하지 않는 구조적 함정, 그리고 로그의 "Detected ... combo" 라인으로 키 도달 여부를 즉시 판별하는 진단 기법을 정리한다. 창 모드 영구 설정값과 호스트-클라이언트 해상도 일치 원칙도 함께 다룬다.
[Economi] Moonlight 스트리밍 중 단축키와 창 모드 교차 작업 — 검증된 키 목록과 "포커스 함정"
배경
Flatpak 전환(2026-09-02-economi-moonlight-flatpak-migration-plan) 이후 실사용 단계에서, 스트리밍 화면과 로컬 데스크톱(hb5u)을 오가며 작업할 필요가 생겼다. 기본 설정인 "테두리 없는 전체창"에서는 로컬 바탕화면이 완전히 가려져 교차 작업이 불가능했다. 이 과정에서 확보한 검증된 단축키 목록과, 단축키가 "작동하지 않는 것처럼 보이는" 함정, 그리고 그것을 로그로 즉시 판별하는 방법을 기록한다.
검증된 단축키 목록 (Moonlight 6.1.0)
스트리밍 중 Ctrl + Alt + Shift + 아래 키:
| 키 | 기능 | 비활성 조건 |
|---|---|---|
X |
전체화면 ↔ 창 모드 전환 | eglfs 플랫폼 |
Z |
마우스·키보드 캡처 해제 (로컬 데스크톱 조작) | eglfs 플랫폼 |
D |
창 최소화 | eglfs 플랫폼 |
M |
마우스 모드 전환(절대/상대 좌표) | 없음 |
C |
커서 표시/숨김 | 없음 |
L |
포인터를 영상 영역에 고정 | 없음 |
S |
성능 통계 오버레이 | 없음 |
V |
클립보드 텍스트 붙여넣기 | 없음 |
Q |
스트리밍 종료 | 없음 |
출처 검증에 관한 주의
이 표는 설치된 버전과 동일한 태그(v6.1.0)의 소스에서 확인한 것이다. 처음에는 master 브랜치 소스를 참조했는데, master에는 6.1.0에 없는 항목(E: quit and exit, K: 키보드 그랩 토글)이 추가되어 있었고 비활성 조건의 서술도 달랐다("데스크톱 환경 미실행 시" vs "eglfs 플랫폼"). 문서를 인용할 때 설치 버전과 소스 태그를 일치시키지 않으면 존재하지 않는 기능을 안내하게 된다.
"포커스 함정" — 단축키가 안 먹는 것처럼 보이는 이유
사령관이 Ctrl+Alt+Shift+X가 작동하지 않는다고 보고했다. 조사 결과 원인은 단축키 자체가 아니라 키보드 포커스였다.
직전에 Ctrl+Alt+Shift+Z(캡처 해제)를 눌러 마우스·키보드를 로컬로 되돌린 상태였고, 그 뒤 로컬 창을 조작하면서 키보드 포커스가 Moonlight 창을 떠나 있었다. 이 상태에서 누른 X는 포커스를 가진 다른 창으로 전달되어 Moonlight에는 도달조차 하지 않았다. Moonlight 창을 다시 클릭해 포커스를 준 뒤 누르자 즉시 동작했다.
교차 작업 시나리오에서는 Z(캡처 해제) → 로컬 작업 → 다시 스트림 조작이라는 순서가 자연스럽기 때문에, 이 함정은 구조적으로 자주 발생한다.
진단 기법: 단축키가 앱에 도달했는지 로그로 판별한다
Moonlight는 조합키를 인식하면 로그에 명시적으로 기록한다:
00:10:01 - SDL Info (0): Detected mouse capture toggle combo ← Z 는 도달함
00:15:01 - SDL Info (0): Detected full-screen toggle combo ← 포커스를 준 뒤 X 도 도달함
따라서 "단축키가 안 된다"는 보고를 받았을 때 로그에 Detected ... combo 라인이 있는지만 보면 두 가지 원인을 즉시 가를 수 있다:
- 라인 있음 → 키는 도달했으나 동작이 실패한 것 (앱/컴포지터 측 문제)
- 라인 없음 → 키가 앱에 도달하지 못한 것 (포커스, 입력기, 상위 단축키 충돌)
이번 사례는 Z는 기록되고 X는 기록되지 않은 상태였으므로, "조합키 메커니즘 자체는 정상인데 X만 도달하지 않았다"로 범위가 즉시 좁혀졌다.
상위 단축키 충돌도 함께 배제했다
포커스를 의심하기 전에, 상위 계층이 키를 가로챌 가능성을 먼저 배제했다:
# GNOME 키바인딩 중 Ctrl+Alt+Shift 조합 전수 검색
for schema in $(gsettings list-schemas | grep -iE "keybinding|shell|media-keys|mutter"); do
gsettings list-recursively "$schema" | grep -iE "<Control><Alt><Shift>|<Shift><Control><Alt>"
done
결과: Escape, Tab, 방향키만 사용 중이며 X는 미사용. 한글 입력기(ibus-hangul) 역시 트리거가 <Super>space, 전환키가 Hangul/Shift+space로 무관함을 확인했다. 이렇게 외부 요인을 먼저 배제해두었기 때문에 남은 후보가 포커스로 좁혀졌다.
창 모드 영구 설정
단축키로 매번 전환하는 대신 처음부터 창으로 띄우려면 설정을 바꾼다. Flatpak 설치 시 설정 파일 경로는 다음과 같다:
~/.var/app/com.moonlight_stream.Moonlight/config/Moonlight Game Streaming Project/Moonlight.conf
windowmode 값의 의미:
| 값 | 모드 |
|---|---|
| 0 | 전체화면(Fullscreen) |
| 1 | 테두리 없는 창(Borderless windowed) — 기본값 |
| 2 | 창 모드(Windowed) — 제목표시줄·테두리 있음 |
주의: 앱 실행 중에 이 파일을 편집하면 앱 종료 시 메모리상의 설정으로 덮어써진다. 반드시 앱을 완전히 종료한 뒤 편집하거나, 앱 설정 UI(표시 모드)에서 변경해야 한다.
해상도는 호스트와 일치시키는 것이 원칙
호스트(Sunshine 측) 데스크톱 해상도를 변경한 뒤에도 이미 연결된 세션의 스트림 해상도는 바뀌지 않는다 — 해상도는 세션 시작 시점에 협상되며, 변경을 반영하려면 재접속이 필요하다.
또한 클라이언트 요청 해상도가 호스트 실제 해상도보다 크면 호스트 측에서 업스케일한 영상이 전송되어 선명도가 떨어진다. 클라이언트 스트림 해상도 = 호스트 데스크톱 해상도로 맞추는 것이 화질·대역폭·디코딩 부하 모든 면에서 유리하다.
실무 요약
교차 작업 워크플로우:
Ctrl+Alt+Shift+X— 창 모드로 전환 (또는windowmode=2로 영구 설정)Ctrl+Alt+Shift+Z— 캡처 해제 후 로컬 데스크톱 작업- 다시 스트림을 조작할 때는 먼저 Moonlight 창을 클릭해 포커스를 준다
- 세션 종료는
Ctrl+Alt+Shift+Q, 이후 앱까지 완전히 종료한다 (2026-09-03-economi-moonlight-teardown-receive-loop-leak참조)
참고
- 선행 논문:
2026-09-02-economi-moonlight-flatpak-migration-plan(v3),2026-09-03-economi-moonlight-teardown-receive-loop-leak - 검증 소스: moonlight-qt v6.1.0 태그의
app/streaming/input/input.cpp - 실행 환경:
hb5u(Ubuntu 25.10, GNOME Shell 49.0, Wayland) · Moonlight Flatpak 6.1.0