تحديد تركيبة عناصر الوسائط

توفّر مكتبة Media3 Transformer مجموعة من الأدوات لتعديل الوسائط ومعالجتها. ومن المكوّنات الأساسية لتعديل مواد عرض متعدّدة واجهة برمجة التطبيقات Composition. تتيح لك هذه الواجهة ترتيب عدة مواد وسائط إدخال، مثل مقاطع الفيديو والصور والمقاطع الصوتية، في بنية واحدة متماسكة يمكن معالجتها أو معاينتها أو تصديرها بعد ذلك. يمكن اعتبار Composition بمثابة مخطط زمني يحتوي على تسلسل واحد أو أكثر من تسلسلات الوسائط. يحتوي كل تسلسل (محدّد بواسطة EditedMediaItemSequence) على مواد وسائط فردية (محدّدة ككائنات EditedMediaItem). يمكن تطبيق عمليات التحويل والتأثيرات على فرديEditedMediaItem أو على Composition بأكمله.

Composition هي نقطة الدخول إلى مجموعة متنوّعة من حالات الاستخدام مع Media3 Transformer، مثل:

• الجمع بين مواد العرض الصوتية والمرئية والفيديو بالتسلسل
• تراكب فيديو على فيديو آخر (صورة داخل صورة)
• دمج مقطع صوتي في الخلفية مع تسلسل فيديو
• تطبيق تأثيرات مرئية أو صوتية على مقطع معدَّل بأكمله
• التعامل مع السيناريوهات المعقدة، مثل معالجة فيديو HDR

يركّز هذا الدليل على كيفية تحديد كائنات Composition وإنشائها، بما في ذلك الفئات الرئيسية المعنيّة، وكيفية إنشاء تركيبات أساسية وأكثر تعقيدًا باستخدام تسلسل واحد أو عدة تسلسلات، وكيفية تطبيق التأثيرات على مستويات مختلفة.

التعريفات والفئات الرئيسية

لاستخدام واجهة برمجة التطبيقات Composition بفعالية، من المهم فهم الفئات الرئيسية المعنيّة بإنشاء تركيبة وسائط:

Effects:

• الغرض: كائن Effects هو مجموعة من معالِجات الصوت وتأثيرات الفيديو.
• كيفية الاستخدام: في سياق Composition، يمكن ضبط Effects على كائنات EditedMediaItem فردية لتعديل مقاطع معيّنة، أو على Composition بأكمله (عادةً لتأثيرات Presentation التي تؤثّر في الناتج النهائي، مثل تعديل دقة العرض أو معدّل الإطارات).
• سبب الأهمية: Effects هي الآلية لتطبيق عمليات التحويل والفلاتر والمعالجة الأخرى على الوسائط على مستوى كل مادة عرض وعلى مستوى التركيبة بشكل عام. لمزيد من المعلومات، يُرجى الاطّلاع على Transformations.

EditedMediaItem:

• الغرض: تمثّل هذه الفئة مادة وسائط واحدة (مثل فيديو أو صورة أو ملف صوتي) والتعديلات التي سيتم تطبيقها عليها.
• كيفية الاستخدام: يجمّع EditedMediaItem كائن MediaItem (الذي يشير إلى محتوى الوسائط الفعلي) مع كائن Effects.
• سبب الأهمية: هذه هي اللبنة الأساسية للتركيبة. تتيح لك تحديد الوسائط التي تريد تضمينها بدقة وكيفية ظهور كل مادة وسائط فردية وصوتها قبل دمجها مع مواد أخرى في تسلسل.

EditedMediaItemSequence:

• الغرض: يمثّل تسلسلاً خطيًا من كائنات EditedMediaItem التي يُفترض تشغيلها واحدًا تلو الآخر.
• كيفية الاستخدام: يتم إنشاء EditedMediaItemSequence باستخدام قائمة من EditedMediaItem كائنات. يشبه كل تسلسل ضِمن Composition مقطعًا أو طبقة في مخطط زمني لتعديل الفيديو متعدد المقاطع. على سبيل المثال، قد يحتوي أحد التسلسلات على مقاطع الفيديو الرئيسية، بينما قد يحتوي تسلسل آخر، يتداخل في الوقت، على مقاطع فيديو يتم تراكبها على التسلسل الأول، وقد يحتوي تسلسل آخر على مقطع صوتي فقط للموسيقى في الخلفية.
• سبب الأهمية: يجمّع EditedMediaItemSequence مواد وسائط ذات صلة يجب أن تتبع بعضها البعض مباشرةً. باستخدام تسلسلات متعددة، يمكنك إنشاء ترتيبات أكثر تعقيدًا، مثل إضافة طبقات صوتية أو إنشاء تراكبات مرئية.

