Media3 Workmanager Offline Ops

Trigger

Use for offline media downloads, download constraints and scheduling, retryable background media operations, or media3-exoplayer-workmanager.

Rules

• Start with media3-background-playback-service and media3-datasources-networking for service and network policy.
• Pin Media3 to 1.10.1 through the version catalog.
• Offline downloads MUST use the official Media3 stack: a DownloadService subclass driven by a singleton DownloadManager, with downloads submitted as DownloadRequest via DownloadService.sendAddDownload. Use DownloadHelper to prepare adaptive (HLS/DASH) downloads and select tracks.
• DownloadIndex (from DownloadManager) is the single source of truth for download state. Track it separately from player state.
• Express constraints (network type, charging, storage) with Media3 Requirements applied through DownloadService.sendSetRequirements, NOT WorkManager Constraints.
• media3-exoplayer-workmanager only provides WorkManagerScheduler, a Scheduler that restarts the DownloadService when pending Requirements are met again. Return it from getScheduler(); that is the entire WorkManager role in downloads.
• Use WorkManager directly only for genuinely custom non-download deferrable work, for example cache cleanup or license refresh sweeps.
• DownloadService MUST be declared with foregroundServiceType="dataSync", which on targetSdk 35+ has a 6-hour runtime cap per app session. Keep downloads resumable; the Scheduler restarts the service later.
• Keep download and cache policy centralized and observable.
• Make cancellation and removal explicit through DownloadService.sendRemoveDownload; stale downloads are product bugs.

Example

media3-exoplayer-workmanager = { module = "androidx.media3:media3-exoplayer-workmanager", version.ref = "media3" }

class MediaDownloadService : DownloadService(NOTIFICATION_ID) {
    override fun getDownloadManager(): DownloadManager = AppDeps.downloadManager
    override fun getScheduler(): Scheduler = WorkManagerScheduler(this, "media3_downloads")
    override fun getForegroundNotification(
        downloads: MutableList,
        notMetRequirements: Int,
    ): Notification = AppDeps.downloadNotificationHelper.buildProgressNotification(
        this, R.drawable.ic_download, null, null, downloads, notMetRequirements)
}

DownloadService.sendAddDownload(
    context, MediaDownloadService::class.java,
    DownloadRequest.Builder(contentId, contentUri).build(), false)

DownloadService.sendSetRequirements(
    context, MediaDownloadService::class.java,
    Requirements(Requirements.NETWORK_UNMETERED), false)

Do Not

• DO NOT hand-roll download Workers; WorkManager cannot own Media3 download state or resumption.
• DO NOT gate downloads with WorkManager Constraints; use Requirements.
• Do not use WorkManager for live playback lifetime.
• Do not start unbounded parallel downloads; cap via DownloadManager.maxParallelDownloads.
• Do not let UI screens own offline queue truth; read DownloadIndex.

Related

• media3-background-playback-service
• media3-datasources-networking
• media3-vod-playback

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sunnat629
• Source: sunnat629/android-media-pack
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.