このページは Cloud Translation API によって翻訳されました。

メディアのダウンロード

ExoPlayer には、オフライン再生用にメディアをダウンロードする機能が用意されています。ほとんどのユースケースでは、アプリがバックグラウンドにある場合でもダウンロードを継続することが望ましいです。これらのユースケースでは、アプリはサブクラス化する必要がありますDownloadServiceダウンロードを追加、削除、制御するためのコマンドをサービスに送信します。次の図は、関係する主なクラスを示しています。

メディアをダウンロードするためのクラス。矢印の方向はデータの流れを示します。

DownloadService: DownloadManager をラップし、コマンドを転送します。このサービスでは、DownloadManagerアプリがバックグラウンドにあるときでも実行を継続します。
DownloadManager: 複数のダウンロードを管理し、それらの状態をロード（および保存）します。DownloadIndexネットワーク接続などの要件に基づいてダウンロードを開始および停止します。コンテンツをダウンロードするために、マネージャーは通常、ダウンロードされるデータを HttpDataSource から読み取り、Cache に書き込みます。
DownloadIndex: ダウンロードの状態を保持します。

DownloadService の作成

を作成するにはDownloadServiceをサブクラス化し、その抽象メソッドを実装します。

getDownloadManager(): 使用する DownloadManager を返します。
getScheduler(): オプションの Scheduler を返します。これは、保留中のダウンロードを進めるために必要な要件が満たされたときにサービスを再起動できます。ExoPlayer は次の実装を提供します:
- PlatformScheduler（JobScheduler を使用、最小 API は 21）。アプリの権限要件については、PlatformScheduler の javadoc をご覧ください。
- WorkManagerScheduler（WorkManager を使用）。
getForegroundNotification(): サービスがフォアグラウンドで実行されているときに表示される通知を返します。DownloadNotificationHelper.buildProgressNotification を使用して、デフォルトスタイルの通知を作成できます。

最後に、AndroidManifest.xml ファイルでサービスを定義します。

<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>

具体的な例については、ExoPlayer デモアプリの DemoDownloadService と AndroidManifest.xml をご覧ください。

DownloadManager の作成

次のコードスニペットは、DownloadManager をインスタンス化する方法を示しています。これは、DownloadService の getDownloadManager() によって返される可能性があります。

Kotlin

// 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

Java

// 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);

具体的な例については、デモアプリの DemoUtil をご覧ください。

ダウンロードを追加する

ダウンロードを追加するには、DownloadRequest を作成して DownloadService に送信します。アダプティブストリームの場合、DownloadHelper を使用して DownloadRequest の構築を支援します。次の例は、ダウンロードリクエストを作成する方法を示しています。

Kotlin

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

Java

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

この例では、contentId はコンテンツの一意の識別子です。単純なケースでは、contentUri多くの場合、contentIdただし、アプリはユースケースに最適な ID スキームを自由に使用できます。DownloadRequest.Builderオプションのセッターもいくつかあります。たとえば、setKeySetId と setData を使用して、アプリがダウンロードに関連付けたい DRM とカスタムデータをそれぞれ設定できます。contentUri からコンテンツタイプを推測できない場合、ヒントとして setMimeType を使用してコンテンツの MIME タイプを指定することもできます。

作成したリクエストは、DownloadService に送信してダウンロードを追加できます。

Kotlin

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

Java

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

この例では、MyDownloadService はアプリの DownloadService サブクラスであり、foreground パラメータはサービスがフォアグラウンドで開始されるかどうかを制御します。アプリがすでにフォアグラウンドにある場合、DownloadService は実行する作業があると判断するとフォアグラウンドに移行するため、通常は foreground パラメータを false に設定する必要があります。

ダウンロードを削除しています

ダウンロードを削除するには、DownloadService に削除コマンドを送信します。ここで、contentId は削除するダウンロードを識別します。

Kotlin

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

Java

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

DownloadService.sendRemoveAllDownloads を使用して、ダウンロードしたすべてのデータを削除することもできます。

ダウンロードの開始と停止

ダウンロードは、次の 4 つの条件が満たされた場合にのみ進行します。

