About Ketch

Ketch is simple, powerful, customisable file downloader library for Android built entirely in Kotlin. It simplifies the process of downloading files in Android applications by leveraging the power of WorkManager. Ketch guarantees the download irrespective of application state.

Why use Ketch?

• Ketch can download any type of file. (jpg, png, gif, mp4, mp3, pdf, apk and many more) and guarantees download unless cancelled explicitly or download is failed.

• Ketch provide all download info including speed, file size, progress.

• Ketch can download multiple files in parallel with support of pause-resume, retry-cancel and deletion of downloads.

• Ketch provide notification for each download providing download info (speed, time left, total size, progress) and option to pause, resume, retry and cancel from notification itself.

• Ketch provide option to observe download items (or single download item) as Flow.

• Ketch provides various customisation including custom timeout, custom okhttp client and custom notification.

Usage

Ketch is very simple to use: Add the dependency, pass the url, path and fileName to download and observe the download.

// build.gradle
dependencies {
  implementation 'com.github.khushpanchal:Ketch:2.0.0'
}

//Application
private lateinit var ketch: Ketch
override fun onCreate() {
  super.onCreate(savedInstanceState)
  ketch = Ketch.builder().build(this)
}

//To download the file
val id = ketch.download(url, fileName, path)
lifecycleScope.launch { // e.g., from activity
  repeatOnLifecycle(Lifecycle.State.STARTED) {
    ketch.observeDownloadById(id)
      .flowOn(Dispatchers.IO)
      .collect { downloadModel -> 
        // use downloadModel
      }
  }
}

// To cancel the download
ketch.cancel(downloadModel.id) // other options: cancel(tag), cancelAll()

// To pause the download
ketch.pause(downloadModel.id) // other options: pause(tag), pauseAll()

// To resume the download
ketch.resume(downloadModel.id) // other options: resume(tag), resumeAll()

// To retry the download
ketch.retry(downloadModel.id) // other options: retry(tag), retryAll()

// To delete the download
ketch.clearDb(downloadModel.id) // other options: clearDb(tag), clearAllDb(), clearDb(timeInMillis)
ketch.clearDb(downloadModel.id, false) // Pass "false" to skip the actual file deletion (only clear entry from DB)

// To observe all the downloads
viewLifecycleOwner.lifecycleScope.launch { // e.g., from fragment
  repeatOnLifecycle(Lifecycle.State.STARTED) {
    ketch.observeDownloads() // other options: observe download by id, by tag
      .flowOn(Dispatchers.IO)      
      .collect { 
         //set items to adapter
      }
  }
}

To enable the notification, add appropriate notification permission and pass notification config while initialising the library.

ketch = Ketch.builder().setNotificationConfig(
         config = NotificationConfig(
           enabled = true,
           smallIcon = R.drawable.ic_launcher_foreground // It is required to pass the smallIcon for notification.
         )
       ).build(this)

How Ketch works?

High Level Design

Component Details

• Ketch: It is the core class client interacts with. It has various exposed function including init, download, pause, resume, retry, cancel, clearDb, observeDownloads. It has the instance of DownloadManager.

• DownloadManager: It is the central class of library that has instance of downloads database and WorkManager. It is responsible for enqueuing the work request. It directly observe the database carrying all download related information making database the single source of truth. Additionally this class has observe functions that return the flow of list of DownloadModel (data class carrying all download information) to the client.

• DownloadWorker: It extends CoroutineWorker for downloading the items in background. It has the instance of DownloadTask, DownloadNotificationManager and Download database.

• DownloadTask: It has the suspend function download and provide callbacks like onStart and onProgress. It has the length of file and also carries the logic of calculating download speed. It has DownloadService class that uses Retrofit for making network request.

• DownloadNotificationManager: It is responsible for showing the notification to user. It creates notification channel and notification. It also sendBroadcast which is received by NotificationReceiver after work is finished.

• DownloadDao: It carryies all database query for storing, updating or getting download info from database. Library uses ROOM for database.

• NotificationReceiver: It is responsible for showing the terminating notification to user after DownloadWorker is finished or cancelled. It shows Cancel, Failed (with retry and cancel action), Paused (with resume and cancel action) and Successful Notification message.

Ketch provides lot more features with plenty of customisation options, check out the GitHub project for more information:

Github Project: https://github.com/khushpanchal/Ketch

If this project helps you, show love ❤️ by putting a ⭐ on this project ✌️

Contact Me: LinkedIn, Twitter

Happy coding ✌️