aerial-tv 딥다이브
— 리모컨 한 번 뒤에 숨은 Android 시스템 설계

1프로젝트 한줄 요약

aerial-tv는 Android TV의 홈 화면을 tvOS에서 영감을 받은 앱 타일·배경화면·화면보호기로 바꾸는 오픈소스 앱입니다. 설치된 동영상 서비스를 대신 재생하는 서비스가 아니라, 그 앱을 찾아 실행하는 출발점입니다. Android 패키지 이름은 app.orchard.tv이고, 사용자에게 보이는 이름은 Aerial입니다.

이 저장소의 가장 좋은 공부거리는 화면을 그리는 코드와 TV 펌웨어의 제약을 다루는 코드가 한 제품 안에서 만나는 과정입니다. Kotlin 파일 51개, 주석·빈 줄을 포함해 11,644줄이므로 작은 예제보다는 크지만, 처음부터 여러 서버를 띄워야 하는 서비스보다 전체 흐름을 따라가기 쉽습니다.

1-1. 사용자 행동을 코드에 대응시키기

파일 경로는 저장소 루트 기준입니다. 주요 Kotlin 구현은 app/src/main/java/app/orchard/tv/ 아래에 있으며, app/src/main/java/app/orchard/tv/apps/Apps.kt는 앱 검색과 타일 구성을 담당합니다.

2왜 주목받는가

2-1. 선정 사실과 인기의 원인에 대한 해석을 구분하기

선정 근거는 TrendShift Daily #12이며 분석일은 2026-10-23입니다. 2026-10-23 GitHub 기준, 2026-10-20에 생성된 저장소의 스타는 3,403개, 포크는 248개입니다. 생성일은 공개 저장소의 생성 시점이며, 전체 개발 기간이나 모든 코드가 사흘 만에 작성됐다는 증거는 아닙니다.

관심을 끄는 이유로는 광고·추천 피드가 없는 단순한 홈 화면, 익숙한 tvOS 계열 시각 언어, 중국 시장용 TV의 설치·대기 복귀 문제를 다루는 실용성을 들 수 있습니다. 이는 README의 제품 설명과 소스 구조를 바탕으로 한 분석자의 해석입니다. 방문자 유입 경로나 스타를 누른 사람의 동기를 측정한 결과는 아닙니다.

제품의 매력은 간결한 화면에 있고, 학습 가치는 그 간결함을 유지하기 위해 처리한 시스템 예외에 있습니다.

2-2. 어떤 대안과 비교해야 할까?

위 표는 제품 범주와 Aerial의 구현 범위를 비교합니다. 다른 런처의 성능·가격·전체 기능을 조사한 순위표는 아닙니다. Aerial의 구체적인 차별점은 app/build.gradle.kts의 두 빌드 변형과 app/src/main/java/app/orchard/tv/guard/의 복귀 로직에서 확인할 수 있습니다.

2-3. “광고 없음”의 정확한 범위

README는 광고와 추천 피드가 없는 홈 화면을 내세웁니다. 소스에서도 홈 UI는 설치 앱·입력 소스·시계·배경화면을 중심으로 구성되고, 의존성 목록에는 광고 SDK가 선언되어 있지 않습니다. 그러나 TV 펌웨어가 띄우는 부팅 광고까지 제거한다는 뜻은 아닙니다. README도 부팅 광고가 남는다고 명시합니다.

또한 MainActivity.idleBeforeScreensaver()는 제조사 화면보호기보다 먼저 앱의 화면보호기를 띄우도록 시간을 조정합니다. 이는 홈 화면에 있을 때의 동작이며, 모든 앱 위에서 제조사 광고 화면보호기를 전역 차단하는 구조는 아닙니다.

2-4. “설치 성공” 이후까지 이어지는 설계

• 처음 실행: HomeViewModel.offerSetupOnce()가 기본 홈 상태와 권한을 보고 설정 안내를 제안합니다.
• 대기 후 복귀: RevivalListener와 RevivalSync가 시스템 재바인딩을 이용하는 복구 경로를 제공합니다.
• 업데이트: Updates.install()이 APK를 받아 검사를 거친 뒤 TV의 시스템 설치기를 엽니다.
• 문제 보고: app/src/main/java/app/orchard/tv/system/Diagnostics.kt와 기기별 문서로 환경 차이를 기록합니다.

3기술 스택 전체 지도

3-1. 프론트엔드: 네이티브 TV UI와 작은 웹 페이지

