tvOS: Focus Engine을 사용한 Apple TV 개발

tvOS란?

tvOS — Apple TV 셋톱박스용 Apple의 운영 체제로, iOS와 동일한 Darwin XNU 커널을 기반으로 합니다. 2015년 10월 30일 4세대 Apple TV와 함께 처음 출시되었습니다. tvOS는 구형 Apple TV Software(iOS 기반, App Store 및 SDK 없음)를 대체했습니다. 이 시스템은 4K HDR(Dolby Vision)까지의 해상도와 Dolby Atmos 사운드로 TV 작동에 최적화되어 있습니다.

Apple(WWDC 2025)에 따르면 tvOS는 Apple TV HD(2015), Apple TV 4K(2017, 2021, 2022)에 설치되어 있으며 AirPlay를 통해 일부 Smart TV 모델에 내장되어 있습니다. Apple TV는 A8(HD), A10X Fusion(1세대 4K), A12 Bionic(2세대 4K) 및 A15 Bionic(3세대 4K) 칩을 사용합니다. 모든 모델이 tvOS 17을 지원합니다. tvOS에는 카메라, 마이크(리모컨 제외), 터치스크린 또는 GPS가 없습니다.

tvOS의 주요 기능은 Focus Engine으로, 터치 제어를 포커스 내비게이션으로 대체합니다. 사용자는 Siri Remote를 사용하여 UI 요소 간에 선택을 이동합니다. 개발자는 Swift/SwiftUI(네이티브) 또는 JavaScript/TVML(Netflix, Hulu와 같은 미디어 앱)로 앱을 만듭니다.

tvOS 버전 역사

tvOS 9(2015) — SDK 및 App Store를 갖춘 첫 번째 버전. tvOS 10(2016) — 케이블 구독을 위한 SSO(싱글 사인온). tvOS 11(2017) — Amazon Prime Video 지원 및 자동 모드. tvOS 12(2018) — Dolby Atmos. tvOS 13(2019) — 다중 사용자 모드. tvOS 17(2023) — FaceTime, VPN, HDMI를 통한 오디오 프로필.

tvOS 아키텍처 및 iOS와의 차이점

tvOS 아키텍처는 iOS와 동일한 스택을 기반으로 합니다: XNU 커널, Core Services 시스템 서비스, Media 계층 및 Cocoa Touch 사용자 계층. 그러나 TV 플랫폼의 특성과 관련된 중요한 차이점이 있습니다.

하드웨어 제한 사항

3세대 Apple TV 4K는 6개의 CPU 코어(2개 성능, 4개 효율)와 5코어 GPU를 갖춘 A15 Bionic을 사용합니다. RAM — 4GB(64GB부터 내부 SSD 스토리지). 시스템에는 클래식한 의미의 영구 로컬 스토리지가 없습니다: 공간이 부족하면 tvOS가 모든 앱 데이터를 삭제할 수 있습니다(purgeable). 개발자는 상태 보존을 위해 iCloud Key-Value Storage 또는 CloudKit을 사용해야 합니다.

TVMLKit 및 TVJS

TVMLKit — JavaScript 및 TVML(Apple 고유 XML 유사 언어)로 인터페이스를 만들 수 있는 tvOS 고유의 프레임워크입니다. TVMLKit은 서버에서 JSON/XML을 로드하고 네이티브 UI 구성 요소를 렌더링합니다. 이것은 스트리밍 서비스의 주요 기술입니다: Netflix, Hulu, Amazon Prime Video가 TVMLKit을 사용합니다. TVJS — 격리된 컨텍스트에서 실행되는 JavaScript 환경입니다.

영구 스토리지 부족

tvOS는 디스크 공간을 자동으로 관리합니다: 공간이 부족하면 시스템이 캐시, 다운로드된 리소스 및 앱 자체도 삭제할 수 있습니다(아이콘 유지). 다시 열면 앱이 상태를 복원해야 합니다. iCloud NSUbiquitousKeyValueStore는 설정을 위한 유일하게 보장된 영구 스토리지입니다(앱당 최대 1MB).

import Foundation

// // tvOS에서 상태 저장 및 복원
final class StateManager {

    private let store = NSUbiquitousKeyValueStore.default
    private let coder = JSONEncoder()
    private let decoder = JSONDecoder()

