開始使用

如要開始使用 Transformer，請按照下列步驟操作：

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

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

新增 Media3 Transformer 做為依附元件

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

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

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

其中 1.3.1 是偏好版本。您可以在版本資訊中找到最新版本。

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

開啟 Java 8 支援

如果尚未啟用 Java 8，您必須在依附 Transformer 的所有 build.gradle 檔案啟用 Java 8 支援，方法是將以下內容新增至 android 區段：

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

開始轉換

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

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)

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 執行個體必須透過單一應用程式執行緒存取，且會在同一個執行緒上呼叫事件監聽器方法。在大多數情況下，應用程式執行緒可以單純是應用程式的主要執行緒。在內部，Transformer 會在背景執行工作，並將呼叫發布至應用程式執行緒上的事件監聽器方法。

監聽事件

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

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

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 方法以更新進度列。

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

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 取消匯出作業。硬體視訊轉碼器等資源有限，尤其是在低階裝置上，因此在不需要輸出內容時，請務必釋出資源。