주 화면은 브라우저가 아니라 Jetpack Compose로 그립니다. MainActivity.onCreate()에서 setContent를 호출해 HomeScreen()을 올리고, HomeViewModel이 앱 목록과 오버레이 상태를 보유합니다. 휴대폰 설정 화면만 app/src/main/assets/web/index.html이라는 HTML 자산입니다.

표의 버전은 app/build.gradle.kts의 선언값입니다. 이 파일의 주석은 해당 BOM이 Compose 1.9.5를 사용하며 Android 5.0 지원을 유지하기 위한 선택이라고 설명합니다. BOM 선언값과 소스 주석의 개별 버전 설명은 구분해 읽어야 합니다.

3-2. 백엔드: TV 프로세스 안의 설정용 서버

독립적인 클라우드 API 서버나 회원 DB는 없습니다. 대신 PhoneServer가 TV 안에서 NanoHTTPD 2.3.1을 이용해 포트 8790의 HTTP 요청을 처리합니다. ZXing Core 3.5.3은 이 서버로 가는 QR 코드를 만듭니다. 서버를 직접 호스팅할 별도 PC는 필요하지 않습니다.

저장소에는 package.json, Cargo.toml, pyproject.toml, go.mod, Dockerfile이 없습니다. 저장소의 중심은 단일 Android :app 모듈입니다. site/의 배포용 웹 페이지와 TV가 제공하는 휴대폰 페이지는 위치와 수명이 다른 화면입니다.

3-3. 인프라·빌드: 오래된 TV 지원이 버전을 결정한다

// app/build.gradle.kts의 핵심 설정 발췌
android {
    compileSdk = 36
    defaultConfig {
        minSdk = 21
        targetSdk = 34
        versionCode = 39
        versionName = "1.37"
    }
    flavorDimensions += "home"
    productFlavors {
        create("standard") { dimension = "home" }
        create("guard") {
            dimension = "home"
            versionNameSuffix = "-guard"
        }
    }
}

의존성 버전은 최신이라는 이유만으로 올리는 것이 아니라, 제품이 지원해야 할 가장 오래된 운영체제와 함께 결정해야 합니다. 이 저장소의 빌드 주석과 docs/HANDOFF.md는 Android 5.0 지원 때문에 Compose·Media3 업그레이드에 주의하라고 설명합니다.

웹 배포는 wrangler.jsonc의 assets.directory = "./site"를 사용하는 Cloudflare Worker 정적 자산 방식입니다. tools/deploy-site.sh는 릴리스 APK와 도구를 복사한 뒤 npx wrangler@4 deploy를 호출합니다. 여기서 @4는 정확한 패치 버전 고정이 아닙니다. 현재 .github/에는 이슈 템플릿이 있고 .github/workflows/의 CI 설정은 없습니다.

릴리스 서명은 local/signing.properties가 있으면 그 키를 사용하고, 없으면 로컬 debug 키로 대체합니다. 키 파일은 저장소에 없습니다. 이 설정만으로 공개 APK의 실제 서명 키를 확인할 수는 없으며, 같은 패키지에 덮어쓰려면 서명 연속성이 필요합니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조

Aerial의 주요 기능은 TV의 앱 프로세스 안에서 실행됩니다. Android 시스템이 Activity·Service·Receiver로 이벤트를 전달하고, UI는 로컬 앱 목록과 저장된 배치를 결합합니다. 휴대폰 설정은 같은 프로세스의 서버로 들어오는 별도 입력 통로입니다.

주목할 점은 UI 계층이 모든 일을 직접 하지 않는다는 것입니다. MainActivity는 생명주기와 앱 실행을, HomeViewModel은 표시할 상태와 사용자 의도를, AppCatalog·LayoutStore는 목록과 배치를 담당합니다. 다만 별도의 domain 모듈이나 DI 프레임워크로 엄격하게 분리된 구조는 아닙니다.

4-2. 패턴 ① 상태를 올려 두고 화면은 그 상태를 읽는다

app/src/main/java/app/orchard/tv/HomeViewModel.kt에는 apps, hiddenApps, folderApps, overlay, movingKey가 있습니다. mutableStateOf로 만든 관찰 가능한 상태를 HomeScreen()이 읽습니다. 화면 조작은 moveBy(), hide(), onHomePressed() 같은 함수로 이어집니다.

이 구조를 MVVM 계열의 상태 분리로 이해할 수 있습니다. Compose의 상태와 단방향 데이터 흐름에 대한 일반 원리는 Android 공식 상태 문서에서도 설명합니다. 이 저장소에서는 ViewModel 외에 Wallpapers 같은 전역 객체도 상태를 보유하므로, 모든 상태가 한 곳에 모인 구조라고 일반화하면 안 됩니다.

