開始使用

Transformer 的開始步驟如下：

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

請繼續閱讀，進一步瞭解這些步驟，並參閱轉換器示範應用程式中的 TransformerActivity，瞭解完整範例。

將 Media3 轉換器新增為依附元件

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

Kotlin

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

Groovy

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

其中 1.5.0 是您偏好的版本。您可以參閱版本資訊，查看最新版本。

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

開啟 Java 8 支援

如果尚未啟用，您必須在所有依附 Transformer 的 build.gradle 檔案中啟用 Java 8 支援功能，方法是在 android 區塊中加入下列內容：

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 取消匯出作業。硬體影片編解碼等資源有限，尤其是在低階裝置上，因此如果不需要輸出，請務必執行這項操作，釋出資源。