شروع به کار

برای موارد استفاده ساده، شروع به کار با ExoPlayer شامل اجرای مراحل زیر است:

  1. ExoPlayer را به عنوان یک وابستگی به پروژه خود اضافه کنید.
  2. یک نمونه ExoPlayer ایجاد کنید.
  3. پخش‌کننده را به یک نما (برای خروجی ویدیو و ورودی کاربر) وصل کنید.
  4. پخش‌کننده را با یک MediaItem برای پخش آماده کنید.
  5. وقتی کارتان تمام شد، پخش‌کننده را رها کنید.

این مراحل با جزئیات بیشتر در زیر شرح داده شده‌اند. برای یک مثال کامل، به PlayerActivity در برنامه آزمایشی اصلی مراجعه کنید.

ExoPlayer را به عنوان یک وابستگی اضافه کنید

ماژول‌های ExoPlayer را اضافه کنید

ساده‌ترین راه برای شروع استفاده از AndroidX Media3، اضافه کردن وابستگی‌های gradle به کتابخانه‌های مورد نیاز در فایل build.gradle ماژول برنامه شما است.

برای مثال، برای وابستگی به ExoPlayer با پشتیبانی از پخش DASH و اجزای رابط کاربری، می‌توانید وابستگی‌هایی را به ماژول‌ها مانند این اضافه کنید:

کاتلین 

implementation("androidx.media3:media3-exoplayer:1.8.0")
implementation("androidx.media3:media3-exoplayer-dash:1.8.0")
implementation("androidx.media3:media3-ui:1.8.0")
implementation("androidx.media3:media3-ui-compose:1.8.0")

گرووی 

implementation "androidx.media3:media3-exoplayer:1.8.0"
implementation "androidx.media3:media3-exoplayer-dash:1.8.0"
implementation "androidx.media3:media3-ui:1.8.0"
implementation("androidx.media3:media3-ui-compose:1.8.0")

که در آن نسخه ۱.۸.۰ نسخه مورد نظر شماست (آخرین نسخه را می‌توانید با مراجعه به یادداشت‌های انتشار پیدا کنید). همه ماژول‌ها باید از یک نسخه باشند.

AndroidX Media3 ماژول‌های کتابخانه‌ای دارد که برای ارائه قابلیت‌های اضافی به کتابخانه‌های خارجی وابسته هستند. برخی از آنها از مخزن Maven در دسترس هستند، در حالی که برخی دیگر باید به صورت دستی ساخته شوند. برای جزئیات بیشتر، فهرست کتابخانه‌ها را مرور کنید و README های جداگانه را ببینید.

اطلاعات بیشتر در مورد ماژول‌های کتابخانه‌ای موجود را می‌توانید در صفحه Google Maven AndroidX Media بیابید.

فعال کردن پشتیبانی از جاوا ۸

اگر از قبل فعال نشده است، باید حداقل پشتیبانی از جاوا ۸ را در تمام فایل‌های build.gradle که به ExoPlayer وابسته هستند، با اضافه کردن موارد زیر به بخش android ، فعال کنید:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

بازیکن را ایجاد کنید

شما می‌توانید با استفاده از ExoPlayer.Builder یک نمونه ExoPlayer ایجاد کنید که طیف وسیعی از گزینه‌های سفارشی‌سازی را ارائه می‌دهد. کد زیر ساده‌ترین مثال از ایجاد یک نمونه است.

کاتلین 

val player = ExoPlayer.Builder(context).build()

جاوا 

ExoPlayer player = new ExoPlayer.Builder(context).build();

نکته‌ای در مورد نخ‌کشی

نمونه‌های ExoPlayer باید از طریق یک نخ برنامه قابل دسترسی باشند. در اکثر موارد، این باید نخ اصلی برنامه باشد. استفاده از نخ اصلی برنامه هنگام استفاده از اجزای رابط کاربری ExoPlayer یا افزونه IMA الزامی است.

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

برای اطلاعات بیشتر در مورد مدل نخ‌کشی ExoPlayer، به بخش «مدل نخ‌کشی» در Javadoc ExoPlayer مراجعه کنید.

