開始使用

開始使用 Transformer 的步驟如下：

  1. 在專案中新增 Media3 Transformer 做為依附元件。
  2. 建立 EditedMediaItem，代表要處理的媒體和要套用的編輯內容。
  3. 建構 Transformer，說明必要輸出內容，以及完成和錯誤事件的監聽器。
  4. 啟動匯出作業，傳遞要編輯的 EditedMediaItem 和輸出路徑。匯出期間，您可以查詢目前進度或取消作業。
  5. 匯出作業完成後，請視需要處理輸出內容。舉例來說，您可以將輸出內容分享至其他應用程式，或上傳至伺服器。

如要進一步瞭解這些步驟，請參閱下文，並在轉換器示範應用程式中查看 TransformerActivity 的完整範例。

將 Media3 Transformer 新增為依附元件

如要開始使用 Transformer，最簡單的方法是在應用程式模組的 build.gradle 檔案中，新增程式庫的 Gradle 依附元件：

Kotlin

implementation("androidx.media3:media3-transformer:1.7.1")
implementation("androidx.media3:media3-effect:1.7.1")
implementation("androidx.media3:media3-common:1.7.1")

Groovy

implementation "androidx.media3:media3-transformer:1.7.1"
implementation "androidx.media3:media3-effect:1.7.1"
implementation "androidx.media3:media3-common:1.7.1"

其中 1.7.1 是您偏好的版本。如要查看最新版本，請參閱版本資訊。

如要進一步瞭解可用的程式庫模組，請參閱 Google Maven AndroidX Media3 頁面。

開啟 Java 8 支援

如果尚未啟用，您需要在所有依附於 Transformer 的 build.gradle 檔案中，將下列內容新增至 android 區段，開啟 Java 8 支援：

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

開始轉換

以下範例說明如何建立 EditedMediaItem，移除輸入檔案的音訊，然後建立及設定 Transformer 執行個體，匯出 H.265/HEVC 影片，並將結果輸出至 outputPath。

Kotlin

val inputMediaItem = MediaItem.fromUri("path_to_input_file")
val editedMediaItem =
    EditedMediaItem.Builder(inputMediaItem).setRemoveAudio(true).build()
val transformer = Transformer.Builder(context)
    .setVideoMimeType(MimeTypes.VIDEO_H265)
    .addListener(transformerListener)
    .build()
transformer.start(editedMediaItem, outputPath)

Java

MediaItem inputMediaItem = MediaItem.fromUri("path_to_input_file");
EditedMediaItem editedMediaItem =
    new EditedMediaItem.Builder(inputMediaItem).setRemoveAudio(true).build();
Transformer transformer =
    new Transformer.Builder(context)
        .setVideoMimeType(MimeTypes.VIDEO_H265)
        .addListener(transformerListener)
        .build();
transformer.start(editedMediaItem, outputPath);

如要進一步瞭解媒體項目，請參閱 ExoPlayer 媒體項目頁面。輸入內容可以是漸進式或自適應串流，但輸出內容一律為漸進式串流。如果是自適應輸入內容，系統一律會選取最高解析度的音軌進行轉換。輸入內容可以是 ExoPlayer 支援的任何容器格式，但輸出內容一律為 MP4 檔案。

您可以在同一個Transformer執行個體上依序執行多項匯出作業，但不支援使用同一個執行個體同時匯出。

執行緒注意事項

必須從單一應用程式執行緒存取轉換器例項，且接聽程式方法會在相同執行緒上呼叫。在大多數情況下，應用程式執行緒可以是應用程式的主執行緒。在內部，Transformer 會在背景執行工作，並將呼叫發布至應用程式執行緒上的接聽程式方法。

監聽事件

start 方法為非同步性質。這個方法會立即回傳，並透過傳遞至 Transformer 建構工具的監聽器，將事件通知應用程式。

Kotlin

val transformerListener: Transformer.Listener =
    object : Transformer.Listener {
  override fun onCompleted(composition: Composition, result: ExportResult) {
    playOutput()
  }

  override fun onError(composition: Composition, result: ExportResult,
                       exception: ExportException) {
    displayError(exception)
  }
}

Java

Transformer.Listener transformerListener =
    new Transformer.Listener() {
      @Override
      public void onCompleted(Composition composition, ExportResult result) {
        playOutput();
      }

      @Override
      public void onError(Composition composition, ExportResult result,
          ExportException exception) {
        displayError(exception);
      }
    };

ExportResult 包含輸出檔案的相關資訊，包括檔案大小，以及音訊和視訊的平均位元率 (如適用)。

取得進度更新

呼叫 Transformer.getProgress 查詢轉換作業的目前進度。傳回的值會指出進度狀態。如果進度狀態為 PROGRESS_STATE_AVAILABLE，系統會以目前的進度百分比更新提供的 ProgressHolder。以下範例說明如何定期查詢轉換進度，其中 updateProgressInUi 方法可實作來更新進度列。

Kotlin

transformer.start(inputMediaItem, outputPath)
val progressHolder = ProgressHolder()
mainHandler.post(
    object : Runnable {
      override fun run() {
        val progressState: @ProgressState Int = transformer.getProgress(progressHolder)
        updateProgressInUi(progressState, progressHolder)
        if (progressState != Transformer.PROGRESS_STATE_NOT_STARTED) {
          mainHandler.postDelayed(/* r= */this,  /* delayMillis= */500)
        }
      }
    }
)

Java

transformer.start(inputMediaItem, outputPath);
ProgressHolder progressHolder = new ProgressHolder();
mainHandler.post(
    new Runnable() {
      @Override
      public void run() {
        @Transformer.ProgressState int progressState = transformer.getProgress(progressHolder);
        updateProgressInUi(progressState, progressHolder);
        if (progressState != PROGRESS_STATE_NOT_STARTED) {
          mainHandler.postDelayed(/* r= */ this, /* delayMillis= */ 500);
        }
      }
    });

取消轉換

如果使用者選擇退出匯出流程，請使用 Transformer.cancel 取消匯出作業。硬體視訊轉碼器等資源有限，在低階裝置上更是如此，因此如果不需要輸出內容，請務必執行這項操作，釋放資源。