איך מתחילים?

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

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

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

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

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

Kotlin

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

מגניב

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

כאשר 1.4.1 היא הגרסה המועדפת עליכם. הגרסה האחרונה מופיעה בהערות המוצר.

חשוב: אם אתם משתמשים במודולים אחרים של Media3, כולל Media3 ExoPlayer, כולם צריכים להיות באותה גרסה.

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

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

אם עדיין לא הפעלתם את התמיכה ב-Java 8, צריך להוסיף את הקטע הבא לקטע android בכל הקבצים build.gradle שמסתמכים על Transformer:

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.

הערה לגבי שרשור

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

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

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