Utiliser la bibliothèque Jetpack Picture-in-Picture

La bibliothèque Jetpack Picture-in-picture (PIP) offre une solution simplifiée et robuste aux développeurs d'applications Android pour implémenter la fonctionnalité PIP, en particulier pour les applications de lecture multimédia, de communication vidéo et de navigation. En fournissant une API unifiée, la bibliothèque permet d'éliminer le code récurrent, les bugs courants dans l'application et d'améliorer la qualité globale de l'expérience utilisateur en mode PIP.

La bibliothèque Jetpack PiP facilite les API PiP existantes en résolvant plusieurs problèmes et incohérences clés dans l'écosystème Android :

  • Fragmentation de l'OS : la bibliothèque gère automatiquement les différences dans les appels d'API PiP entre les différentes versions d'Android, par exemple en utilisant enterPictureInPictureMode avant Android 12 et isAutoEnterEnabled après. Les développeurs n'ont donc pas besoin de gérer les différences de version.
  • Paramètres PiP incorrects : fournit une solution unifiée pour définir correctement les paramètres PiP, par exemple setSourceRectHint, afin de créer des animations fluides et de haute qualité lors de la lecture de contenus multimédias.
  • Rappels d'état PiP unifiés : ils regroupent onPictureInPictureModeChanged et onPictureInPictureUiStateChanged dans une interface de rappel unique et unifiée (PictureInPictureDelegate.OnPictureInPictureEventListener) pour simplifier la gestion de l'état et de l'UI.
  • Réduction du code récurrent : la bibliothèque réduit la quantité de code récurrent en proposant des ensembles prédéfinis de RemoteActions pour les cas d'utilisation courants, tels que les commandes de lecture et les actions d'appel vidéo.
  • Pérennité : d'autres fonctionnalités PiP sont fournies par le biais de la bibliothèque Jetpack, ce qui permet aux utilisateurs d'accéder à des fonctionnalités supplémentaires avec un effort minimal, voire nul.

Workflow de migration

Identifiez la catégorie du cas d'utilisation de l'application et l'ancienne logique PiP :

Catégories : lecture vidéo, navigation ou appel vidéo.

Logique PiP héritée à identifier :

  • onUserLeaveHint
  • setAutoEnterEnabled
  • onPictureInPictureModeChanged
  • onPictureInPictureUiStateChanged
  • setPictureInPictureParams.

2. Configuration d'AndroidManifest

Assurez-vous que l'activité entrant dans le mode PIP déclare la prise en charge dans AndroidManifest.xml avec le configChanges nécessaire pour éviter les redémarrages inutiles :

<activity
android:name="VideoActivity" android:supportsPictureInPicture="true"
android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation">
</activity>

3. Configuration de l'environnement

Ajoutez les dépendances requises à build.gradle :

dependencies {
implementation("androidx.core:core:1.18.0")
implementation("androidx.activity:activity:1.13.0")
implementation("androidx.core:core-pip:1.0.0-alpha02") }

Utilisez les dernières bibliothèques AndroidX pour les dépendances et consultez la page Releases pour obtenir ces informations.

4. Sélection et initialisation du modèle

Choisissez le modèle d'implémentation qui correspond le mieux au cas d'utilisation de l'application :

  • Navigation et appel vidéo : BasicPictureInPicture ; le redimensionnement fluide n'est généralement pas pris en charge et vous n'avez pas besoin d'un indice de rectangle source.
  • Lecture vidéo : VideoPlaybackPictureInPicture ; suit automatiquement les limites de vue du lecteur pour l'indication de rectangle source et permet un redimensionnement fluide par défaut.

Pour adopter la bibliothèque Jetpack, remplacez votre implémentation PiP personnalisée existante par les API de la bibliothèque Jetpack. La complexité et le coût de l'adoption varient en fonction de l'implémentation actuelle de l'application.

Les sections suivantes décrivent certains cas d'utilisation typiques du mode PIP et les étapes d'implémentation nécessaires :

L'application informe la bibliothèque de l'état actif ou inactif de la navigation et définit le format. La bibliothèque Jetpack s'occupe du reste.