// app/src/main/java/app/orchard/tv/HomeViewModel.kt의 실제 선언 일부
sealed interface Overlay {
    data object None : Overlay
    data class ControlCenter(val page: CcPage = CcPage.Main) : Overlay
    data class Folder(val id: String) : Overlay
    data object HiddenApps : Overlay
    data object Wallpaper : Overlay
}

// 목록 이동의 흐름을 줄여 표현한 설명용 의사코드
사용자_방향입력(delta)
    → HomeViewModel.moveBy(delta)
    → LayoutStore.move(key, target)
    → arrange()
    → apps 상태 변경
    → HomeScreen이 새 순서 표시

Overlay에는 이 발췌 외에 앱 메뉴와 PIN 입력 상태도 있습니다. 여러 개의 참·거짓 변수로 패널 열림을 표현하는 대신, 하나의 sealed interface 값으로 현재 패널의 종류와 필요한 데이터를 함께 표현합니다. “제어판도 열려 있고 폴더도 열린” 조합을 별도로 조정할 부담이 줄어듭니다.

reload()는 이전 loadJob을 취소하고 새 작업을 시작합니다. AppCatalog.load()는 Dispatchers.Default에서 실행되고, 입력 소스 조회도 withContext(Dispatchers.Default)로 옮깁니다. 이어 arrange()가 설치 앱과 고정 입력 소스를 합쳐 사용자 배치에 적용합니다.

LayoutStore.arrange()는 앱의 표시 이름 대신 패키지 기반 key로 순서를 유지합니다. 폴더에는 folder:, 입력 소스에는 input: 접두사를 써 앱 패키지와 구분합니다. 업데이트 중 앱이 잠깐 목록에서 사라져도 저장된 키는 남겨, 복귀했을 때 원래 위치를 찾도록 설계했습니다.

4-3. 패턴 ② 리모컨 입력을 작은 상태 기계로 다룬다

Pressable()은 단순히 “확인 키를 받으면 실행”하지 않습니다. PressState에 focused, pressed, byKey를 보관하고, 이 컨트롤에서 시작한 키 누름만 키를 뗄 때 클릭으로 인정합니다. 키 반복 이벤트는 최초 누름과 구분합니다.

// app/src/main/java/app/orchard/tv/ui/components/Pressable.kt의 핵심 로직 발췌
KeyEventType.KeyDown -> {
    if (e.nativeKeyEvent.repeatCount == 0) {
        state.pressed = true
        state.byKey = true
    }
    true
}
KeyEventType.KeyUp -> {
    val was = state.pressed && state.byKey
    state.pressed = false
    state.byKey = false
    if (was) {
        Sounds.select()
        onClick()
    }
    true
}

앱 타일을 길게 눌러 메뉴를 열었다고 상상해 보세요. 키를 뗄 때 포커스는 이미 메뉴 첫 항목으로 옮겨 있을 수 있습니다. 새 항목이 키를 뗐다는 사실만 보고 클릭하면 메뉴가 열리는 순간 원치 않는 명령까지 실행됩니다. 시작한 누름의 소유권을 확인하면 이런 중복 동작을 막을 수 있습니다.

onFocusChanged는 포커스가 빠질 때 누름 상태를 초기화합니다. 터치 입력은 detectTapGestures로 처리하고, byKey는 손가락의 해제가 리모컨 누름 상태를 잘못 끝내지 않도록 구분합니다. 리모컨·마우스·터치가 함께 있는 기기에서 특히 유용한 사고방식입니다.

MainActivity.dispatchKeyEvent()에도 같은 원칙이 보입니다. 화면보호기를 끝낸 키의 KeyDown을 소비하고 swallowKeyUp에 키 코드를 저장해 뒤따르는 KeyUp도 소비합니다. 깨어나려고 누른 한 번의 확인 키가 뒤의 앱까지 실행하지 않게 만드는 것입니다.

4-4. 패턴 ③ 비싼 그림은 미리 만들고, 재사용 조건을 키로 적는다

app/src/main/java/app/orchard/tv/apps/Apps.kt의 entry()는 메모리 캐시를 먼저 보고, 없으면 TileDiskCache.read()를 시도합니다. 둘 다 없거나 조건이 달라졌을 때만 타일을 새로 만듭니다. 생성한 그림은 메모리와 디스크에 저장해 다음 실행에 재사용합니다.

