תחילת העבודה

כדי להתחיל להשתמש ב-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")

Groovy

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