Mendownload media

ExoPlayer menyediakan fungsionalitas untuk mendownload media untuk pemutaran offline. Dalam sebagian besar kasus penggunaan, sebaiknya download dilanjutkan bahkan saat aplikasi berada di latar belakang. Untuk kasus penggunaan ini, aplikasi Anda harus membuat subclass DownloadService dan mengirimkan perintah ke layanan untuk menambahkan, menghapus, dan mengontrol download. Diagram berikut menunjukkan class utama yang terlibat.

• DownloadService: Menggabungkan DownloadManager dan meneruskan perintah ke sana. Layanan memungkinkan DownloadManager tetap berjalan meskipun aplikasi berada di latar belakang.
• DownloadManager: Mengelola beberapa download, memuat (dan menyimpan) statusnya dari (dan ke) DownloadIndex, memulai dan menghentikan download berdasarkan persyaratan seperti konektivitas jaringan, dan sebagainya. Untuk mendownload konten, pengelola biasanya akan membaca data yang sedang didownload dari HttpDataSource, dan menulisnya ke dalam Cache.
• DownloadIndex: Mempertahankan status download.

Membuat DownloadService

Untuk membuat DownloadService, buat subclass dan terapkan metode abstraknya:

• getDownloadManager(): Menampilkan DownloadManager yang akan digunakan.
• getScheduler(): Menampilkan Scheduler opsional, yang dapat memulai ulang layanan saat persyaratan yang diperlukan untuk progres download yang tertunda terpenuhi. ExoPlayer menyediakan implementasi ini:
  • PlatformScheduler, yang menggunakan JobScheduler (Minimum API adalah 21). Lihat javadocs PlatformScheduler untuk mengetahui persyaratan izin aplikasi.
  • WorkManagerScheduler, yang menggunakan WorkManager.
• getForegroundNotification(): Menampilkan notifikasi yang akan ditampilkan saat layanan berjalan di latar depan. Anda dapat menggunakan DownloadNotificationHelper.buildProgressNotification untuk membuat notifikasi dengan gaya default.

Terakhir, tentukan layanan di file AndroidManifest.xml Anda:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC"/>
<application>
  <service android:name="com.myapp.MyDownloadService"
      android:exported="false"
      android:foregroundServiceType="dataSync">
    <!-- This is needed for Scheduler -->
    <intent-filter>
      <action android:name="androidx.media3.exoplayer.downloadService.action.RESTART"/>
      <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
  </service>
</application>

Lihat DemoDownloadService dan AndroidManifest.xml di aplikasi demo ExoPlayer untuk contoh konkret.

Membuat DownloadManager

Cuplikan kode berikut menunjukkan cara membuat instance DownloadManager, yang dapat ditampilkan oleh getDownloadManager() dalam DownloadService Anda:

// Note: This should be a singleton in your app.
val databaseProvider = StandaloneDatabaseProvider(context)

// A download cache should not evict media, so should use a NoopCacheEvictor.
val downloadCache = SimpleCache(downloadDirectory, NoOpCacheEvictor(), databaseProvider)

// Create a factory for reading the data from the network.
val dataSourceFactory = DefaultHttpDataSource.Factory()

// Choose an executor for downloading data. Using Runnable::run will cause each download task to
// download data on its own thread. Passing an executor that uses multiple threads will speed up
// download tasks that can be split into smaller parts for parallel execution. Applications that
// already have an executor for background downloads may wish to reuse their existing executor.
val downloadExecutor = Executor(Runnable::run)

// Create the download manager.
val downloadManager =
  DownloadManager(context, databaseProvider, downloadCache, dataSourceFactory, downloadExecutor)

// Optionally, properties can be assigned to configure the download manager.
downloadManager.requirements = requirements
downloadManager.maxParallelDownloads = 3

// Note: This should be a singleton in your app.
databaseProvider = new StandaloneDatabaseProvider(context);

// A download cache should not evict media, so should use a NoopCacheEvictor.
downloadCache = new SimpleCache(downloadDirectory, new NoOpCacheEvictor(), databaseProvider);

// Create a factory for reading the data from the network.
dataSourceFactory = new DefaultHttpDataSource.Factory();

// Choose an executor for downloading data. Using Runnable::run will cause each download task to
// download data on its own thread. Passing an executor that uses multiple threads will speed up
// download tasks that can be split into smaller parts for parallel execution. Applications that
// already have an executor for background downloads may wish to reuse their existing executor.
Executor downloadExecutor = Runnable::run;