Différences majeures :

  1. Il n'est pas nécessaire de faire la différence entre l'entrée automatique et l'ancienne entrée côté application.
  2. Interfaces de rappel consolidées.
  3. Nouveau générateur PictureInPictureParams pour la rétrocompatibilité.

Appel vidéo

L'application informe la bibliothèque de l'état actif ou inactif de l'appel et définit le format.

Différences majeures :

  1. Il n'est pas nécessaire de faire la différence entre l'entrée automatique et l'ancienne entrée côté application.
  2. Interfaces de rappel consolidées.
  3. Nouveau générateur PictureInPictureParams pour la rétrocompatibilité.
  4. Icônes d'action standardisées pour les appels vidéo.

5. Migration de code

  • Logique d'entrée : remplacez la logique spécifique à l'API, telle que setAutoEnterEnabled pour Android 12 et versions ultérieures, ou onUserLeaveHint pour Android 11 et versions antérieures, par setEnabled. Déclenchez cet événement chaque fois que l'état d'éligibilité au mode PIP change.
  • Rappels : consolidez onPictureInPictureModeChanged (bascule de mise en page) et onPictureInPictureUiStateChanged (animation/états) dans un rappel unifié basé sur les événements onPictureInPictureEvent.
  • Actions et paramètres : mettez à jour les paramètres à l'aide de setActions et setAspectRatio sur l'instance de modèle chaque fois qu'ils changent.

Modèles d'implémentation de référence

Exemples d'implémentations.

Navigation et appel vidéo

class NavOrVideoCallJpipActivity : ComponentActivity(), PictureInPictureDelegate.OnPictureInPictureEventListener {
    private lateinit var pictureInPictureImpl: BasicPictureInPicture
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        pictureInPictureImpl = BasicPictureInPicture(this)
        // BasicPictureInPicture is ideal for Navigation and Video call use cases.
        pictureInPictureImpl.addOnPictureInPictureEventListener(
            ContextCompat.getMainExecutor(this),
            this
        )
        setContent {
        }
    }
    override fun onPictureInPictureEvent(
        event: PictureInPictureDelegate.Event,
        config: Configuration?
    ) {
        when (event) {
            PictureInPictureDelegate.Event.ENTERED -> { /* Toggle to PiP layout */ }
            PictureInPictureDelegate.Event.EXITED -> { /* Toggle to Full-screen layout */ }
            PictureInPictureDelegate.Event.STASHED -> { /* Optional: PiP is stashed */ }
            PictureInPictureDelegate.Event.UNSTASHED -> { /* Optional: PiP is unstashed */ }
        }
    }
}

Lecture de vidéos

class VideoPlaybackJpipActivity : ComponentActivity(), PictureInPictureDelegate.OnPictureInPictureEventListener {
    private lateinit var pictureInPictureImpl: VideoPlaybackPictureInPicture
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        pictureInPictureImpl = VideoPlaybackPictureInPicture(this)
        pictureInPictureImpl.addOnPictureInPictureEventListener(
            ContextCompat.getMainExecutor(this),
            this
        )
        setContent {
            ContentScreen(pictureInPictureImpl)
        }
    }
    override fun onPictureInPictureEvent(
        event: PictureInPictureDelegate.Event,
        config: Configuration?
    ) {
        when (event) {
            PictureInPictureDelegate.Event.ENTER_ANIMATION_START -> { /* Hide overlays */ }
            PictureInPictureDelegate.Event.ENTER_ANIMATION_END -> { /* Animation finished */ }
            PictureInPictureDelegate.Event.ENTERED -> { /* Switch to PiP layout */ }
            PictureInPictureDelegate.Event.STASHED -> { /* PiP stashed */ }
            PictureInPictureDelegate.Event.UNSTASHED -> { /* PiP unstashed */ }
            PictureInPictureDelegate.Event.EXITED -> { /* Return to full-screen */ }
        }
    }

    @Composable
    fun ContentScreen(pipController: VideoPlaybackPictureInPicture) {
        DisposableEffect(pipController) {
            onDispose {
                pipController.close()
            }
        }
    }
}

Précédent
Ajouter des actions à distance à PiP
Suivant
À propos de la prévisualisation du Retour