شروع به کار

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

که در آن ۱.۱۱.۱ نسخه ترجیحی شما است (جدیدترین نسخه را می‌توانید با مشاوره با یادداشت‌های انتشار پیدا کنید). همه واحدها باید از نسخه یکسانی باشند.

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

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

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

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

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

ایجاد پخش‌کننده

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

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

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

نکته‌ای درباره رشته‌سازی

به نمونه‌های 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
HelloWorld.kt

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

استفاده از عناصر رابط کاربری پیش‌ساخته 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 عنصر ترکیبی، کافی است آن را به‌عنوان آرگومان ارسال کنید:

// 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 انجام دهید.