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

يتكون بدء استخدام "Transformer" من الخطوات التالية:

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

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

إضافة المحوِّل Media3 كتبعية

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

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

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

حيث يكون الإصدار 1.4.0 هو الإصدار المفضل لديك. يمكن أن يكون أحدث إصدار تم العثور عليها من خلال الرجوع إلى إصدار الملاحظات.

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

تفعيل دعم Java 8

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

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

بدء تحويل

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

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

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