// Create the download manager.
downloadManager =
    new DownloadManager(
        context, databaseProvider, downloadCache, dataSourceFactory, downloadExecutor);

// Optionally, setters can be called to configure the download manager.
downloadManager.setRequirements(requirements);
downloadManager.setMaxParallelDownloads(3);

Lihat DemoUtil di aplikasi demo untuk contoh konkret.

Menambahkan download

Untuk menambahkan download, buat DownloadRequest dan kirimkan ke DownloadService Anda. Untuk streaming adaptif, gunakan DownloadHelper untuk membantu mem-build DownloadRequest. Contoh berikut menunjukkan cara membuat permintaan download:

val downloadRequest = DownloadRequest.Builder(contentId, contentUri).build()

DownloadRequest downloadRequest = new DownloadRequest.Builder(contentId, contentUri).build();

Dalam contoh ini, contentId adalah ID unik untuk konten tersebut. Dalam kasus sederhana, contentUri sering kali dapat digunakan sebagai contentId, tetapi aplikasi bebas menggunakan skema ID apa pun yang paling sesuai dengan kasus penggunaannya. DownloadRequest.Builder juga memiliki beberapa penyetel opsional. Misalnya, setKeySetId dan setData dapat digunakan untuk menetapkan DRM dan data kustom yang ingin dikaitkan oleh aplikasi dengan download. Jenis MIME konten juga dapat ditentukan menggunakan setMimeType, sebagai petunjuk untuk kasus ketika jenis kontennya tidak dapat ditentukan dari contentUri.

Setelah dibuat, permintaan dapat dikirim ke DownloadService untuk menambahkan download:

DownloadService.sendAddDownload(
  context,
  MyDownloadService::class.java,
  downloadRequest,
  /* foreground= */ false
)

DownloadService.sendAddDownload(
    context, MyDownloadService.class, downloadRequest, /* foreground= */ false);

Dalam contoh ini, MyDownloadService adalah subclass DownloadService aplikasi, dan parameter foreground mengontrol apakah layanan akan dimulai di latar depan atau tidak. Jika aplikasi sudah berada di latar depan, parameter foreground biasanya harus ditetapkan ke false karena DownloadService akan menempatkan dirinya sendiri di latar depan jika menentukan bahwa ada tugas yang harus dilakukan.

Menghapus download

Download dapat dihapus dengan mengirimkan perintah hapus ke DownloadService, tempat contentId mengidentifikasi download yang akan dihapus:

DownloadService.sendRemoveDownload(
  context,
  MyDownloadService::class.java,
  contentId,
  /* foreground= */ false
)

DownloadService.sendRemoveDownload(
    context, MyDownloadService.class, contentId, /* foreground= */ false);

Anda juga dapat menghapus semua data yang didownload dengan DownloadService.sendRemoveAllDownloads.

Memulai dan menghentikan download

Download hanya akan berjalan jika empat kondisi terpenuhi:

• Download tidak memiliki alasan berhenti.
• Download tidak dijeda.
• Persyaratan untuk melanjutkan download terpenuhi. Persyaratan dapat menentukan batasan pada jenis jaringan yang diizinkan, serta apakah perangkat harus tidak ada aktivitas atau terhubung ke pengisi daya.
• Jumlah maksimum download paralel tidak terlampaui.

Semua kondisi ini dapat dikontrol dengan mengirimkan perintah ke DownloadService.

Menetapkan dan menghapus alasan download berhenti

Anda dapat menetapkan alasan dihentikannya satu atau semua download:

// Set the stop reason for a single download.
DownloadService.sendSetStopReason(
  context,
  MyDownloadService::class.java,
  contentId,
  stopReason,
  /* foreground= */ false
)

// Clear the stop reason for a single download.
DownloadService.sendSetStopReason(
  context,
  MyDownloadService::class.java,
  contentId,
  Download.STOP_REASON_NONE,
  /* foreground= */ false
)

// Set the stop reason for a single download.
DownloadService.sendSetStopReason(
    context, MyDownloadService.class, contentId, stopReason, /* foreground= */ false);

// Clear the stop reason for a single download.
DownloadService.sendSetStopReason(
    context,
    MyDownloadService.class,
    contentId,
    Download.STOP_REASON_NONE,
    /* foreground= */ false);

stopReason dapat berupa nilai apa pun yang bukan nol (Download.STOP_REASON_NONE = 0 adalah nilai khusus yang berarti download tidak dihentikan). Aplikasi yang memiliki beberapa alasan untuk menghentikan download dapat menggunakan nilai yang berbeda untuk melacak alasan setiap download dihentikan. Menetapkan dan menghapus alasan berhenti untuk semua download berfungsi dengan cara yang sama seperti menetapkan dan menghapus alasan berhenti untuk satu download, kecuali bahwa contentId harus ditetapkan ke null.

