開始使用

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