Caching

You can now cache online media items for future playback on certain platforms. The media player will automatically playback from the cache when a media item is present, otherwise the behaviour will be exactly the same as before with media being played over the internet.

Currently caching is not automatic and you need to specifically request that media is added to the cache.

You can check if the current platform supports caching as follows:

if (mediaPlayer.Cache.IsMediaCachingSupported())
{
    // Caching is supported
}

In order to add media to the cache, call:

mediaPlayer.Cache.AddMediaToCache(url, headers, options);

where:

  • url is the URL of the asset to cache
  • headers are any HTTP headers required to access the asset
  • options are any options to configure how the media is cached:
    • minimumRequiredBitRate the lowest bitrate that is acceptable to cache
    • minimumRequiredResolution the lowest resolution that is acceptable to cache
    • maximumRequiredBitRate the highest bitrate that is acceptable to cache (Android only)
    • maximumRequiredResolution the highest resolution that is acceptable to cache (Android only)

To remove media from the cache, call:

mediaPlayer.Cache.RemoveMediaFromCache(url);

where:

  • url is the URL of the asset to remove

To stop the caching of a media item:

mediaPlayer.Cache.CancelDownloadOfMediaToCache(url)

where:

  • url is the URL of the asset to cancel caching

To pause an active caching download of a media item (Android only):

mediaPlayer.Cache.PauseDownloadOfMediaToCache(url)

where:

  • url is the URL of the asset to pause caching

To resume a paused caching download of a media item (Android only):

mediaPlayer.Cache.ResumeDownloadOfMediaToCache(url)

where:

  • url is the URL of the asset to resume caching

To get the status of media in the cache:

float progress = 0.0f;
CachedMediaStatus status = mediaPlayer.Cache.GetCachedMediaStatus(url, ref progress);

where:

  • url is the URL of the asset to cancel caching
  • progress returns the current progress in the range 0...1 of the download should the returned status be CachedMediaStatus.Caching and status is one of:
  • CachedMediaStatus.NotCached the media is not cached
  • CachedMediaStatus.Caching the media is currently being cached
  • CachedMediaStatus.Cached the media is cached

To see if the currently open media will play or is playing from the cache:

if (mediaPlayer.Cache.IsMediaCached())
{
    // The open media is cached
}

Platform specifics

Android

The following limitiations exist for Android:

  • Storing and playback of media from cache is currently only supported when using the ExoPlayer API path for playback.
  • Cached media items are downloaded to the default external cache folder. They are stored in a proprietary ExoPlayer format and are not readable/usable externally from the ExoPlayer architecture.
  • Only remote video files can be cached to the local file system.
  • HLS/DASH/SmoothStream and MP4 can all be cached.
  • Playback whilst caching is possible but will depend on the available network resources.
  • Currently only caching of clear-key (where the key is included in the manifest) AES encrypted streams is supported.
  • The following MediaCachingOptions will not be supported: title, artwork.

iOS

Cached media items are listed in the Settings app in the iPhone Storage or iPad Storage page of the General section. By default the name given to the items is taken from the URL so it might not be that user friendly. You can use the title and artwork members of the MediaCachingOptions class to provide more user friendly details as follows:

MediaCachingOptions options = new MediaCachingOptions();
options.title = "User Friendly Name";

TextAsset artwork = Resources.Load<TextAsset>("artwork.png");
if (artwork)
{
    options.artwork = artwork.bytes;
}

_mediaPlayer.Cache.AddMediaToCache("https://example.com/media/movie.m3u8", null, options);

The following limitiations exist for iOS:

  • iOS 11.0 and above
  • Only caching of HLS videos is supported, not progressive downloads (i.e. mp4 files).
  • Only caching of VOD streams is supported, Live streams will fail unless the stream has already finished and is complete in the manifest.
  • Playback whilst caching is possible but will depend on the available network resources. Caching is likely to be paused whilst a video is playing in order to maintain the best playback quality for the viewer.
  • Currently only the variants marked as DEFAULT in the playlist will be cached.
  • Cached videos may be removed by the system if storage space is low on the device.
  • Currently only caching of clear-key (where the key is included in the manifest) AES encrypted streams is supported.
  • MediaCachingOptions.minimumRequiredResolution is supported on Android and iOS 14.0 and later only.
  • MediaCachingOptions.maximumRequiredBitRate and MediaCachingOptions.maximumRequiredResolution are not supported.
  • Currently Pause/Resume of an active video caching download is not supported.

macOS / tvOS

Caching is not currently supported on macOS or tvOS.

Windows / UWP

Caching is not currently supported on Windows or UWP.