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<Download>,
        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)