    // 시청 진행 상황 저장 중
    func saveProgress<T: Codable>(_ value: T, for key: String) {
        if let data = try? coder.encode(value) {
            store.set(data, for: key)
            store.synchronize()
        }
    }

    // 캐시 삭제 후 상태 복원 중
    func restoreProgress<T: Codable>(_ type: T.Type, for key: String) -> T? {
        guard let data = store.data(for: key) else { return nil }
        return try? decoder.decode(type, from: data)
    }

    // 다른 기기에서 변경 알림 처리
    init() {
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(ubiquitousKeyValueStoreDidChange),
            name: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
            object: store
        )
    }

    @objc
    private func ubiquitousKeyValueStoreDidChange(_ notification: Notification) {
        print("다른 기기에서 데이터 변경됨")
    }
}

StateManager는 tvOS에서 앱 상태를 저장하기 위해 NSUbiquitousKeyValueStore를 사용합니다. 로컬 스토리지는 시스템에 의해 지워질 수 있으므로 iCloud만 데이터 지속성을 보장합니다. store.synchronize()는 즉시 서버에 데이터를 보내고, didChangeExternallyNotification은 사용자의 다른 기기에서 변경 사항을 앱에 알립니다.

Focus Engine: 내비게이션 및 포커스

Focus Engine — 터치 이벤트를 포커스 내비게이션으로 대체하는 tvOS의 주요 메커니즘입니다. 사용자는 Siri Remote(터치 표면 또는 버튼)를 사용하여 UI 요소 간에 선택을 이동합니다. 시스템은 거리와 이동 방향에 따라 다음 포커스 요소를 자동으로 계산합니다.

UIFocusEnvironment 및 포커스 계층 구조

포커스를 받을 수 있는 각 UI 요소는 UIFocusEnvironment 프로토콜을 구현합니다. UIKit은 요소 지오메트리를 기반으로 자동으로 내비게이션 순서를 결정합니다. 개발자는 preferredFocusEnvironments를 통해 기본 포커스를 재정의하고, 하위 focusEnvironment 배열을 지정하며, UIFocusHeading(up, down, left, right)을 통해 이동을 제어할 수 있습니다. UIFocusGuide는 복잡한 레이아웃에 대한 사용자 지정 경로를 설정할 수 있습니다.

UIFocusEffect 및 시차 효과

tvOS는 포커스된 요소에 자동으로 UIFocusEffect를 추가합니다: 그림자, 하이라이트 및 시차 효과(리모컨 기울임에 따른 오프셋). 개발자는 focusedValue를 통해 효과를 비활성화하거나 UIFocusEffect.transform을 통해 사용자 지정할 수 있습니다. SwiftUI에서 시차 효과는 .hoverEffect(.highlight) 수정자로 추가됩니다.

import SwiftUI

// // 사용자 지정 포커스가 있는 tvOS 구성 요소
struct MovieCardView: View {
    let movie: Movie
    @State private var isFocused = false
    @Environment(\.isFocused) var envFocused

    var body: some View {
        VStack(spacing: 8) {
            AsyncImage(url: movie.posterURL) { phase in
                if let image = phase.image {
                    image
                        .resizable()
                        .aspectRatio(contentMode: .fill)
                        .frame(width: 320, height: 180)
                        .cornerRadius(8)
                        .overlay(
                            RoundedRectangle(cornerRadius: 8)
                                .stroke(isFocused ? Color.blue : Color.clear, lineWidth: 3)
                        )
                        .scaleEffect(isFocused ? 1.08 : 1.0)
                }
            }

            Text(movie.title)
                .font(.caption)
                .lineLimit(2)
                .foregroundStyle(isFocused ? .white : .gray)
        }
        .onHover { hovering in
            withAnimation(.spring(response: 0.35)) {
                isFocused = hovering
            }
        }
        .onPlayPauseCommand {
            // 리모컨의 Play/Pause 버튼 처리
            startPlayback()
        }
        .focusable()
        .focusEffect { phase in
            // 사용자 지정 포커스 효과
            phase == .active ?
                AnyView(self.scaleEffect(1.08)) :
                AnyView(self.scaleEffect(1.0))
        }
    }

    private func startPlayback() {
        print("재생 중: \(movie.title)")
    }
}

