Which storage capacity key should be used for offline video downloads: volumeAvailableCapacityKey or volumeAvailableCapacityForImportantUsageKey?

Question

Created 1d

Replies 1

Boosts 0

Participants 1

I’m trying to understand which storage capacity key is the correct one to use when deciding whether my app can start downloading offline video content.

I read the documentation here: https://developer.apple.com/documentation/foundation/checking-volume-storage-capacity

but I still don’t fully understand the intended usage difference between:

volumeAvailableCapacityKey
volumeAvailableCapacityForImportantUsageKey

My app allows users to download videos for offline viewing. These downloads may remain on the device for a long time (days or even months), so they are not just temporary cache files.

On one hand, this seems to match the description of “storing data based on a user request”, which suggests using volumeAvailableCapacityForImportantUsageKey.

On the other hand, my understanding is that this value may assume the system is willing to aggressively purge caches and reclaim space for this “important usage”. I’m worried this could lead to unexpected or unpleasant side effects for the user if my app relies on that space.

What confuses me even more is that the values are significantly different on my device:

iPhone Settings reports about 142 GB free
volumeAvailableCapacityKey returns only ~56 GB
volumeAvailableCapacityForImportantUsageKey returns ~132 GB

So my question is:

For an app that downloads videos for offline playback — where the user explicitly requested the download, but the content may stay on device for a long time — which value is the recommended one to use when deciding whether there is enough free space to start the download?

Should offline media downloads generally be treated as “important usage” in the sense intended by this API?

Boost

Answer 1

KseniiaGonta OP

2h

I did some additional testing on my second device and noticed behavior that seems interesting, but I’m not sure whether I’m interpreting it correctly.

Case 1:

iPad Settings reports ~20 GB free
volumeAvailableCapacityKey returns ~7.6 GB
volumeAvailableCapacityForImportantUsageKey returns ~19.3 GB

Case 2 (after I intentionally downloaded a large amount of content to fill up the device storage):

iPad Settings reports ~215 MB free
volumeAvailableCapacityKey returns ~157 MB
volumeAvailableCapacityForImportantUsageKey returns ~197 MB

What surprised me is that in the first case, volumeAvailableCapacityForImportantUsageKey is very close to the value shown in Settings, while volumeAvailableCapacityKey is much lower.

But in the second case, when the device is almost full, all three values become much closer to each other.

Am I understanding correctly that as the device runs out of storage, the system has less reclaimable/purgeable space available, so the different capacity estimates start converging because there is simply less content that iPadOS can optimize or clean up automatically?

Another interesting observation is that after reaching the values from Case 2, content downloads in many apps effectively stopped working.

For example:

Netflix appeared to start downloading, but nothing actually happened
Some other apps with content downloading also stopped downloading videos without showing any error
App Store no longer allowed installing apps because of insufficient storage
Xcode once failed to install my app onto the device because there was not enough space available

What confuses me is that all of the reported values were still greater than zero.

At the same time, ~215 MB free space is the absolute minimum I managed to reach on the device, so perhaps iPadOS has some kind of internal storage reservation or minimum writable threshold that is not reflected directly in these APIs?

0