Jika download memiliki alasan berhenti bukan nol, download akan berada dalam status Download.STATE_STOPPED. Alasan penghentian dipertahankan dalam DownloadIndex, sehingga akan dipertahankan jika proses aplikasi dihentikan dan kemudian dimulai ulang.

Menjeda dan melanjutkan semua download

Semua download dapat dijeda dan dilanjutkan sebagai berikut:

// Pause all downloads.
DownloadService.sendPauseDownloads(
  context,
  MyDownloadService::class.java,
  /* foreground= */ false
)

// Resume all downloads.
DownloadService.sendResumeDownloads(
  context,
  MyDownloadService::class.java,
  /* foreground= */ false
)

// Pause all downloads.
DownloadService.sendPauseDownloads(context, MyDownloadService.class, /* foreground= */ false);

// Resume all downloads.
DownloadService.sendResumeDownloads(context, MyDownloadService.class, /* foreground= */ false);

Saat download dijeda, download akan berada dalam status Download.STATE_QUEUED. Tidak seperti menyetel alasan penghentian, pendekatan ini tidak mempertahankan perubahan status. Ini hanya memengaruhi status runtime DownloadManager.

Menetapkan persyaratan untuk melanjutkan download

Requirements dapat digunakan untuk menentukan batasan yang harus dipenuhi agar download dapat dilanjutkan. Persyaratan dapat ditetapkan dengan memanggil DownloadManager.setRequirements() saat membuat DownloadManager, seperti dalam contoh di atas. Parameter ini juga dapat diubah secara dinamis dengan mengirimkan perintah ke DownloadService:

// Set the download requirements.
DownloadService.sendSetRequirements(
  context, MyDownloadService::class.java, requirements, /* foreground= */ false)

// Set the download requirements.
DownloadService.sendSetRequirements(
  context,
  MyDownloadService.class,
  requirements,
  /* foreground= */ false);

Jika download tidak dapat dilanjutkan karena persyaratannya tidak terpenuhi, download akan berada dalam status Download.STATE_QUEUED. Anda dapat mengkueri persyaratan yang tidak terpenuhi dengan DownloadManager.getNotMetRequirements().

Menyetel jumlah maksimum download paralel

Jumlah maksimum download paralel dapat disetel dengan memanggil DownloadManager.setMaxParallelDownloads(). Tindakan ini biasanya akan dilakukan saat membuat DownloadManager, seperti dalam contoh di atas.

Jika download tidak dapat dilanjutkan karena jumlah maksimum download paralel sedang berlangsung, download tersebut akan berada dalam status Download.STATE_QUEUED.

Membuat kueri download

DownloadIndex dari DownloadManager dapat dikueri untuk status semua download, termasuk yang telah selesai atau gagal. DownloadIndex dapat diperoleh dengan memanggil DownloadManager.getDownloadIndex(). Kursor yang melakukan iterasi pada semua download kemudian dapat diperoleh dengan memanggil DownloadIndex.getDownloads(). Atau, status dari satu download dapat dikueri dengan memanggil DownloadIndex.getDownload().

DownloadManager juga menyediakan DownloadManager.getCurrentDownloads(), yang menampilkan status download saat ini saja (yaitu tidak selesai atau gagal). Metode ini berguna untuk mengupdate notifikasi dan komponen UI lainnya yang menampilkan progres dan status download saat ini.

Mendengarkan hasil download

Anda dapat menambahkan pemroses ke DownloadManager untuk diberi tahu saat status download saat ini berubah:

downloadManager.addListener(
  object : DownloadManager.Listener { // Override methods of interest here.
  }
)

downloadManager.addListener(
    new DownloadManager.Listener() {
      // Override methods of interest here.
    });

Lihat DownloadManagerListener di class DownloadTracker aplikasi demo untuk contoh konkret.

Memutar konten yang didownload

Memutar konten yang didownload mirip dengan memutar konten online, kecuali bahwa data dibaca dari Cache download, bukan melalui jaringan.

Untuk memutar konten yang didownload, buat CacheDataSource.Factory menggunakan instance Cache yang sama dengan yang digunakan untuk mendownload, dan masukkan ke dalam DefaultMediaSourceFactory saat membuat pemutar:

