문제 해결
디버깅 연결, 설치와 런처 전환을 확인하기 위한 실용적인 점검 방법입니다.
개발자 옵션을 찾을 수 없습니다
설정 → 시스템 또는 기기 환경설정 → 정보에서 찾아보세요. Build 항목을 일곱 번 누릅니다. 메뉴 이름은 제조사마다 다릅니다. 관리되는 기기나 인터넷 서비스 제공업체가 제공한 기기에서 디버깅 제어가 잠겨 있다면 이 펌웨어에서는 이 흐름을 사용할 수 없을 수 있습니다. 펌웨어 제한을 해결하려고 라우터 설정을 계속 바꾸지 마세요.
컴퓨터에서 TV를 찾지 못합니다
- TV가 켜져 있고 두 기기가 같은 로컬 네트워크에 있는지 확인하세요. 게스트 Wi-Fi나 격리된 IoT 네트워크에서는 기기 간 통신이 막힐 수 있습니다.
- TV 네트워크 설정에서 현재 IP 주소를 다시 확인하세요. 재부팅 후 주소가 바뀔 수 있습니다.
- TV에 해당 스위치가 있다면 USB 디버깅과 네트워크/ADB 디버깅을 켜세요. TV에 표시되는 인증 대화상자를 확인하고 신뢰하는 컴퓨터만 승인하세요.
- 일부 Google TV 모델은 5555 포트를 바로 여는 대신 무선 디버깅 페어링 코드와 임시 포트를 사용합니다. 설치 프롬프트의 페어링 단계를 따르세요.
- 인터넷 라우터를 통해 ADB 포트를 포워딩하지 마세요.
macOS에서는 “No route to host” 메시지가 로컬 네트워크 개인정보 설정 때문에 나타날 수 있습니다. 소스 패키지에는 대안으로 사용할 Python ADB 클라이언트가 들어 있습니다. 소스 패키지를 압축 해제한 뒤 TV가 오프라인이라고 단정하기 전에 docs/TROUBLESHOOTING.md의 Connecting 항목을 읽어 보세요.
USB 스피커나 드라이브가 작동하지 않습니다
일부 TV 박스는 USB 디버깅이 켜져 있는 동안 USB 포트 동작을 변경합니다. 작업이 끝나면 디버깅을 끄고 기기를 다시 확인하세요. 일상적인 사용을 위해 런처에서 디버깅을 계속 켜 둘 필요는 없습니다.
런처 빌드 또는 APK 설치에 실패했습니다
개별 APK나 빌드 파일만 다운로드하지 말고, 전체 소스 패키지를 압축 해제해 사용하세요. Python 3, JDK 17, Android SDK Platform 34, Android Build Tools 34.0.0을 준비합니다. 검증을 끄거나 관련 없는 APK를 설치하지 말고 실제 오류를 확인하세요. 일부 TV 펌웨어는 설치 중 화면에서 확인을 요청하기도 합니다.
소스 패키지에서 압축을 푼 README.md와 docs/TROUBLESHOOTING.md가 빌드 준비 조건과 모델별 문제를 확인하는 참고 자료입니다. 함께 제공되는 Windows 빌드 스크립트와 macOS/Linux 빌드 스크립트는 압축을 푼 launcher/ 디렉터리에 넣어야 합니다.
Home 버튼을 눌러도 이전 런처가 열립니다
앱을 설치하는 것과 Home 소유자로 지정하는 것은 서로 다른 단계입니다. 먼저 새 런처가 열리는지 확인하세요. 실제로 Home을 처리하는 구성 요소를 어시스턴트가 확인하고 정확한 모델의 안내를 따르게 하세요. 전환하는 동안 작동하는 런처를 활성화해 두세요. 이름이 관련 있어 보인다는 이유만으로 추측하거나 시스템 패키지를 비활성화하지 마세요.
리모컨, 오디오, HDMI 또는 캐스팅이 바뀌었습니다
변경을 중지하고 최근 패키지 변경 사항을 원래 백업과 비교하세요. 이러한 기능은 제조사 서비스에 의존할 수 있습니다. 해당하는 복원 절차를 사용한 다음 각 기능을 따로 테스트하세요.
스트리밍 앱에 광고가 계속 표시됩니다
예상된 동작입니다. 이 프로젝트는 시스템 홈 화면과 일부 제조사 서비스를 변경합니다. YouTube, Netflix 또는 다른 스트리밍 앱 안의 광고나 구독 요구 사항을 제거하지 않습니다.
공개 issue에 포함할 내용
모델, 지역, 펌웨어 버전, 실패한 단계와 민감한 정보가 제거된 오류 메시지를 공유하세요. 공개 보고서에는 개인 주소, 기기 식별자, 디버깅 키, 자격 증명과 전체 백업을 포함하지 마세요.