// // 영화 그리드가 있는 메인 화면
struct MovieGridScreen: View {
    let movies: [Movie]

    var body: some View {
        ScrollView {
            LazyVGrid(columns: [GridItem(.adaptive(minimum: 320, maximum: 400))], spacing: 24) {
                ForEach(movies) { movie in
                    MovieCardView(movie: movie)
                }
            }
            .padding(60)
        }
        .focusSection() // 탐색을 위한 그룹화
    }
}

MovieCardView는 SwiftUI에서 Focus Engine을 보여줍니다: .focusable() 수정자는 요소를 포커스 가능하게 만들고, .onHover는 상태 변화를 추적하며, .focusEffect는 사용자 지정 포커스 애니메이션을 허용합니다. .onPlayPauseCommand는 Siri Remote의 Play/Pause 버튼 누름을 처리합니다. focusSection은 순환 내비게이션을 위해 그리드를 그룹화합니다.

Siri Remote: 제스처 및 버튼

2세대 Siri Remote(2021)에는 터치 표면, 5개의 버튼 및 마이크가 있습니다. tvOS는 제스처를 지원합니다: 스와이프(내비게이션), 탭(선택), 더블 탭(중앙 맞춤), 핀치 줌(이미지), 길게 누르기(컨텍스트 메뉴). UIPress 유형 .select, .playPause, .menu, .upArrow, .downArrow, .leftArrow, .rightArrow — 미리 정의된 누름 유형. 리모컨의 마이크는 Siri 및 음성 검색에 사용됩니다.

Top Shelf 및 앱 화면

Top Shelf는 Apple TV 홈 화면의 영역으로, 앱이 상단 행에 있을 때 동적 콘텐츠를 표시합니다. tvOS 17에서 Top Shelf는 사용자 지정 배경 및 대화형 요소가 있는 최대 8개의 위젯을 지원합니다. 개발자는 콘텐츠를 제공하기 위해 TVTopShelfProvider를 구현합니다.

Top Shelf 스타일

세 가지 Top Shelf 스타일을 사용할 수 있습니다: Sectioned — 분류된 목록(장르별 시리즈), Inset — 상세 설명이 있는 중앙 요소(추천 영화), Photo — 이미지 그리드(사진 앨범). 시스템은 watchOS와 유사하게 BGTaskScheduler를 통해 백그라운드에서 Top Shelf를 업데이트합니다. 제공자는 신속하게 콘텐츠를 반환해야 합니다 — tvOS는 데이터를 24시간 동안 캐시합니다.

앱 화면

tvOS 홈 화면은 Top Shelf 행과 앱 그리드로 구성됩니다. 사용자는 아이콘을 재정렬하고 폴더를 만들 수 있습니다. 리소스가 부족하면 tvOS가 자동으로 메모리에서 앱을 언로드하므로 개발자는 UISceneDidDisconnectNotification을 올바르게 처리하고 다시 시작할 때 상태를 복원해야 합니다.

Apple TV용 SwiftUI

SwiftUI는 tvOS 13부터 tvOS에서 완전히 지원됩니다. Apple은 모든 새 프로젝트에 SwiftUI를 권장합니다. 동일한 SwiftUI 코드가 Focus Engine에 대한 최소한의 적응으로 iOS, iPadOS, macOS 및 tvOS에서 작동합니다. tvOS용 SwiftUI는 .focusable(), .focusSection(), .onPlayPauseCommand 및 .onExitCommand 수정자를 제공합니다.

tvOS 적응

iOS 앱을 tvOS로 포팅할 때: TabView를 포커스 내비게이션이 있는 NavigationView로 교체하고, 글꼴 크기를 늘리고(제목 최소 30pt, 본문 22pt), 여백을 추가합니다(가장자리에서 최소 40pt — TV의 안전 영역). tvOS는 텍스트 필드가 있는 UIAlertController, UIWebView 및 MFMailComposeViewController를 지원하지 않습니다.

디자인 권장 사항

tvOS용 Apple HIG: 최소 터치 영역 크기 60×60포인트, 3미터 거리에서 텍스트 읽기 가능(본문 글꼴 크기 22pt 이상), 텍스트 대비 4.5:1, 어두운 배경(밝은 배경은 OLED TV에서 눈부심 유발), 모든 요소는 복잡한 제스처 없이 접근 가능. 해상도: Apple TV 4K는 60FPS에서 3840×2160(4K) 또는 1920×1080(HD)을 출력합니다. 모든 이미지는 @2x(1080p용) 및 @4x(4K용)여야 합니다.

