التحكّم في تشغيل الإعلان والإعلان عنه باستخدام MediaSession

توفّر جلسات الوسائط طريقة عالمية للتفاعل مع مشغّل ملف صوتي أو فيديو. في Media3، يكون المشغّل التلقائي هو فئة ExoPlayer التي تنفّذ واجهة Player. من خلال ربط جلسة الوسائط بالمشغّل، يمكن للتطبيق إعلام المستخدمين بتشغيل الوسائط خارجيًا وتلقّي أوامر التشغيل من مصادر خارجية.

قد تأتي الأوامر من أزرار فعلية، مثل زر التشغيل على سماعة الرأس أو جهاز التحكّم عن بُعد بالتلفزيون. وقد تأتي أيضًا من تطبيقات العميل التي تتضمّن جهاز تحكّم في الوسائط، مثل توجيه "إيقاف مؤقت" إلى "مساعد Google". وتفوّض جلسة الوسائط هذه الطلبات إلى مشغّل تطبيق الوسائط.

حالات اختيار جلسة وسائط

عند تنفيذ MediaSession، تسمح للمستخدمين بالتحكم في التشغيل:

• من خلال سماعات الرأس غالبًا ما تتضمّن سمّاعات الرأس أزرارًا أو تفاعلات تعمل باللمس يمكن للمستخدِم تنفيذها لتشغيل الوسائط أو إيقافها مؤقتًا أو الانتقال إلى المقطع الصوتي التالي أو السابق.
• من خلال التحدّث إلى مساعد Google من الأنماط الشائعة قول "Ok Google، أريد إيقاف المحتوى مؤقتًا" لإيقاف أي محتوى وسائط يتم تشغيله حاليًا على الجهاز مؤقتًا.
• من خلال ساعة Wear OS ويتيح ذلك سهولة الوصول إلى عناصر التحكم في التشغيل الأكثر شيوعًا أثناء التشغيل على هواتفهم.
• من خلال عناصر التحكّم في الوسائط تعرِض لوحة العرض الدوّارة هذه عناصر التحكّم في كل جلسة وسائط تتم إعادة تشغيلها.
• على التلفزيون السماح بتنفيذ الإجراءات باستخدام أزرار التشغيل المادية والتحكّم في تشغيل المنصة وإدارة الطاقة (على سبيل المثال، إذا تم إيقاف تشغيل التلفزيون أو مكبّر الصوت العمودي أو جهاز استقبال A/V أو تم تبديل مصدر الإدخال، يجب إيقاف التشغيل في التطبيق)
• وأي عمليات خارجية أخرى تحتاج إلى التأثير في التشغيل

وهذا مفيد في العديد من حالات الاستخدام. وعلى وجه الخصوص، ننصحك بشدة باستخدامMediaSession في الحالات التالية:

• إذا كنت تبث محتوى فيديو طويل، مثل الأفلام أو البث التلفزيوني المباشر
• إذا كنت تبث محتوى صوتيًا طويلاً، مثل ملفات البودكاست أو قوائم تشغيل الموسيقى
• أنت تنشئ تطبيق تلفزيون.

ومع ذلك، لا تتوافق بعض حالات الاستخدام مع MediaSession. يمكنك استخدام الرمز Player فقط في الحالات التالية:

• إذا كنت تعرض محتوى قصيرًا، حيث يكون تفاعل المستخدمين مهمًا للغاية
• لا يتوفّر فيديو نشط واحد، مثل أن ينتقل المستخدم للأعلى أو للأسفل في قائمة ويظهر فيديوهات متعددة على الشاشة في الوقت نفسه.
• إذا كنت تعرض فيديو تقديميًا أو توضيحيًا لمرة واحدة، والذي تتوقّع أن يشاهده المستخدم بنشاط
• إذا كان المحتوى حساسًا من حيث الخصوصية ولا تريد أن تحصل العمليات الخارجية على إذن بالوصول إلى البيانات الوصفية للوسائط (مثل وضع التصفّح المتخفي في المتصفّح)

