Surviving tvOS: An Engineering Log of an Atypical Media Player

If you are just writing a Demo, tvOS actually looks easy; but as soon as you try to build an App that requires long-term maintenance and faces a real user environment, you will quickly discover: tvOS has never been just a magnified iPad.

It has almost no reliable local persistent storage, and data can be cleared or processes killed by the system at any time; the entire interaction model centers on Focus, with no browser and no WebView, yet at the player level, it deeply relies on the entire Web world. From a design perspective, tvOS is essentially a display terminal, not a workstation.

Syncnext happens to be an atypical example: it is not a custom player serving a single backend, but an attempt to face the real and chaotic network environment on tvOS. This article is not a tutorial, but an engineering log, organizing the design trade-offs and realistic compromises made to “survive” on this platform.

If you are considering making a tvOS App that is more than just a Demo, these experiences might help you avoid some detours.

I. Core Interaction Philosophy: Non-Contact Operation

The UI/UX concept of tvOS is distinct from “touch” systems or “mouse-mode” systems. You need to think using Game UX concepts. On console platforms, the controller interaction model is the primary reference for developing tvOS Apps.

1. Focus Engine vs. SwiftUI @FocusState

In tvOS development, you will encounter two focus systems:

• Focus Engine: Centered around UIKit, the native solution designed specifically for tvOS.
• SwiftUI @FocusState: Centered around the entire Apple platform, a cross-platform state management system.

Please note, they are products of completely different concepts. Although the interaction forms are similar, the logic is different.

• Common Trap: You can use both @FocusState and Focus Engine to highlight two focuses on the UI simultaneously, but the “real focus” recognized by the system is only the instruction of your last operation.

2. Deep Remote Support

tvOS remotes are mainly divided into two generations:

1. Siri Remote (1st Gen): Touchpad dominant.
2. Siri Remote (2nd Gen): Physical buttons + Touch ring.

If you don’t care about older users who prefer the old remote, you can simply use standard SwiftUI modifiers. But if you pursue the ultimate experience, you need to use the Game Controller Framework to go deep into the RAW layer to process input signals.

• Reference: Practical example of “Game Controller Framework” in the project

II. System Limits & Survival Guide

1. Harsh Storage Environment

• No Persistent Storage: You do not have permission to write to the Document directory; you can only write to the Cache folder.
• Data Loss at Any Time: When tvOS detects that storage space is tight, the system will randomly delete the App’s Cache data. If your App relies on a local SQLite database as its core, this will be catastrophic.
  • Common Phenomenon: “Because your Apple TV ran out of space, the database of this App was deleted.”
  • Suggested Check: Are Aerial screensavers/iCloud Photos enabled? Is the cache for Infuse/SenPlayer set to memory mode?

2. Missing Web Capabilities

• No Browser: tvOS has no WebView, only a JavaScriptCore framework. Concepts relying on DOM operations cannot be realized here.

3. Network & Device Differences

• IPv6 Priority: Under the same LAN, a situation may occur where a phone can access the API, but tvOS cannot due to IPv6 strategies.
• Compute Power Gap: The performance difference between Apple TV 4K models (2017, 2021, 2022) is huge. If you create cool visual effects, please be sure to provide an option to “Turn Off Effects” for older devices.

4. Localization & Troubleshooting

• No Simplified Chinese Siri: When using Siri voice input, the system will only recognize and output “Traditional Chinese”. If your API requires Simplified Chinese, you must build a “Traditional-Simplified Conversion” system within the App.
• The Ultimate Solution: If the App fails to launch on some users’ devices (black screen or crash), this is usually not an issue with your code. Please advise the user to “Unplug and Restart” the Apple TV.

III. SwiftUI on tvOS: Practical Workarounds

1. The “Shadow Tactic” for Input Fields

SwiftUI’s TextField on tvOS is both ugly and difficult to use. The solution is the “Shadow Input Method”:

• UI Layer: Use a beautiful Button to build the UI.
• Function Layer: Place a transparent CocoaTextField (UIKit) in the view background.
• Interaction: When the button is clicked, call textField.becomeFirstResponder() to summon the keyboard.

2. Navigation & State Management

