媒體項目

播放清單 API 以 MediaItem 執行個體為基礎，可使用 MediaItem.Builder 輕鬆建構。在播放器中，MediaItem 會由 MediaSource.Factory 轉換為可播放的 MediaSource。如果沒有自訂設定，這項轉換作業會由 DefaultMediaSourceFactory 執行，該物件可根據媒體項目的屬性建構複雜的媒體來源。以下列出可對媒體項目設定的部分屬性。

簡單媒體項目

您可以使用 fromUri 便利方法，建構僅包含串流 URI 的媒體項目：

Kotlin

val mediaItem = MediaItem.fromUri(videoUri)
MediaItems.kt

Java

MediaItem mediaItem = MediaItem.fromUri(videoUri);
MediaItems.java

如果是其他情況，則可使用 MediaItem.Builder。在下列範例中，媒體項目是使用 ID 和一些附加的中繼資料建構而成：

Kotlin

val mediaItem =
  MediaItem.Builder().setMediaId(mediaId).setTag(myAppData).setUri(videoUri).build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder().setMediaId(mediaId).setTag(myAppData).setUri(videoUri).build();
MediaItems.java

附加中繼資料有助於在播放清單轉換時更新應用程式的 UI。

圖片

如要播放圖片，媒體項目必須包含時間長度，指定圖片在播放期間的顯示時間。如要進一步瞭解動態相片和圖片載入程式庫 (例如 Glide)，請參閱「圖片」指南頁面。

Kotlin

val mediaItem = MediaItem.Builder().setUri(imageUri).setImageDurationMs(3000).build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder().setUri(imageUri).setImageDurationMs(3_000).build();
MediaItems.java

自適應媒體的非標準副檔名

ExoPlayer 提供 DASH、HLS 和 SmoothStreaming 的自適應媒體來源。如果這類自適應媒體項目的 URI 結尾是標準副檔名，系統就會自動建立對應的媒體來源。如果 URI 具有非標準副檔名或完全沒有副檔名，則可以明確設定 MIME 類型，指出媒體項目的類型：

Kotlin

val mediaItem =
  MediaItem.Builder().setUri(hlsUri).setMimeType(MimeTypes.APPLICATION_M3U8).build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder().setUri(hlsUri).setMimeType(MimeTypes.APPLICATION_M3U8).build();
MediaItems.java

漸進式媒體串流不需要 MIME 類型。

受保護的內容

如果是受保護的內容，則應設定媒體項目的 DRM 屬性。UUID 為必填，其他屬性則為選填。

以下是播放受 Widevine DRM 保護項目的設定範例，其中授權 URI 無法直接在媒體中取得 (例如在 DASH 播放清單中)，且需要多個工作階段 (例如由於金鑰輪替)：

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setDrmConfiguration(
      MediaItem.DrmConfiguration.Builder(C.WIDEVINE_UUID)
        .setLicenseUri(licenseUri)
        .setMultiSession(true)
        .setLicenseRequestHeaders(httpRequestHeaders)
        .build()
    )
    .build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setDrmConfiguration(
            new MediaItem.DrmConfiguration.Builder(C.WIDEVINE_UUID)
                .setLicenseUri(licenseUri)
                .setMultiSession(true)
                .setLicenseRequestHeaders(httpRequestHeaders)
                .build())
        .build();
MediaItems.java

在播放器中，DefaultMediaSourceFactory 會將這些屬性傳遞至 DrmSessionManagerProvider，以取得 DrmSessionManager，然後插入建立的 MediaSource。您可以進一步自訂 DRM 行為，以符合自身需求。

側載字幕軌

如要側載字幕軌，可以在建構媒體項目時新增 MediaItem.Subtitle 例項：

Kotlin

val subtitle =
  MediaItem.SubtitleConfiguration.Builder(subtitleUri)
    .setMimeType(mimeType) // The correct MIME type (required).
    .setLanguage(language) // The subtitle language (optional).
    .setSelectionFlags(selectionFlags) // Selection flags for the track (optional).
    .build()
val mediaItem =
  MediaItem.Builder().setUri(videoUri).setSubtitleConfigurations(listOf(subtitle)).build()
MediaItems.kt

Java

MediaItem.SubtitleConfiguration subtitle =
    new MediaItem.SubtitleConfiguration.Builder(subtitleUri)
        .setMimeType(mimeType) // The correct MIME type (required).
        .setLanguage(language) // The subtitle language (optional).
        .setSelectionFlags(selectionFlags) // Selection flags for the track (optional).
        .build();
MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setSubtitleConfigurations(ImmutableList.of(subtitle))
        .build();
MediaItems.java

在內部，DefaultMediaSourceFactory 會使用 MergingMediaSource，將內容媒體來源與每個字幕軌的 SingleSampleMediaSource 結合。DefaultMediaSourceFactory 不支援為多週期 DASH 側載字幕。

剪輯媒體串流

如要剪輯媒體項目參照的內容，請設定自訂開始和結束位置：

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setClippingConfiguration(
      MediaItem.ClippingConfiguration.Builder()
        .setStartPositionMs(startPositionMs)
        .setEndPositionMs(endPositionMs)
        .build()
    )
    .build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setClippingConfiguration(
            new ClippingConfiguration.Builder()
                .setStartPositionMs(startPositionMs)
                .setEndPositionMs(endPositionMs)
                .build())
        .build();
MediaItems.java

在內部，DefaultMediaSourceFactory 會使用 ClippingMediaSource 包裝內容媒體來源。還有其他剪輯屬性。詳情請參閱 MediaItem.Builder Javadoc。

插入廣告

如要插入廣告，請設定媒體項目的廣告代碼 URI 屬性：

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setAdsConfiguration(MediaItem.AdsConfiguration.Builder(adTagUri).build())
    .build()
MediaItems.kt

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
        .build();
MediaItems.java

在內部，DefaultMediaSourceFactory 會將內容媒體來源包裝在 AdsMediaSource 中，插入廣告代碼定義的廣告。如要這麼做，播放器也必須DefaultMediaSourceFactory 相應設定。