Implémenter une fiche multimédia dans AAOS

Une fiche multimédia est un ViewGroup autonome qui affiche des métadonnées multimédias telles que le titre, la pochette de l'album, etc., et des commandes de lecture telles que Lecture et Pause, Passer et même des actions personnalisées fournies par l'application multimédia tierce. Une fiche multimédia peut également afficher une file d'attente d'éléments multimédias, comme une playlist.

Fiche de contenu multimédia

Fiche de contenu multimédia

Fiche de contenu multimédia

Figure 1. Exemples de mise en œuvre de fiches multimédias.

Comment les fiches multimédias sont-elles mises en œuvre dans AAOS ?

Les ViewGroups qui affichent des informations multimédias observent les mises à jour LiveData à partir du modèle de données de la bibliothèque car-media-common, PlaybackViewModel, pour remplir le ViewGroup. Chaque mise à jour LiveData correspond à un sous-ensemble d'informations multimédias qui ont changé, telles que MediaItemMetadata, PlaybackStateWrapper et MediaSource.

Comme cette approche entraîne la répétition du code (chaque application cliente ajoute des observateurs sur chaque élément LiveData et de nombreuses vues similaires sont attribuées aux données mises à jour), nous avons créé le PlaybackCardController.

PlaybackCardController

Le PlaybackCardController a été ajouté à la bibliothèque car-media-common pour faciliter la création d'une fiche multimédia. Il s'agit d'une classe publique construite avec un ViewGroup (mView), un PlaybackViewModel (mDataModel), un PlaybackCardViewModel (mViewModel) et une instance MediaItemsRepository (mItemsRepository).

Dans la fonction setupController, le ViewGroup est analysé pour certaines vues par ID, avec mView.findViewById(R.id.xxx) et attribué à des objets View protégés.

private void getViewsFromWidget() {
        mTitle = mView.findViewById(R.id.title);
        mAlbumCover = mView.findViewById(R.id.album_art);
        mDescription = mView.findViewById(R.id.album_title);
        mLogo = mView.findViewById(R.id.content_format);

        mAppIcon = mView.findViewById(R.id.media_widget_app_icon);
        mAppName = mView.findViewById(R.id.media_widget_app_name);

         // ...
}

Chaque mise à jour LiveData du PlaybackViewModel est observée dans une méthode protégée et interagit avec les vues pertinentes pour les données reçues. Par exemple, un observateur sur MediaItemMetadata définit le titre sur le mTitle TextView et transmet le MediaItemMetadata.ArtworkRef à la pochette de l'album art ImageBinder mAlbumArtBinder. Si les métadonnées sont nulles, les vues sont masquées. Les sous-classes du contrôleur peuvent remplacer cette logique si nécessaire.

mDataModel.getMetadata().observe(mViewLifecycle, this::updateMetadata);
// ...

/** Update views with {@link MediaItemMetadata} */
protected void updateMetadata(MediaItemMetadata metadata) {
        if (metadata != null) {
            String defaultTitle = mView.getContext().getString(
                    R.string.metadata_default_title);
            updateTextViewAndVisibility(mTitle, metadata.getTitle(),    defaultTitle);
            updateTextViewAndVisibility(mSubtitle, metadata.getSubtitle());
            updateMediaLink(mSubtitleLinker,metadata.getSubtitleLinkMediaId());
            updateTextViewAndVisibility(mDescription, metadata.getDescription());
            updateMediaLink(mDescriptionLinker, metadata.getDescriptionLinkMediaId());
            updateMetadataAlbumCoverArtworkRef(metadata.getArtworkKey());
            updateMetadataLogoWithUri(metadata);
        } else {
            ViewUtils.setVisible(mTitle, false);
            ViewUtils.setVisible(mSubtitle, false);
            ViewUtils.setVisible(mAlbumCover, false);
            ViewUtils.setVisible(mDescription, false);
            ViewUtils.setVisible(mLogo, false);
        }
    }

Étendre le PlaybackCardController

Les applications clientes qui souhaitent créer une fiche multimédia doivent étendre le PlaybackCardController si elles disposent d'une fonctionnalité supplémentaire qu'elles souhaitent gérer dans chaque mise à jour LiveData. Les clients existants dans AAOS suivent ce modèle. Tout d'abord, une sous-classe PlaybackCardController doit être créée, comme le MediaCardController. Ensuite, le MediaCardController doit ajouter une classe Builder interne statique qui étend celle du PlaybackCardController.

public class MediaCardController extends PlaybackCardController {

    // extra fields specific to MediaCardController

    /** Builder for {@link MediaCardController}. Overrides build() method to
     * return NowPlayingController rather than base {@link PlaybackCardController}
     */
    public static class Builder extends PlaybackCardController.Builder {

        @Override
        public MediaCardController build() {
            MediaCardController controller = new MediaCardController(this);
            controller.setupController();
            return controller;
        }
    }

    public MediaCardController(Builder builder) {
        super(builder);
    // any other function calls needed in constructor
    // ...

  }
}

Instancier le PlaybackCardController ou une sous-classe

La classe Controller doit être instanciée à partir d'un fragment ou d'une activité afin de disposer d'un LifecycleOwner pour les observateurs LiveData.

