Sterowanie odtwarzaniem i reklamowanie go za pomocą sesji MediaSession

Sesje multimedialne zapewniają uniwersalny sposób interakcji z odtwarzaczem audio lub wideo. W Media3 domyślnym odtwarzaczem jest klasa ExoPlayer, która implementuje interfejs Player. Połączenie sesji multimediów z odtwarzaczem umożliwia aplikacji wyświetlanie reklam odtwarzania multimediów na zewnątrz i odbieranie poleceń odtwarzania z zewnętrznych źródeł.

Polecenia mogą pochodzić z przycisków fizycznych, takich jak przycisk odtwarzania na słuchawkach lub pilocie do telewizora. Mogą one też pochodzić z aplikacji klienckich, które mają kontroler multimediów, np. polecenie „wstrzymaj” dla Asystenta Google. Sesja multimediów deleguje te polecenia do odtwarzacza aplikacji multimedialnej.

Kiedy wybrać sesję multimediów

Gdy wdrożysz MediaSession, użytkownicy będą mogli kontrolować odtwarzanie:

• za pomocą słuchawek. Często w słuchawkach są przyciski lub funkcje dotykowe, które umożliwiają użytkownikowi odtwarzanie lub wstrzymywanie multimediów albo przechodzenie do poprzedniego lub następnego utworu.
• przez rozmowę z Asystentem Google. Typowym poleceniem jest „OK Google, wstrzymaj”, aby wstrzymać odtwarzanie multimediów na urządzeniu.
• za pomocą zegarka z Wear OS, Dzięki temu użytkownicy będą mogli łatwiej korzystać z najczęstszych elementów sterowania odtwarzaniem podczas oglądania na telefonie.
• za pomocą elementów sterujących multimediami. Ten pokaz slajdów zawiera elementy sterujące dla każdej trwającej sesji multimediów.
• Na telewizorze. Umożliwia wykonywanie działań przy użyciu fizycznych przycisków odtwarzania, sterowania odtwarzaniem na platformie oraz zarządzania zasilaniem (np. jeśli telewizor, soundbar lub odbiornik A/V wyłączy się lub zmieni wejście, odtwarzanie w aplikacji powinno się zatrzymać).
• oraz inne procesy zewnętrzne, które muszą wpływać na odtwarzanie.

Jest to przydatne w wielu przypadkach. Szczególnie zalecamy używanie MediaSession w tych przypadkach:

• Odtwarzasz długie filmy, takie jak filmy czy telewizja na żywo.
• Odtwarzasz długie treści audio, takie jak podcasty lub playlisty muzyczne.
• Tworzysz aplikację na telewizor.

Nie wszystkie przypadki użycia jednak pasują do MediaSession. W tych sytuacjach możesz użyć tylko Player:

• Wyświetlasz krótkie treści, w przypadku których zaangażowanie i interakcje użytkowników są kluczowe.
• Nie ma jednego aktywnego filmu, np. użytkownik przewija listę, a na ekranie wyświetla się kilka filmów jednocześnie.
• odtwarzasz jednorazowy film wprowadzający lub wyjaśniający, który użytkownik powinien aktywnie obejrzeć;
• Twoje treści są poufne i nie chcesz, aby procesy zewnętrzne miały dostęp do metadanych multimediów (np. tryb incognito w przeglądarce).

Jeśli Twój przypadek użycia nie pasuje do żadnego z wymienionych powyżej, zastanów się, czy zgadzasz się na kontynuowanie odtwarzania przez aplikację, gdy użytkownik nie jest aktywnie zaangażowany w treści. Jeśli odpowiedź brzmi „tak”, prawdopodobnie wybierzesz MediaSession. Jeśli odpowiedź jest przecząca, użyj operatora Player.

Tworzenie sesji multimedialnej

Sesja multimedialna jest związana z odtwarzaczem, którym zarządza. Sesję multimedialną możesz utworzyć za pomocą obiektów Context i Player. W razie potrzeby należy utworzyć i inicjializować sesję multimediów, na przykład za pomocą metody cyklu życia onStart() lub onResume() obiektu Activity lub Fragment albo metody onCreate() obiektu Service, który jest właścicielem sesji multimediów i powiązanego z nią odtwarzacza.

Aby utworzyć sesję multimediów, zainicjuj Player i prześlij ją do MediaSession.Builder w ten sposób:

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();

Automatyczne przetwarzanie stanu

