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

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

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

Media3 همچنین پیاده‌سازی میانای Player را ارائه می‌دهد که ExoPlayer نامیده می‌شود.

میانای متداول بین مؤلفه‌ها

چندین مؤلفه در Media3 واسط Player را پیاده‌سازی می‌کنند، برای مثال:

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

معماری بازپخش Media3

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

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

وضعیت پخش‌کننده

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

1. وضعیت بازپخش
   • با getPlaybackState() بازیابی کنید.
   • مقدار وضعیت تعریف‌شده توسط میانای STATE_IDLE، STATE_BUFFERING، STATE_READY، و STATE_ENDED است.
2. فهرست پخش فایل‌های رسانه‌ای
   • توالی MediaItem نمونه برای بازپخش.
   • بازیابی با getCurrentTimeline()
   • Player instances can provide playlist operation methods like adding or removing a MediaItem and convenience methods like getCurrentMediaItem().
3. ویژگی‌های پخش/مکث، مانند:
   • playWhenReady: نشانه‌ای از اینکه آیا کاربر می‌خواهد رسانه درصورت امکان پخش شود یا در حالت توقف موقت باقی بماند
   • دلیل توقف بازپخش: نشانه‌ای از دلیل توقف بازپخش، درصورت وجود، حتی اگر playWhenReady true باشد
   • isPlaying: نشانه‌ای از اینکه آیا پخش‌کننده درحال‌حاضر درحال پخش است یا نه، که فقط true خواهد بود اگر وضعیت بازپخش STATE_READY باشد، playWhenReady true باشد، و بازپخش سرکوب نشده باشد
4. موقعیت بازپخش، ازجمله:
   • نمایه فایل رسانه‌ای کنونی: نمایه MediaItem کنونی در فهرست پخش.
   • isPlayingAd: نشانه‌ای از اینکه آیا آگهی درج‌شده درحال پخش است یا نه.
   • موقعیت بازپخش فعلی: موقعیت بازپخش فعلی در MediaItem فعلی یا آگهی درج‌شده.

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

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

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

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

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

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

کنترل بازپخش

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

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

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

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

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

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

class CustomPlayer(looper: Looper) : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(Commands.EMPTY) // 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()
  }
}
Player.kt

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

  @Override
  protected State getState() {
    return new State.Builder()
        .setAvailableCommands(Commands.EMPTY) // 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();
  }
}
Player.java

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

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

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

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