mMediaCardController = (MediaCardController) new MediaCardController.Builder()
                    .setModels(mViewModel.getPlaybackViewModel(),
                            mViewModel,
                            mViewModel.getMediaItemsRepository())
                    .setViewGroup((ViewGroup) view)
                    .build();

mViewModel est une instance du PlaybackCardViewModel (ou d'une sous-classe).

PlaybackCardViewModel pour enregistrer l'état

Le PlaybackCardViewModel est un ViewModel d'enregistrement d'état lié à un fragment ou à une activité qui doit être utilisé pour reconstruire le contenu de la fiche multimédia en cas de modification de la configuration (par exemple, le passage d'un thème clair à un thème sombre lorsqu'un utilisateur traverse un tunnel). Le PlaybackCardViewModel par défaut gère le stockage des instances des MediaModel pour la lecture, à partir desquelles le PlaybackViewModel et le MediaItemsRepository peuvent être récupérés. Utilisez le PlaybackCardViewModel pour suivre l'état de la file d'attente, de l'historique et du menu de dépassement à l'aide des getters et setters fournis.

public class PlaybackCardViewModel extends AndroidViewModel {

    private MediaModels mModels;
    private boolean mNeedsInitialization = true;
    private boolean mQueueVisible = false;
    private boolean mHistoryVisible = false;
    private boolean mOverflowExpanded = false;

    public PlaybackCardViewModel(@NonNull Application application) {
        super(application);
    }

    /** Initialize the PlaybackCardViewModel */
    public void init(MediaModels models) {
        mModels = models;
        mNeedsInitialization = false;
    }

    /**
     * Returns whether the ViewModel needs to be initialized. The ViewModel may
     * need re-initialization if a config change occurs or if the system kills
     * the Fragment.
     */
    public boolean needsInitialization() {
        return mNeedsInitialization;
    }

    public MediaItemsRepository getMediaItemsRepository() {
        return mModels.getMediaItemsRepository();
    }

    public PlaybackViewModel getPlaybackViewModel() {
        return mModels.getPlaybackViewModel();
    }

    public MediaSourceViewModel getMediaSourceViewModel() {
        return mModels.getMediaSourceViewModel();
    }

    public void setQueueVisible(boolean visible) {
        mQueueVisible = visible;
    }

    public boolean getQueueVisible() {
        return mQueueVisible;
    }

    public void setHistoryVisible(boolean visible) {
        mHistoryVisible = visible;
    }

    public boolean getHistoryVisible() {
        return mHistoryVisible;
    }

    public void setOverflowExpanded(boolean expanded) {
        mOverflowExpanded = expanded;
    }

    public boolean getOverflowExpanded() {
        return mOverflowExpanded;
    }
}

Cette classe peut être étendue si des états supplémentaires doivent être suivis.

Afficher une file d'attente dans une fiche multimédia

Le PlaybackViewModel fournit des API LiveData pour détecter si le MediaSource est compatible avec une file d'attente et pour récupérer la liste des objets MediaItemMetadata dans la file d'attente. Bien que ces API puissent être utilisées directement pour remplir un objet RecyclerView avec les informations de la file d'attente, une classe PlaybackQueueController a été ajoutée à la bibliothèque car-media-common pour simplifier ce processus. La mise en page de chaque élément du CarUiRecyclerView est spécifiée par l'application cliente, ainsi qu'une mise en page d'en-tête facultative. L'application cliente peut également choisir de limiter le nombre d'éléments affichés dans la file d'attente pendant l'état de conduite avec des restrictions UXR personnalisées.

Le constructeur et les setters PlaybackQueueController sont présentés dans l'exemple suivant. Les ressources de mise en page queueResource et headerResource peuvent être transmises en tant que Resources.ID_NULL si, dans le premier cas, le conteneur contient déjà un CarUiRecyclerView avec id queue_list et, dans le second cas, la file d'attente ne comporte pas d'en-tête.

   /**
    * Construct a PlaybackQueueController. If clients don't have a separate
    * layout for the queue, where the queue is already inflated within the
    * container, they should pass {@link Resources.ID_NULL} as the LayoutRes
    * resource. If clients don't require a UxrContentLimiter, they should pass
    * null for uxrContentLimiter and the int passed for uxrConfigurationId will
    * be ignored.
    */
    public PlaybackQueueController(
            ViewGroup container,
            @LayoutRes int queueResource,
            @LayoutRes int queueItemResource,
            @LayoutRes int headerResource,
            LifecycleOwner lifecycleOwner,
            PlaybackViewModel playbackViewModel,
            MediaItemsRepository itemsRepository,
            @Nullable LifeCycleObserverUxrContentLimiter uxrContentLimiter,
            int uxrConfigurationId) {
      // ...
    }

    public void setShowTimeForActiveQueueItem(boolean show) {
        mShowTimeForActiveQueueItem = show;
    }

    public void setShowIconForActiveQueueItem(boolean show) {
        mShowIconForActiveQueueItem = show;
    }

    public void setShowThumbnailForQueueItem(boolean show) {
        mShowThumbnailForQueueItem = show;
    }

    public void setShowSubtitleForQueueItem(boolean show) {
        mShowSubtitleForQueueItem = show;
    }

    /** Calls {@link RecyclerView#setVerticalFadingEdgeEnabled(boolean)} */
    public void setVerticalFadingEdgeLengthEnabled(boolean enabled) {
        mQueue.setVerticalFadingEdgeEnabled(enabled);
    }

    public void setCallback(PlaybackQueueCallback callback) {
        mPlaybackQueueCallback = callback;
    }

La mise en page de chaque élément de la file d'attente doit contenir les ID des vues qu'elle souhaite afficher et qui correspondent à celles utilisées dans la classe interne QueueViewHolder.

QueueViewHolder(View itemView) {
            super(itemView);
            mView = itemView;
            mThumbnailContainer = itemView.findViewById(R.id.thumbnail_container);
            mThumbnail = itemView.findViewById(R.id.thumbnail);
            mSpacer = itemView.findViewById(R.id.spacer);
            mTitle = itemView.findViewById(R.id.queue_list_item_title);
            mSubtitle = itemView.findViewById(R.id.queue_list_item_subtitle);
            mCurrentTime = itemView.findViewById(R.id.current_time);
            mMaxTime = itemView.findViewById(R.id.max_time);
            mTimeSeparator = itemView.findViewById(R.id.separator);
            mActiveIcon = itemView.findViewById(R.id.now_playing_icon);

            // ...
}

Pour afficher une file d'attente dans une fiche multimédia créée avec le PlaybackCardController (ou une sous-classe), le PlaybackQueueController peut être construit dans le constructeur PlaybackCardController à l'aide de mDataModel et mItemsRepository pour les instances PlaybackViewModel et MediaItemsRepository, respectivement.

Afficher l'historique des MediaSources précédemment lus

Dans cette section, vous allez apprendre à afficher et à présenter l'historique des sources multimédias précédemment lues.

Obtenir la liste de l'historique avec l'API PlaybackCardViewModel

PlaybackCardViewModel fournit une API LiveData appelée getHistoryList() pour récupérer la liste de l'historique multimédia. Elle renvoie un LiveData contenant une liste de MediaSources qui ont déjà été lus. Ces données peuvent être utilisées pour remplir un objet CarUiRecyclerView. Comme pour PlaybackQueueController, une classe nommée PlaybackHistoryController a été ajoutée à la bibliothèque car-media-common pour simplifier le processus.

public class PlaybackCardViewModel extends AndroidViewModel {

    public PlaybackCardViewModel(@NonNull Application application) {
    }

    /** Initialize the PlaybackCardViewModel */
    public void init(MediaModels models) {
    }

    public LiveData<List<MediaSource>> getHistoryList() {
        return mHistoryListData;
    }
}

Présenter l'UI de l'historique avec PlaybackHistoryController

Utilisez le nouveau PlaybackHistoryController pour remplir les données de l'historique dans un CarUiRecyclerView. Les constructeurs et les fonctions principales de cette classe sont les suivants. Le conteneur transmis par l'application cliente doit contenir un CarUiRecyclerView avec l'ID history_list. Le CarUiRecyclerView affiche les éléments de la liste et un en-tête facultatif. Les deux mises en page de l'élément de liste et de l'en-tête peuvent être transmises à partir de l'application cliente. Si Resources.ID_NULL est défini comme headerResource, l'en-tête n'est pas affiché. Une fois le PlaybackCardViewModel transmis au contrôleur, il surveille le LiveData<List<MediaSource>> récupéré à partir de playbackCardViewModel.getHistoryList().

public class PlaybackHistoryController {

    public PlaybackHistoryController(
            LifecycleOwner lifecycleOwner,
            PlaybackCardViewModel playbackCardViewModel,
            ViewGroup container,
            @LayoutRes int itemResource,
            @LayoutRes int headerResource,
            int uxrConfigurationId) {
    }

    /**
     * Renders the view.
     */
    public void setupView() {
    }
}

La mise en page de chaque élément doit contenir les ID des vues qu'elle souhaite afficher et qui correspondent à celles utilisées dans la classe interne ViewHolder.

HistoryItemViewHolder(View itemView) {
            super(itemView);
            mContext = itemView.getContext();
            mActiveView = itemView.findViewById(R.id.history_card_container_active);
            mInactiveView = itemView.findViewById(R.id.history_card_container_inactive);
            mMetadataTitleView = itemView.findViewById(R.id.history_card_title_active);
            mAdditionalInfo = itemView.findViewById(R.id.history_card_subtitle_active);
            mAppIcon = itemView.findViewById(R.id.history_card_app_thumbnail);
            mAlbumArt = itemView.findViewById(R.id.history_card_album_art);
            mAppTitleInactive = itemView.findViewById(R.id.history_card_app_title_inactive);
            mAppIconInactive = itemView.findViewById(R.id.history_item_app_icon_inactive);
// ...
}

Pour afficher une liste d'historique dans une fiche multimédia créée avec le PlaybackCardController (ou une sous-classe), le PlaybackHistoryController peut être construit dans le constructeur du PlaybackCardController.