Offline Downloads

Offline Downloads

Orchard Mobile can download tracks for permanent offline playback. This is a feature of Orchard Mobile only; Orchard desktop has a Song Cache instead, which is a different thing.

Downloads compared to the cache

Both keep audio on the device, and they behave very differently.

	Stream cache	Downloads
Created by	Playing a track	Explicitly requesting a download
Removed by	Automatic eviction when the size limit is reached	Only by you
Size limit	Yes, 256 MB to 8192 MB	None
Survives running low on space	No	Yes
Works with no network	Only if the track happens to still be cached	Yes, by design

If you want specific music guaranteed to be there on a plane or a commute, download it. The cache is an optimization, and eviction can remove anything from it at any time.

Downloading

Request a download from a track's menu. The download is queued, and Orchard processes the queue in the background.

Three tracks download concurrently. Requesting an album queues everything and works through it three at a time rather than saturating the connection.

Each individual track is fetched in parallel byte ranges: 512 KB chunks distributed across six concurrent workers. This is substantially faster than a single sequential stream, because a single connection to YouTube's CDN is often throttled well below the available bandwidth. If the server refuses ranged requests or does not report a content length, Orchard falls back to a plain sequential download.

Download states

Each download moves through an explicit lifecycle:

Status	Meaning
QUEUED	Accepted and waiting for a free worker
DOWNLOADING	Actively fetching, with live progress and byte counts
COMPLETED	On disk and playable offline
PAUSED	Suspended, resumable
FAILED	Stopped, with the error message retained

Progress, bytes downloaded, and total bytes are tracked per item, so a partially finished download reports a real percentage rather than a spinner.

Failures keep their error message rather than discarding it, which is what makes a failed download diagnosable instead of just red.

Browsing offline

Downloads are not just a flat list. When the catalog is unreachable, Orchard synthesizes browse pages from what you have downloaded, using downloaded tracks plus your cached library metadata. Album and artist pages still work with no network at all.

Artist pages built this way contain only the tracks you actually downloaded, so an offline artist page is an honest view of what you can play rather than a list of things that will fail when tapped.

Storage

Downloads live in the app's external files directory, falling back to internal storage if that is unavailable. Because this is app-scoped storage, downloads are removed when you uninstall Orchard, and they are not visible to other apps or your gallery.

Downloaded audio keeps whatever container the stream used, most commonly WebM.

Managing downloads

Individual downloads can be cancelled while in progress, and removed once complete. Removal is available in bulk as well, so clearing out an album does not mean tapping through every track.

Removing a download deletes the file. It does not affect the stream cache, your library, or your playback history.

Interaction with audio quality

A download captures the stream that your audio quality setting selects at download time. Downloading on Data Saver and later switching to High does not upgrade what is already on disk; remove and re-download for that. See Orchard Mobile Settings.

Interaction with Smart Crossfade

Downloaded tracks analyze the same way streamed ones do, so Smart Crossfade and Best Mix work normally offline. Analysis runs on the device from the audio itself, so it needs no network.

Source map

Path	Role
mobile/.../download/DownloadManager.kt	Queue, concurrency, cancellation, reactive state
mobile/.../download/TrackDownloader.kt	Ranged parallel fetch and sequential fallback
mobile/.../download/DownloadStore.kt	On-disk persistence and file locations
mobile/.../download/DownloadModels.kt	Status lifecycle and item model
mobile/.../download/OfflineDetailSynthesizer.kt	Browse pages built from downloads
mobile/.../download/DownloadPlaybackHelper.kt	Playing from a downloaded file