// TileDiskCache.key()가 표현하는 유효성 조건을 풀어 쓴 도식
타일 키 =
  stamp
  | TileArtFactory.W
  | TileArtFactory.unified
  | Locale.getDefault().toLanguageTag()
  | BuildConfig.VERSION_CODE

// stamp는 app/src/main/java/app/orchard/tv/apps/Apps.kt에서 두 수정 시각을 더한 값
stamp = 패키지의 lastUpdateTime + CustomIcons.stamp(pkg)

// 타일 파일이 완성된 뒤 최종 이름으로 바꾼다
임시 파일에 key·label·그림 기록
    → 출력 스트림 닫기
    → renameTo(최종 파일)
    → 다음 시작에서 key가 같을 때만 읽기

TileDiskCache.write()는 SupervisorJob() + Dispatchers.IO의 별도 코루틴에서 PNG와 메타데이터를 기록합니다. read()가 손상된 파일을 읽다 실패하면 null로 돌아가 새 그림을 만들 수 있게 합니다. 캐시는 정답의 유일한 저장소가 아니라 다시 만들 수 있는 결과를 보관하는 곳입니다.

Wallpapers.loadBaked()는 마지막 배경을 시작 시 바로 보여 주고, 필요하면 최신 배경을 나중에 계산합니다. saveBaked()는 기존 키를 지우고 두 이미지 파일을 쓴 뒤 키를 마지막에 기록합니다. 중간에 기록이 끊긴 결과를 완성된 묶음으로 읽지 않게 하는 간단한 완성 표시입니다.

app/src/main/java/app/orchard/tv/ui/components/SmoothCorners.kt의 smoothMask()는 복잡한 곡선을 CPU에서 비트맵으로 만듭니다. baked()의 접근 순서 기반 캐시는 최대 32개 항목을 유지합니다. 이 파일의 GPU 처리 시간은 소스 주석에 기록된 특정 Xiaomi 기기의 측정값입니다.

캐시 설계의 핵심은 저장 자체보다, 무엇이 바뀌었을 때 결과를 다시 만들어야 하는지 명시하는 데 있습니다.

4-5. 패턴 ④ 표준 기능을 먼저 쓰고, 기기별 대체 경로를 둔다

app/src/main/java/app/orchard/tv/system/SystemState.kt의 SystemProbe.sources()는 표준 프레임워크 입력을 먼저 조회하고, 결과가 비어 있을 때 Konka → TCL → Whaley 경로를 차례로 시도합니다. firstResolvable()는 실행 가능한 첫 설정 화면을 고르며, 후보가 모두 없으면 마지막 후보를 반환합니다. 음량 조절은 adjustStreamVolume이 권한 예외로 실패하면 setStreamVolume을 시도합니다. 공통 API가 있다는 것과 모든 펌웨어에서 똑같이 동작한다는 것은 다릅니다.

기기 이름을 비교하는 DeviceProfile.current()도 존재합니다. 따라서 “모든 호환 처리를 자동 탐지한다”는 설명은 틀립니다. 이 저장소의 규칙은 가능한 기능 탐지를 우선하고, 탐지할 수 없는 하드웨어 매핑 등에 기종별 예외를 남기는 것입니다.

HOME 처리의 분기는 빌드 시점부터 시작합니다. app/src/standard/AndroidManifest.xml만 CATEGORY_HOME을 추가합니다. guard는 공통 Manifest의 일반 실행 진입점만 사용하고, 권한과 설정이 갖춰졌을 때 접근성 서비스를 통한 복귀를 시도합니다.

takeOverOnceSettled()는 SETTLE_MS = 1500 뒤에 복귀 여부를 확인합니다. 부팅·켜짐 직후 HDMI-CEC가 입력을 열고 있을 수 있으므로, 바로 홈을 덮으면 사용자가 보려던 외부 기기를 가리게 됩니다. goHome()은 화면 꺼짐과 특정 빠른 대기 설정도 확인합니다.

updateKeyFilter()의 실제 조건도 중요합니다. Android 11 이하이고, 해당 TV가 키 통과 대상이 아니며, Aerial이 기본 HOME이 아닐 때 필터를 요청합니다. Android 12 이상에서는 이 경로의 필터를 쓰지 않고 창 이벤트와 homekey 사유의 브로드캐스트를 활용합니다. 일부 오래된 기기 문서에 있는 “기존 런처 방문 중에만 필터” 설명보다 현재 함수 조건이 더 정확합니다.

MainActivity.bringBackIntent()에는 CATEGORY_HOME을 넣지 않습니다. ACTION_MAIN과 작업 플래그를 사용해 기존 작업을 복귀시키며, 공통 Manifest의 launchMode="singleTask"와 함께 동작합니다. 제조사 TV에서 HOME 카테고리를 붙여 새 작업이 생기고 포커스가 초기화되던 문제를 피하려는 설계입니다.

