À partir d'Android 8.0 (niveau d'API 26), Android permet aux activités de se lancer en mode Picture-in-picture (PIP). Le mode PIP est un type spécial de mode multifenêtre utilisé pour la lecture de vidéos, les appels vidéo et la navigation. Elle permet à l'utilisateur d'épingler la fenêtre d'activité existante dans un coin de l'écran tout en naviguant entre les applications ou en parcourant le contenu de l'écran principal.
Le mode PIP utilise les API multifenêtres disponibles dans Android 7.0 pour fournir la fenêtre de superposition vidéo épinglée. Pour ajouter le mode PIP à votre application, vous devez enregistrer les activités compatibles avec le mode PIP, basculer votre activité en mode PIP si nécessaire, et vous assurer que les éléments d'interface utilisateur sont masqués et que la lecture vidéo se poursuit lorsque l'activité est en mode PIP.
La fenêtre PIP apparaît au premier plan de l'écran, dans un coin choisi par le système.
Le mode PIP est également compatible avec les appareils Android TV OS compatibles exécutant Android 14 (niveau d'API 34) ou version ultérieure. Bien qu'il existe de nombreuses similitudes, il faut tenir compte de points supplémentaires lorsque vous utilisez le PIP sur un téléviseur.
Comment les utilisateurs peuvent interagir avec la fenêtre PIP
Les utilisateurs peuvent faire glisser la fenêtre PiP vers un autre emplacement. À partir d'Android 12, les utilisateurs peuvent également :
Appuyez une fois sur la fenêtre pour afficher un bouton bascule plein écran, un bouton de fermeture, un bouton de paramètres et les actions personnalisées fournies par votre application (par exemple, les commandes de lecture).
Appuyez deux fois sur la fenêtre pour alterner entre la taille actuelle de la fenêtre PIP et sa taille maximale ou minimale. Par exemple, si vous appuyez deux fois sur une fenêtre agrandie, elle est réduite, et inversement.
Rangez la fenêtre en la faisant glisser vers le bord gauche ou droit de l'écran. Pour désencombrer la fenêtre, appuyez sur la partie visible de la fenêtre encombrée ou faites-la glisser.
Redimensionnez la fenêtre PIP à l'aide du geste de pincement pour zoomer.
Votre application contrôle le moment où l'activité en cours passe en mode PIP. Voici quelques exemples :
Une activité peut passer en mode PIP lorsque l'utilisateur appuie sur le bouton Accueil ou balaye l'écran vers le haut pour revenir à l'écran d'accueil. C'est ainsi que Google Maps continue d'afficher l'itinéraire pendant que l'utilisateur exécute une autre activité en même temps.
Votre application peut déplacer une vidéo en mode PIP lorsque l'utilisateur revient en arrière depuis la vidéo pour parcourir d'autres contenus.
Votre application peut passer une vidéo en mode PIP pendant qu'un utilisateur regarde la fin d'un épisode de contenu. L'écran principal affiche des informations promotionnelles ou un résumé du prochain épisode de la série.
Votre application peut permettre aux utilisateurs d'ajouter des contenus à la file d'attente pendant qu'ils regardent une vidéo. La lecture de la vidéo se poursuit en mode PIP tandis que l'écran principal affiche une activité de sélection de contenu.
Déclarer la prise en charge du mode PIP
Par défaut, le système n'est pas compatible avec le mode PIP pour les applications. Si vous souhaitez prendre en charge le mode PIP dans votre application, enregistrez votre activité vidéo dans votre fichier manifeste en définissant android:supportsPictureInPicture sur true. Spécifiez également que votre activité gère les modifications de configuration de la mise en page afin qu'elle ne redémarre pas lorsque des modifications de mise en page se produisent lors des transitions en mode PIP.
<activity android:name="VideoActivity"
android:supportsPictureInPicture="true"
android:configChanges=
"screenSize|smallestScreenSize|screenLayout|orientation"
...
Implémenter le mode PIP avec Jetpack
Utilisez la bibliothèque Picture-in-picture Jetpack pour implémenter l'expérience Picture-in-picture, car elle simplifie l'intégration et réduit les problèmes courants dans l'application. Consultez notre application exemple de plate-forme pour voir un exemple de son utilisation. Toutefois, si vous préférez implémenter le mode PIP à l'aide des API de plate-forme, consultez la documentation suivante.
Passer à l'activité en mode Picture-in-picture
À partir d'Android 12, vous pouvez passer votre activité en mode PIP en définissant l'indicateur setAutoEnterEnabled sur true. Avec ce paramètre, une activité passe automatiquement en mode PIP si nécessaire, sans avoir à appeler explicitement enterPictureInPictureMode() dans onUserLeaveHint. Cela présente l'avantage supplémentaire de fournir des transitions beaucoup plus fluides. Pour en savoir plus, consultez Rendre les transitions vers le mode PIP plus fluides à partir de la navigation par gestes.
Si vous ciblez Android 11 ou une version antérieure, une activité doit appeler enterPictureInPictureMode() pour passer en mode PIP. Par exemple, le code suivant bascule une activité en mode PIP lorsque l'utilisateur clique sur un bouton dédié dans l'UI de l'application :
override fun onActionClicked(action: Action) {
if (action.id.toInt() == R.id.lb_control_picture_in_picture) {
activity?.enterPictureInPictureMode()
return
}
}
Vous pouvez inclure une logique qui bascule une activité en mode PIP au lieu de la mettre en arrière-plan. Par exemple, Google Maps passe en mode PIP si l'utilisateur appuie sur le bouton "Accueil" ou "Applications récentes" pendant que l'application est en train de naviguer. Vous pouvez gérer ce cas en remplaçant onUserLeaveHint() :
override fun onUserLeaveHint() {
if (iWantToBeInPipModeNow()) {
enterPictureInPictureMode()
}
}
Recommandation : offrir aux utilisateurs une transition fluide vers le mode PIP
Android 12 a apporté des améliorations esthétiques importantes aux transitions animées entre les fenêtres plein écran et PIP. Nous vous recommandons vivement d'implémenter toutes les modifications applicables. Une fois que vous l'aurez fait, ces modifications s'adapteront automatiquement aux grands écrans tels que les appareils pliables et les tablettes, sans nécessiter d'autres efforts.
Si votre application n'inclut pas les mises à jour applicables, les transitions PiP restent fonctionnelles, mais les animations sont moins fluides. Par exemple, le passage du mode plein écran au mode PIP peut entraîner la disparition de la fenêtre PIP pendant la transition, avant qu'elle ne réapparaisse une fois la transition terminée.
Voici les modifications apportées :
- Fluidifier les transitions vers le mode PIP depuis la navigation par gestes
- Définir un
sourceRectHintapproprié pour entrer et quitter le mode PIP - Désactiver le redimensionnement fluide pour le contenu non vidéo
Consultez l'exemple Picture-in-Picture Android Kotlin pour savoir comment offrir une expérience de transition fluide.
Transitions plus fluides vers le mode PIP depuis la navigation par gestes
À partir d'Android 12, l'indicateur setAutoEnterEnabled permet une animation beaucoup plus fluide pour la transition vers le contenu vidéo en mode PIP à l'aide de la navigation par gestes (par exemple, lorsque vous balayez l'écran de haut en bas pour revenir à l'écran d'accueil depuis le mode plein écran).
Pour effectuer cette modification, procédez comme suit :
- Utilisez
setAutoEnterEnabledpour construirePictureInPictureParams.Builder:
setPictureInPictureParams(PictureInPictureParams.Builder()
.setAspectRatio(aspectRatio)
.setSourceRectHint(sourceRectHint)
.setAutoEnterEnabled(true)
.build())
Note: When `setAutoEnterEnabled` is enabled, you don't need to explicitly
call [`enterPictureInPictureMode`][5] in [`onUserLeaveHint`][6].
Appelez
setPictureInPictureParamsavec laPictureInPictureParamsà jour à l'avance. L'application n'attend pas le rappelonUserLeaveHint(comme elle l'aurait fait dans Android 11).Par exemple, vous pouvez appeler
setPictureInPictureParamslors de la toute première lecture et de toute lecture ultérieure si le format est modifié.Appelle
setAutoEnterEnabled(false), mais uniquement si nécessaire. Par exemple, vous ne souhaitez probablement pas passer en mode PIP si la lecture actuelle est en pause.
Définir un sourceRectHint approprié pour passer en mode PIP et en sortir
Depuis l'introduction du mode PIP dans Android 8.0, setSourceRectHint indique la zone de l'activité qui est visible après la transition vers le mode Picture-in-picture (par exemple, les limites de la vue vidéo dans un lecteur vidéo).
Avec Android 12, le système utilise sourceRectHint pour implémenter une animation beaucoup plus fluide lors du passage en mode PIP et de la sortie de ce mode.
Pour définir correctement sourceRectHint pour l'entrée et la sortie du mode PIP :
- Construisez
PictureInPictureParamsen utilisant les limites appropriées commesourceRectHint. Nous vous recommandons également d'associer un écouteur de changement de mise en page au lecteur vidéo :
val mOnLayoutChangeListener =
OnLayoutChangeListener { v: View?, left: Int,
top: Int, right: Int, bottom: Int, oldLeft: Int, oldTop:
Int, oldRight: Int, oldBottom: Int ->
val sourceRectHint = Rect()
mYourVideoView.getGlobalVisibleRect(sourceRectHint)
val builder = PictureInPictureParams.Builder()
.setSourceRectHint(sourceRectHint)
setPictureInPictureParams(builder.build())
}
mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener)
- Si nécessaire, mettez à jour le
sourceRectHintavant que le système ne démarre la transition de sortie. Lorsque le système est sur le point de quitter le mode PIP, la hiérarchie des vues de l'activité est mise en page selon sa configuration de destination (par exemple, en plein écran). L'application peut associer un écouteur de changement de mise en page à sa vue racine ou à sa vue cible (telle que la vue du lecteur vidéo) pour détecter l'événement et mettre à joursourceRectHintavant le début de l'animation.
// Listener is called immediately after the user exits PiP but before animating.
playerView.addOnLayoutChangeListener { _, left, top, right, bottom,
oldLeft, oldTop, oldRight, oldBottom ->
if (left != oldLeft
|| right != oldRight
|| top != oldTop
|| bottom != oldBottom) {
// The playerView's bounds changed, update the source hint rect to
// reflect its new bounds.
val sourceRectHint = Rect()
playerView.getGlobalVisibleRect(sourceRectHint)
setPictureInPictureParams(
PictureInPictureParams.Builder()
.setSourceRectHint(sourceRectHint)
.build()
)
}
}
Désactiver le redimensionnement fluide pour les contenus non vidéo
Android 12 ajoute l'indicateur setSeamlessResizeEnabled, qui fournit une animation de fondu enchaîné beaucoup plus fluide lors du redimensionnement du contenu non vidéo dans la fenêtre PIP. Auparavant, le redimensionnement de contenus non vidéo dans une fenêtre PIP pouvait créer des artefacts visuels choquants.
Pour activer le redimensionnement fluide du contenu vidéo :
setPictureInPictureParams(PictureInPictureParams.Builder()
.setSeamlessResizeEnabled(true)
.build())
Gérer l'UI pendant le mode PIP
Lorsque l'activité entre ou sort du mode Picture-in-picture (PIP), le système appelle Activity.onPictureInPictureModeChanged() ou Fragment.onPictureInPictureModeChanged().
Android 15 introduit des modifications qui permettent une transition encore plus fluide lors du passage en mode PIP. Cela est utile pour les applications dont les éléments d'interface utilisateur sont superposés à leur interface utilisateur principale, qui passe en mode PIP.
Les développeurs utilisent le rappel onPictureInPictureModeChanged() pour définir la logique qui active ou désactive la visibilité des éléments d'UI superposés. Ce rappel est déclenché lorsque l'animation d'entrée ou de sortie du mode PIP est terminée. À partir d'Android 15, la classe PictureInPictureUiState inclut un nouvel état.
Avec ce nouvel état d'UI, les applications ciblant Android 15 observent l'appel de rappel Activity#onPictureInPictureUiStateChanged() avec isTransitioningToPip() dès que l'animation PIP commence. De nombreux éléments d'interface utilisateur ne sont pas pertinents pour l'application lorsqu'elle est en mode PIP. Par exemple, les vues ou la mise en page qui incluent des informations telles que des suggestions, des vidéos à venir, des notes et des titres. Lorsque l'application passe en mode PIP, utilisez le rappel onPictureInPictureUiStateChanged() pour masquer ces éléments d'interface utilisateur. Lorsque l'application passe en mode plein écran à partir de la fenêtre PIP, utilisez le rappel onPictureInPictureModeChanged() pour afficher ces éléments, comme illustré dans les exemples suivants :
override fun onPictureInPictureUiStateChanged(pipState: PictureInPictureUiState) {
if (pipState.isTransitioningToPip()) {
// Hide UI elements.
}
}
override fun onPictureInPictureModeChanged(
isInPictureInPictureMode: Boolean,
newConfig: Configuration
) {
super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
if (!isInPictureInPictureMode) {
// Unhide UI elements.
}
}
Ce bouton d'activation/désactivation rapide de la visibilité des éléments d'interface utilisateur non pertinents (pour une fenêtre PIP) permet de garantir une animation d'entrée PIP plus fluide et sans scintillement.
Remplacez ces rappels pour redessiner les éléments d'UI de l'activité. N'oubliez pas qu'en mode Picture-in-picture, votre activité est affichée dans une petite fenêtre. Les utilisateurs ne peuvent pas interagir avec les éléments d'interface utilisateur de votre application lorsqu'elle est en mode PIP, et les détails des petits éléments d'interface utilisateur peuvent être difficiles à voir. Les activités de lecture vidéo avec une UI minimale offrent la meilleure expérience utilisateur.
Si votre application doit fournir des actions personnalisées pour le mode PIP, consultez la section Ajouter des commandes sur cette page. Supprimez les autres éléments de l'UI avant que votre activité ne passe en mode PIP, puis restaurez-les lorsque votre activité redevient en plein écran.
Ajouter des commandes
La fenêtre PIP peut afficher des commandes lorsque l'utilisateur ouvre le menu de la fenêtre (en appuyant sur la fenêtre sur un appareil mobile ou en sélectionnant le menu à l'aide de la télécommande du téléviseur).
Si une application dispose d'une session multimédia active, les commandes de lecture, de pause, de titre suivant et de titre précédent s'affichent.
Vous pouvez également spécifier explicitement des actions personnalisées en créant PictureInPictureParams avec PictureInPictureParams.Builder.setActions() avant de passer en mode PIP, et en transmettant les paramètres lorsque vous passez en mode PIP à l'aide de enterPictureInPictureMode(android.app.PictureInPictureParams) ou setPictureInPictureParams(android.app.PictureInPictureParams). Fais attention. Si vous essayez d'ajouter plus de getMaxNumPictureInPictureActions(), vous n'obtiendrez que le nombre maximal.
Poursuivre la lecture d'une vidéo en mode PIP
Lorsque votre activité passe en mode PIP, le système la place à l'état "en pause" et appelle la méthode onPause() de l'activité. La lecture de la vidéo ne doit pas être mise en pause et doit se poursuivre si l'activité est mise en pause lors de la transition vers le mode Picture-in-picture.
Dans Android 7.0 (niveau d'API 24) et versions ultérieures, vous devez mettre en pause et reprendre la lecture vidéo lorsque le système appelle les méthodes onStop() et onStart() de votre activité. Vous pouvez ainsi éviter de vérifier si votre application est en mode PIP dans onPause() et de poursuivre explicitement la lecture.
Si vous n'avez pas défini l'indicateur setAutoEnterEnabled sur true et que vous devez mettre en pause la lecture dans votre implémentation onPause(), vérifiez le mode PIP en appelant isInPictureInPictureMode() et gérez la lecture de manière appropriée. Exemple :
override fun onPause() {
super.onPause()
// If called while in PiP mode, don't pause playback.
if (isInPictureInPictureMode) {
// Continue playback.
} else {
// Use existing playback logic for paused activity behavior.
}
}
Lorsque votre activité quitte le mode PIP pour revenir au mode plein écran, le système la reprend et appelle votre méthode onResume().
Utiliser une seule activité de lecture pour le mode Picture-in-picture
Dans votre application, un utilisateur peut sélectionner une nouvelle vidéo lorsqu'il recherche du contenu sur l'écran principal, tandis qu'une activité de lecture vidéo est en mode Picture-in-picture. Lisez la nouvelle vidéo dans l'activité de lecture existante en mode plein écran, au lieu de lancer une nouvelle activité qui pourrait dérouter l'utilisateur.
Pour vous assurer qu'une seule activité est utilisée pour les demandes de lecture vidéo et qu'elle est activée ou désactivée en mode PIP selon les besoins, définissez le android:launchMode de l'activité sur singleTask dans votre fichier manifeste :
<activity android:name="VideoActivity"
...
android:supportsPictureInPicture="true"
android:launchMode="singleTask"
...
Dans votre activité, remplacez onNewIntent() et gérez la nouvelle vidéo, en arrêtant la lecture de toute vidéo existante si nécessaire.
Prendre en charge le mode PIP pour les applications d'appareil photo
Pour activer le mode PIP pour les applications d'appareil photo, vous devez vous assurer que l'appareil photo reste actif en mode PIP en ne le fermant pas lorsque onPause() est appelé :
override fun onPause() {
super.onPause()
// Don't close the camera if the app is entering PiP mode
if (!isInPictureInPictureMode) {
closeCamera()
}
}
Comme pour les autres cas d'utilisation, masquez les éléments d'interface utilisateur non essentiels (tels que les commandes et les calques) et ajoutez des actions personnalisées pour contrôler la caméra (par exemple, arrêter l'enregistrement ou inverser la caméra).
Calculer sourceRectHint pour des transitions fluides
Il est essentiel de fournir un sourceRectHint précis avec les coordonnées exactes de l'écran du viseur de l'appareil photo pour une animation d'entrée fluide. Vous pouvez obtenir les limites de la vue d'aperçu à l'aide de getGlobalVisibleRect() comme suit :
val previewView = findViewById<View>(R.id.preview_view)
val globalRect = Rect()
// Ensure the view is laid out before calling getGlobalVisibleRect() to get valid screen coordinates.
previewView.getGlobalVisibleRect(globalRect)
val params = PictureInPictureParams.Builder()
.setSourceRectHint(globalRect)
.build()
setPictureInPictureParams(params)
Informations complémentaires
Il est possible que le mode PIP soit désactivé sur les appareils disposant d'une faible quantité de RAM. Avant que votre application utilise le mode PIP, vérifiez qu'il est disponible en appelant hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE).
Le mode PIP est destiné aux activités qui lisent des vidéos en plein écran. Lorsque vous passez votre activité en mode PIP, évitez d'afficher autre chose que du contenu vidéo. Suivez le moment où votre activité passe en mode PIP et masquez les éléments d'interface utilisateur, comme décrit dans Gérer l'UI en mode PIP.
Lorsqu'une activité est en mode PIP, elle ne reçoit pas le focus d'entrée par défaut. Pour recevoir des événements d'entrée en mode PIP, utilisez MediaSession.setCallback().
Pour en savoir plus sur l'utilisation de setCallback(), consultez Afficher une carte "En écoute".
Lorsque votre application est en mode PIP, la lecture de la vidéo dans la fenêtre PIP peut provoquer des interférences audio avec une autre application, telle qu'une application de lecteur de musique ou de recherche vocale. Pour éviter cela, demandez la priorité audio lorsque vous commencez à lire la vidéo et gérez les notifications de changement de priorité audio, comme décrit dans Gérer la priorité audio. Si vous recevez une notification de perte de priorité audio en mode Picture-in-picture, mettez en pause ou arrêtez la lecture de la vidéo.
Lorsque votre application est sur le point de passer en mode PIP, notez que seule l'activité supérieure passe en mode Picture-in-picture. Dans certaines situations, par exemple sur les appareils en mode multifenêtre, il est possible que l'activité sous-jacente s'affiche et redevienne visible à côté de l'activité PIP. Vous devez gérer ce cas en conséquence, y compris l'activité sous-jacente recevant un rappel onResume() ou onPause().
Il est également possible que l'utilisateur interagisse avec l'activité.
Par exemple, si une activité de liste de vidéos est affichée et que l'activité de lecture de la vidéo est en mode PIP, l'utilisateur peut sélectionner une nouvelle vidéo dans la liste et l'activité PIP doit être mise à jour en conséquence.
Exemples de code supplémentaires
Pour télécharger une application exemple écrite en Kotlin, consultez Exemple Picture-in-Picture Android (Kotlin).