رابط پخش کننده

پخش‌کننده (player) بخشی از برنامه شماست که پخش آیتم‌های رسانه‌ای را تسهیل می‌کند. رابط کاربری Media3 Player طرحی کلی برای عملکردهایی که عموماً توسط یک پخش‌کننده انجام می‌شود، تنظیم می‌کند. این شامل موارد زیر است:

• تأثیرگذاری بر کنترل‌های پخش، مانند پخش، مکث و جستجو
• پرس‌وجو از ویژگی‌های رسانه در حال پخش، مانند موقعیت پخش
• مدیریت لیست پخش/صف اقلام رسانه‌ای
• پیکربندی ویژگی‌های پخش، مانند پخش تصادفی، تکرار، سرعت و میزان صدا
• رندر کردن ویدیو روی صفحه نمایش

Media3 همچنین پیاده‌سازی از رابط Player را با نام ExoPlayer ارائه می‌دهد.

رابط مشترک بین اجزا

چندین کامپوننت در Media3 رابط پخش‌کننده را پیاده‌سازی می‌کنند، برای مثال:

اگرچه یک MediaSession رابط Player را پیاده‌سازی نمی‌کند، اما هنگام ایجاد آن به یک Player نیاز دارد. هدف آن فراهم کردن دسترسی به Player از طریق سایر فرآیندها یا نخ‌ها است.

معماری پخش Media3

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

هنگام پخش رسانه در پس‌زمینه، باید جلسه رسانه و پخش‌کننده خود را در یک MediaSessionService یا MediaLibraryService که به عنوان یک سرویس پیش‌زمینه اجرا می‌شود، قرار دهید. اگر این کار را انجام دهید، می‌توانید پخش‌کننده خود را از Activity در برنامه خود که شامل رابط کاربری برای کنترل پخش است، جدا کنید. این ممکن است مستلزم استفاده از یک کنترل‌کننده رسانه باشد.

وضعیت بازیکن

وضعیت یک پخش‌کننده رسانه که رابط Player را پیاده‌سازی می‌کند، عمدتاً از 4 دسته اطلاعات تشکیل شده است:

1. وضعیت پخش
   • بازیابی با getPlaybackState() .
   • مقدار وضعیت تعریف‌شده توسط رابط عبارتند از STATE_IDLE ، STATE_BUFFERING ، STATE_READY و STATE_ENDED .
2. لیست پخش موارد رسانه‌ای
   • دنباله‌ای از نمونه‌های MediaItem برای پخش.
   • بازیابی با getCurrentTimeline()
   • نمونه‌های Player می‌توانند متدهای عملیات لیست پخش مانند اضافه کردن یا حذف کردن یک MediaItem و متدهای راحتی مانند getCurrentMediaItem() را ارائه دهند.
3. ویژگی‌های پخش/مکث، مانند:
   • playWhenReady : نشانه‌ای از اینکه آیا کاربر می‌خواهد رسانه در صورت امکان پخش شود یا در حالت مکث باقی بماند
   • دلیل توقف پخش : نشانه‌ای از اینکه چرا پخش متوقف می‌شود، در صورت وجود، حتی اگر playWhenReady true داشته باشد
   • isPlaying : نشانه‌ای از اینکه آیا پخش‌کننده در حال پخش است یا خیر، که تنها در صورتی true خواهد بود که وضعیت پخش STATE_READY باشد، playWhenReady true باشد و پخش متوقف نشده باشد.
4. موقعیت پخش، شامل:
   • فهرست آیتم رسانه فعلی : فهرست MediaItem فعلی در لیست پخش.
   • isPlayingAd : نشانه‌ای از اینکه آیا تبلیغ درج‌شده در حال پخش است یا خیر.
   • موقعیت پخش فعلی : موقعیت پخش فعلی در MediaItem فعلی یا تبلیغ درج شده.

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

به تغییرات گوش دهید

از یک Player.Listener برای گوش دادن به تغییرات در یک Player استفاده کنید. برای جزئیات بیشتر در مورد نحوه ایجاد و استفاده از یک listener، به مستندات ExoPlayer در مورد رویدادهای Player مراجعه کنید.