إذا لم يكن سيناريو الاستخدام الخاص بك يتطابق مع أيّ من السيناريوهات المذكورة أعلاه، ننصحك بالتفكير في ما إذا كان يناسبك أن يواصل تطبيقك تشغيل المحتوى عندما لا يتفاعل المستخدم معه بنشاط. إذا كانت الإجابة "نعم"، عليك على الأرجح اختيار MediaSession. إذا كانت الإجابة لا، ننصحك باستخدام العلامة Player بدلاً من ذلك.

إنشاء جلسة وسائط

تُعرض جلسة الوسائط بجانب المشغّل الذي تديره. يمكنك إنشاء جلسة وسائط باستخدام كائن Context وكائن Player. يجب إنشاء جلسة وسائط و تهيئةها عند الحاجة، مثل onStart() أو onResume() طريقة دورة حياة Activity أو Fragment أو onCreate() طريقة Service التي تملك جلسة الوسائط ومشغّلها المرتبط بها.

لإنشاء جلسة وسائط، يجب إعداد Player وتقديمه إلى "MediaSession.Builder" على النحو التالي:

Kotlin

val player = ExoPlayer.Builder(context).build()
val mediaSession = MediaSession.Builder(context, player).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();
MediaSession mediaSession = new MediaSession.Builder(context, player).build();

معالجة الحالة التلقائية

تعدّل مكتبة Media3 جلسة الوسائط تلقائيًا باستخدام حالة المشغّل. وبالتالي، لا تحتاج إلى إجراء عملية الربط يدويًا من المشغّل إلى الجلسة.

يختلف هذا النهج عن النهج القديم الذي كان يتطلّب إنشاء PlaybackStateCompat وإدارته بشكل مستقل عن المشغّل نفسه، على سبيل المثال لتحديد أي أخطاء.

ملاحظة: إذا كان تطبيقك يعتمد على حالة التشغيل كما هو مذكور أعلاه للتواصل مع العميل، مثل عند إضافة مصادقة إلى تطبيق لنظام التشغيل Android Automotive، عليك توخّي الحذر عند نقل البيانات إلى Media3. وذلك لأن إدارة الحالة التلقائية في Media3 تحل محل هذه الوظيفة السابقة. يُرجى الرجوع لاحقًا للحصول على إرشادات أكثر تفصيلاً حول أفضل طريقة للتعامل مع هذه الحالات.

المعرّف الفريد للجلسة

ينشئ MediaSession.Builder تلقائيًا جلسة باستخدام سلسلة فارغة كمعرّف الجلسة. وهذا كافٍ إذا كان التطبيق يريد إنشاء مثيل واحد فقط للجلسة، وهو الإجراء الأكثر شيوعًا.

إذا أراد التطبيق إدارة عدّة نُسخ من الجلسة في الوقت نفسه، عليه التأكّد من أنّ رقم تعريف الجلسة لكلّ جلسة فريد. يمكن ضبط معرّف الجلسة عند إنشاء الجلسة باستخدام MediaSession.Builder.setId(String id).

إذا ظهرت لك رسالة خطأ IllegalStateException تشير إلى تعطُّل تطبيقك IllegalStateException: Session ID must be unique. ID=، من المرجّح أنّه تم إنشاء جلسة بشكل غير متوقّع قبل إنهاء جلسة سابقة تم إنشاؤها باستخدام رقم التعريف نفسه. لتجنّب تسرُّب الجلسات بسبب خطأ في البرمجة، يتم رصد هذه الحالات وإرسال إشعار بها من خلال طرح أحد الاستثناءات.

منح إمكانية التحكم لعملاء آخرين

جلسة الوسائط هي المفتاح للتحكم في التشغيل. ويتيح لك توجيه الطلبات من مصادر خارجية إلى المشغّل الذي يشغّل الوسائط. يمكن أن تكون هذه المصادر أزرارًا مادية، مثل زر التشغيل في سماعات الرأس أو جهاز التحكّم عن بُعد في التلفزيون، أو طلبات غير مباشرة، مثل توجيه "إيقاف مؤقت" إلى "مساعد Google". وبالمثل، قد تحتاج إلى منح الإذن بالوصول إلى نظام Android لتسهيل استخدام عناصر التحكّم في الإشعارات وشاشة القفل، أو إلى ساعة Wear OS لكي تتمكّن من التحكّم في التشغيل من خلفية شاشة الساعة. يمكن للعملاء الخارجيين استخدام وحدة تحكّم في الوسائط لإصدار أوامر التشغيل إلى تطبيق الوسائط. ويتم تلقّي هذه الأوامر من خلال جلسة الوسائط التي تفوض الأوامر في نهاية المطاف إلى مشغّل الوسائط.