Composition:

• الغرض: هذا هو الكائن ذو المستوى الأعلى الذي يمثّل المخطط الزمني الكامل للوسائط التي سيتم معالجتها. يعمل كحاوية لجميع تسلسلات الوسائط وأي إعدادات أو تأثيرات عامة تنطبق على الناتج بأكمله.
• كيفية الاستخدام: يتكوّن Composition من كائن واحد أو أكثر من كائنات EditedMediaItemSequence يمكنك أيضًا تطبيق تأثيرات على مستوى التركيبة وضبط الإعدادات العامة، مثل وضع HDR، مباشرةً على Composition. إذا كان Composition يحتوي على عدة كائنات EditedMediaItemSequence، يمكن ترتيب هذه التسلسلات لتشغيلها بالتسلسل أو يمكن أن تتداخل في الوقت، ما يسمح بتصاميم متراكبة، مثل صورة داخل صورة أو عمليات انتقال من تسلسل إلى آخر.
• سبب الأهمية: يحدّد Composition البنية العامة لوسائط الإدخال التي سيتم معالجتها، وهو كائن شائع يمكنك استخدامه لمعاينة التعديلات باستخدام CompositionPlayer وتصدير فيديو ناتج مع تطبيق التعديلات باستخدام Transformer.

إنشاء Composition وتصديره

في ما يلي مثال على إنشاء مادة عرض فيديو تتكوّن من مقطعَين معدَّلَين من الفيديو، يتم تراكبهما مع مقطع صوتي، وتصديرها:

val video1 = EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build()

val video2 = EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build()

val videoSequence = EditedMediaItemSequence.withAudioAndVideoFrom(listOf(video1, video2))

val backgroundAudio = EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build()

val backgroundAudioSequence =
  EditedMediaItemSequence.withAudioFrom(listOf(backgroundAudio))
    .buildUpon()
    .setIsLooping(true) // Loop audio track through duration of videoSequence
    .build()

val composition = Composition.Builder(videoSequence, backgroundAudioSequence).build()

transformer.start(composition, filePath)
Composition.kt

EditedMediaItem video1 = new EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build();

EditedMediaItem video2 = new EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build();

EditedMediaItemSequence videoSequence =
    EditedMediaItemSequence.withAudioAndVideoFrom(ImmutableList.of(video1, video2));

EditedMediaItem backgroundAudio =
    new EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build();

EditedMediaItemSequence backgroundAudioSequence =
    EditedMediaItemSequence.withAudioFrom(ImmutableList.of(backgroundAudio))
        .buildUpon()
        .setIsLooping(true) // Loop audio track through duration of videoSequence
        .build();

Composition composition =
    new Composition.Builder(videoSequence, backgroundAudioSequence).build();

transformer.start(composition, filePath);
CompositionJava.java

أمثلة على حالات الاستخدام المتوافقة

في ما يلي قائمة غير شاملة بحالات الاستخدام التي تتيحها واجهة برمجة التطبيقات Transformer API مع Composition:

• الجمع بين مواد العرض الصوتية والمرئية والفيديو بالتسلسل
• إضافة صوت في الخلفية إلى مادة عرض فيديو
• إضافة تأثيرات إلى التركيبة
• تحويل النطاق الديناميكي العالي (HDR) للإدخال إلى نطاق ديناميكي عادي (SDR) لإنشاء ناتج SDR بجودة مرئية أفضل

القيود الحالية

يجب أن تستوفي التسلسلات ضِمن التركيبة الشروط الموضّحة في Transformer.start(). بالإضافة إلى ذلك، لا تتوفّر العمليات التالية بعد عند العمل باستخدام التركيبات:

• تلاشي مقاطع الفيديو أو المقاطع الصوتية

طلبات الميزات

إذا كانت لديك أي طلبات ميزات لواجهات برمجة التطبيقات Transformer API، يمكنك الإبلاغ عن مشكلة في مستودع Media3 على GitHub.