Biblioteka Media3 automatycznie aktualizuje sesję multimediów na podstawie stanu odtwarzacza. W związku z tym nie musisz ręcznie mapować odtwarzacza na sesję.

Jest to odstępstwo od starego podejścia, w którym trzeba było tworzyć i utrzymywać PlaybackStateCompat niezależnie od odtwarzacza, na przykład w celu wskazywania błędów.

Uwaga: jeśli aplikacja korzysta ze stanu odtwarzania, aby komunikować się z klientem, np. gdy dodajesz uwierzytelnianie do aplikacji na Android Automotive OS, musisz zachować ostrożność podczas migracji do Media3. Dzieje się tak, ponieważ automatyczne zarządzanie stanem w Media3 zastępuje tę poprzednią funkcję. Wróć później, aby uzyskać bardziej szczegółowe wskazówki dotyczące postępowania w takich przypadkach.

Unikalny identyfikator sesji

Domyślnie funkcja MediaSession.Builder tworzy sesję z pustym ciągiem znaków jako identyfikatorem sesji. Wystarczy to, jeśli aplikacja ma utworzyć tylko 1 sesję, co jest najczęstszym przypadkiem.

Jeśli aplikacja chce zarządzać kilkoma instancjami sesji jednocześnie, musi zadbać o to, aby identyfikator każdej sesji był unikalny. Identyfikator sesji można ustawić podczas tworzenia sesji za pomocą funkcji MediaSession.Builder.setId(String id).

Jeśli widzisz, że IllegalStateException powoduje awarię aplikacji z komunikatem o błędzie IllegalStateException: Session ID must be unique. ID=, prawdopodobnie sesja została utworzona nieoczekiwanie, zanim wcześniej utworzona instancja o tym samym identyfikatorze została zwolniona. Aby uniknąć wycieku danych z sesji spowodowanego błędem programistycznym, takie przypadki są wykrywane i zgłaszane przez wyjątek.

Przyznawanie kontroli innym klientom

Sesja multimediów jest kluczowa dla sterowania odtwarzaniem. Umożliwia ona kierowanie poleceń z zewnętrznych źródeł do odtwarzacza, który odtwarza Twoje multimedia. Źródłami mogą być przyciski fizyczne, takie jak przycisk odtwarzania na zestawie słuchawkowym lub pilocie telewizora, lub polecenia pośrednie, takie jak polecenie „zatrzymaj” skierowane do Asystenta Google. Możesz też przyznać dostęp do systemu Android, aby ułatwić obsługę powiadomień i ekranu blokady, lub do zegarka z Wear OS, aby móc sterować odtwarzaniem z tarczy zegarka. Klienci zewnętrzni mogą używać kontrolera multimediów, aby wydawać polecenia odtwarzania do Twojej aplikacji multimedialnej. Są one odbierane przez sesję multimediów, która ostatecznie deleguje polecenia do odtwarzacza multimediów.

Ilustracja 1. Sterownik multimediów ułatwia przekazywanie poleceń ze źródeł zewnętrznych do sesji multimediów.

Uwaga: podczas odtwarzania multimediów w tle MediaSession i odtwarzacz muszą być umieszczone w komponencie MediaSessionService lub MediaLibraryService, który działa jako usługa na pierwszym planie. Więcej informacji znajdziesz w artykule Odtwarzanie w tle z użyciem MediaSessionService

.

Gdy kontroler ma się połączyć z sesją multimediów, wywoływana jest metoda onConnect(). Możesz użyć otrzymanego ControllerInfo, aby zdecydować, czy zaakceptować, czy odrzucić prośbę. Przykład zaakceptowania prośby o połączenie znajdziesz w sekcji Zadeklaruj dostępne polecenia.

Po połączeniu kontroler może wysyłać do sesji polecenia odtwarzania. Sesja przekazuje te polecenia odtwarzaczowi. Polecenia odtwarzania i playlist zdefiniowane w interfejsie Player są automatycznie obsługiwane przez sesję.

Inne metody wywołania umożliwiają obsługę np. żądań dotyczących niestandardowych poleceń odtwarzania i modyfikowania playlisty. Te funkcje zwracane zawierają obiekt ControllerInfo, dzięki czemu możesz modyfikować sposób odpowiadania na poszczególne żądania w zależności od kontrolera.

Modyfikowanie playlisty