الشكل 1: يسهّل وحدة تحكّم الوسائط تمرير تعليمات من مصادر خارجية إلى جلسة الوسائط.

ملاحظة: عند تشغيل الوسائط في الخلفية، يجب أن يكون كلّ من MediaSession ومشغّل الوسائط مضمّنَين في MediaSessionService أو MediaLibraryService يعملان كخدمة تعمل في المقدّمة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تشغيل المحتوى في الخلفية باستخدام MediaSessionService.

عندما يكون جهاز التحكّم على وشك الاتصال بجلسة الوسائط، يتمّ استدعاء الأسلوب onConnect(). يمكنك استخدام رمز ControllerInfo المتوفر لتحديد ما إذا كنت تريد قبول الطلب أو رفضه. يمكنك الاطّلاع على مثال لقبول طلب ربط في قسم Declare available commands (تعريف الأوامر المتاحة).

بعد الاتصال، يمكن لوحدة التحكّم إرسال أوامر التشغيل إلى الجلسة. بعد ذلك، تفوّض الجلسة هذه الأوامر إلى المشغّل. تعالج الجلسة تلقائيًا تعليمات التشغيل وقائمة التشغيل المحدّدة في واجهة Player.

تتيح لك طرق الاستدعاء الأخرى معالجة طلبات، على سبيل المثال، أوامر التشغيل المخصّصة و تعديل قائمة التشغيل). تتضمّن هذه طلبات إعادة الاتصال أيضًا عنصر ControllerInfo حتى تتمكّن من تعديل طريقة الردّ على كل طلب على أساس كل وحدة تحكّم.

تعديل قائمة التشغيل

يمكن لجلسة وسائط تعديل قائمة التشغيل الخاصة بالمشغّل مباشرةً كما هو موضّح في دليل ExoPlayer لقوائم التشغيل. يمكن لأجهزة التحكّم أيضًا تعديل قائمة التشغيل إذا كان الخياران COMMAND_SET_MEDIA_ITEM أو COMMAND_CHANGE_MEDIA_ITEMS متاحَين لجهاز التحكّم.

عند إضافة عناصر جديدة إلى قائمة التشغيل، يحتاج المشغّل عادةً إلى نسخ MediaItem ذات معرّف موارد منتظم (URI) محدّد لإتاحة تشغيلها. يتم تلقائيًا إعادة توجيه العناصر المُضافة حديثًا إلى طرق المشغّل، مثل player.addMediaItem، إذا كان لها عنوان URL محدّد.

إذا أردت تخصيص مواضع تكرار MediaItem التي تمت إضافتها إلى المشغّل، يمكنك تجاوز onAddMediaItems(). يجب تنفيذ هذه الخطوة عندما تريد دعم وحدات التحكُّم التي تطلب الوسائط بدون معرّف موارد منتظم (URI) محدّد. بدلاً من ذلك، يحتوي MediaItem عادةً على حقل واحد أو أكثر من الحقول التالية تم ضبطها لوصف الوسائط المطلوبة:

• MediaItem.id: معرّف عام يحدّد الوسائط
• MediaItem.RequestMetadata.mediaUri: عنوان URI للطلب الذي قد يستخدم ملف شخصي مخصّصًا ولا يمكن تشغيله مباشرةً من خلال المشغّل.
• MediaItem.RequestMetadata.searchQuery: طلب بحث نصي، على سبيل المثال من "مساعد Google"
• MediaItem.MediaMetadata: البيانات الوصفية المنظَّمة مثل "العنوان" أو "الفنان"

