الخطوات الأولى

تتألف عملية البدء في استخدام Transformer من الخطوات التالية:

1. أضف Media3 Transformer كتبعية في مشروعك.
2. أنشِئ EditedMediaItem تمثّل الوسائط التي تريد معالجتها والتعديلات عليها.
3. أنشئ Transformer يصف الإخراج المطلوب ومستمعًا لأحداث الاكتمال والأخطاء.
4. ابدأ عملية التصدير، مع إدخال EditedMediaItem لتعديله وأحد مسارات الإخراج. أثناء التصدير، يمكنك الاستعلام عن مستوى التقدّم الحالي أو إلغاء العملية.
5. عند انتهاء عملية التصدير، تعامل مع الإخراج حسب الحاجة. على سبيل المثال، يمكنك مشاركة المخرجات مع تطبيق آخر أو تحميلها على خادم.

اطّلِع على المزيد من التفاصيل حول هذه الخطوات، واطّلِع على TransformerActivity في تطبيق نموذج "المحوِّل" التمهيدي للحصول على مثال كامل.

إضافة Media3 Transformer كعنصر تابع

تتمثل أسهل طريقة لبدء استخدام Transformer في إضافة تبعيات Gradle إلى المكتبة في ملف build.gradle بوحدة تطبيقك:

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 هو الإصدار المفضّل لديك. يمكن العثور على أحدث إصدار من خلال الرجوع إلى ملاحظات الإصدار.

يمكنك الاطّلاع على مزيد من المعلومات عن وحدات المكتبة المتاحة على صفحة Google Maven AndroidX Media3.

تفعيل ميزة "التوافق مع Java 8"

إذا لم يتم التفعيل من قبل، يجب تفعيل دعم Java 8 في جميع ملفات build.gradle التي تعتمد على Transformer من خلال إضافة ما يلي إلى قسم android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

بدء عملية تحويل

في ما يلي مثال على إنشاء EditedMediaItem لإزالة الصوت من ملف input ، ثم إنشاء مثيل 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 عمله في الخلفية وينشر طلبات الاستماع إلى methods في سلسلة محادثات التطبيق.

الاستماع إلى الأحداث

الطريقة 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". إنّ الموارد، مثل برامج ترميز الفيديوهات للأجهزة، محدودة، خاصةً على الأجهزة المنخفضة التكلفة، لذا من المهم إجراء ذلك لإخلاء الموارد إذا لم تكن النتيجة مطلوبة.