tvOS: desarrollo para Apple TV con Focus Engine

¿Qué es tvOS?

tvOS — el sistema operativo de Apple para decodificadores Apple TV, basado en el mismo núcleo Darwin XNU que iOS. Lanzado por primera vez el 30 de octubre de 2015 con el Apple TV de 4ª generación. tvOS reemplazó al obsoleto Apple TV Software (basado en iOS, sin App Store ni SDK). El sistema está optimizado para funcionar en televisores con resolución de hasta 4K HDR (Dolby Vision) y sonido Dolby Atmos.

Según Apple (WWDC 2025), tvOS está instalado en Apple TV HD (2015), Apple TV 4K (2017, 2021, 2022) y está integrado en algunos modelos de Smart TV a través de AirPlay. Apple TV utiliza los chips A8 (HD), A10X Fusion (4K 1ª gen.), A12 Bionic (4K 2ª gen.) y A15 Bionic (4K 3ª gen.). Todos los modelos son compatibles con tvOS 17. tvOS no tiene cámara, micrófono (excepto el mando), pantalla táctil ni GPS.

La característica clave de tvOS es Focus Engine, que reemplaza el control táctil con navegación por enfoque. El usuario mueve la selección entre elementos de la interfaz con el Siri Remote. Los desarrolladores crean aplicaciones en Swift/SwiftUI (nativas) o JavaScript/TVML (aplicaciones multimedia como Netflix, Hulu).

Historial de versiones de tvOS

tvOS 9 (2015) — primera versión con SDK y App Store. tvOS 10 (2016) — inicio de sesión único (SSO) para suscripciones de cable. tvOS 11 (2017) — soporte para Amazon Prime Video y modo automático. tvOS 12 (2018) — Dolby Atmos. tvOS 13 (2019) — modo multiusuario. tvOS 17 (2023) — FaceTime, VPN, perfiles de audio por HDMI.

Arquitectura de tvOS y diferencias con iOS

La arquitectura de tvOS se basa en la misma pila que iOS: núcleo XNU, servicios del sistema Core Services, capa multimedia Media y capa de usuario Cocoa Touch. Sin embargo, existen diferencias significativas relacionadas con las especificidades de la plataforma de TV.

Limitaciones de hardware

El Apple TV 4K de 3ª generación utiliza A15 Bionic con 6 núcleos de CPU (2 de rendimiento, 4 de eficiencia) y una GPU de 5 núcleos. RAM — 4 GB (almacenamiento SSD interno desde 64 GB). El sistema no tiene almacenamiento local persistente en el sentido clásico: todos los datos de las aplicaciones pueden ser eliminados por tvOS cuando falta espacio (purgeable). El desarrollador debe usar iCloud Key-Value Storage o CloudKit para conservar el estado.

TVMLKit y TVJS

TVMLKit — un framework único de tvOS que permite crear interfaces en JavaScript y TVML (lenguaje similar a XML específico de Apple). TVMLKit carga JSON/XML desde el servidor y renderiza componentes de interfaz nativos. Es la tecnología principal para servicios de streaming: Netflix, Hulu, Amazon Prime Video usan TVMLKit. TVJS — un entorno JavaScript que se ejecuta en un contexto aislado.

Falta de almacenamiento persistente

tvOS gestiona automáticamente el espacio en disco: cuando falta espacio, el sistema puede eliminar la caché, los recursos descargados e incluso la propia aplicación (conservando el icono). Al reabrirse, la aplicación debe restaurar su estado. iCloud NSUbiquitousKeyValueStore es el único almacenamiento persistente garantizado para configuraciones (hasta 1 MB por aplicación).

import Foundation

// // Conservación y restauración del estado en tvOS
final class StateManager {

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

    // Guardando el progreso de visualización
    func saveProgress<T: Codable>(_ value: T, for key: String) {
        if let data = try? coder.encode(value) {
            store.set(data, for: key)
            store.synchronize()
        }
    }

    // Restaurando el estado después de eliminar la caché
    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)
    }

    // Manejando notificación de cambio en otro dispositivo
    init() {
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(ubiquitousKeyValueStoreDidChange),
            name: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
            object: store
        )
    }

    @objc
    private func ubiquitousKeyValueStoreDidChange(_ notification: Notification) {
        print("Datos modificados en otro dispositivo")
    }
}