لمزيد من خيارات التخصيص لقوائم التشغيل الجديدة بالكامل، يمكنك أيضًا إلغاء onSetMediaItems() الذي يتيح لك تحديد عنصر البداية وموضعه في قائمة التشغيل. على سبيل المثال، يمكنك توسيع أحد العناصر المطلوبة ليشمل قائمة تشغيل بأكملها ثم توجيه المشغّل للبدء من فهرس العنصر المطلوب في الأصل. يمكن العثور على نموذج لتنفيذ onSetMediaItems() مع هذه الميزة في تطبيق الجلسة التجريبي.

إدارة التنسيق المخصّص والأوامر المخصّصة

توضِّح الأقسام التالية كيفية الإعلان عن تنسيق مخصّص لأزرار التحكم المخصّصة في التطبيقات العميلة وتفويض وحدات التحكّم بإرسال الطلبات المخصّصة.

تحديد تنسيق مخصّص للجلسة

للإشارة إلى تطبيقات العميل التي تريد عرض عناصر التحكّم في التشغيل أمام العميل، اضبط التنسيق المخصّص للجلسة عند إنشاء MediaSession في طريقة onCreate() للخدمة.

Kotlin

override fun onCreate() {
  super.onCreate()

  val likeButton = CommandButton.Builder()
    .setDisplayName("Like")
    .setIconResId(R.drawable.like_icon)
    .setSessionCommand(SessionCommand(SessionCommand.COMMAND_CODE_SESSION_SET_RATING))
    .build()
  val favoriteButton = CommandButton.Builder()
    .setDisplayName("Save to favorites")
    .setIconResId(R.drawable.favorite_icon)
    .setSessionCommand(SessionCommand(SAVE_TO_FAVORITES, Bundle()))
    .build()

  session =
    MediaSession.Builder(this, player)
      .setCallback(CustomMediaSessionCallback())
      .setCustomLayout(ImmutableList.of(likeButton, favoriteButton))
      .build()
}

Java

@Override
public void onCreate() {
  super.onCreate();

  CommandButton likeButton = new CommandButton.Builder()
    .setDisplayName("Like")
    .setIconResId(R.drawable.like_icon)
    .setSessionCommand(new SessionCommand(SessionCommand.COMMAND_CODE_SESSION_SET_RATING))
    .build();
  CommandButton favoriteButton = new CommandButton.Builder()
    .setDisplayName("Save to favorites")
    .setIconResId(R.drawable.favorite_icon)
    .setSessionCommand(new SessionCommand(SAVE_TO_FAVORITES, new Bundle()))
    .build();

  Player player = new ExoPlayer.Builder(this).build();
  mediaSession =
      new MediaSession.Builder(this, player)
          .setCallback(new CustomMediaSessionCallback())
          .setCustomLayout(ImmutableList.of(likeButton, favoriteButton))
          .build();
}

تحديد الأوامر المتاحة للمشغّل والأوامر المخصّصة

يمكن لتطبيقات الوسائط تحديد أوامر مخصّصة يمكن استخدامها مثلاً في تنسيق مخصّص. على سبيل المثال، قد تحتاج إلى تنفيذ أزرار تسمح للمستخدم بحفظ ملف وسائط في قائمة بالعناصر المفضّلة. يرسل "MediaController" أوامر مخصّصة ويستلمها MediaSession.Callback.

ويمكنك تحديد أوامر الجلسات المخصّصة المتاحة لجهاز MediaController عند اتصاله بجلسة الوسائط. يمكنك إجراء ذلك من خلال تجاوز MediaSession.Callback.onConnect(). يمكنك ضبط مجموعة الأوامر المتاحة وإعادتها عند قبول طلب اتصال من MediaController في طريقة معاودة الاتصال onConnect:

Kotlin

private inner class CustomMediaSessionCallback: MediaSession.Callback {
  // Configure commands available to the controller in onConnect()
  override fun onConnect(
    session: MediaSession,
    controller: MediaSession.ControllerInfo
  ): MediaSession.ConnectionResult {
    val sessionCommands = ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
        .add(SessionCommand(SAVE_TO_FAVORITES, Bundle.EMPTY))
        .build()
    return AcceptedResultBuilder(session)
        .setAvailableSessionCommands(sessionCommands)
        .build()
  }
}

