תחילת העבודה

כדי להתחיל להשתמש ב-Transformer, צריך לבצע את השלבים הבאים:

  1. מוסיפים את Media3 Transformer כתלות בפרויקט.
  2. יוצרים EditedMediaItem שמייצג את המדיה שרוצים לעבד ואת העריכות שרוצים להחיל עליה.
  3. יוצרים Transformer, מתארים את הפלט הנדרש ומאזין לאירועי השלמה ושגיאה.
  4. מתחילים את פעולת הייצוא, ומעבירים את ה-EditedMediaItem לעריכה ואת נתיב הפלט. במהלך הייצוא, אתם יכולים לשלוח שאילתה לגבי ההתקדמות הנוכחית או לבטל את הפעולה.
  5. כשהייצוא מסתיים, מטפלים בפלט לפי הצורך. לדוגמה, אתם יכולים לשתף את הפלט עם אפליקציה אחרת או להעלות אותו לשרת.

בהמשך מפורט מידע נוסף על השלבים האלה, וב-TransformerActivity באפליקציית ההדגמה של Transformer יש דוגמה פתורה.

הוספת Media3 Transformer כתלות

הדרך הכי קלה להתחיל להשתמש ב-Transformer היא להוסיף יחסי תלות של Gradle בספרייה בקובץ build.gradle של מודול האפליקציה:

Kotlin

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

מגניב

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

כאשר 1.11.1 היא הגרסה המועדפת. הגרסה העדכנית ביותר מופיעה בנתוני הגרסה.

מידע נוסף על המודולים הזמינים של הספרייה זמין בדף Google Maven AndroidX Media3.

הפעלת התמיכה ב-Java 8

אם התמיכה ב-Java 8 עדיין לא מופעלת, צריך להפעיל אותה בכל קובצי build.gradle שתלויים ב-Transformer. כדי לעשות את זה, מוסיפים את הקוד הבא לקטע 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 משרשור אחד של האפליקציה, והשיטות של המאזין נקראות באותו שרשור. ברוב המקרים, ה-thread של האפליקציה יכול להיות ה-thread הראשי של האפליקציה. באופן פנימי, Transformer פועל ברקע ומפרסם את הקריאות שלו לשיטות של מאזינים בשרשור של האפליקציה.

האזנה לאירועים

ה-method‏ start היא אסינכרונית. היא מחזירה מיד והאפליקציה מקבלת התראות על אירועים דרך פונקציית ה-listener שמועברת ל-builder של 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. משאבים כמו רכיבי codec של וידאו בחומרה מוגבלים, במיוחד במכשירים פשוטים יותר, לכן חשוב לעשות זאת כדי לפנות משאבים אם הפלט לא נדרש.