improve documentation on how to update queue when asynchronously loading media item assets

Issue #5494

PiperOrigin-RevId: 234138162

extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/MediaSessionConnector.java

@@ -79,6 +79,9 @@ import java.util.Map;
  *   <li>An {@link ErrorMessageProvider} for providing human readable error messages and
  *   <li>An {@link ErrorMessageProvider} for providing human readable error messages and
  *       corresponding error codes can be set by calling {@link
  *       corresponding error codes can be set by calling {@link
  *       #setErrorMessageProvider(ErrorMessageProvider)}.
  *       #setErrorMessageProvider(ErrorMessageProvider)}.
+ *   <li>A {@link MediaMetadataProvider} can be set by calling {@link
+ *       #setMediaMetadataProvider(MediaMetadataProvider)}. By default the {@link
+ *       DefaultMediaMetadataProvider} is used.
  * </ul>
  * </ul>
  */
  */
 public final class MediaSessionConnector {
 public final class MediaSessionConnector {
@@ -562,7 +565,8 @@ public final class MediaSessionConnector {
   }
   }
 
 
   /**
   /**
-   * Sets a provider of metadata to be published to the media session.
+   * Sets a provider of metadata to be published to the media session. Pass {@code null} if no
+   * metadata should be published.
    *
    *
    * @param mediaMetadataProvider The provider of metadata to publish, or {@code null} if no
    * @param mediaMetadataProvider The provider of metadata to publish, or {@code null} if no
    *     metadata should be published.
    *     metadata should be published.
@@ -579,6 +583,9 @@ public final class MediaSessionConnector {
    *
    *
    * <p>Apps normally only need to call this method when the backing data for a given media item has
    * <p>Apps normally only need to call this method when the backing data for a given media item has
    * changed and the metadata should be updated immediately.
    * changed and the metadata should be updated immediately.
+   *
+   * <p>The {@link MediaMetadataCompat} which is published to the session is obtained by calling
+   * {@link MediaMetadataProvider#getMetadata(Player)}.
    */
    */
   public final void invalidateMediaSessionMetadata() {
   public final void invalidateMediaSessionMetadata() {
     MediaMetadataCompat metadata =
     MediaMetadataCompat metadata =
@@ -779,8 +786,8 @@ public final class MediaSessionConnector {
   }
   }
 
 
   /**
   /**
-   * Provides a default {@link MediaMetadataCompat} with properties and extras propagated from the
-   * active queue item to the session metadata.
+   * Provides a default {@link MediaMetadataCompat} with properties and extras taken from the {@link
+   * MediaDescriptionCompat} of the {@link MediaSessionCompat.QueueItem} of the active queue item.
    */
    */
   public static final class DefaultMediaMetadataProvider implements MediaMetadataProvider {
   public static final class DefaultMediaMetadataProvider implements MediaMetadataProvider {
 
 

extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/TimelineQueueNavigator.java

@@ -76,6 +76,11 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu
   /**
   /**
    * Gets the {@link MediaDescriptionCompat} for a given timeline window index.
    * Gets the {@link MediaDescriptionCompat} for a given timeline window index.
    *
    *
+   * <p>Often artworks and icons need to be loaded asynchronously. In such a case, return a {@link
+   * MediaDescriptionCompat} without the images, load your images asynchronously off the main thread
+   * and then call {@link MediaSessionConnector#invalidateMediaSessionQueue()} to make the connector
+   * update the queue by calling {@link #getMediaDescription(Player, int)} again.
+   *
    * @param player The current player.
    * @param player The current player.
    * @param windowIndex The timeline window index for which to provide a description.
    * @param windowIndex The timeline window index for which to provide a description.
    * @return A {@link MediaDescriptionCompat}.
    * @return A {@link MediaDescriptionCompat}.