• Searchable Throttling: tvOS triggers search based on input frequency; be sure to implement throttling and cache results.
• Custom NavigationLink: SwiftUI’s native navigation lacks flexibility. It is recommended to encapsulate a .navigate(using:destination:) modifier to implement “state-driven” navigation transitions.

3. The Necessity of TVUIKit

SwiftUI’s .card style often gives a “knock-off” feel. To develop an App with an official quality, you need to encapsulate TVUIKit components:

• Typography: Use UILabel for precise line height control; use UITextView for scrolling reading with the remote.
• Visuals: Use TVPosterView to get native parallax and focus effects.
• Input: Use TVDigitEntryViewController to implement native numeric passcode input.

4. The Disaster of Mixing Focus Systems

When mixing SwiftUI with UITableView on tvOS, SwiftUI’s focus prediction mechanism often conflicts with the actual height of the list, causing focus misalignment. The solution is usually to take over the Focus system of UITableView directly.

• Reference: Focus errors when mixing UITableView and SwiftUI

5. Developer Experience Optimization

• Debug Input: Text cannot be entered efficiently during development. It is recommended to use #if DEBUG macros to wrap dedicated buttons that fill in test keywords with one click.
• Visual Debugging: Use a custom debugOnlyModifier to highlight the size and position of Views.
  • Gist: View+debugOnlyModifier
• Further Reading: My Fuck SwiftUI Notes

IV. Player Core Technical Details

1. Silky Progress Bar Interaction

Implemented based on UIPanGestureRecognizer. The touchpad of the TV remote is not a mouse and cannot map displacement directly.

• Virtual Damping: Set a proportional coefficient of location / 5. This “feel value” scales the displacement non-linearly, ensuring precise positioning down to the second even in long videos.
• Real-time Feedback: The status must drive the UI Overlay directly during sliding to achieve “What You See Is What You Get”.

2. Dual UI Overlay & Back Button Logic

The logic of the Menu (Back) button is multi-dimensional and requires a state machine:

1. State A (UI Showing): If focus is on a button, press Menu -> Focus returns to the progress bar.
2. State B (Focus on Progress Bar): Press Menu -> Hide UI.
3. State C (UI Hidden): Press Menu -> Exit playback.

3. AVPlayer Tuning

AVPlayer is a “brute force” network player by default and needs targeted tuning:

• Reduce Latency:

player?.automaticallyWaitsToMinimizeStalling = true
player?.currentItem?.preferredForwardBufferDuration = 0 // Recommended for Live/Stream

• Local File Specialization:

// If local file
automaticallyWaitsToMinimizeStalling = false
preferredForwardBufferDuration = 1

• HLS Support: AVPlayer mandates HTTP(s) protocols. If you need to dynamically rebuild m3u8, you must use a Local Server (Recommended framework: Swifter).
• Dynamic Background: If using AVPlayer for dynamic backgrounds, be sure to set AVAudioSession to .ambient to avoid interrupting system audio.

4. Custom Dismiss Behavior

In newer versions of tvOS, AVPlayer’s response to dismiss has changed. It is recommended to rewrite the dismiss logic, checking in order: presentingViewController (dismiss) -> navigationController (pop) -> removeFromParent.

V. Data Synchronization Strategy

Not Recommended: CoreData with CloudKit

From the perspective of 2026, I do not recommend using the CoreData with CloudKit solution. It has never solved the problem of Space Inflation, and the risk is extremely high on tvOS, which lacks persistent storage.

Recommended: sqlite-data

I recommend using sqlite-data as an iCloud support solution. It has been tested in the TracklyReborn project and performs stably and controllably.

• GitHub: pointfreeco/sqlite-data

VI. Postscript: About eisonAI

Before ending this hardcore tvOS engineering record, I want to introduce my latest work — eisonAI.

This is an App about “Memory” and “Flow”. We often encounter situations where we can’t find things we’ve seen, or our thoughts get messy as soon as we write them down. eisonAI introduces the concept of Cognitive Index™: it remembers not just “content”, but “utility”. It acts like a librarian in your brain, automatically filing inspiration, background data, and citations, protecting your thought flow from being interrupted.

• App Store: Download eison
• GitHub: qoli/eisonAI
• Demo Video: YouTube Shorts | Full Story