# 주식회사 제로독 (zerodoc Inc.)
# AetherStream v0.1.0 (Alpha) 사용자 가이드

**최종 갱신**: 2026-11-03

AetherStream은 Windows PC(호스트)의 화면과 소리를 다른 기기(클라이언트)로 전송하고, 클라이언트의 키보드·마우스·컨트롤러 입력을 호스트로 되돌려 보내는 원격 스트리밍 프로그램입니다.

> **반드시 먼저 읽어 주십시오 — 알파 버전 보안 고지**
> - 현재 배포된 v0.1.0의 스트리밍 경로는 **암호화되지 않으며 접속 인증이 적용되어 있지 않습니다.** 같은 네트워크의 다른 기기가 화면을 수신하거나 입력을 주입할 수 있습니다(감사 보고서 [`AUDIT_2026-11-03.md`](AUDIT_2026-11-03.md) §2.2).
> - 이를 해결하는 보안 프로토콜 v2(PIN 페어링 + ChaCha20-Poly1305 암호화)는 **진행 중 (2026-11-03)** 이며, 이 가이드의 v2 절차는 해당 업데이트가 배포된 이후에 적용됩니다.
> - v2 배포 전에는 **신뢰할 수 있는 개인 네트워크(가정 내 LAN)에서만** 사용하고, 공용 Wi-Fi·회사망·카페 네트워크에서는 사용하지 마십시오. 사용하지 않을 때는 호스트 프로그램을 종료해 주십시오.
> - 지연 시간 등 성능 수치는 아직 측정·공개되지 않았습니다 ([`CLAIMS.md`](CLAIMS.md)).

---

## 1. 기능 및 상태

| 기능 | 상태 | 비고 |
| :--- | :--- | :--- |
| Windows 호스트 화면 캡처 및 H.264 인코딩 (Media Foundation 하드웨어 인코더, 실패 시 소프트웨어 인코더) | 부분 | GPU 제조사별 호환성 미검증 |
| Windows 데스크톱 클라이언트에서 화면 보기 | 부분 | |
| 키보드·마우스 원격 입력 | 진행 중 (2026-11-03) | 입력 처리 결함 수정 중 |
| 가상 Xbox 컨트롤러 (ViGEmBus 드라이버 필요) | 부분 | |
| 호스트 소리 전송 | 부분 | 데스크톱 클라이언트 재생 미구현 |
| 6자리 PIN 페어링, 전 구간 암호화 | 진행 중 (2026-11-03) | |
| 8자리 룸코드 (`XXXX-XXXX`) | 진행 중 (2026-11-03) | |
| 인터넷(WAN) 너머 원격 접속 | 로드맵 | M7. 임시 경로는 5절 |
| 클립보드 동기화 | 부분 | 보안 적용 전까지 기본 OFF |
| Android 앱 | 부분 | |
| iOS 앱 | 로드맵 | M8. 현재 설치 가능한 앱 없음 |
| Google 계정 로그인, Discord 연동, 결제 | 로드맵 | MLP 이후로 보류 (M9) |

---

## 2. 설치

### 2.1 다운로드
최신 릴리즈는 GitHub Releases에서 내려받습니다.
- <https://github.com/pqowp90/AetherStream-Release/releases/latest>

Windows 인스톨러 파일명 형식: `zerodoc_AetherStream_Setup_v<버전>.exe`

> 현재 인스톨러에는 코드 서명(Authenticode)이 적용되어 있지 않아 Windows SmartScreen 경고가 표시될 수 있습니다. 서명은 로드맵 M4입니다. 반드시 위 공식 주소에서만 내려받으십시오.

### 2.2 설치 및 방화벽
1. 인스톨러를 실행하고 안내에 따라 설치합니다(기본 경로: `Program Files\zerodoc\AetherStream`).
2. 방화벽 규칙: 프로토콜 v2 기준 인스톨러는 다음 범위의 규칙만 등록합니다 — **진행 중 (2026-11-03)**
   - 프로토콜/포트: **UDP 47998** (이전 버전의 UDP 47999는 폐지)
   - 네트워크 프로필: **개인(Private)** 만
   - 원격 주소: **로컬 서브넷(LocalSubnet)** 만
3. Windows의 현재 네트워크 프로필이 **공용(Public)** 이면 규칙이 적용되지 않습니다. 가정 네트워크라면 `설정 > 네트워크 및 인터넷 > (연결 이름) > 네트워크 프로필 유형`에서 **개인 네트워크**로 변경하십시오.