Sesja multimediów może bezpośrednio modyfikować playlistę odtwarzacza zgodnie z opisem w przewodniku po playlistach ExoPlayera. Kontroler może też modyfikować playlistę, jeśli COMMAND_SET_MEDIA_ITEM lub COMMAND_CHANGE_MEDIA_ITEMS jest dostępny.

Podczas dodawania nowych elementów do playlisty odtwarzacz zwykle wymaga MediaItem wystąpieni z zdefiniowanego URI, aby można było je odtworzyć. Domyślnie nowo dodane elementy są automatycznie przekazywane do metod odtwarzacza, takich jak player.addMediaItem, jeśli mają zdefiniowany identyfikator URI.

Jeśli chcesz dostosować instancje MediaItem dodane do odtwarzacza, możesz je zastąpić, używając parametru onAddMediaItems(). Ten krok jest potrzebny, jeśli chcesz obsługiwać kontrolery, które proszą o media bez zdefiniowanego identyfikatora URI. Zwykle zawiera ona co najmniej 1 z tych pól, które opisują żądane media:MediaItem

• MediaItem.id: ogólny identyfikator mediów.
• MediaItem.RequestMetadata.mediaUri: Identyfikator URI żądania, który może używać niestandardowego schematu i niekoniecznie jest bezpośrednio odtwarzany przez odtwarzacz.
• MediaItem.RequestMetadata.searchQuery: tekstowe zapytanie, np. z Asystenta Google.
• MediaItem.MediaMetadata: uporządkowane metadane, takie jak „title” (tytuł) czy „artist” (artysta).

Aby uzyskać więcej opcji dostosowywania zupełnie nowych playlist, możesz dodatkowo zastąpić onSetMediaItems(), co pozwala zdefiniować element początkowy i jego pozycję na playliście. Możesz na przykład rozszerzyć pojedynczy żądany element na całą playlistę i zlecić odtwarzaczowi rozpoczęcie od indeksu pierwotnie żądanego elementu. Przykładowa implementacja onSetMediaItems() z tą funkcją jest dostępna w aplikacji demonstracyjnej sesji.

Zarządzanie układem niestandardowym i poleceniami niestandardowymi

W następnych sekcjach opisujemy, jak reklamować niestandardowy układ niestandardowych przycisków poleceń w aplikacjach klienckich i autoryzować kontrolery do wysyłania niestandardowych poleceń.

Definiowanie niestandardowego układu sesji

Aby wskazać aplikacjom klienckim, które elementy sterowania odtwarzaniem chcesz wyświetlać użytkownikowi, ustaw niestandardowy układ sesji podczas tworzenia MediaSession w metodzie onCreate() usługi.

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();
}

Zadeklaruj dostępne polecenia odtwarzacza i niestandardowe

Aplikacje multimedialne mogą definiować polecenia niestandardowe, które można na przykład używać w niestandardowym układzie. Możesz na przykład wdrożyć przyciski, które pozwolą użytkownikowi zapisać element multimedialny na liście ulubionych. Usługa MediaController wysyła polecenia niestandardowe, a usługa MediaSession.Callback je odbiera.

Możesz określić, które polecenia sesji niestandardowej są dostępne dla MediaController, gdy połączy się z Twoją sesją multimedialną. Aby to zrobić, zastąpij wartość MediaSession.Callback.onConnect(). Skonfiguruj i zwróć zbiór dostępnych poleceń podczas akceptowania prośby o połączenie z urządzenia MediaController w ramach metody wywołania zwrotnego 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();
  }
}

Aby otrzymywać żądania niestandardowych poleceń z poziomu MediaController, zastąpij metodę onCustomCommand() w 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)
      );
    }
    ...
  }
}

Korzystając z właściwości packageName obiektu MediaSession.ControllerInfo, możesz śledzić, który kontroler multimediów wysyła żądanie. Właściwość ta jest przekazywana do metod Callback. Pozwala to dostosować działanie aplikacji na podstawie danego polecenia, jeśli pochodzi ono z systemu, Twojej aplikacji lub innych aplikacji klienckich.

Uwaga: komendy niestandardowe należy zaimplementować jako zupełnie nowe działanie. Nie używaj polecenia niestandardowego do zastąpienia jednego ze standardowych elementów sterujących zdefiniowanych w interfejsie Player.

Aktualizowanie niestandardowego układu po interakcji użytkownika

