自訂

ExoPlayer 程式庫的核心是 Player 介面。Player 會公開傳統的高階媒體播放器功能，例如緩衝媒體、播放、暫停和快轉。預設實作 ExoPlayer 的設計目的是盡量不對播放的媒體類型、儲存方式和位置，以及顯示方式做出任何假設 (因此也不會對這些項目施加任何限制)。ExoPlayer 實作項目並未直接實作媒體的載入和轉譯作業，而是將這項工作委派給在建立播放器或將新媒體來源傳遞至播放器時，會被插入的元件。所有 ExoPlayer 實作項目都包含下列元件：

  • MediaSource 例項會定義要播放的媒體、載入媒體，以及可讀取已載入媒體的來源。播放器中的 MediaSource.Factory 會從 MediaItem 建立 MediaSource 例項。您也可以使用以媒體來源為準的播放清單 API，直接將這些資訊傳遞給播放器。
  • 將 MediaItem 轉換為 MediaSource 的 MediaSource.Factory 例項。系統會在建立播放器時插入 MediaSource.Factory。
  • 用於轉譯媒體個別元件的 Renderer 例項。這些會在建立玩家時插入。
  • TrackSelector 會選取 MediaSource 提供的曲目，供每個可用的 Renderer 使用。建立播放器時會插入 TrackSelector。
  • LoadControl 可控制 MediaSource 緩衝更多媒體的時間，以及緩衝多少媒體。建立播放器時會插入 LoadControl。
  • LivePlaybackSpeedControl 可控制直播播放期間的播放速度，讓播放器保持在所設定的直播偏移範圍內。建立播放器時會插入 LivePlaybackSpeedControl。

在整個程式庫中，都會注入可實作部分播放器功能的元件。部分元件的預設實作會將工作委派給進一步插入的元件。這樣一來，您就能個別將許多子元件取代為以自訂方式設定的實作項目。

自訂播放器

以下列舉一些常見的例子，說明如何透過插入元件自訂播放器。

設定網路堆疊

我們有一個頁面，說明如何自訂 ExoPlayer 使用的網路堆疊。

快取從網路載入的資料

請參閱暫時動態快取和下載媒體的指南。

自訂伺服器互動

部分應用程式可能會攔截 HTTP 要求和回應。您可能需要插入自訂要求標頭、讀取伺服器的回應標頭、修改要求的 URI 等。舉例來說，應用程式可以在要求媒體片段時，將符記當作標頭插入，以便驗證自身。

以下範例說明如何在 DefaultMediaSourceFactory 中插入自訂 DataSource.Factory，以實作這些行為：

Kotlin

val dataSourceFactory =
  DataSource.Factory {
    val dataSource = httpDataSourceFactory.createDataSource()
    // Set a custom authentication request header.
    dataSource.setRequestProperty("Header", "Value")
    dataSource
  }
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory)
    )
    .build()

Java

DataSource.Factory dataSourceFactory =
    () -> {
      HttpDataSource dataSource = httpDataSourceFactory.createDataSource();
      // Set a custom authentication request header.
      dataSource.setRequestProperty("Header", "Value");
      return dataSource;
    };

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

在上述程式碼片段中，插入的 HttpDataSource 會在每個 HTTP 要求中加入標頭 "Header: Value"。每當與 HTTP 來源互動時，這項行為都會修正。

如需更精細的方法，您可以使用 ResolvingDataSource 插入 just-in-time 行為。下列程式碼片段說明如何在與 HTTP 來源互動之前，插入要求標頭：

Kotlin

val dataSourceFactory: DataSource.Factory =
  ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec ->
    // Provide just-in-time request headers.
    dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri))
  }

Java

    DataSource.Factory dataSourceFactory =
        new ResolvingDataSource.Factory(
            httpDataSourceFactory,
            // Provide just-in-time request headers.
            dataSpec -> dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri)));

您也可以使用 ResolvingDataSource 對 URI 進行即時修改，如以下程式碼片段所示：

Kotlin

val dataSourceFactory: DataSource.Factory =
  ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec ->
    // Provide just-in-time URI resolution logic.
    dataSpec.withUri(resolveUri(dataSpec.uri))
  }

Java

DataSource.Factory dataSourceFactory =
    new ResolvingDataSource.Factory(
        httpDataSourceFactory,
        // Provide just-in-time URI resolution logic.
        dataSpec -> dataSpec.withUri(resolveUri(dataSpec.uri)));

自訂錯誤處理

實作自訂 LoadErrorHandlingPolicy 可讓應用程式自訂 ExoPlayer 對載入錯誤的反應方式。舉例來說，應用程式可能會選擇快速失敗，而非重試多次，或者可能會自訂輪詢邏輯，控制玩家在每次重試之間等待的時間長度。下列程式碼片段說明如何實作自訂的退避邏輯：