규칙 확인(관리자 PowerShell):
```powershell
netsh advfirewall firewall show rule name=all | Select-String -Context 0,12 "AetherStream"
```

> 이미 배포된 v0.1.0 인스톨러는 규칙 `zerodoc AetherStream UDP`로 UDP 47998-47999를 프로필·원격 주소 제한 없이 허용합니다. v2 인스톨러(규칙명 `zerodoc AetherStream UDP 47998`)는 설치 시 이 구 규칙을 삭제하도록 작업 중입니다. 그 전에 직접 범위를 줄이려면 해당 규칙의 속성에서 프로필을 "개인", 원격 IP를 "로컬 서브넷"으로 변경하십시오.

---

## 3. 호스트 PC 준비

1. 시작 메뉴 또는 바탕화면의 **AetherStream** 을 실행합니다. 데스크톱 앱이 호스트 엔진(`aether-server.exe`)을 함께 시작합니다.
2. 호스트 화면에 표시되는 **6자리 PIN** 을 확인합니다. PIN은 처음 기기를 페어링할 때 한 번만 사용합니다. (v2 동작, 진행 중 (2026-11-03))
3. 다중 모니터 환경에서는 송출할 모니터를 선택합니다(상태: 부분).
4. 컨트롤러를 사용하려면 호스트 PC에 **ViGEmBus 드라이버** 가 설치되어 있어야 합니다. 없으면 컨트롤러 입력은 동작하지 않으며 키보드·마우스만 사용할 수 있습니다.

---

## 4. 연결 및 페어링 (프로토콜 v2) — 진행 중 (2026-11-03)

### 4.1 최초 페어링 (6자리 PIN)
1. 클라이언트(다른 Windows PC의 AetherStream, 또는 Android 앱)에서 호스트를 지정합니다.
   - 같은 LAN: 호스트 PC의 IP 주소 또는 룸코드
   - 룸코드: **8자리 `XXXX-XXXX`** 형식 (Cloudflare 랑데부 서비스 경유, 진행 중 (2026-11-03))
2. 호스트 화면의 **6자리 PIN** 을 클라이언트에 입력합니다.
3. PIN이 맞으면 클라이언트는 호스트로부터 페어링 자격 증명을 받아 기기 보안 저장소에 보관합니다. 이후 접속부터는 PIN을 다시 입력하지 않습니다(페어링된 기기 모드).
4. 클라이언트는 호스트의 연결 승인 응답을 받은 뒤에만 "연결됨"을 표시합니다.

참고:
- PIN을 5회 이상 틀리면 해당 IP는 일정 시간 접속이 차단됩니다. 전체 실패가 누적되면 호스트가 PIN을 새로 발급합니다(PROTOCOL §3.7).
- 룸코드를 아는 것만으로는 접속할 수 없습니다. PIN 또는 페어링 자격 증명이 반드시 필요합니다.
- 기기를 분실한 경우 호스트에서 해당 기기의 페어링을 해제(철회)하십시오.

### 4.2 Windows PC에서 보기
1. 클라이언트 PC에서 AetherStream을 실행하고 **클라이언트 모드** 로 전환합니다.
2. 호스트를 지정하고(최초 1회 PIN 입력) 연결합니다.
3. 스트림 뷰어 창이 열립니다.

### 4.3 Android에서 보기
Android 앱은 현재 부분 구현 상태이며, 공용 코어 연동(ROADMAP M6) 전까지 v2 보안 연결을 지원하지 않습니다. 배포 여부는 GitHub Releases의 해당 버전 노트를 확인하십시오.

### 4.4 iOS
현재 설치 가능한 iOS 앱은 없습니다(ROADMAP M8).

---

## 5. 외부(인터넷)에서 접속하기

정식 WAN 원격 접속(랑데부 + TURN 릴레이)은 **로드맵 M7** 입니다. 그 전까지는 다음 방법을 **문서화된 임시 경로** 로 안내합니다.

**메쉬 VPN을 통한 접속**
1. 호스트 PC와 클라이언트 기기 양쪽에 동일한 메쉬 VPN(기기 간 사설 가상 네트워크를 구성하는 서비스) 클라이언트를 설치하고 같은 계정·네트워크에 등록합니다.
2. 클라이언트에서 호스트의 **VPN 가상 IP 주소** 로 접속합니다.
3. 방화벽 규칙이 로컬 서브넷으로 제한되어 있으므로, VPN 가상 네트워크 대역을 원격 주소에 추가하거나 VPN 어댑터 프로필을 확인해야 할 수 있습니다. 규칙 범위를 "모든 주소"로 넓히지 마십시오.