El StateManager utiliza NSUbiquitousKeyValueStore para guardar el estado de la aplicación en tvOS. Dado que el almacenamiento local puede ser limpiado por el sistema, solo iCloud garantiza la persistencia de los datos. store.synchronize() envía los datos inmediatamente al servidor, mientras que didChangeExternallyNotification notifica a la aplicación sobre cambios desde otros dispositivos del usuario.

Focus Engine: navegación y enfoque

Focus Engine — el mecanismo clave de tvOS que reemplaza los eventos táctiles con navegación por enfoque. El usuario mueve la selección entre elementos de la interfaz usando el Siri Remote (superficie táctil o botones). El sistema calcula automáticamente el siguiente elemento de enfoque basándose en la distancia y la dirección del movimiento.

UIFocusEnvironment y jerarquía de enfoque

Cada elemento de la interfaz capaz de recibir enfoque implementa el protocolo UIFocusEnvironment. UIKit determina automáticamente el orden de navegación basándose en la geometría de los elementos. El desarrollador puede anular el enfoque preferido mediante preferredFocusEnvironments, especificar un array de focusEnvironment secundarios y controlar el movimiento a través de UIFocusHeading (up, down, left, right). UIFocusGuide permite establecer rutas personalizadas para diseños no triviales.

UIFocusEffect y paralaje

tvOS añade automáticamente UIFocusEffect al elemento enfocado: sombra, resaltado y efecto de paralaje (desplazamiento al inclinar el mando). El desarrollador puede desactivar el efecto mediante focusedValue o personalizarlo a través de UIFocusEffect.transform. En SwiftUI, el paralaje se añade con el modificador .hoverEffect(.highlight).

import SwiftUI

// // Componente tvOS con enfoque personalizado
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 {
            // Manejando el botón Play/Pause en el mando
            startPlayback()
        }
        .focusable()
        .focusEffect { phase in
            // Efecto de enfoque personalizado
            phase == .active ?
                AnyView(self.scaleEffect(1.08)) :
                AnyView(self.scaleEffect(1.0))
        }
    }

    private func startPlayback() {
        print("Reproduciendo: \(movie.title)")
    }
}

// // Pantalla principal con cuadrícula de películas
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() // Agrupación para la navegación
    }
}

MovieCardView demuestra el Focus Engine en SwiftUI: el modificador .focusable() hace que el elemento sea enfocable, .onHover rastrea los cambios de estado, .focusEffect permite animar el enfoque personalizado. .onPlayPauseCommand maneja la pulsación del botón Play/Pause en Siri Remote. focusSection agrupa una cuadrícula para navegación cíclica.

Siri Remote: gestos y botones

El Siri Remote de segunda generación (2021) tiene una superficie táctil, 5 botones y un micrófono. tvOS admite gestos: deslizamientos (navegación), toque (seleccionar), doble toque (centrar), pellizco-zoom (imágenes), pulsación larga (menú contextual). UIPress con tipos .select, .playPause, .menu, .upArrow, .downArrow, .leftArrow, .rightArrow — tipos de pulsación predefinidos. El micrófono del mando se usa para Siri y búsqueda por voz.

Top Shelf y pantalla de aplicaciones

Top Shelf es un área en la pantalla principal de Apple TV que muestra contenido dinámico de la aplicación cuando está en la fila superior. En tvOS 17, Top Shelf admite hasta 8 widgets con fondos personalizados y elementos interactivos. El desarrollador implementa TVTopShelfProvider para proporcionar contenido.

Estilos de Top Shelf

Hay tres estilos de Top Shelf disponibles: Sectioned — lista categorizada (series por género), Inset — elemento central con descripción detallada (película recomendada), Photo — cuadrícula de imágenes (álbumes de fotos). El sistema actualiza Top Shelf en segundo plano mediante BGTaskScheduler, similar a watchOS. El proveedor debe devolver contenido rápidamente — tvOS almacena en caché los datos durante 24 horas.

Pantalla de aplicaciones

La pantalla principal de tvOS consta de una fila de Top Shelf y una cuadrícula de aplicaciones. Los usuarios pueden reorganizar iconos y crear carpetas. tvOS descarga automáticamente las aplicaciones de la memoria cuando faltan recursos, por lo que los desarrolladores deben manejar correctamente UISceneDidDisconnectNotification y restaurar el estado al reiniciar.

SwiftUI para Apple TV

SwiftUI es totalmente compatible con tvOS desde tvOS 13. Apple recomienda SwiftUI para todos los proyectos nuevos. El mismo código SwiftUI funciona en iOS, iPadOS, macOS y tvOS con adaptaciones mínimas para Focus Engine. SwiftUI para tvOS proporciona los modificadores .focusable(), .focusSection(), .onPlayPauseCommand y .onExitCommand.