ダウンロードに停止理由がありません。
ダウンロードは一時停止されません。
ダウンロードを進行するための要件が満たされています。要件では、許可されるネットワークタイプに関する制約や、デバイスがアイドル状態であるか、充電器に接続されているかを指定できます。
並列ダウンロードの最大数を超えていない。

これらの条件はすべて、DownloadService にコマンドを送信することで制御できます。

ダウンロード停止理由の設定とクリア

1 つまたはすべてのダウンロードが停止した理由を設定できます。

Kotlin

// 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
)

Java

// 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ゼロ以外の任意の値（Download.STOP_REASON_NONE = 0ダウンロードが停止されないことを意味する特別な値です。ダウンロードを停止する理由が複数あるアプリでは、異なる値を使用して、各ダウンロードが停止された理由を追跡できます。すべてのダウンロードの停止理由を設定およびクリアする処理は、単一のダウンロードの停止理由を設定およびクリアする処理と同じですが、contentId を null に設定する必要があります。

ダウンロードにゼロ以外の停止理由がある場合、Download.STATE_STOPPED 状態になります。停止理由は DownloadIndex に保持されるため、アプリプロセスが強制終了されて後で再起動された場合でも保持されます。

すべてのダウンロードを一時停止、再開する

すべてのダウンロードは、次のように一時停止して再開できます。

Kotlin

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

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

Java

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

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

ダウンロードが一時停止されると、Download.STATE_QUEUED州。停止理由の設定とは異なり、このアプローチでは状態の変更は保持されません。これは DownloadManager の実行時の状態にのみ影響します。

ダウンロードを進めるための要件を設定する

Requirements を使用すると、ダウンロードを続行するために満たす必要がある制約を指定できます。要件は、上記の例のように、DownloadManager の作成時に DownloadManager.setRequirements() を呼び出すことによって設定できます。また、コマンドを送信することで動的に変更することもできます。DownloadService:

Kotlin

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

Java

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

要件が満たされていないためにダウンロードを続行できない場合、ダウンロードは Download.STATE_QUEUED 状態になります。満たされていない要件は DownloadManager.getNotMetRequirements() でクエリできます。

同時ダウンロードの最大数の設定

並列ダウンロードの最大数は、DownloadManager.setMaxParallelDownloads() を呼び出すことで設定できます。これは通常、上記の例のように、DownloadManager を作成するときに行われます。

並行ダウンロードの最大数がすでに進行中のためダウンロードを続行できない場合、状態は Download.STATE_QUEUED になります。

ダウンロードのクエリ

そのDownloadIndexのDownloadManager完了したものや失敗したものも含め、すべてのダウンロードの状態を照会できます。そのDownloadIndex電話で入手できますDownloadManager.getDownloadIndex()。すべてのダウンロードを反復処理するカーソルは、DownloadIndex.getDownloads() を呼び出すことによって取得できます。あるいは、DownloadIndex.getDownload() を呼び出して、1 回のダウンロードの状態を照会することもできます。

DownloadManagerまた、DownloadManager.getCurrentDownloads()は、現在の（つまり、完了または失敗していない）ダウンロードの状態のみを返します。このメソッドは、現在のダウンロードの進行状況とステータスを表示する通知やその他の UI コンポーネントを更新するのに便利です。

ダウンロードを聴く

現在のダウンロードの状態が変化したときに通知を受け取るように、DownloadManager にリスナーを追加できます。

Kotlin

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

Java

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

具体的な例については、デモアプリの DownloadTracker クラスの DownloadManagerListener をご覧ください。

ダウンロードしたコンテンツの再生

ダウンロードしたコンテンツの再生は、ネットワーク経由ではなくダウンロード Cache からデータを読み取る点を除き、オンラインコンテンツの再生と似ています。

ダウンロードしたコンテンツを再生するには、CacheDataSource.Factory同じものを使用してCacheダウンロードに使用されたインスタンスを抽出し、DefaultMediaSourceFactoryプレーヤーを構築するとき:

Kotlin

// 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()

Java

// 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();