Java

class CustomMediaSessionCallback implements MediaSession.Callback {
  // Configure commands available to the controller in onConnect()
  @Override
  public ConnectionResult onConnect(
    MediaSession session,
    ControllerInfo controller) {
    SessionCommands sessionCommands =
        ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
            .add(new SessionCommand(SAVE_TO_FAVORITES, new Bundle()))
            .build();
    return new AcceptedResultBuilder(session)
        .setAvailableSessionCommands(sessionCommands)
        .build();
  }
}

لتلقّي طلبات أوامر مخصّصة من MediaController، يمكنك إلغاء أسلوب onCustomCommand() في Callback.

Kotlin

private inner class CustomMediaSessionCallback: MediaSession.Callback {
  ...
  override fun onCustomCommand(
    session: MediaSession,
    controller: MediaSession.ControllerInfo,
    customCommand: SessionCommand,
    args: Bundle
  ): ListenableFuture<SessionResult> {
    if (customCommand.customAction == SAVE_TO_FAVORITES) {
      // Do custom logic here
      saveToFavorites(session.player.currentMediaItem)
      return Futures.immediateFuture(
        SessionResult(SessionResult.RESULT_SUCCESS)
      )
    }
    ...
  }
}

Java

class CustomMediaSessionCallback implements MediaSession.Callback {
  ...
  @Override
  public ListenableFuture<SessionResult> onCustomCommand(
    MediaSession session, 
    ControllerInfo controller,
    SessionCommand customCommand,
    Bundle args
  ) {
    if(customCommand.customAction.equals(SAVE_TO_FAVORITES)) {
      // Do custom logic here
      saveToFavorites(session.getPlayer().getCurrentMediaItem());
      return Futures.immediateFuture(
        new SessionResult(SessionResult.RESULT_SUCCESS)
      );
    }
    ...
  }
}

يمكنك تتبُّع وحدة التحكّم في الوسائط التي تقدّم طلبًا باستخدام سمة packageName لكائن MediaSession.ControllerInfo الذي يتم تمريره إلى طرق Callback. يتيح لك ذلك تخصيص سلوك تطبيقك استجابةً لأمر معيّن إذا كان مصدره هو النظام أو تطبيقك الخاص أو تطبيقات العميل الأخرى.

ملاحظة: يجب تنفيذ الأوامر المخصّصة كسلوك جديد تمامًا. لا تستخدِم أمرًا مخصّصًا لاستبدال أحد عناصر التحكّم العادية المحدّدة في واجهة Player.

تعديل التنسيق المخصّص بعد تفاعل المستخدِم

بعد التعامل مع أمر مخصص أو أي تفاعل آخر مع المشغل، قد تحتاج إلى تحديث التنسيق المعروض في واجهة مستخدم وحدة التحكم. ومن الأمثلة النموذجية زر التبديل الذي يغير رمزه بعد تشغيل الإجراء المرتبط بهذا الزر. لتعديل التنسيق، يمكنك استخدام MediaSession.setCustomLayout:

Kotlin

val removeFromFavoritesButton = CommandButton.Builder()
  .setDisplayName("Remove from favorites")
  .setIconResId(R.drawable.favorite_remove_icon)
  .setSessionCommand(SessionCommand(REMOVE_FROM_FAVORITES, Bundle()))
  .build()
mediaSession.setCustomLayout(ImmutableList.of(likeButton, removeFromFavoritesButton))

Java

CommandButton removeFromFavoritesButton = new CommandButton.Builder()
  .setDisplayName("Remove from favorites")
  .setIconResId(R.drawable.favorite_remove_icon)
  .setSessionCommand(new SessionCommand(REMOVE_FROM_FAVORITES, new Bundle()))
  .build();
mediaSession.setCustomLayout(ImmutableList.of(likeButton, removeFromFavoritesButton));

تخصيص سلوك أوامر التشغيل

لتخصيص سلوك أمر محدّد في واجهة Player، مثل play() أو seekToNext()، عليك تضمين Player في ForwardingPlayer.