4-6. 휴대폰 설정과 영상 재생을 흐름으로 검증하기

PhoneServer.start()는 서버가 없을 때 SecureRandom으로 8자리 토큰을 만들고, QR에는 TV 주소·8790 포트·토큰 경로를 넣습니다. serve()는 토큰 접두사를 검사한 뒤 api/state, api/upload, api/icon 등의 요청을 분기합니다. 설정 반영은 runBlocking(Dispatchers.Main)으로 메인 스레드에서 마친 뒤 응답합니다.

WallpaperSheet()는 패널이 열릴 때 서버를 시작하고, 닫힌 뒤 5분이 지나면 정지시킵니다. 아직 실행 중인 서버를 다시 쓰면 토큰도 재사용하므로, 아키텍처 문서의 “패널을 열 때마다 새 토큰” 설명과는 차이가 있습니다. 업로드의 MAX_UPLOAD는 200MiB이지만, 현재 사전 검사는 선언된 Content-Length를 기준으로 합니다. 이를 모든 전송 방식에 대한 강제 스트리밍 제한으로 해석해서는 안 됩니다.

AerialStream.player()는 무음·반복 재생, 연결 5초·읽기 8초 타임아웃, 재시도 정책과 버퍼 목표를 설정합니다. 기본 계열 24MiB, 4K 32MiB, Dolby Vision 48MiB는 버퍼 목표값이며 프로세스 전체 메모리 상한이 아닙니다. Media3 공식 문서의 구성 요소 교체 방식이 이 코드에서 어떻게 쓰이는지 비교해 볼 수 있습니다.

prepareOpener()는 다음 영상 후보의 앞 8MiB와 뒤 1MiB를 미리 받습니다. 뒤쪽에는 MP4 인덱스가 있다는 소스 설명에 따른 최적화입니다. 재생 중인 영상을 제외한 후보에서 준비된 도입부가 3개 미만이면 하나를 추가로 준비하며, 디스크 캐시는 48MiB LRU로 제한합니다. 재생 경로는 setCacheWriteDataSinkFactory(null)이라 전체 영상을 재생하면서 계속 저장하지 않습니다.

5디렉토리 구조 해부

아래 트리는 저장소 루트 기준의 핵심 경로를 보여 줍니다. Android 앱의 구현과 자산은 app/에 모여 있습니다. local/은 문서와 빌드에서 참조하는 비공개 환경 경로입니다.

5-1. 폴더 이름보다 변경 이유를 먼저 본다

site/만 고쳐서는 휴대폰 설정 화면이 바뀌지 않습니다. 반대로 app/src/main/assets/web/index.html을 고쳐도 배포 홈페이지는 바뀌지 않습니다. 파일 확장자가 같다는 이유로 같은 화면 계층이라고 생각하지 않는 연습이 필요합니다.

5-2. 추적 파일 기준 코드 규모

표는 git ls-files에 나오는 추적 파일 중 UTF-8 텍스트의 물리적 줄 수입니다. 주석과 빈 줄을 포함하며 이미지·폰트·바이너리·.git은 제외합니다. HTML 안의 내장 JavaScript는 HTML에 포함되므로 위 수치는 언어 파서 기준의 순수 코드 줄 수가 아닙니다.

app/src/main/assets/cities-cn.tsv는 데이터 3,940줄이고, app/src/main/assets/aerials.json은 한 줄로 압축된 JSON이며 videos 배열에 114개 항목이 있습니다. 데이터 행 수와 구현 코드 크기를 합쳐 프로젝트가 더 복잡한 것처럼 표현하지 않는 것이 좋습니다.

6학습 포인트 (기술별)

6-1. Kotlin: 널 가능성과 닫힌 상태 모델

AppEntry는 일반 앱·입력 소스·폴더를 하나의 타일 모델로 나타냅니다. source: TvSource?와 folder: Folder?는 해당 종류가 아닐 때 null입니다. 반면 Overlay는 가능한 패널 종류를 sealed interface로 나눕니다. 같은 프로젝트 안에서 두 모델링 방식을 비교할 수 있습니다.

읽을 질문: launchIntent()는 입력 소스가 있을 때와 일반 앱일 때 어떻게 갈라질까요? folderEntry()의 패키지 필드가 실제 앱 패키지가 아닌 폴더 키인 이유는 무엇일까요? 이름보다 필드가 실제로 쓰이는 위치를 추적해 보세요.

