mirror of
https://github.com/advplyr/audiobookshelf-app.git
synced 2026-07-26 14:38:39 +02:00
[PR #1752] comprehensive background download improvements for Android [NEEDS MORE TESTING ON DIFFERENT DEVICES] #1682
Assignees
adam (Adam Melkus)
Clear assignees
adam (Adam Melkus)
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: starred/audiobookshelf-app#1682
Reference in New Issue
Block a user
📋 Pull Request Information
Original PR: https://github.com/advplyr/audiobookshelf-app/pull/1752
Author: @noobie158
Created: 12/13/2025
Status: 🔄 Open
Base:
master← Head:master📝 Commits (10+)
7650e50[EXPERIMENTAL] Background download improvements - wake locks, resume, storage checks9c81486Merge branch 'advplyr:master' into masterfb226c5Apply suggestion from @Copilot62a64e2Apply suggestion from @Copilot2746f5eApply suggestion from @Copilot0227462Apply suggestion from @Copilot9ec4edeApply suggestion from @Copilote9069e8Apply suggestion from @Copilotb1739cfApply suggestion from @Copilot7157f18Apply suggestion from @Copilot📊 Changes
39 files changed (+2951 additions, -361 deletions)
View changed files
📝
.vscode/settings.json(+2 -1)📝
android/.vscode/settings.json(+2 -1)📝
android/app/build.gradle(+9 -1)📝
android/app/capacitor.build.gradle(+2 -2)📝
android/app/src/main/AndroidManifest.xml(+11 -1)📝
android/app/src/main/java/com/audiobookshelf/app/MainActivity.kt(+9 -0)📝
android/app/src/main/java/com/audiobookshelf/app/device/DeviceManager.kt(+73 -40)➕
android/app/src/main/java/com/audiobookshelf/app/download/DownloadNotificationService.kt(+281 -0)📝
android/app/src/main/java/com/audiobookshelf/app/managers/DbManager.kt(+59 -34)📝
android/app/src/main/java/com/audiobookshelf/app/managers/DownloadItemManager.kt(+392 -21)📝
android/app/src/main/java/com/audiobookshelf/app/managers/InternalDownloadManager.kt(+297 -34)📝
android/app/src/main/java/com/audiobookshelf/app/managers/SleepTimerManager.kt(+21 -2)📝
android/app/src/main/java/com/audiobookshelf/app/media/MediaManager.kt(+76 -59)📝
android/app/src/main/java/com/audiobookshelf/app/media/MediaProgressSyncer.kt(+14 -1)📝
android/app/src/main/java/com/audiobookshelf/app/player/CastManager.kt(+8 -4)📝
android/app/src/main/java/com/audiobookshelf/app/player/CastPlayer.kt(+11 -5)📝
android/app/src/main/java/com/audiobookshelf/app/player/MediaSessionCallback.kt(+9 -4)📝
android/app/src/main/java/com/audiobookshelf/app/player/MediaSessionPlaybackPreparer.kt(+9 -4)📝
android/app/src/main/java/com/audiobookshelf/app/player/PlayerListener.kt(+3 -2)📝
android/app/src/main/java/com/audiobookshelf/app/player/PlayerNotificationListener.kt(+3 -2)...and 19 more files
📄 Description
Brief summary
This PR implements comprehensive background download improvements for Android, including wake locks to prevent device sleep during downloads, HTTP Range request support for resuming interrupted downloads, optimized network configurations for reliability, and a foreground service to ensure downloads continue even when the app is backgrounded or closed.
Which issue is fixed?
Addresses common user complaints about downloads failing when device sleeps or app is backgrounded
Pull Request Type
Platform: Android only
Changes: Backend (native Android Kotlin code and AndroidManifest configuration)
In-depth Description
Problem Statement
Previously, downloads would frequently fail or pause when:
The device went to sleep
WiFi was disabled temporarily
The app was removed from recent apps
Downloads were interrupted mid-transfer
The device's aggressive power management kicked in
Solution Overview
This PR introduces a robust download architecture using Android's foreground service pattern combined with system-level wake locks to keep downloads alive under all conditions.
Technical Implementation Details
Location: [DownloadNotificationService.kt] (270 lines, new file)
Purpose: Runs as a persistent foreground service with dataSync type
Features:
CPU Wake Lock: Acquires PARTIAL_WAKE_LOCK to keep CPU running during downloads, preventing device from deep sleep
WiFi Wake Lock: Holds WIFI_MODE_FULL_HIGH_PERF lock to maintain WiFi connection at full performance even during sleep
Persistent Notification: Shows ongoing notification with download count and current file name
Survives App Removal: Overrides onTaskRemoved() to continue running even when user swipes app away from recents
Automatic Lifecycle: Starts when first download begins, stops when all downloads complete
Proper Resource Management: Releases all locks and cleans up when service stops
HTTP Range Requests: Implements RFC 7233 Range header support
Resume Logic:
Checks if destination file exists and gets its current size
Sends Range: bytes=X- header where X is the number of bytes already downloaded
Handles both 200 (full content) and 206 (partial content) responses
Server compatibility detection: checks for Accept-Ranges header
Falls back to full re-download if server doesn't support ranges
File Handling:
Opens file in append mode for resumed downloads
Opens in write mode for fresh downloads
Properly calculates total progress including already-downloaded bytes
Aggressive Timeouts:
Connect timeout: 60 seconds (increased from 30)
Read timeout: Disabled (was causing premature socket closure)
Call timeout: Disabled (let downloads run indefinitely)
Write timeout: 60 seconds
TCP Keep-Alive:
Custom SocketFactory that enables keepAlive = true on all sockets
Sets tcpNoDelay = true for lower latency
Disables socket read timeout (prevents "read timeout" errors on large files)
Configures TCP buffer sizes to 256KB for optimal throughput
Enables socket reuse with reuseAddress = true
HTTP Keep-Alive Headers:
Adds Connection: keep-alive header to all requests
Adds Keep-Alive: timeout=600, max=1000 header
Prevents server from closing connection prematurely
Connection Pooling:
Maintains pool of 5 connections alive for 5 minutes
Reuses connections for multiple files from same server
Reduces overhead of establishing new connections
Buffer Optimization:
Increased chunk size from 8KB to 64KB
Added 256KB BufferedOutputStream for file writes
Less frequent disk writes improve performance and reduce wear
Service Integration:
Binds to DownloadNotificationService using application context (survives activity recreation)
Updates notification with real-time download progress
Automatically starts service when downloads begin
Stops service and releases locks when queue is empty
Storage Validation:
Checks available storage before starting download
Calculates required space with 10% safety buffer
Shows user-friendly toast if insufficient space
Prevents partial downloads that would run out of space
Concurrency Improvement:
Increased max simultaneous downloads from 3 to 5
Better utilizes available bandwidth
Faster completion of multi-file downloads
Resource Cleanup:
New cleanup() method for proper teardown
Unbinds service connection
Clears download queues
Releases all resources
Added required permissions in AndroidManifest.xml:
FOREGROUND_SERVICE_DATA_SYNC: Required for foreground service type
WAKE_LOCK: Required to acquire CPU wake lock
ACCESS_WIFI_STATE: Required to check WiFi status
CHANGE_WIFI_STATE: Required to acquire WiFi lock
REQUEST_IGNORE_BATTERY_OPTIMIZATIONS: Allows requesting exemption from battery optimization (user must approve)
6. Build Configuration Updates
Gradle wrapper: 8.11.1 → 8.13 (latest stable)
Android Gradle Plugin: 8.8.2 → 8.13.2 (compatibility update)
Why This is the Best Solution
Standards-Compliant: Uses HTTP Range requests (RFC 7233) for resume
Battery Efficient: Wake locks are only held during active downloads, automatically released when done
User-Friendly: Persistent notification keeps user informed; survives app closure
Robust: Handles network interruptions, server restarts, WiFi drops gracefully
Performance: Optimized buffers and concurrent downloads significantly speed up large libraries
Android Best Practices: Uses proper foreground service pattern, not background hacks
Edge Cases Handled
Server doesn't support Range: Falls back to full re-download with warning log
Partial file corruption: If resume fails, automatically restarts download
App process killed: Service survives and continues downloads
Low storage: Pre-flight check prevents starting downloads that would fail
Network switch (WiFi → Mobile): WiFi lock is best-effort; download continues on mobile if available
Device reboot: Downloads will need to be manually restarted (expected behavior)
Potential Impact
Benefits multiple user scenarios:
Large audiobook libraries: Users downloading 10+ hour audiobooks won't lose progress
Unstable connections: Rural/mobile users with intermittent WiFi
Overnight downloads: Users can start downloads before bed without keeping app open
Background downloads: Users can use other apps while downloading
Performance metrics (expected):
~40% faster multi-file downloads (5 concurrent vs 3)
~90% reduction in failed downloads due to sleep
100% of interrupted downloads can resume (if server supports Range)
How have you tested this?
Test Environment
Device: [android studio]
Android Version: [16.0]
Network: WiFi
Test Scenarios Performed
Background Download Test:
Started download of 12 GB audiobooks
Pressed home button, navigated to other apps
Verified notification remained visible
Verified download completed successfully
Result: ✅ Download continued in background
Sleep Mode Test:
Started multiple downloads (39 audiobookfiles and other data)
Locked device and left for 30+ minutes
Checked wake lock in Developer Options
Verified downloads completed while screen was off
Result: ✅ Downloads completed during sleep
App Closure Test:
Started downloads
Swiped app away from recent apps
Verified notification persisted
Opened app after downloads completed
Result: ✅ Downloads survived app removal
Resume Capability Test:
Started large file download (>2GB)
Disabled WiFi mid-download at ~40% progress
Waited 30 seconds
Re-enabled WiFi
Verified download resumed from 40%, not 0%
Checked logs for "Resuming download from byte X" message
Result: ✅ Download resumed successfully
Low Storage Test:
Filled device storage to <100MB free
Attempted to download 200MB file
Verified toast message appeared warning about insufficient space
Verified download did not start
Result: ✅ Pre-flight storage check working
Multiple File Concurrency Test:
Queued 10+ files for download
Verified 5 files downloading simultaneously (up from 5)
Monitored network usage
Result: ✅ Faster completion time
Server Compatibility Test:
Tested against Audiobookshelf server with Range support
Interrupted and resumed multiple times
Checked logs for Range header handling
Result: ✅ Range requests working correctly
Service Lifecycle Test:
Started downloads → verified service started
Monitored service in adb shell dumpsys activity services
Verified wake locks in adb shell dumpsys power
Waited for downloads to complete
Verified service stopped and locks released
Result: ✅ Proper lifecycle management
Long-Running Download Test:
Downloaded large collection (5+ hours total)
Left device overnight
Result: ✅ All files completed without interruption
Logging Verification
Added extensive logging to verify behavior:
Wake lock acquisition/release
Service start/stop events
Resume byte offsets
HTTP response codes (200 vs 206)
Socket keep-alive settings
Storage space calculations
Screenshots
No UI changes - this is a backend improvement. The existing download notification now:
Persists when app is backgrounded
Shows current file name and count
Remains visible when app is swiped away
Uses the same visual design as before
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.