Kotlin

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

val forwardingPlayer = object : ForwardingPlayer(player) {
  override fun play() {
    // Add custom logic
    super.play()
  }

  override fun setPlayWhenReady(playWhenReady: Boolean) {
    // Add custom logic
    super.setPlayWhenReady(playWhenReady)
  }
}

val mediaSession = MediaSession.Builder(context, forwardingPlayer).build()

Java

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

ForwardingPlayer forwardingPlayer = new ForwardingPlayer(player) {
  @Override
  public void play() {
    // Add custom logic
    super.play();
  }

  @Override
  public void setPlayWhenReady(boolean playWhenReady) {
    // Add custom logic
    super.setPlayWhenReady(playWhenReady);
  }
};

MediaSession mediaSession =
  new MediaSession.Builder(context, forwardingPlayer).build();

لمزيد من المعلومات حول ForwardingPlayer، اطّلِع على دليل ExoPlayer حول التخصيص.

تحديد وحدة التحكم التي تطلب الأمر من اللاعب

عندما يبدأ طلب Player من MediaController، يمكنك تحديد مصدره باستخدام MediaSession.controllerForCurrentRequest والحصول على ControllerInfo للطلب الحالي:

Kotlin

class CallerAwareForwardingPlayer(player: Player) :
  ForwardingPlayer(player) {

  override fun seekToNext() {
    Log.d(
      "caller",
      "seekToNext called from package ${session.controllerForCurrentRequest?.packageName}"
    )
    super.seekToNext()
  }
}

Java

public class CallerAwareForwardingPlayer extends ForwardingPlayer {
  public CallerAwareForwardingPlayer(Player player) {
    super(player);
  }

  @Override
  public void seekToNext() {
    Log.d(
        "caller",
        "seekToNext called from package: "
            + session.getControllerForCurrentRequest().getPackageName());
    super.seekToNext();
  }
}

الاستجابة لأزرار الوسائط

أزرار الوسائط هي أزرار أجهزة موجودة على أجهزة Android والأجهزة الملحقة الأخرى، مثل زر التشغيل/الإيقاف المؤقت على سماعة رأس بلوتوث. يعالج Media3 أحداث أزرار الوسائط نيابةً عنك عند وصولها إلى الجلسة ويُطلِب طريقة Player المناسبة في مشغّل الجلسة.

ويمكن لتطبيق ما إلغاء السلوك التلقائي من خلال تجاوز MediaSession.Callback.onMediaButtonEvent(Intent). في هذه الحالة، يمكن للتطبيق التعامل مع جميع تفاصيل واجهة برمجة التطبيقات بنفسه أو يحتاج إلى ذلك.

معالجة الأخطاء والإبلاغ عنها

هناك نوعان من الأخطاء التي تُرسِلها الجلسة وتُبلغ بها أدوات التحكّم. تشير الأخطاء المميتة إلى حدوث خطأ فني في تشغيل جلسة المشغّل يؤدي إلى مقاطعة التشغيل. يتم تلقائيًا إبلاغ وحدة التحكّم بالأخطاء المميتة عند حدوثها. الأخطاء غير المميتة هي أخطاء غير فنية أو أخطاء تتعلّق بالسياسة ولا تؤدي إلى إيقاف التشغيل، ويتم إرسالها إلى أدوات التحكّم من قِبل التطبيق يدويًا.

أخطاء فادحة في التشغيل

يبلّغ المشغّل الجلسة بخطأ فادح في التشغيل، ثم يبلّغ عنه وحدات التحكم لإجراء طلب من خلال Player.Listener.onPlayerError(PlaybackException) وPlayer.Listener.onPlayerErrorChanged(@Nullable PlaybackException).

في هذه الحالة، يتم نقل حالة التشغيل إلى STATE_IDLE وMediaController.getPlaybackError() يعرض PlaybackException الذي تسبب في النقل. ويمكن لوحدة التحكّم هذه فحص PlayerException.errorCode للحصول على معلومات حول سبب الخطأ.