同じプレーヤーインスタンスを使用してダウンロードされていないコンテンツも再生する場合は、再生中にそのコンテンツもダウンロードされないように、CacheDataSource.Factory を読み取り専用として構成する必要があります。

プレーヤーの設定が完了したら、CacheDataSource.Factoryすると、ダウンロードしたコンテンツにアクセスして再生できるようになります。ダウンロードしたファイルを再生するには、対応するMediaItemプレイヤーに。MediaItem は、Download.request.toMediaItem を使用して Download から取得することも、DownloadRequest.toMediaItem を使用して DownloadRequest から直接取得することもできます。

MediaSource の構成

上記の例では、すべての MediaItem の再生でダウンロードキャッシュを使用できるようにしています。ダウンロードキャッシュを個々の MediaSource インスタンスで使用できるようにすることもできます。このインスタンスはプレーヤーに直接渡すことができます。

Kotlin

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

Java

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

アダプティブストリームのダウンロードと再生

アダプティブストリーム（DASH、SmoothStreaming、HLS など）には通常、複数のメディアトラックが含まれています。多くの場合、同じコンテンツが異なる品質で含まれている複数のトラックが存在します (例: SD、HD、4K ビデオトラック)。同じタイプのトラックが複数あり、それぞれ異なるコンテンツが含まれている場合もあります（異なる言語の音声トラックが複数あるなど）。

ストリーミング再生の場合、トラックセレクタを使用して、どのトラックを再生するかを選択できます。同様に、ダウンロードの場合、DownloadHelper を使用して、どのトラックをダウンロードするかを選択できます。DownloadHelper の一般的な使用方法は次のとおりです。

構築するDownloadHelper使用してDownloadHelper.Factory実例。ヘルパーを準備して、コールバックを待ちます。

Kotlin

val downloadHelper =
     DownloadHelper.Factory()
      .setRenderersFactory(DefaultRenderersFactory(context))
      .setDataSourceFactory(dataSourceFactory)
      .create(MediaItem.fromUri(contentUri))
downloadHelper.prepare(callback)

Java

DownloadHelper downloadHelper =
   new DownloadHelper.Factory()
        .setRenderersFactory(new DefaultRenderersFactory(context))
        .setDataSourceFactory(dataSourceFactory)
        .create(MediaItem.fromUri(contentUri));
downloadHelper.prepare(callback);

必要に応じて、getMappedTrackInfo と getTrackSelections を使用してデフォルトで選択されているトラックを検査し、clearTrackSelections、replaceTrackSelections、addTrackSelection を使用して調整します。
作成するDownloadRequest選択したトラックを呼び出すgetDownloadRequest。リクエストはあなたのDownloadService上記のようにダウンロードを追加します。
release() を使用してヘルパーを解放します。

ダウンロードしたアダプティブコンテンツを再生するには、上記のようにプレーヤーを構成し、対応する MediaItem を渡す必要があります。

MediaItem をビルドするときは、MediaItem.localConfiguration.streamKeys を DownloadRequest の値と一致するように設定して、プレーヤーがダウンロードされたトラックのサブセットのみを再生するようにする必要があります。Download.request.toMediaItem と DownloadRequest.toMediaItem を使用して MediaItem をビルドすると、この処理が自動的に行われます。

メディアのダウンロード コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

DownloadService の作成

DownloadManager の作成

Kotlin

Java

ダウンロードを追加する

Kotlin

Java

Kotlin

Java

ダウンロードを削除しています

Kotlin

Java

ダウンロードの開始と停止

ダウンロード停止理由の設定とクリア

Kotlin

Java

すべてのダウンロードを一時停止、再開する

Kotlin

Java

ダウンロードを進めるための要件を設定する

Kotlin

Java

同時ダウンロードの最大数の設定

ダウンロードのクエリ

ダウンロードを聴く

Kotlin

Java

ダウンロードしたコンテンツの再生

Kotlin

Java

MediaSource の構成

Kotlin

Java

アダプティブ ストリームのダウンロードと再生

Kotlin

Java

メディアのダウンロード

アダプティブストリームのダウンロードと再生