TVMLKit 및 미디어 애플리케이션

TVMLKit — 웹 기술을 사용하여 tvOS에서 미디어 앱을 만들기 위한 프레임워크: JavaScript(TVJS) 및 TVML(Apple 고유 XML). TVMLKit 앱은 컴파일이 필요하지 않습니다 — 인터페이스가 서버에서 로드되어 App Review 없이 콘텐츠를 업데이트할 수 있습니다. 주요 스트리밍 서비스에서 콘텐츠 캐러셀에 사용합니다.

TVML: 템플릿 구조

TVML은 준비된 템플릿을 제공합니다: CatalogTemplate(섹션이 있는 카탈로그), ProductTemplate(콘텐츠 상세 페이지), FormTemplate(로그인 양식), LoadingTemplate(로딩 표시기). 템플릿은 XML로 설명되고 CSS 유사 속성을 통해 스타일이 지정됩니다. TVJS 코드는 누름을 처리하고 네이티브 API를 호출합니다.

<!-- CatalogTemplate — TVML 영화 카탈로그 -->
<document>
  <catalogTemplate>
    <banner>
      <title>새로운 영화</title>
      <description>새로운 프리미어와 독점</description>
    </banner>
    <section>
      <header>
        <title>인기 콘텐츠</title>
      </header>
      <items>
        <lockup>
          <img src="https://cdn.example.com/movie1.jpg" width=300 height=450/>
          <title>인터스텔라</title>
        </lockup>
        <lockup>
          <img src="https://cdn.example.com/movie2.jpg" width=300 height=450/>
          <title>인셉션</title>
        </lockup>
      </items>
    </section>
  </catalogTemplate>
</document>

TVML CatalogTemplate에는 제목이 있는 배너와 lockup 요소가 있는 섹션이 포함됩니다. 각 lockup은 이미지와 제목이 있는 영화 카드입니다. Focus Engine은 lockup 요소 간의 내비게이션을 자동으로 관리합니다. 누르면 TVJS 핸들러가 select 이벤트를 수신하고 ProductTemplate을 통해 상세 페이지를 표시할 수 있습니다.

TVJS: 이벤트 처리

TVJS는 기본 앱에서 격리된 JavaScript 환경입니다. TVML 템플릿을 로드하고 이벤트를 처리할 때 TVJS 코드가 호출됩니다. TVJS는 Appliance 및 Player를 통해 네이티브 API에 액세스하여 비디오 재생을 제어할 수 있습니다. Apple은 콘텐츠 업데이트가 빈번한 미디어 앱에만 TVMLKit 사용을 권장합니다. 게임 및 대화형 앱의 경우 SwiftUI가 선호됩니다.

tvOS 앱 게시

tvOS 앱 게시에는 Apple Developer Program 구독($99/년)이 필요합니다. 앱은 App Store Connect를 통해 별도 제품 또는 유니버설 바이너리(iOS + tvOS)의 일부로 업로드됩니다. App Review는 안정성, HIG 준수 및 4GB 크기 제한을 확인합니다.

빌드 및 배포

Xcode는 .app 확장자(.ipa 패키지)로 tvOS 대상을 생성합니다. 아키텍처 — arm64(Apple TV는 Apple Silicon ARM 칩 사용). tvOS는 i386 또는 x86_64가 있는 프레임워크를 지원하지 않습니다. 앱은 Apple Development 인증서(테스트) 또는 Apple Distribution 인증서(게시)로 서명됩니다. 기업 고객을 위한 Volume Purchase Program을 통한 배포가 가능합니다.

App Review 요구 사항

tvOS 특별 요구 사항: 모든 인터페이스 요소는 터치스크린이나 키보드 없이 Focus Engine을 통해 접근 가능해야 합니다. 인증이 필요한 앱은 iTunes Store를 통한 싱글 사인온(SSO)을 지원해야 합니다. 광고 콘텐츠는 사용자 동의 없이 재생을 중단할 수 없습니다. 업로드된 바이너리 크기는 4GB를 초과할 수 없습니다.