شروع به کار

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

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

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

افزودن ExoPlayer به‌عنوان وابستگی

برای استفاده از ExoPlayer در برنامه‌تان، واحدهای لازم را اضافه کنید و پشتیبانی از Java 8 را فعال کنید.

افزودن پیمانه‌های ExoPlayer

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

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

کاتلین

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

شیک

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

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

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

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

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

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

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

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

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

کاتلین

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

جاوا

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

استفاده از مؤلفه‌های میانای کاربر ازپیش‌ساخته Media3 اختیاری است. برای برنامه‌های ویدیویی که رابط کاربری خودشان را پیاده‌سازی می‌کنند، SurfaceView، TextureView، SurfaceHolder یا Surface هدف را می‌توان به‌ترتیب بااستفاده از روش‌های setVideoSurfaceView، setVideoTextureView، setVideoSurfaceHolder، و setVideoSurface «پخش‌کننده» تنظیم کرد. از فراخوانی برگشتی 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)

برای کسب اطلاعات بیشتر درباره استفاده از مؤلفه‌های واسط کاربر 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 انجام دهید.