작은 실습: “일반 앱 / 입력 소스 / 폴더”를 각각 하나씩 종이에 만들고 key, source, folder, 실행 경로를 표로 적으세요. 다음 단계로 별도 학습 프로젝트에서 이를 sealed interface Tile로 바꾼 모델과 비교해 볼 수 있습니다.

6-2. Compose: 상태의 수명과 포커스

Pressable() 안의 누름 상태는 remember로 보관합니다. 홈 전체에서 쓰는 앱 목록은 ViewModel에, 앱 재실행 뒤에도 남아야 하는 순서는 LayoutStore의 설정 저장소에 있습니다. 이 세 수명을 구별하면 “화면이 다시 계산되자 값이 초기화됐다”는 문제를 더 정확히 설명할 수 있습니다.

작은 실습: focused, movingKey, 앱 순서, 배경 사진 파일을 각각 “컴포넌트가 있는 동안 / 화면 상태 보유자 동안 / 프로세스 재시작 뒤”로 분류하세요. ViewModel이 프로세스 종료까지 자동으로 버텨 주는 저장소라고 생각하지 않는 것이 핵심입니다.

app/src/main/java/app/orchard/tv/ui/home/HomeScreen.kt의 격자는 COLUMNS = 5이고, GridMetrics.slot()이 나머지와 몫으로 열·행을 계산합니다. 스마트폰의 터치 좌표와 달리 TV는 “현재 포커스에서 다음에 갈 곳”이 사용성의 중심이므로 마지막 열·마지막 행·앱 제거 후 포커스를 함께 생각해야 합니다.

6-3. 코루틴: 취소·실행 스레드·순서 보장

HomeViewModel.reload()는 이전 로딩을 취소합니다. Wallpapers.rebuildBackdrop()도 이전 배경 작업을 취소하고 새 배경을 계산합니다. 사용자가 빠르게 선택을 바꿀 때 오래된 결과가 늦게 도착해 새 선택을 덮지 않도록 설계할 때 살펴볼 사례입니다.

작은 실습: 사진 선택 A → 사진 선택 B → A 계산 완료라는 시간선을 그리세요. 취소가 어떤 시점에 확인되는지, CPU 계산이 협조적으로 취소되는지까지 점검하는 것이 다음 단계입니다. cancel() 호출만으로 이미 시작한 모든 처리가 즉시 멈춘다고 가정하면 안 됩니다.

6-4. Android 시스템: 등록·권한·실행 결과는 별개

공통 Manifest에는 접근성 서비스, 알림 리스너, 부팅 수신기, DreamService가 등록되어 있습니다. 그렇다고 등록만으로 권한이 활성화되거나 기본 HOME이 되는 것은 아닙니다. SystemProbe.homeStatus()는 실제 기본 HOME 패키지와 가드 실행 여부를 보고 Default, Guarded, NotDefault를 구분합니다.

작은 실습: “APK 설치됨 / 일반 앱 목록에 아이콘 있음 / HOME 필터 선언됨 / 기본 HOME으로 해석됨 / 가드 서비스 실행 중”을 각각 다른 체크 항목으로 작성하세요. README의 “APK만 USB로 설치하면 홈 복귀는 여전히 기존 런처로 간다”는 설명을 이 구분으로 풀어 보세요.

RevivalListener는 알림 본문 처리 콜백이 아니라 onListenerConnected()를 복구 계기로 사용합니다. RevivalSync도 로그인 서비스가 아닌 로컬 동기화 어댑터를 복구 경로로 씁니다. 이런 방식은 제조사 정책에 의존하므로, 모든 Android 앱의 일반적인 백그라운드 실행 해법으로 외우기보다 해결한 조건을 함께 읽어야 합니다.

6-5. 그래픽: 매 프레임 계산과 한 번 계산의 차이

canvasDensity()는 실제 화면 크기를 기준으로 960×540 설계 좌표계를 확대합니다. 1920×1080 UI이면 배율이 2가 됩니다. 물리 패널이 4K여도 TV가 앱 UI에는 1080p를 보고할 수 있어, UI 해상도와 영상 디코더 능력은 따로 봐야 합니다.

smoothMask()는 크기별 마스크를 미리 만들고, Bitmap.frozen()은 수정 불가 비트맵 복사본을 만듭니다. 배경 명암과 흐림도 Wallpapers.rebuildBackdrop()에서 준비합니다. 이 코드를 통해 CPU 계산·GPU 업로드·프레임당 합성이 서로 다른 비용임을 배울 수 있습니다.