توجه داشته باشید که رابط شنونده هیچ فراخوانی برای ردیابی پیشرفت پخش عادی ندارد. برای نظارت مداوم بر پیشرفت پخش، مانند تنظیم رابط کاربری نوار پیشرفت، باید موقعیت فعلی را در فواصل مناسب پرس و جو کنید.

val handler = Handler(Looper.getMainLooper())
fun checkPlaybackPosition(delayMs: Long): Boolean =
  handler.postDelayed(
    {
      val currentPosition = player.currentPosition
      // Update UI based on currentPosition
      checkPlaybackPosition(delayMs)
    },
    delayMs)

Handler handler = new Handler(Looper.getMainLooper());
boolean checkPlaybackPosition(long delayMs) {
    return handler.postDelayed(() -> {
        long currentPosition = player.getCurrentPosition();
        // Update UI based on currentPosition
        checkPlaybackPosition(delayMs);
    }, delayMs);
}

کنترل پخش

رابط کاربری Player روش‌های زیادی برای دستکاری وضعیت و کنترل پخش ارائه می‌دهد:

• کنترل‌های پخش پایه مانند play() ، pause() ، prepare() و stop()
• عملیات لیست پخش مانند addMediaItem() یا removeMediaItem()
• تلاش برای تغییر مورد یا موقعیت فعلی.
• حالت‌های تکرار و حالت پخش تصادفی را تنظیم کنید.
• تنظیمات انتخاب آهنگ را به‌روزرسانی کنید.
• سرعت پخش را تنظیم کنید.

پیاده‌سازی‌های Player سفارشی

برای ایجاد یک پخش‌کننده‌ی سفارشی، می‌توانید SimpleBasePlayer موجود در Media3 را گسترش دهید. این کلاس یک پیاده‌سازی پایه از رابط Player ارائه می‌دهد تا تعداد متدهایی که باید پیاده‌سازی کنید را به حداقل برساند.

با بازنویسی متد getState() شروع کنید. این متد باید هنگام فراخوانی، وضعیت فعلی بازیکن را شامل موارد زیر، در خود جای دهد:

• مجموعه دستورات موجود
• ویژگی‌های پخش، مانند اینکه آیا پخش‌کننده باید وقتی وضعیت پخش STATE_READY است، پخش را شروع کند یا خیر، اندیس آیتم رسانه‌ای در حال پخش و موقعیت پخش در آیتم فعلی

class CustomPlayer : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build()
  }
}

public class CustomPlayer extends SimpleBasePlayer {
  public CustomPlayer(Looper looper) {
    super(looper);
  }

  @Override
  protected State getState() {
    return new State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build();
  }
}

SimpleBasePlayer تضمین می‌کند که State با ترکیبی معتبر از مقادیر state ایجاد شده باشد. همچنین listenerها را مدیریت کرده و listenerها را از تغییرات state مطلع می‌کند. اگر نیاز دارید که به‌روزرسانی state را به صورت دستی فعال کنید، invalidateState() را فراخوانی کنید.

فراتر از متد getState() ، شما فقط باید متدهایی را پیاده‌سازی کنید که برای دستوراتی که پخش‌کننده شما اعلام می‌کند در دسترس هستند، استفاده می‌شوند. متد کنترل‌کننده‌ی قابل لغوی را که مربوط به عملکردی است که می‌خواهید پیاده‌سازی کنید، پیدا کنید. برای مثال، متد handleSeek() را برای پشتیبانی از عملیاتی مانند COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM و COMMAND_SEEK_TO_NEXT_MEDIA_ITEM لغو کنید.

اصلاح پیاده‌سازی‌های Player

به جای ایجاد یک Player کاملاً سفارشی، می‌توانید از ForwardingSimpleBasePlayer برای تغییر وضعیت و رفتار یک Player موجود استفاده کنید. برای جزئیات بیشتر به راهنمای صفحه Customization مراجعه کنید.