پیش‌نمایش ویرایش‌ها با CompositionPlayer

کتابخانه Jetpack Media3 CompositionPlayer API را ارائه می‌دهد، پیاده‌سازی Player قدرتمندی برای پیش‌نمایش ویرایش‌های ویدیو در زمان واقعی. اگر برنامه شما به کاربران اجازه می‌دهد ویدیوها را ویرایش کنند، مثلاً جلوه اعمال کنند، برش دهند، یا چندین عنصر رسانه‌ای ورودی را ترکیب کنند، CompositionPlayer به شما کمک می‌کند پیش‌نمایش دقیقی از برونداد نشان دهید. این کار می‌تواند در مواردی که نیازی به ذخیره ویرایش‌های اعمال‌شده ندارید یا برای تأیید اینکه ویرایش‌ها همان‌گونه که درنظر گرفته شده‌اند پیکربندی شده‌اند، قبل‌از اینکه آن‌ها را به ویدیو نهایی برای صادر کردن اختصاص دهید، ارزشمند باشد.

CompositionPlayer چیست؟

‫CompositionPlayer پیاده‌سازی تخصصی از واسط پخش‌کننده است که به‌طور خاص برای پخش کردن اشیای Composition طراحی شده است. Composition تعریف می‌کند دارایی‌های رسانه‌ای ورودی، مانند کلیپ‌های ویدیویی و قطعه‌های صوتی، چگونه چیده شوند و چه جلوه‌های صوتی و تصویری باید روی آن‌ها اعمال شود. برای کسب اطلاعات بیشتر درباره Composition API، به تعریف Composition عناصر رسانه‌ای مراجعه کنید.

هدف اصلی CompositionPlayer ارائه این Composition، کامل با همه ویرایش‌های مشخص‌شده، در زمان واقعی است و به کاربران امکان می‌دهد دقیقاً ببینند ویرایش‌هایشان قبل‌از تعهد به فرایند برون‌برد که احتمالاً زمان‌بر و مصرف‌کننده منابع است چگونه خواهد بود. سپس می‌توان از همان شیء Composition با نمونه Transformer برای صادر کردن استفاده کرد که می‌توانید در صادر کردن Composition درباره آن بیشتر بدانید.

‫CompositionPlayer مقابل ExoPlayer

اگرچه هم CompositionPlayer و هم ExoPlayer پیاده‌سازی‌های Player در Media3 هستند، اما برای موارد استفاده متفاوت بهینه‌سازی شده‌اند:

در اصل، CompositionPlayer زمانی بیشترین کمک را می‌کند که نیاز به پرداز کردن Composition پیچیده‌ای از رسانه و جلوه‌ها داشته باشید، معمولاً در بافت ویرایش. از ExoPlayer برای بازپخش عمومی محتوای صوتی یا ویدیویی، یا برای پیش‌نمایش ویرایش‌های تک‌دارایی با setVideoEffects() استفاده کنید.

‫CompositionPlayer برای پیش‌نمایش

ادغام CompositionPlayer در برنامه شما شامل چند مرحله کلیدی است. ابتدا، از الگوی «سازنده» برای نمونه‌سازی 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 استفاده می‌کند، اما اگر «قطعه موسیقی» شما از بیش‌از یک توالی با عناصر تصویر یا ویدیو استفاده می‌کند، هنگام ساختن نمونه CompositionPlayer خود باید از setVideoGraphFactory() استفاده کنید تا به‌جای آن از MultipleInputVideoGraph.Factory استفاده کنید. اگر فقط یک توالی دارای عناصر تصویر یا ویدیو باشد و بقیه فقط صوتی باشند، SingleInputVideoGraph.Factory کافی است.
• همه عناصر رسانه‌ای در «قطعه» شما باید مدت زمان مشخصی داشته باشند، یا با MediaItem.Builder.setImageDurationMs() برای تصاویر، یا با EditedMediaItem.Builder.setDurationUs() برای صدا یا ویدیو.

موارد استفاده زیر پشتیبانی می‌شود:

• پیش‌نمایش تک‌دارایی.
• پیش‌نمایش تک‌توالی (یعنی فایل‌های رسانه‌ای متوالی).
• پیش‌نمایش توالی ویدیو تکی + توالی صوتی تکی (برای مثال، صدای پس‌زمینه).

موارد استفاده زیر درحال توسعه فعال هستند:

• پیش‌نمایش چند دارایی، شامل چیدمان‌هایی مثل تصویردرتصویر، کنارهم، و جدولی، که در آن چندین توالی ویدیو درگیر است.
• سفارشی‌سازی خط لوله ویرایش با موتور گرافیکی متفاوت.

درخواست‌های ویژگی

اگر درخواست ویژگی یا بازخوردی برای CompositionPlayer دارید، مشکلی را در مخزن GitHub مربوط به Media3 ثبت کنید.