بالنسبة إلى إمكانية التشغيل التفاعلي، يتم تكرار خطأ فادح في PlaybackStateCompat لجلسة النظام الأساسي من خلال نقل حالته إلى STATE_ERROR وضبط رمز الخطأ والرسالة وفقًا لـ PlaybackException.

تخصيص خطأ خطير

لتقديم معلومات مترجَمة ومفيدة للمستخدم، يمكن تخصيص رمز الخطأ، ورسالة الخطأ، ومعلومات إضافية عن الخطأ في حال حدوث خطأ فادح في التشغيل، وذلك باستخدام ForwardingPlayer عند إنشاء الجلسة:

Kotlin

val forwardingPlayer = ErrorForwardingPlayer(player)
val session = MediaSession.Builder(context, forwardingPlayer).build()

Java

Player forwardingPlayer = new ErrorForwardingPlayer(player);
MediaSession session =
    new MediaSession.Builder(context, forwardingPlayer).build();

يسجِّل مشغّل التقديم/الترجيع Player.Listener للمشغّل الفعلي ويعترض عمليات الاستدعاء التي تُبلغ عن خطأ. بعد ذلك، يتم تفويض PlaybackException مخصّص للمستمعين الذين تم تسجيلهم على مشغّل الإعادة. لكي يعمل هذا الإجراء، يجب أن تلغي وحدة إعادة التوجيه العنصرَين Player.addListener وPlayer.removeListener للوصول إلى المستمعين الذين يمكن إرسال رمز خطأ أو رسالة أو عناصر إضافية مخصّصة إليهم:

Kotlin

class ErrorForwardingPlayer(private val context: Context, player: Player) :
  ForwardingPlayer(player) {

  private val listeners: MutableList<Player.Listener> = mutableListOf()

  private var customizedPlaybackException: PlaybackException? = null

  init {
    player.addListener(ErrorCustomizationListener())
  }

  override fun addListener(listener: Player.Listener) {
    listeners.add(listener)
  }

  override fun removeListener(listener: Player.Listener) {
    listeners.remove(listener)
  }

  override fun getPlayerError(): PlaybackException? {
    return customizedPlaybackException
  }

  private inner class ErrorCustomizationListener : Player.Listener {

    override fun onPlayerErrorChanged(error: PlaybackException?) {
      customizedPlaybackException = error?.let { customizePlaybackException(it) }
      listeners.forEach { it.onPlayerErrorChanged(customizedPlaybackException) }
    }

    override fun onPlayerError(error: PlaybackException) {
      listeners.forEach { it.onPlayerError(customizedPlaybackException!!) }
    }

    private fun customizePlaybackException(
      error: PlaybackException,
    ): PlaybackException {
      val buttonLabel: String
      val errorMessage: String
      when (error.errorCode) {
        PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW -> {
          buttonLabel = context.getString(R.string.err_button_label_restart_stream)
          errorMessage = context.getString(R.string.err_msg_behind_live_window)
        }
        // Apps can customize further error messages by adding more branches.
        else -> {
          buttonLabel = context.getString(R.string.err_button_label_ok)
          errorMessage = context.getString(R.string.err_message_default)
        }
      }
      val extras = Bundle()
      extras.putString("button_label", buttonLabel)
      return PlaybackException(errorMessage, error.cause, error.errorCode, extras)
    }

    override fun onEvents(player: Player, events: Player.Events) {
      listeners.forEach {
        it.onEvents(player, events)
      }
    }
    // Delegate all other callbacks to all listeners without changing arguments like onEvents.
  }
}

Java

private static class ErrorForwardingPlayer extends ForwardingPlayer {

  private final Context context;
  private List<Player.Listener> listeners;
  @Nullable private PlaybackException customizedPlaybackException;

  public ErrorForwardingPlayer(Context context, Player player) {
    super(player);
    this.context = context;
    listeners = new ArrayList<>();
    player.addListener(new ErrorCustomizationListener());
  }

  @Override
  public void addListener(Player.Listener listener) {
    listeners.add(listener);
  }

  @Override
  public void removeListener(Player.Listener listener) {
    listeners.remove(listener);
  }

  @Nullable
  @Override
  public PlaybackException getPlayerError() {
    return customizedPlaybackException;
  }

