شروع به کار

برای موارد استفاده ساده، شروع با 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")

که در آن 1.8.0 نسخه ترجیحی شماست (آخرین نسخه را می توانید با مراجعه به یادداشت های انتشار پیدا کنید). همه ماژول ها باید از یک نسخه باشند.

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

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

پشتیبانی از جاوا 8 را روشن کنید

اگر قبلاً فعال نیست، باید حداقل پشتیبانی از جاوا 8 را در همه فایل‌های 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، استفاده از رشته اصلی برنامه الزامی است.

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

برای اطلاعات بیشتر در مورد مدل threading ExoPlayer، بخش "Threading model" ExoPlayer Javadoc را ببینید.

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

کتابخانه 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);

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

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

android:keepScreenOn="true"

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

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

در 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 انجام داد.