شروع به کار

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

جاوا 

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

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

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

The thread on which an ExoPlayer instance must be accessed can be explicitly specified by passing a Looper when creating the player. If no Looper is specified, then the Looper of the thread that the player is created on is used, or if that thread does not have a Looper , the Looper of the application's main thread is used. In all cases, the Looper of the thread from which the player must be accessed can be queried using Player.getApplicationLooper .

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

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

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

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

The playlist can be updated during playback without the need to prepare the player again. Read more about populating and manipulating the playlist on the Playlists page . Read more about the different options available when building media items, such as clipping and attaching subtitle files, on the Media items page .

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

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

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

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

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

It's important to release the player when it's no longer needed, so as to free up limited resources such as video decoders for use by other applications. This can be done by calling ExoPlayer.release .