شروع به کار

برای موارد استفاده ساده، شروع به کار با 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.10.0")
implementation("androidx.media3:media3-exoplayer-dash:1.10.0")
implementation("androidx.media3:media3-ui:1.10.0")
implementation("androidx.media3:media3-ui-compose-material3:1.10.0")

گرووی 

implementation "androidx.media3:media3-exoplayer:1.10.0"
implementation "androidx.media3:media3-exoplayer-dash:1.10.0"
implementation "androidx.media3:media3-ui:1.10.0"
implementation("androidx.media3:media3-ui-compose-material3:1.10.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()
HelloWorld.kt

جاوا 

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

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

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

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

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

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

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

کاتلین 

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

جاوا 

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

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

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

android:keepScreenOn="true"

اگر برنامه شما از Jetpack Compose برای رابط کاربری خود استفاده می‌کند، می‌توانید از Player Composable از کتابخانه media3-ui-compose-material3 استفاده کنید. Player ویدیو را نمایش می‌دهد و شامل مقادیر از پیش تعیین‌شده برای اسلات‌های کنترل پخش است. برای اتصال یک شیء androidx.media3.common.Player به یک androidx.media3.ui.compose.material3.Player Composable، فقط آن را به عنوان یک آرگومان ارسال کنید: 

// Bind the player to the composable.
Player(player = player)
HelloWorld.kt

برای اطلاعات بیشتر در مورد استفاده از اجزای رابط کاربری 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()
HelloWorld.kt

جاوا 

// 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();
HelloWorld.java

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()
HelloWorld.kt

جاوا 

// 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();
HelloWorld.java

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

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

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

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

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

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

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