작은 실습: “타일을 그리는 일”을 원본 읽기 → 이미지 분석 → 마스크 생성 → 합성 → 화면 이동으로 나누세요. 어떤 결과는 캐시에 넣을 수 있고 어떤 값은 입력마다 바뀌는지 표시하면 최적화 후보가 보입니다.

6-6. HTTP와 미디어: 한정된 자원을 명시하기

PhoneServer는 인터넷 계정 대신 주소에 포함된 임시 토큰을 사용합니다. installed()는 사용자 아이콘을 적용할 대상을 실제 앱·고정 입력 목록에서 확인합니다. 경로 검사, 입력값 검증, 이미지 크기 처리, 처리 시간은 서로 다른 방어 층이라는 것을 배울 수 있습니다.

AerialFormats.resolve()는 화질 선택과 디코더 지원을 조합해 실제 화질을 고르고, lower()는 실패 시 내려갈 화질을 정합니다. AerialStream에서는 버퍼·타임아웃·캐시를 따로 설정합니다. “네트워크가 느리다”는 문제를 연결 지연·첫 화면 지연·재생 중 고갈로 나누어 생각해 보세요.

초보자가 이 저장소에서 얻을 가장 큰 습관은 기능마다 상태의 소유자, 작업의 수명, 실패 뒤의 경로를 함께 적어 보는 것입니다.

7하드웨어 / 시스템 요구사항

7-1. 실행 환경과 개발 환경

minSdk는 설치 가능한 최소 API이고 targetSdk는 앱이 대상으로 선언한 플랫폼 동작 기준입니다. compileSdk는 컴파일 시 참조하는 API 범위입니다. Android 공식 SDK 선언 문서와 빌드 파일을 같이 읽으면 “SDK 36으로 빌드하니 Android 36 기기만 된다”는 오해를 피할 수 있습니다.

7-2. 영상 화질은 패널·디코더·네트워크를 함께 본다

AerialFormats.probe()는 Android 7.0 이상에서 HEVC의 3840×2160·30fps 지원을 조회하고, Dolby Vision은 추가로 특정 디코더 프로파일과 디스플레이 HDR 지원을 확인합니다. 자동 선택 후에도 실제 재생 오류가 생길 수 있어 하향 경로가 필요합니다. LiveWallpaper는 Dolby Vision의 영상 설정이 홈 타일에까지 적용되는 문제를 피하려고 SDR을 사용한다고 소스 주석에서 설명합니다.

이는 app/src/main/java/app/orchard/tv/wallpaper/Aerials.kt 주석의 추정 전송률이며 최저 회선 요구량을 보장하는 수치는 아닙니다. 영상 구간·서버 응답·Wi-Fi 상태에 따라 여유가 필요합니다. 내장 배경과 로컬 사진을 쓰는 홈 화면 학습에는 항공 영상 재생이 필수가 아닙니다.

7-3. 기기 문서에서 확인되는 지원의 층위

• Xiaomi MiTV-MFTR0: 기기 문서에 Android 14·4GB RAM·32비트 ARM·1080p UI가 기록되어 있습니다. 이는 관찰된 한 기종의 사양입니다.
• TCL MT5879: README와 인수인계 문서의 일상 사용 기기입니다. 설치와 권한 경로에 제조사별 절차가 들어갑니다.
• TCL MT9655: 기기 문서는 APK 설치에 성공해도 홈 화면으로 전환할 권한을 얻지 못한 사례를 기록합니다.
• Hisense VIDAA: README는 부팅 자동 진입이 안 되는 사례를 적습니다. 기기 문서에는 제보 기반의 홈 버튼·입력 관련 제약이 있습니다.
• 비대상 플랫폼: README 기준 LG·Samsung·Huawei Vision 및 Android 4.4 이하는 지원 대상이 아닙니다.

8직접 해볼 수 있는 실습 과제

아래 과제는 별도 학습 사본에서 설계 원리를 익히기 위한 연습입니다. 첫 과제는 개발 도구나 TV 없이도 할 수 있습니다.

# 과제 2의 기대 결과: 설명용 사례
처음: [A, B, C, D]
B를 D 위치로 이동: [A, C, D, B]
D를 B 위치로 이동: [A, D, B, C]
B를 B 위치로 이동: [A, B, C, D]
없는 X를 B 위치로 이동: [A, B, C, D]

# “표시에서 빠짐”과 “저장 순서에서 삭제”를 분리한다
저장 순서: [A, B, C, D]
현재 설치: [A, B, D]
표시 결과: [A, B, D]
C 재등장 뒤 표시: [A, B, C, D]