Kotlin

val loadErrorHandlingPolicy: LoadErrorHandlingPolicy =
  object : DefaultLoadErrorHandlingPolicy() {
    override fun getRetryDelayMsFor(loadErrorInfo: LoadErrorInfo): Long {
      // Implement custom back-off logic here.
      return 0
    }
  }
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setLoadErrorHandlingPolicy(loadErrorHandlingPolicy)
    )
    .build()

Java

LoadErrorHandlingPolicy loadErrorHandlingPolicy =
    new DefaultLoadErrorHandlingPolicy() {
      @Override
      public long getRetryDelayMsFor(LoadErrorInfo loadErrorInfo) {
        // Implement custom back-off logic here.
        return 0;
      }
    };

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context)
                .setLoadErrorHandlingPolicy(loadErrorHandlingPolicy))
        .build();

LoadErrorInfo 引數包含失敗載入作業的詳細資訊，可根據錯誤類型或失敗的請求自訂邏輯。

自訂擷取器標記

您可以使用擷取器標記來自訂從漸進式媒體擷取個別格式的方式。您可以在提供給 DefaultMediaSourceFactory 的 DefaultExtractorsFactory 上設定這些屬性。以下範例會傳遞標記，啟用以索引為基礎的 MP3 串流尋播功能。

Kotlin

val extractorsFactory =
  DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING)
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(DefaultMediaSourceFactory(context, extractorsFactory))
    .build()

Java

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING);

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(new DefaultMediaSourceFactory(context, extractorsFactory))
        .build();

啟用持續比特率尋找功能

針對 MP3、ADTS 和 AMR 串流，您可以使用 FLAG_ENABLE_CONSTANT_BITRATE_SEEKING 標記，透過固定比特率假設啟用近似搜尋功能。如要為個別擷取器設定這些標記，請使用上述的個別 DefaultExtractorsFactory.setXyzExtractorFlags 方法。如要為所有支援的擷取器啟用持續位元率搜尋功能，請使用 DefaultExtractorsFactory.setConstantBitrateSeekingEnabled。

Kotlin

val extractorsFactory = DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true)

Java

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true);

接著，您可以透過 DefaultMediaSourceFactory 插入 ExtractorsFactory，如同上述自訂萃取器標記時所述。

啟用非同步緩衝區佇列

非同步緩衝區排程是 ExoPlayer 轉譯管道中的強化功能，可在非同步模式下運作 MediaCodec 例項，並使用其他執行緒來排定資料解碼和轉譯作業。啟用這項功能後，可以減少影格遺失和音訊不足的情況。

在搭載 Android 12 (API 級別 31) 以上版本的裝置上，系統預設會啟用非同步緩衝區佇列功能，並可從 Android 6.0 (API 級別 23) 開始手動啟用。建議您針對觀察到掉幀或音訊未達標的特定裝置啟用這項功能，尤其是在播放受 DRM 保護或高幀率內容時。

在最簡單的情況下，您需要將 DefaultRenderersFactory 插入播放器，如下所示：

Kotlin

val renderersFactory = 
  DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing()
val exoPlayer = ExoPlayer.Builder(context, renderersFactory).build()

Java

DefaultRenderersFactory renderersFactory =
    new DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing();
ExoPlayer exoPlayer = new ExoPlayer.Builder(context, renderersFactory).build();

如果您要直接將轉譯器例項化，請將 AsynchronousMediaCodecAdapter.Factory 傳遞至 MediaCodecVideoRenderer 和 MediaCodecAudioRenderer 建構函式。

使用 ForwardingSimpleBasePlayer 自訂作業

您可以將 Player 例項包裝在 ForwardingSimpleBasePlayer 的子類別中，自訂部分行為。這個類別可讓您攔截特定「作業」，而不需要直接實作 Player 方法。這可確保 play()、pause() 和 setPlayWhenReady(boolean) 等的行為一致。這也能確保所有狀態變更都正確地傳播至已註冊的 Player.Listener 例項。就大多數自訂用途而言，由於 ForwardingSimpleBasePlayer 可保證一致性，因此應優先採用 ForwardingSimpleBasePlayer，而非較易發生錯誤的 ForwardingPlayer。

舉例來說，如要在播放開始或停止時新增自訂邏輯：

Kotlin

class PlayerWithCustomPlay(player: Player) : ForwardingSimpleBasePlayer(player) {
  override fun handleSetPlayWhenReady(playWhenReady: Boolean): ListenableFuture<*> {
    // Add custom logic
    return super.handleSetPlayWhenReady(playWhenReady)
  }
}