  private class ErrorCustomizationListener implements Listener {

    @Override
    public void onPlayerErrorChanged(@Nullable PlaybackException error) {
      customizedPlaybackException =
          error != null ? customizePlaybackException(error, context) : null;
      for (int i = 0; i < listeners.size(); i++) {
        listeners.get(i).onPlayerErrorChanged(customizedPlaybackException);
      }
    }

    @Override
    public void onPlayerError(PlaybackException error) {
      for (int i = 0; i < listeners.size(); i++) {
        listeners.get(i).onPlayerError(checkNotNull(customizedPlaybackException));
      }
    }

    private PlaybackException customizePlaybackException(
        PlaybackException error, Context context) {
      String buttonLabel;
      String errorMessage;
      switch (error.errorCode) {
        case PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW:
          buttonLabel = context.getString(R.string.err_button_label_restart_stream);
          errorMessage = context.getString(R.string.err_msg_behind_live_window);
          break;
        // Apps can customize further error messages by adding more case statements.
        default:
          buttonLabel = context.getString(R.string.err_button_label_ok);
          errorMessage = context.getString(R.string.err_message_default);
          break;
      }
      Bundle extras = new Bundle();
      extras.putString("button_label", buttonLabel);
      return new PlaybackException(errorMessage, error.getCause(), error.errorCode, extras);
    }

    @Override
    public void onEvents(Player player, Events events) {
      for (int i = 0; i < listeners.size(); i++) {
        listeners.get(i).onEvents(player, events);
      }
    }
    // Delegate all other callbacks to all listeners without changing arguments like onEvents.
  }
}

الأخطاء غير المميتة

بالنسبة إلى الأخطاء غير الفادحة التي لا تنشأ عن استثناء فني، يمكن أن يرسلها التطبيق إلى الكل أو إلى مسؤول تحكّم معيَّن:

Kotlin

val sessionError = SessionError(
  SessionError.ERROR_SESSION_AUTHENTICATION_EXPIRED,
  context.getString(R.string.error_message_authentication_expired),
)

// Sending a nonfatal error to all controllers.
mediaSession.sendError(sessionError)

// Interoperability: Sending a nonfatal error to the media notification controller to set the
// error code and error message in the playback state of the platform media session.
mediaSession.mediaNotificationControllerInfo?.let {
  mediaSession.sendError(it, sessionError)
}

Java

SessionError sessionError = new SessionError(
    SessionError.ERROR_SESSION_AUTHENTICATION_EXPIRED,
    context.getString(R.string.error_message_authentication_expired));

// Sending a nonfatal error to all controllers.
mediaSession.sendError(sessionError);

// Interoperability: Sending a nonfatal error to the media notification controller to set the
// error code and error message in the playback state of the platform media session.
ControllerInfo mediaNotificationControllerInfo =
    mediaSession.getMediaNotificationControllerInfo();
if (mediaNotificationControllerInfo != null) {
  mediaSession.sendError(mediaNotificationControllerInfo, sessionError);
}

يتم تكرار خطأ غير مميت تم إرساله إلى وحدة التحكّم في إشعارات الوسائط إلى PlaybackStateCompat من جلسة المنصة. وبالتالي، يتم ضبط رمز الخطأ و رسالة الخطأ فقط على PlaybackStateCompat وفقًا لذلك، بينما لا يتم تغيير PlaybackStateCompat.state إلى STATE_ERROR.

تلقّي أخطاء غير قاتلة

يتلقّى MediaController خطأً غير مميت من خلال تنفيذ MediaController.Listener.onError:

Kotlin

val future = MediaController.Builder(context, sessionToken)
  .setListener(object : MediaController.Listener {
    override fun onError(controller: MediaController, sessionError: SessionError) {
      // Handle nonfatal error.
    }
  })
  .buildAsync()

Java

MediaController.Builder future =
    new MediaController.Builder(context, sessionToken)
        .setListener(
            new MediaController.Listener() {
              @Override
              public void onError(MediaController controller, SessionError sessionError) {
                // Handle nonfatal error.
              }
            });