주의: 이 경로의 연결 품질·지연은 측정되지 않았으며 VPN 서비스 특성에 따라 달라집니다. 포트포워딩(공유기에서 47998을 인터넷에 개방)은 권장하지 않습니다. 특히 v2 보안 업데이트 이전 버전은 절대 인터넷에 노출하지 마십시오.

---

## 6. 스트리밍 중 조작 (Windows 데스크톱 뷰어)

| 기능 | 조작 | 근거 |
| :--- | :--- | :--- |
| 전체화면 전환 | `F11` | `ClientViewerWindow.xaml.cs:478` |
| 긴급 연결 해제 | `Shift` + `Esc` | `ClientViewerWindow.xaml.cs:454-459` |
| `Esc` 단독 | 키보드 입력 전달이 켜져 있으면 호스트로 전달(게임 일시정지 등), 꺼져 있으면 로컬에 유지. 전체화면은 해제하지 않음 | `ClientViewerWindow.xaml.cs:441-473` |
| 연결 해제 | 뷰어의 `연결 해제` 버튼 | |
| 입력 전달 범위 | 뷰어 설정에서 키보드·마우스 전달 여부 선택 | |

마우스 휠, 상대 이동(게임용 마우스 잠금), 화면 비율이 다를 때의 좌표 보정은 아직 지원되지 않습니다(ROADMAP M3).

---

## 7. 문제 해결

### Q1. "UDP 소켓 바인딩 실패" 또는 `WSAEADDRINUSE` 오류
이전 AetherStream 프로세스가 포트를 점유하고 있을 수 있습니다. 작업 관리자(`Ctrl + Shift + Esc`)에서 `AetherStream.exe`와 `aether-server.exe`를 종료한 뒤 다시 실행하십시오.

### Q2. 같은 집 안의 기기인데 연결되지 않음
1. 두 기기가 같은 공유기(같은 서브넷)에 연결되어 있는지 확인하십시오. 게스트 Wi-Fi는 기기 간 통신이 차단되는 경우가 많습니다.
2. 호스트 PC의 네트워크 프로필이 **개인** 인지 확인하십시오(2.2절).
3. 방화벽 규칙에 UDP 47998이 있는지 확인하십시오.
4. 서드파티 보안 프로그램이 UDP를 차단하는지 확인하십시오.

### Q3. 외부 네트워크(카페, 모바일 핫스팟 등)에서 접속되지 않음
정상적인 현재 동작입니다. WAN 접속은 로드맵 M7이며, 그 전까지는 5절의 메쉬 VPN 경로를 사용하십시오.

### Q4. 화면이 검게 나오거나 깨져 보임
알려진 결함이 있습니다: 일부 GPU에서 하드웨어 인코더의 파라미터 처리 문제로 디코딩이 실패할 수 있으며(감사 §2.3), GPU 제조사별 호환성은 아직 검증되지 않았습니다. 재현 시 호스트 콘솔 로그와 GPU 모델을 첨부하여 이슈로 보고해 주십시오.

### Q5. 컨트롤러가 인식되지 않음
호스트 PC에 ViGEmBus 드라이버가 설치되어 있는지 확인하십시오. 또한 현재 클라이언트 플랫폼마다 컨트롤러 버튼 번호 체계가 달라 일부 버튼이 잘못 매핑될 수 있습니다(감사 §4.3, 수정 진행 중 (2026-11-03)).

### Q6. 소리가 들리지 않음
Windows 데스크톱 클라이언트의 오디오 재생은 아직 구현되지 않았습니다(ROADMAP M3).

### Q7. 업데이트
새 버전은 GitHub Releases에서 직접 내려받아 설치하십시오. 서명 검증 자동 업데이트는 로드맵 M4입니다.

---

## 8. 개발자용: 벤치마크
Glass-to-Glass 지연 측정 하네스는 아직 없습니다(ROADMAP M1). 저장소의 `server/tests/test_pipeline_benchmark.rs`는 `cargo test`로 실행되는 테스트이며, 그 결과는 제품 지연 수치로 공개하지 않습니다.

---
**주식회사 제로독 (zerodoc Inc.)**
소스 저장소: `https://github.com/pqowp90/AetherStream` · 릴리즈: `https://github.com/pqowp90/AetherStream-Release/releases/latest`