Adaptación a tvOS

Al portar una aplicación de iOS a tvOS, es necesario: reemplazar TabView con NavigationView con navegación por enfoque, aumentar el tamaño de las fuentes (mínimo 30pt para títulos, 22pt para texto), añadir márgenes (mínimo 40pt de los bordes — área segura en televisores). tvOS no admite UIAlertController con campo de texto, UIWebView ni MFMailComposeViewController.

Recomendaciones de diseño

HIG de Apple para tvOS: tamaño mínimo del área táctil 60×60 puntos, texto legible desde 3 metros (tamaño de fuente no menor de 22pt para cuerpo), contraste de texto 4.5:1, fondo oscuro (el fondo claro produce reflejos en pantallas OLED), todos los elementos accesibles sin gestos complejos. Resolución: Apple TV 4K emite 3840×2160 (4K) o 1920×1080 (HD) a 60 FPS. Todas las imágenes deben estar en @2x (para 1080p) y @4x (para 4K).

TVMLKit y aplicaciones multimedia

TVMLKit — un framework para crear aplicaciones multimedia en tvOS usando tecnologías web: JavaScript (TVJS) y TVML (XML específico de Apple). Las aplicaciones TVMLKit no requieren compilación — la interfaz se carga desde el servidor, lo que permite actualizar el contenido sin pasar por App Review. Es utilizado por los principales servicios de streaming para carruseles de contenido.

TVML: estructura de plantillas

TVML proporciona plantillas listas para usar: CatalogTemplate (catálogo con secciones), ProductTemplate (página de detalle de contenido), FormTemplate (formularios de inicio de sesión), LoadingTemplate (indicador de carga). Las plantillas se describen en XML y se estilizan mediante atributos similares a CSS. El código TVJS maneja las pulsaciones y llama a las API nativas.

<!-- CatalogTemplate — catálogo de películas en TVML -->
<document>
  <catalogTemplate>
    <banner>
      <title>Estrenos de cine</title>
      <description>Estrenos recientes y exclusivas</description>
    </banner>
    <section>
      <header>
        <title>Popular</title>
      </header>
      <items>
        <lockup>
          <img src="https://cdn.example.com/movie1.jpg" width=300 height=450/>
          <title>Interestelar</title>
        </lockup>
        <lockup>
          <img src="https://cdn.example.com/movie2.jpg" width=300 height=450/>
          <title>Origen</title>
        </lockup>
      </items>
    </section>
  </catalogTemplate>
</document>

La plantilla TVML CatalogTemplate contiene un banner con un título y secciones con elementos lockup. Cada lockup es una tarjeta de película con imagen y título. Focus Engine gestiona automáticamente la navegación entre elementos lockup. Al pulsar, el controlador TVJS recibe el evento select y puede mostrar una página de detalle mediante ProductTemplate.

TVJS: manejo de eventos

TVJS es un entorno JavaScript aislado de la aplicación principal. El código TVJS se llama al cargar una plantilla TVML y manejar eventos. TVJS tiene acceso a las API nativas a través de Appliance y Player para controlar la reproducción de video. Apple recomienda usar TVMLKit solo para aplicaciones multimedia con actualizaciones frecuentes de contenido. Para juegos y aplicaciones interactivas, se prefiere SwiftUI.

Publicación de aplicaciones tvOS

Publicar una aplicación tvOS requiere una suscripción al Apple Developer Program ($99/año). La aplicación se sube a través de App Store Connect como producto independiente o como parte de un binario universal (iOS + tvOS). App Review verifica la estabilidad, el cumplimiento de HIG y el límite de tamaño de 4 GB.

Compilación y distribución

Xcode crea un destino tvOS con extensión .app (paquete .ipa). Arquitectura — arm64 (Apple TV usa chips ARM de Apple Silicon). tvOS no admite frameworks con i386 o x86_64. La aplicación se firma con un certificado Apple Development (pruebas) o Apple Distribution (publicación). Es posible la distribución a través de Volume Purchase Program para clientes empresariales.

Requisitos de App Review

Requisitos especiales de tvOS: todos los elementos de la interfaz deben ser accesibles a través de Focus Engine sin usar pantalla táctil ni teclado. Las aplicaciones que requieren autorización deben admitir inicio de sesión único (SSO) a través de iTunes Store. El contenido publicitario no puede interrumpir la reproducción sin el consentimiento del usuario. El tamaño del binario cargado no debe superar los 4 GB.