پخش کننده را به یک نما وصل کنید

کتابخانه ExoPlayer مجموعه‌ای از کامپوننت‌های رابط کاربری از پیش ساخته شده را برای پخش رسانه ارائه می‌دهد. این کامپوننت‌ها شامل PlayerView هستند که یک PlayerControlView ، یک SubtitleView و یک Surface که ویدیو روی آن رندر می‌شود را کپسوله‌سازی می‌کند. یک PlayerView می‌تواند در طرح‌بندی xml برنامه شما گنجانده شود. به عنوان مثال، برای اتصال پخش‌کننده به نما:

کاتلین 

// Bind the player to the view.
playerView.player = player

جاوا 

// Bind the player to the view.
playerView.setPlayer(player);

استفاده از اجزای رابط کاربری از پیش ساخته شده ExoPlayer اختیاری است. برای برنامه‌های ویدیویی که رابط کاربری مخصوص به خود را پیاده‌سازی می‌کنند، می‌توان به ترتیب با استفاده از متدهای setVideoSurfaceView ، setVideoTextureView ، setVideoSurfaceHolder و setVideoSurface از ExoPlayer، هدف SurfaceView ، TextureView ، SurfaceHolder یا Surface را تنظیم کرد. می‌توان از فراخوانی Listener.onCues برای دریافت زیرنویس‌هایی که باید در حین پخش رندر شوند و setImageOutput برای دریافت تصاویر رمزگشایی شده استفاده کرد.

برای یک تجربه کاربری راحت‌تر، اضافه کردن ویژگی keepScreenOn یا تنظیم قفل بیدارباش روی ExoPlayer را در نظر بگیرید. می‌توانید اقدامات دیگری را که دستگاه را در صفحات کاری پس‌زمینه بیدار نگه می‌دارند، بررسی کنید.

android:keepScreenOn="true"

برای اطلاعات بیشتر در مورد استفاده از اجزای رابط کاربری Media3 و سفارشی‌سازی آنها، به صفحه رابط کاربری مراجعه کنید.

پر کردن لیست پخش و آماده‌سازی پخش‌کننده

در ExoPlayer، هر قطعه رسانه توسط یک MediaItem نمایش داده می‌شود. برای پخش یک قطعه رسانه، باید یک MediaItem مربوطه بسازید، آن را به پخش‌کننده اضافه کنید، پخش‌کننده را آماده کنید و برای شروع پخش، تابع play فراخوانی کنید:

کاتلین 

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

جاوا 

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

ExoPlayer مستقیماً از لیست‌های پخش پشتیبانی می‌کند، بنابراین می‌توان پخش‌کننده را با چندین آیتم رسانه‌ای آماده کرد تا یکی پس از دیگری پخش شوند:

کاتلین 

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

جاوا 

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

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

کنترل پخش کننده

پس از آماده شدن پخش‌کننده، می‌توان پخش را با فراخوانی متدهایی روی پخش‌کننده کنترل کرد. در اینجا برخی از رایج‌ترین متدها آورده شده است:

  • play و pause ، شروع و مکث پخش.
  • seekTo امکان جستجو در داخل رسانه را فراهم می‌کند.
  • hasPrevious ، hasNext ، previous و next امکان پیمایش در لیست پخش را فراهم می‌کنند.
  • setRepeatMode کنترل می‌کند که آیا و چگونه رسانه تکرار شود.
  • setShuffleModeEnabled تغییر در لیست پخش را کنترل می‌کند.
  • setPlaybackParameters سرعت پخش و زیر و بمی صدا را تنظیم می‌کند.

اگر پخش‌کننده به یک PlayerView یا PlayerControlView متصل باشد، تعامل کاربر با این اجزا باعث می‌شود که متدهای مربوطه در پخش‌کننده فراخوانی شوند.

بازیکن را آزاد کنید

مهم است که وقتی دیگر به پخش‌کننده نیازی نیست، آن را آزاد کنید تا منابع محدودی مانند رمزگشاهای ویدیو برای استفاده توسط سایر برنامه‌ها آزاد شوند. این کار را می‌توان با فراخوانی ExoPlayer.release انجام داد.