좋은 실습 결과물은 기능을 하나 늘린 화면뿐 아니라, 그 기능이 잘못 작동하면 안 되는 조건을 설명하는 작은 모델입니다.

9관련 기술 심화 학습 로드맵

주당 4~6시간을 쓰는 학습 계획입니다. 이미 아는 내용은 건너뛰어도 됩니다. “51개 파일을 모두 읽기”보다 매주 하나의 설명 가능한 결과물을 만드는 것이 목표입니다.

9-1. 기초가 막힐 때 되돌아갈 순서

1. 문법이 낯설다: data class, object, sealed interface, ?., ?:부터 정리합니다.
2. UI가 왜 바뀌는지 모르겠다: mutableStateOf를 쓰는 값 하나를 정하고 읽는 함수와 쓰는 함수를 연결합니다.
3. 실행 순서가 헷갈린다: 동기 호출, 코루틴 시작, delay, 시스템 콜백을 서로 다른 줄에 놓고 시간선을 그립니다.
4. 기기 예외가 많다: 표준 Android 경로를 먼저 설명한 다음 예외가 들어오는 위치만 덧붙입니다.
5. 최적화가 어렵다: 원본 읽기·계산·업로드·화면 합성을 나눈 뒤 재사용 가능한 결과부터 표시합니다.

9-2. 마지막 주의 확장 프로젝트

별도 프로젝트에서 “앱처럼 생긴 가짜 타일 10개를 정렬하는 화면”을 만들어 보세요. 실제 앱 조회나 HOME 권한 없이도 상태 모델·리모컨 입력·이동·숨김·폴더·캐시 키를 연습할 수 있습니다. 그 다음 실제 Android 패키지 조회를 붙이면 시스템 의존성을 분리하는 이유를 체감할 수 있습니다.

전체 Aerial을 복제하는 것이 목표는 아닙니다. 선택한 설계 하나를 다른 맥락에서 설명하고 재현할 수 있다면, 그 부분을 배운 것입니다. 기기별 가드 코드는 마지막 확장 주제로 남겨 두어도 됩니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소와 분석한 소스

• 공식 GitHub 저장소 · 현재 프로젝트 진입점
• 분석한 커밋의 전체 파일 · 이후 변경과 구분할 기준
• README의 기능·설치·지원 기기 설명
• v1.37 릴리스 · 2026-10-23 GitHub 기준 최신 릴리스
• 앱 SDK·의존성·flavor·서명 설정
• HomeViewModel의 상태·목록 갱신 흐름
• Pressable의 누름·뗌·포커스 처리
• 타일 디스크 캐시의 읽기·쓰기·키
• Media3 재생·영상 도입부 캐시
• 휴대폰 설정 서버의 라우팅·토큰·업로드
• HOME 복귀·키 필터·부팅 후 판단
• 아키텍처 문서 · 소스와 대조하며 읽기
• 인수인계·기기 검증·알려진 제약 기록
• 기기별 조사 문서 · 기종·펌웨어·제보 범위 확인

11-2. 개념을 확장할 공식 문서

• Android 공식: Compose 상태와 상태 끌어올리기 · ViewModel과 UI의 데이터 흐름을 이해할 때
• Android 공식: ExoPlayer 구성 요소 맞춤화 · 데이터 소스·로딩·재시도 설정을 읽을 때
• Android 공식: 최소 SDK와 타깃 SDK · 기기 지원 버전의 의미를 확인할 때
• Kotlin 공식 문서 · 언어 문법과 타입을 보충할 출발점
• Android 개발자 문서 · Intent·서비스·권한·생명주기를 더 공부할 출발점
• NanoHTTPD 공식 저장소 · TV 내부의 작은 HTTP 서버 구현 배경
• ZXing 공식 저장소 · QR 생성 라이브러리
• TrendShift · 이 글의 저장소 선정 맥락

11-3. 현재 상태 (2026-10-23 확인)

저장소 메타데이터는 2026-10-23 GitHub 기준이며, 버전 설정·구조·코드 규모·테스트·CI 항목은 커밋 12ca103 기준입니다.

11-4. 설명 문서와 현재 구현이 어긋나는 곳

변경 속도가 빠른 저장소에서는 설명 문서가 현재 코드보다 늦을 수 있습니다. 반대로 소스에 분기가 있다는 사실만으로 그 기기에서 실제로 작동했다고 단정할 수도 없습니다. 의도는 문서에서, 현재 조건은 코드에서, 검증 범위는 기기별 기록에서 따로 확인하는 습관이 필요합니다.