Metadata cache keeps clearing!

Current Understanding of the Issue Surrounding Recurring Deletions of Infuse’s Metadata Cache

Part 1 (of 2): WHY IT HAPPENS

According to Apple’s own tvOS developer documentation (linked below), APPLE is the party responsible for deleting Infuse’s metadata cache, and APPLE is the party responsible for preventing Firecore’s developer’s from doing anything about it.

  1. Apple TV apps are not allowed to protect more than 500KB of user data from summary deletion.
  • For Infuse, this is only enough space to preserve the connection details to users’ media shares and iCloud accounts (the latter being used for essential user data backups and multi-device syncing), users’ favorited folders and customized homescreen views, users’ selected settings options, and users’ custom media collections and playlists.
  • Infuse requires far more space to build its metadata databases, especially when users enable the pre-caching of images (which I highly recommend once you’ve completed the steps in Part 2).
  • Many (if not a plurality of) users have an Infuse metadata cache that measures in GBs.
  1. tvOS automatically manages both the caching of automatically downloaded content and the purging of cached content whenever it determines device storage is low.

Local Storage for Your App Is Limited

The maximum size for a tvOS app bundle [is] 4 GB. Moreover, your app can only access 500 KB of persistent storage that is local to the device (using the NSUserDefaults class). Outside of this limited local storage, all other data must be purgeable by the operating system when space is low. You have a few options for managing these resources:

  • Your app can store and retrieve user data in iCloud.
  • Your app can download the data it needs into its cache directory. Downloaded data is not deleted while the app is running. However, when space is low and your app is not running, this data may be deleted. Do not use the entire cache space as this can cause unpredictable results.

The above applies to all apps — not just Infuse. Game environments get wiped and need to be reloaded all the time, too. The difference is gamers are accustomed to waiting while games download and configure unique game content before each session or event; Infuse is not a game with multiple levels of complexity, so users do not expect this — even though the underlying reasons tvOS apps can’t securely cache (or pre-cache) their user environments on the device are the same in each case.

  1. Infuse’s metadata cache (therefore) is data vulnerable to deletion.
  • For Infuse to function as well as it does, it needs to build extensive metadata databases and this requires Infuse to cache a lot of data.
  • It’s natural for Infuse users to expect those meticulously constructed databases to persist over multiple sessions regardless of other activities on the AppleTV.
  • Unfortunately, Apple does not offer developers like Firecore the ability to safeguard that amount of data from deletion — Apple’s reasoning would probably be this: “If we let Firecore do it, then we’d have to let everyone do it. It’d be chaos!! There’d be no room left for us to sell more apps and in-app purchases!
  1. Automatic downloads of updated versions of iOS software, apps, and third-party apps may displace vulnerable data.

  2. Automatic downloads of new screensavers may displace vulnerable data.

  3. Users’ newly downloaded apps may displace vulnerable data.

  4. Any other apps’ newly cached data may displace Infuse’s vulnerable data, such as:

  • a gaming app downloading new game environments, characters, vehicles, tools, puzzles, or entirely new gameplay levels.
  • a streaming video app pre-caching high-bitrate downloads (up to 10s of GBs/hour for highest quality 4K) while you watch them
  1. Apple offers no easy way to determine the actual amount of truly free-space there is on a device; as data vulnerable to deletion appears to be reported as free space.
  • It is in Apple’s self-interest to display the largest possible number when reporting free space, because users who see they have lots of free space will download more apps.
  • A full device can’t download more apps — preventing Apple from earning additional revenue through the selling of new apps (and new in-app purchases).
  • This is (at least in part) why Apple helpfully manages the automatic off-loading of users’ less frequently used apps, to make space for new apps they know you’ll just love to buy.
  1. Apple offers no easy way to determine how much space is actually used by any particular app, because cached data is not included in the app’s displayed usage (which is only the installed file size of the downloaded app itself).

  2. Apple offers no way to determine how much space is used by the downloaded screensavers on any given device — and this is usually far more than most people expect.

  3. Apple’s screensavers themselves are cached data vulnerable to deletion (as they CAN be forced off the device, same as Infuse’s cached data can) and perhaps this is why there is no easy method provided for purposefully deleting them.

  • Unfortunately, Apple’s screensavers seem to hold priority status over all third-party apps’ cached content.
  • This is likely because Apple wants nothing to get in the way of all the pretty pictures and videos that show off users’ high-quality, high-resolution displays so well … and few apps like Infuse are noticeably affected by cached data being deleted.


Okay, smart guy: but why does this never happen with Netflix or Plex or (insert app here)?

  • Netflix and Plex (plus all other streaming apps, and many premium gaming apps) are client apps that depend on connecting to off-device servers which do the heavy lifting of managing users’ accounts, creating and updating the apps’ user-interface, remembering users’ app settings, watchlists, and playlists; sourcing and displaying all media content metadata (both textual and image-based); as well as doing all the heavy lifting of sourcing, encoding, and streaming content to one’s AppleTV.
  • Infuse is an app, that unlike Plex / Emby / Jellyfin / Netflix and all those others, does not require an off-device server app in order to function — and it does not have one.
  • Infuse therefore must, while constrained to only utilizing the hardware and software resources made available to them by Apple on the Apple devices on which Infuse is installed, perform all the functions of both a client and server (without a server). It does this job rather well, considering the complexity of the task and the limitations imposed on it.

Fair enough. So why doesn’t Firecore create its own server software, like Plex?

  • You’d have to ask them, but I suspect the answer would be, “that’s waaay harder than you think — and not the kind of software we strive to be. We like being an app that sets-up and works easily, all by itself on your Apple device, without needing to deal with any of the sort of shenanigans involved in setting up and configuring independent client and server applications.
  • However, if using your own metadata server is important to you, that’s why we allow you to use Infuse as a client connected to your Plex, Emby, or Jellyfin server; and also why we allow you to sync Infuse data with your Tract account.”

Fine. But that doesn’t answer why Firecore won’t allow users to move Infuses’s metadata cache off of our AppleTVs where it might randomly be erased, and onto the devices or cloud services of our choice, such as the ones where we currently store our media. Firecore at least ought to be able to do that, right?

  • I don’t know. People have been alternatively asking, begging, or demanding that Firecore do that exact thing for a really long time.
  • it’s probably faaar harder to implement and support than people assume, given the multitude of different devices and cloud services running different operating systems in different release editions and version revisions while using any number of different communication protocols; plus the need to be secure persistent write permissions (while simultaneously avoiding the hazard of overwriting users’ existing data due to any possible glitches somewhere along the line); and the need to have to spend only the gods know how many hours responding to tech-support complaints from users who just can’t seem to get it to work on their very unique hardware / software / service configuration.

In Part 2, I’ll discuss the numerous steps users can take to prevent their AppleTVs from deleting Infuse’s metadata cache.