// Create a read-only cache data source factory using the download cache.
val cacheDataSourceFactory: DataSource.Factory =
  CacheDataSource.Factory()
    .setCache(downloadCache)
    .setUpstreamDataSourceFactory(httpDataSourceFactory)
    .setCacheWriteDataSinkFactory(null) // Disable writing.

val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setDataSourceFactory(cacheDataSourceFactory)
    )
    .build()

// Create a read-only cache data source factory using the download cache.
DataSource.Factory cacheDataSourceFactory =
    new CacheDataSource.Factory()
        .setCache(downloadCache)
        .setUpstreamDataSourceFactory(httpDataSourceFactory)
        .setCacheWriteDataSinkFactory(null); // Disable writing.

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context).setDataSourceFactory(cacheDataSourceFactory))
        .build();

Jika instance pemutar yang sama juga akan digunakan untuk memutar konten yang tidak didownload, CacheDataSource.Factory harus dikonfigurasi sebagai hanya baca untuk menghindari download konten tersebut juga selama pemutaran.

Setelah pemutar dikonfigurasi dengan CacheDataSource.Factory, pemutar akan memiliki akses ke konten yang didownload untuk diputar. Memutar download semudah meneruskan MediaItem yang sesuai ke pemutar. MediaItem dapat diperoleh dari Download menggunakan Download.request.toMediaItem, atau langsung dari DownloadRequest menggunakan DownloadRequest.toMediaItem.

Konfigurasi MediaSource

Contoh sebelumnya membuat cache download tersedia untuk pemutaran semua MediaItem. Anda juga dapat menyediakan cache download untuk setiap instance MediaSource, yang dapat diteruskan langsung ke pemutar:

val mediaSource =
  ProgressiveMediaSource.Factory(cacheDataSourceFactory)
    .createMediaSource(MediaItem.fromUri(contentUri))
player.setMediaSource(mediaSource)
player.prepare()

ProgressiveMediaSource mediaSource =
    new ProgressiveMediaSource.Factory(cacheDataSourceFactory)
        .createMediaSource(MediaItem.fromUri(contentUri));
player.setMediaSource(mediaSource);
player.prepare();

Mendownload dan memutar streaming adaptif

Streaming adaptif (misalnya DASH, SmoothStreaming, dan HLS) biasanya berisi beberapa trek media. Sering kali ada beberapa trek yang berisi konten sama dalam kualitas yang berbeda (misalnya trek video SD, HD, dan 4K). Mungkin juga ada beberapa trek dari jenis yang sama yang berisi konten yang berbeda (misalnya beberapa trek audio dalam bahasa yang berbeda).

Untuk pemutaran streaming, pemilih trek dapat digunakan untuk memilih trek mana yang akan diputar. Demikian pula, untuk mendownload, DownloadHelper dapat digunakan untuk memilih trek yang akan didownload. Penggunaan standar DownloadHelper mengikuti langkah-langkah berikut:

1. Bangun DownloadHelper menggunakan salah satu metode DownloadHelper.forMediaItem. Siapkan helper dan tunggu callback.

   Kotlin

   val downloadHelper =
    DownloadHelper.forMediaItem(
      context,
      MediaItem.fromUri(contentUri),
      DefaultRenderersFactory(context),
      dataSourceFactory
    )
   downloadHelper.prepare(callback)
   

   Java

   DownloadHelper downloadHelper =
      DownloadHelper.forMediaItem(
          context,
          MediaItem.fromUri(contentUri),
          new DefaultRenderersFactory(context),
          dataSourceFactory);
   downloadHelper.prepare(callback);
   

2. Secara opsional, periksa jalur default yang dipilih menggunakan getMappedTrackInfo dan getTrackSelections, serta lakukan penyesuaian menggunakan clearTrackSelections, replaceTrackSelections, dan addTrackSelection.
3. Buat DownloadRequest untuk jalur yang dipilih dengan memanggil getDownloadRequest. Permintaan dapat diteruskan ke DownloadService untuk menambahkan download, seperti yang dijelaskan di atas.
4. Rilis helper menggunakan release().

Pemutaran konten adaptif yang didownload memerlukan konfigurasi pemutar dan meneruskan MediaItem yang sesuai, seperti yang dijelaskan di atas.

Saat mem-build MediaItem, MediaItem.localConfiguration.streamKeys harus ditetapkan agar cocok dengan yang ada di DownloadRequest agar pemain hanya mencoba memutar subset trek yang telah didownload. Penggunaan Download.request.toMediaItem dan DownloadRequest.toMediaItem untuk mem-build MediaItem akan menangani hal ini untuk Anda.