Po obsłudze polecenia niestandardowego lub jakiejkolwiek innej interakcji z odtwarzaczem możesz zaktualizować układ wyświetlany w interfejsie kontrolera. Typowym przykładem jest przełącznik, którego ikona zmienia się po wywołaniu działania powiązanego z tym przyciskiem. Aby zaktualizować układ, możesz użyć: 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));

Dostosowywanie działania poleceń odtwarzania

Aby dostosować działanie polecenia zdefiniowanego w interfejsie Player, takiego jak play() lub seekToNext(), owiń Player w element 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();

Więcej informacji o ForwardingPlayer znajdziesz w przewodniku ExoPlayer dotyczącym dostosowywania.

Określanie żądającego kontrolera polecenia gracza

Gdy wywołanie metody Player pochodzi z poziomu MediaController, możesz zidentyfikować źródło za pomocą MediaSession.controllerForCurrentRequesti uzyskać ControllerInfo dla bieżącego żądania:

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();
  }
}

Odpowiedź na przyciski multimediów

Przyciski multimedialne to przyciski sprzętowe dostępne na urządzeniach z Androidem i innych urządzeniach peryferyjnych, np. przycisk odtwarzania/pauzowania w słuchawkach Bluetooth. Media3 obsługuje zdarzenia przycisków multimediów, gdy docierają do sesji, i wywołuje odpowiednią metodę Player w odtwarzaczu sesji.

Aplikacja może zastąpić domyślne działanie, zastępując je elementem MediaSession.Callback.onMediaButtonEvent(Intent). W takim przypadku aplikacja może samodzielnie obsługiwać wszystkie specyfikacje interfejsu API.

Obsługa i zgłaszanie błędów

Sesja może generować i przekazywać kontrolerom 2 rodzaje błędów. Błędy krytyczne wskazują na techniczną awarię odtwarzacza sesji, która przerywa odtwarzanie. Błędy krytyczne są automatycznie zgłaszane sterownikowi, gdy tylko wystąpią. Błędy niekrytyczne to błędy nietechniczne lub błędy związane z przestrzeganiem zasad, które nie przerywają odtwarzania i są wysyłane do kontrolerów przez aplikację ręcznie.

Krytyczne błędy odtwarzania

Odtwarzacz zgłasza do sesji krytyczny błąd odtwarzania, a potem do sterowników, aby wywołać Player.Listener.onPlayerError(PlaybackException) i Player.Listener.onPlayerErrorChanged(@Nullable PlaybackException).

W takim przypadku stan odtwarzania zmienia się na STATE_IDLE, a MediaController.getPlaybackError() zwraca wartość PlaybackException, która spowodowała przejście. Kontroler może sprawdzić PlayerException.errorCode, aby uzyskać informacje o przyczynie błędu.

W celu zapewnienia interoperacyjności fatalny błąd jest replikowany do PlaybackStateCompatsesji platformy przez przejście do stanu STATE_ERROR i ustawienie kodu błędu oraz komunikatu zgodnie z PlaybackException.

Dostosowywanie krytycznego błędu

Aby wyświetlać użytkownikowi lokalizowane i przydatne informacje, kod błędu, komunikat o błędzie i informacje dodatkowe dotyczące krytycznego błędu odtwarzania można dostosować, używając ForwardingPlayer podczas tworzenia sesji:

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();

Odtwarzacz przekierowujący rejestruje Player.Listener dla rzeczywistego odtwarzacza i przechwytuje wywołania zwrotne, które zgłaszają błąd. Następnie do odbiorców zarejestrowanych na odtwarzaczu przekierowującym jest delegowany niestandardowy adres PlaybackException. Aby to działało, odtwarzacz przekierowujący zastępuje Player.addListener i Player.removeListener, aby uzyskać dostęp do odbiorców, do których można wysłać niestandardowy kod błędu, wiadomość lub dodatkowe informacje:

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.
  }
}

Błędy niekrytyczne

Aplikacja może wysłać błędy niekrytyczne, które nie pochodzą z wyjątku technicznego, do wszystkich lub do konkretnego kontrolera:

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);
}

Niekrytyczny błąd wysłany do kontrolera powiadomień o mediach jest replikowany do PlaybackStateCompat sesji platformy. W związku z tym tylko kod błędu i komunikat o błędzie są odpowiednio ustawione na PlaybackStateCompat, a PlaybackStateCompat.state nie zmienia się na STATE_ERROR.

Otrzymywanie błędów niekrytycznych

MediaController otrzymuje błąd niekrytyczny, ponieważ implementuje 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.
              }
            });