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

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

CompositionPlayer چیست؟

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

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

CompositionPlayer در مقابل ExoPlayer

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

ویژگی

پخش‌کننده‌ی ترکیب

اکسو پلیر

رسانه ورودی

یک شیء Composition واحد می‌گیرد که می‌تواند شامل چندین نمونه EditedMediaItem با جلوه‌های ویژه برای هر آیتم باشد.

یک MediaItem واحد یا یک لیست پخش از نمونه‌های MediaItem را می‌گیرد.

گاهشمار

جدول زمانی و مدت زمان بر اساس کل ترکیب است.

جدول زمانی و مدت زمان مربوط به آیتم رسانه‌ای فعال در حال پخش است.

اثرات

جلوه‌ها درون کامپوزیشن تعریف می‌شوند و می‌توانند روی یک EditedMediaItem یا کل کامپوزیشن اعمال شوند.

افکت‌ها با استفاده از تابع setVideoEffects() روی خود نمونه‌ی ExoPlayer تنظیم می‌شوند و هر افکت به صورت جداگانه روی هر آیتم در لیست پخش اعمال می‌شود.

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

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

ادغام CompositionPlayer در برنامه شما شامل چند مرحله کلیدی است. ابتدا، از الگوی Builder برای نمونه‌سازی یک CompositionPlayer استفاده کنید، سپس Composition برای پخش تنظیم کنید: 

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

برای راهنمایی در مورد نحوه ایجاد یک Composition ، به بخش ایجاد یک Composition مراجعه کنید.

توجه داشته باشید که از آنجایی که CompositionPlayer رابط Player را پیاده‌سازی می‌کند، می‌توانید خروجی هدف را تنظیم کرده و پخش‌کننده را از طریق متدهای استاندارد Player کنترل کنید.

مدیریت خطا

یک نمونه Player.Listener را به CompositionPlayer خود پیوست کنید تا به رویدادها و خطاهای پخش واکنش نشان دهد. تابع فراخوانی onPlayerError() همچنین هرگونه مشکلی را که از اجزای مخصوص ویرایش مانند Composition یا VideoGraph.Factory ناشی می‌شود، نشان می‌دهد. برای جزئیات بیشتر، مستندات رویدادهای Player را مطالعه کنید.

ملاحظات مهم

برخی از ویژگی‌ها و محدودیت‌هایی که باید هنگام استفاده CompositionPlayer در نظر داشته باشید:

  • اگرچه CompositionPlayer مبتنی بر رابط Player است، اما برخی از رفتارهای آن با ExoPlayer متفاوت است زیرا برای پخش به یک Composition وابسته است. به عنوان مثال، CompositionPlayer فقط از تنظیم حالت تکرار روی REPEAT_MODE_OFF یا REPEAT_MODE_ALL پشتیبانی می‌کند.
  • به طور پیش‌فرض، CompositionPlayer از SingleInputVideoGraph.Factory استفاده می‌کند، اما اگر Composition شما از بیش از یک توالی با آیتم‌های تصویر یا ویدیو استفاده می‌کند، باید هنگام ساخت نمونه CompositionPlayer خود setVideoGraphFactory() استفاده کنید تا به جای آن از MultipleInputVideoGraph.Factory استفاده کنید. SingleInputVideoGraph.Factory در صورتی کافی است که فقط یک توالی دارای آیتم‌های تصویر یا ویدیو باشد و بقیه فقط صدا داشته باشند.
  • تمام آیتم‌های رسانه‌ای در کامپوزیشن شما باید مدت زمان مشخصی داشته باشند، چه با MediaItem.Builder.setImageDurationMs() برای تصاویر، و چه با EditedMediaItem.Builder.setDurationUs() برای صدا یا ویدیو.

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

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

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

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

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

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