R2D2
데모:
프로젝트 배경 이야기 읽기: R2D2 for webOS.
웹OS TV를 위한 로컬 홈 화면, 개인 원격 브라우저, 그리고 푸시 투 토크(push-to-talk) 음성 비서입니다. Linux 컴퓨트 호스트가 Chromium과 음성 모델을 실행하며; TV는 디스플레이, 애플리케이션 및 리모컨 제어를 제공합니다.
면책 조항 (Disclaimer)
[!WARNING]
TV 구성 요소들은 root 권한으로 실행되며 특정 펌웨어 빌드에서 공급업체 시스템 서비스(vendor system services)를 수정합니다. 이는 지원되지 않으며, 보증을 무효화할 수 있고, 재부팅 또는 공장 초기화 전까지 TV를 사용할 수 없게 만들 수 있습니다. 사용은 전적으로 본인의 책임 하에 이루어져야 합니다.
- keyfilter 패치, Home/idle 라우팅, 네이티브 음성 캡처는 공급업체 서비스를 대체하거나 후킹(hook)합니다. 실수할 경우 TV를 복구하기 전까지 원격 제어, 홈 기능 또는 음성 기능을 비활성화시킬 수 있습니다.
- 펌웨어 SHA-256 핀, 코드 오프셋(code offsets), 심볼 이름(symbol names), 패치 앵커(patch anchors)는 하나의 참조 빌드를 대상으로 합니다. 사용자 자신의 펌웨어를 위해 이를 재파생해야 하며, 절대 일치하지 않는 핀을 강제해서는 안 됩니다.
- 이 소프트웨어는 어떠한 보증 없이 '있는 그대로' 제공됩니다. LICENSE.md를 참조하십시오.
상태 (Status)
하나의 TV/펌웨어를 대상으로 한 참조 배포 환경에서는 홈 화면, 브라우저, 원격 음성 명령이 종단 간(end to end)으로 작동합니다. 다른 TV, 펌웨어, 리모컨 및 호스트 조합은 검증되지 않았습니다. 이 저장소는 범용적인 root, 펌웨어 또는 호스트 설치 프로그램이 아니라 소스 코드와 오프라인 테스트를 제공합니다.
구성 요소 간의 연동 방식 (How it fits together)
- 컴퓨트 호스트 (
paths에서 spark/): aarch64 Linux 머신입니다. 이는 샌드박스화된 Chromium 세션을 개인 디스플레이 및 오디오 세션에 렌더링하고 이를 LAN을 통해 TV로 스트리밍합니다. 또한 로컬 음성 인식 및 의도 모델(intent models), 그리고 폐쇄형 명령 레지스트리를 실행합니다.
- TV (
tv/, voice/tv/): 홈 애플리케이션과 브라우저 뷰어로, 원격 입력을 호스트로 전송합니다. root 캡처 소유자(root capture owner)는 리모컨의 음성 키를 가져와 상호 TLS(mutual TLS)를 통해 바운디드 오디오(bounded audio)를 호스트로 전송합니다.
- 콘텐츠 보호 (
protection/): 폐기 가능한 브라우저 프로필 각각에 로드되는 고정된 필터 규칙입니다.
모델 추론(Model inference)은 호스트(host)에 머무릅니다. 요청된 웹사이트, 검색, 스트리밍 앱 및 선택적 날씨 정보는 여전히 해당 제공업체와 통신합니다. 자세한 내용은 SECURITY.md를 참조하십시오.
요구 사항 (Requirements)
- 빌드 머신(Build machine): Python 3.10 이상 및 Node.js 20 이상.
- 컴퓨팅 호스트(Compute host): 비루트 서비스 계정(UID 1000)을 사용하는 aarch64 Linux; 샌드박스가 활성화된 Chromium snap; 사설 X 디스플레이를 위한 Xvfb; WebRTC 경로를 위한 PipeWire, WirePlumber 및 GStreamer 플러그인; MSE 및 AirPlay 경로를 위한 하드웨어 HEVC 인코딩이 가능한 FFmpeg; 고정된 로컬 모델(약 10 GB의 가중치)을 위한 CUDA 지원 GPU 및 Python 3.12.
- TV: 시스템(root) 접근 권한이 있고 패키지 설치에 대한 승인된 방법이 있는 webOS TV. 네이티브 캡처(Native capture) 또한 정확한 펌웨어 빌드와 일치하는 툴체인 및 헤더가 필요합니다.
- 네트워크(Network): TV와 호스트가 동일한 LAN에 연결되어 있어야 합니다. 처리량(throughput)과 지터(jitter)를 측정하십시오. 명목 링크 속도만으로는 재생 품질을 보장할 수 없습니다.
로컬 빌드 (Build locally)
cp config/example.json config.local.json
python3 tools/build.py --config config.local.json --output dist/local --include-tests
출력물에는 서명되지 않은 Home 패키지, 렌더링된 호스트 서비스, TV 서비스 소스 및 파일 매니페스트가 포함됩니다. 빌드 과정은 소프트웨어를 설치하거나 장치와 통신하지 않습니다. 출력 디렉토리는 새롭고 비어 있어야 합니다.
브라우저 바로 가기를 활성화하려면, 사설 기능 키(private capability key)를 생성하여 빌드에 전달해야 합니다:
umask 077
python3 -c 'import secrets; print(secrets.token_hex(32), end=
```sh
python3 -B -m unittest discover -s tests
node tests/test_protection_proof.js
node tests/test_home_core.js
...
UI 테스트에는 Playwright의 Chromium이 사용됩니다:
npm ci --ignore-scripts
npx --no-install playwright install chromium
npm run test:home
...
완벽한 오프라인 점검 목록은 CI 워크플로우에 나와 있습니다. 오프라인 점검은 물리적인 비디오 캐던스, 마이크 품질 또는 다른 펌웨어 빌드와의 호환성을 확립하지 않습니다.
호스트 배포 (Deploy the host)
서비스 계정이 소유한 버전별 디렉터리로 완전하게 렌더링된 spark/ 트리를 스테이징한 다음, 세션 관리자를 활성화하기 전에 프리플라이트(preflight)를 실행합니다:
python3 -B "$RENDERED_SPARK/runtime/trial.py" --run --preflight-only
RENDERED_SPARK는 스테이징된 디렉터리를 가리킵니다. 프리플라이트는 샌드박스, 디스플레이/오디오, 콘텐츠 보호, DNS 및 정리(cleanup)를 점검합니다. 패키지를 설치하거나 TV 재생을 검증하지 않습니다. 일반적인 호스트 설치 프로그램은 없으며, 의존성 설치와 서비스 감독(service supervision)은 호스트 관리 영역입니다.
런타임은 자체 기능 키와 선택적 음성 구성을 $HOME/.local/share/baaz-browser/ 아래에 유지합니다. baaz-browser는 호환성을 위해 유지되는 레거시 런타임 디렉터리 이름입니다. 해당 파일들은 개인 디렉터리에 모드 0600으로 보관하십시오. 거주 음성(Resident voice) 또한 고정된 모델 스냅샷, TLS 자격 증명 및 로컬 페어링된 TV 제어를 필요로 하므로 음성 백엔드를 참조하십시오.
TV에 설치 (Install on the TV)
웹OS 패키지 워크플로우를 통해 Home 패키지를 설치하고 먼저 일반 애플리케이션으로 테스트하십시오. Home 및 유휴(idle) 경로 변경은 별도의 단계입니다: 오프라인 Home 플래너는 펌웨어에서 캡처된 상태로부터 후보군과 롤백 페이로드를 생성합니다.
음성 캡처는 로컬 캡처 활성화 계약(local-capture activation contract)을 따릅니다. 공개 빌더는 장치 접근 권한을 얻거나, 시스템 파일을 패치하거나, 서비스를 활성화하지 않습니다. 원본 파일과 복구 경로는 UI 재시작으로 종료되는 어떤 프로세스 외부에도 보관하십시오. 그런 다음 리모컨, 기존 앱, 브라우저 재생, 연속 음성 입력(consecutive voice presses), 대기 모드/재개(standby/resume), 전원 순환(power cycling)을 확인하십시오.
소스 맵 (Source map)
| Path | Purpose |
|---|
tv/home/ | 홈 애플리케이션 템플릿 (Home application templates) |
| ... | |
| 장치 구성(device configuration), 키(keys), 펌웨어 이미지(firmware images), 및 런타임 데이터(runtime data)는 버전 관리 시스템 외부로 유지하십시오. 보안 경계 및 보고는 SECURITY.md에 있습니다. | |
라이선스 (License)
프로젝트 코드는 MIT 라이선스를 따릅니다(LICENSE.md). 브라우저 확장 프로그램, 필터 도구 및 데이터, 그리고 두 개의 런타임 어댑터(runtime adapters)는 GPL-3.0 또는 그 이후 버전입니다. THIRD_PARTY_NOTICES.md에 해당 구성 요소와 상위 기여 목록이 나와 있습니다.