معاينة التعديلات باستخدام CompositionPlayer

توفّر مكتبة Jetpack Media3 واجهة برمجة التطبيقات CompositionPlayer، وهي عملية تنفيذ قوية Player لمعاينة تعديلات الفيديو في الوقت الفعلي. إذا كان تطبيقك يتيح للمستخدمين تعديل الفيديوهات، مثل تطبيق التأثيرات أو القص أو دمج عدة عناصر وسائط إدخال، يساعدك CompositionPlayer في عرض معاينة دقيقة للإخراج. يمكن أن يكون هذا الإجراء مفيدًا في الحالات التي لا تحتاج فيها إلى حفظ التعديلات التي تم تطبيقها، أو للتحقّق من أنّ التعديلات تم ضبطها على النحو المطلوب قبل حفظها في الفيديو النهائي وتصديره.

ما المقصود بـ CompositionPlayer؟

CompositionPlayer هي عملية تنفيذ متخصّصة لواجهة Player، وهي مصمَّمة خصيصًا لتشغيل عناصر Composition. يحدّد Composition طريقة ترتيب مواد العرض الوسائطية، مثل مقاطع الفيديو والمقاطع الصوتية، والتأثيرات الصوتية والمرئية التي يجب تطبيقها عليها. لمزيد من المعلومات حول واجهة برمجة التطبيقات Composition، يُرجى الاطّلاع على تحديد Composition لعناصر الوسائط.

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

‫CompositionPlayer مقارنةً بـ ExoPlayer

على الرغم من أنّ كلاً من CompositionPlayer وExoPlayer هما عمليات تنفيذ Player ضمن Media3، إلا أنّهما محسّنان لحالات استخدام مختلفة:

بشكل أساسي، تكون CompositionPlayer مفيدة جدًا عندما تحتاج إلى عرض Composition معقّد من الوسائط والتأثيرات، عادةً في سياق التعديل. استخدِم ExoPlayer لتشغيل محتوى صوتي أو فيديو بشكل عام، أو لمعاينة التعديلات على مواد عرض فردية باستخدام setVideoEffects().

CompositionPlayer للمعاينة

يتضمّن دمج CompositionPlayer في تطبيقك بعض الخطوات الرئيسية. أولاً، استخدِم نمط Builder لإنشاء مثيل CompositionPlayer، ثم اضبط Composition ليتم تشغيله:

val compositionPlayer = CompositionPlayer.Builder(context).build()
compositionPlayer.setComposition(composition)
compositionPlayer.prepare()
compositionPlayer.play()
CompositionPlayer.kt

للحصول على إرشادات حول كيفية إنشاء Composition، راجِع قسم إنشاء Composition.

يُرجى العِلم أنّه بما أنّ CompositionPlayer تنفّذ واجهة Player، يمكنك بعد ذلك ضبط الناتج المستهدف والتحكّم في المشغّل من خلال طرق Player العادية.

معالجة الأخطاء

أرفِق مثيلاً من Player.Listener بـ CompositionPlayer للتفاعل مع أحداث التشغيل والأخطاء. ستعرض وظيفة الاستدعاء onPlayerError() أيضًا أي مشاكل ناتجة عن تعديل مكوّنات معيّنة، مثل Composition أو VideoGraph.Factory. يمكنك الاطّلاع على مستندات أحداث اللاعبين لمزيد من التفاصيل.

اعتبارات مهمة

في ما يلي بعض الميزات والقيود التي يجب وضعها في الاعتبار عند استخدام CompositionPlayer:

• على الرغم من أنّ CompositionPlayer يستند إلى واجهة Player، تختلف بعض سلوكياته عن ExoPlayer لأنّه يعتمد على Composition لتشغيل المحتوى. على سبيل المثال، لا تتيح السمة CompositionPlayer سوى ضبط وضع التكرار على REPEAT_MODE_OFF أو REPEAT_MODE_ALL.
• يستخدم CompositionPlayer تلقائيًا SingleInputVideoGraph.Factory، ولكن إذا كان التصميم يستخدم أكثر من تسلسل واحد مع عناصر صور أو فيديو، يجب استخدام setVideoGraphFactory() عند إنشاء مثيل CompositionPlayer لاستخدام MultipleInputVideoGraph.Factory بدلاً من ذلك. يكون SingleInputVideoGraph.Factory كافيًا إذا كان تسلسل واحد فقط يتضمّن عناصر صور أو فيديوهات، وكانت العناصر الأخرى عبارة عن صوت فقط.
• يجب أن يتم ضبط مدة جميع عناصر الوسائط في المقطوعة الموسيقية بشكل صريح، إما باستخدام MediaItem.Builder.setImageDurationMs() للصور، أو باستخدام EditedMediaItem.Builder.setDurationUs() للملفات الصوتية أو الفيديوهات.

تتوفّر حالات الاستخدام التالية:

• معاينة مادة عرض واحدة
• معاينة تسلسل واحد (أي عناصر الوسائط المتسلسلة)
• معاينة تسلسل فيديو واحد + تسلسل صوتي واحد (على سبيل المثال، الصوت في الخلفية)

نعمل حاليًا على تطوير حالات الاستخدام التالية:

• معاينة مواد عرض متعددة، بما في ذلك تخطيطات مثل "صورة داخل صورة" و"جنبًا إلى جنب" و"شبكة"، حيث يتم عرض عدة تسلسلات فيديو
• تخصيص مسار التعديل باستخدام محرّك رسومات مختلف

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

إذا كانت لديك أي طلبات ميزات أو ملاحظات بشأن CompositionPlayer، يمكنك الإبلاغ عن مشكلة في مستودع Media3 على GitHub.