Java

class PlayerWithCustomPlay extends ForwardingSimpleBasePlayer {

  public PlayerWithCustomPlay(Player player) {
    super(player);
  }

  @Override
  protected ListenableFuture<?> handleSetPlayWhenReady(boolean playWhenReady) {
    // Add custom logic
    return super.handleSetPlayWhenReady(playWhenReady);
  }
}

或者，如要禁止 SEEK_TO_NEXT 指令 (並確保 Player.seekToNext 為無操作)：

Kotlin

class PlayerWithoutSeekToNext(player: Player) : ForwardingSimpleBasePlayer(player) {
  override fun getState(): State {
    val state = super.getState()
    return state
      .buildUpon()
      .setAvailableCommands(
        state.availableCommands.buildUpon().remove(COMMAND_SEEK_TO_NEXT).build()
      )
      .build()
  }

  // We don't need to override handleSeek, because it is guaranteed not to be called for
  // COMMAND_SEEK_TO_NEXT since we've marked that command unavailable.
}

Java

class PlayerWithoutSeekToNext extends ForwardingSimpleBasePlayer {

  public PlayerWithoutSeekToNext(Player player) {
    super(player);
  }

  @Override
  protected State getState() {
    State state = super.getState();
    return state
        .buildUpon()
        .setAvailableCommands(
            state.availableCommands.buildUpon().remove(COMMAND_SEEK_TO_NEXT).build())
        .build();
  }

  // We don't need to override handleSeek, because it is guaranteed not to be called for
  // COMMAND_SEEK_TO_NEXT since we've marked that command unavailable.
}

自訂 MediaSource

上述範例會在播放所有傳遞至播放器的 MediaItem 物件時，插入自訂元件。如果需要精細的自訂設定，您也可以將自訂元件插入個別 MediaSource 例項，並直接傳遞給播放器。以下範例說明如何自訂 ProgressiveMediaSource，以便使用自訂 DataSource.Factory、ExtractorsFactory 和 LoadErrorHandlingPolicy：

Kotlin

val mediaSource =
  ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory)
    .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy)
    .createMediaSource(MediaItem.fromUri(streamUri))

Java

ProgressiveMediaSource mediaSource =
    new ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory)
        .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy)
        .createMediaSource(MediaItem.fromUri(streamUri));

建立自訂元件

程式庫針對常見用途，提供本頁頂端所列元件的預設實作方式。ExoPlayer 可以使用這些元件，但如果需要非標準行為，也可以建構為使用自訂實作項目。自訂實作項目的用途包括：

  • Renderer：您可能需要導入自訂 Renderer，以便處理程式庫提供的預設導入作業不支援的媒體類型。
  • TrackSelector：實作自訂 TrackSelector 後，應用程式開發人員就能變更 MediaSource 公開的曲目選取方式，讓每個可用的 Renderer 都能使用這些曲目。
  • LoadControl：實作自訂 LoadControl 可讓應用程式開發人員變更播放器的緩衝政策。
  • Extractor：如果您需要支援目前未受資料庫支援的容器格式，請考慮實作自訂 Extractor 類別。
  • MediaSource：如果您想以自訂方式取得媒體樣本，並將其提供給轉譯器，或是想實作自訂的 MediaSource 合成行為，則可考慮實作自訂 MediaSource 類別。
  • MediaSource.Factory：實作自訂 MediaSource.Factory 可讓應用程式自訂從 MediaItem 建立 MediaSource的方式。
  • DataSource：ExoPlayer 的上游套件已包含多個 DataSource 實作項目，可用於不同用途。您可能想實作自己的 DataSource 類別，以其他方式載入資料，例如透過自訂通訊協定、使用自訂 HTTP 堆疊，或從自訂的持續快取。

建構自訂元件時，建議您採取下列做法：

  • 如果自訂元件需要將事件回報給應用程式，建議您使用與現有 ExoPlayer 元件相同的模型，例如使用 EventDispatcher 類別，或是將 Handler 與事件監聽器一起傳遞至元件的建構函式。
  • 建議自訂元件使用與現有 ExoPlayer 元件相同的模型，以便在播放期間由應用程式重新設定。為此，自訂元件應實作 PlayerMessage.Target，並在 handleMessage 方法中接收設定變更。應用程式程式碼應透過呼叫 ExoPlayer 的 createMessage 方法、設定訊息，然後使用 PlayerMessage.send 將其傳送至元件，傳遞設定變更。傳送要在播放執行緒中傳送的訊息，可確保這些訊息會依序執行，並且在播放器上執行任何其他作業。