Ajouter des vidéos en mode Picture-in-picture (PIP)

Essayer Compose
Jetpack Compose est le kit d'outils d'UI recommandé pour Android. Découvrez comment prendre en charge le mode Picture-in-picture dans Compose.
Picture-in-picture →

À 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 Picture-in-picture est un type spécial de mode multifenêtre principalement utilisé pour la lecture de vidéos. Elle permet à l'utilisateur de regarder une vidéo dans une petite fenêtre épinglée 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 vos activités compatibles avec le mode PIP, basculer votre activité en mode PIP selon les besoins 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 y a des points supplémentaires à prendre en compte lorsque vous utilisez le PIP sur un téléviseur.

Comment les utilisateurs peuvent-ils 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 en 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 basculer 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. Pour sortir la fenêtre de la pile, appuyez sur la partie visible de la fenêtre empilé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 des itinéraires 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 du contenu à une file d'attente pendant qu'ils regardent une vidéo. La vidéo continue d'être lue en mode PIP tandis que l'écran principal affiche une activité de sélection de contenu.

Déclarer la compatibilité avec le mode PIP

Par défaut, le système n'est pas compatible avec le mode PIP pour les applications. Si vous souhaitez que votre application soit compatible avec le mode PIP, 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"
    ...

Passer à l'activité en mode PIP

À 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 :

Kotlin

override fun onActionClicked(action: Action) {
    if (action.id.toInt() == R.id.lb_control_picture_in_picture) {
        activity?.enterPictureInPictureMode()
        return
    }
}

Java

@Override
public void onActionClicked(Action action) {
    if (action.getId() == R.id.lb_control_picture_in_picture) {
        getActivity().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() :

Kotlin

override fun onUserLeaveHint() {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode()
    }
}

Java

@Override
public void onUserLeaveHint () {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode();
    }
}

Recommandation : offrez aux utilisateurs une expérience de 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 Picture-in-picture. 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 écrans pliables et les tablettes, sans que vous ayez à faire quoi que ce soit d'autre.

Si votre application n'inclut pas les mises à jour applicables, les transitions PiP restent fonctionnelles, mais les animations sont moins soignées. 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.

Ces modifications concernent les points suivants :

  • Fluidifier les transitions vers le mode PIP depuis la navigation par gestes
  • Définir un sourceRectHint approprié pour entrer et sortir du mode Picture-in-picture
  • Désactiver le redimensionnement fluide pour les contenus non vidéo

Consultez l'exemple PictureInPicture Kotlin Android pour savoir comment activer une expérience de transition fluide.

Rendre les transitions vers le mode PIP plus fluides 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 bas en haut pour revenir à l'écran d'accueil depuis le mode plein écran).

Pour effectuer cette modification, procédez comme suit et consultez cet exemple pour obtenir une référence :

  1. Utilisez setAutoEnterEnabled pour construire PictureInPictureParams.Builder :

    Kotlin

    setPictureInPictureParams(PictureInPictureParams.Builder()
    .setAspectRatio(aspectRatio)
    .setSourceRectHint(sourceRectHint)
    .setAutoEnterEnabled(true)
    .build())

    Java

    setPictureInPictureParams(new PictureInPictureParams.Builder()
    .setAspectRatio(aspectRatio)
    .setSourceRectHint(sourceRectHint)
    .setAutoEnterEnabled(true)
    .build());

  2. Appelez setPictureInPictureParams avec la PictureInPictureParams à jour en avance. L'application n'attend pas le rappel onUserLeaveHint (comme elle l'aurait fait dans Android 11).

    Par exemple, vous pouvez appeler setPictureInPictureParams lors de la toute première lecture et de toute lecture suivante si le format est modifié.

  3. Appelez 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 entrer et sortir du mode PIP

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 entrer et sortir du mode PIP :

  1. Construisez PictureInPictureParams en utilisant les limites appropriées comme sourceRectHint. Nous vous recommandons également d'associer un écouteur de changement de mise en page au lecteur vidéo :

    Kotlin

    val mOnLayoutChangeListener =
OnLayoutChangeListener { v: View?, oldLeft: Int,
        oldTop: Int, oldRight: Int, oldBottom: Int, newLeft: Int, newTop:
        Int, newRight: Int, newBottom: Int ->
    val sourceRectHint = Rect()
    mYourVideoView.getGlobalVisibleRect(sourceRectHint)
    val builder = PictureInPictureParams.Builder()
        .setSourceRectHint(sourceRectHint)
    setPictureInPictureParams(builder.build())
}

mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener)

    Java

    private final View.OnLayoutChangeListener mOnLayoutChangeListener =
        (v, oldLeft, oldTop, oldRight, oldBottom, newLeft, newTop, newRight,
        newBottom) -> {
    final Rect sourceRectHint = new Rect();
    mYourVideoView.getGlobalVisibleRect(sourceRectHint);
    final PictureInPictureParams.Builder builder =
        new PictureInPictureParams.Builder()
            .setSourceRectHint(sourceRectHint);
    setPictureInPictureParams(builder.build());
};

mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener);

  2. Si nécessaire, mettez à jour le sourceRectHint avant 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 à jour sourceRectHint avant le début de l'animation.

    Kotlin

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

    Java

    // Listener is called right after the user exits PiP but before animating.
playerView.addOnLayoutChangeListener((v, 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.
        final Rect sourceRectHint = new Rect();
        playerView.getGlobalVisibleRect(sourceRectHint);
        setPictureInPictureParams(
            new 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 désagréables.

Pour activer le redimensionnement fluide du contenu vidéo :

Kotlin

setPictureInPictureParams(PictureInPictureParams.Builder()
    .setSeamlessResizeEnabled(true)
    .build())

Java

setPictureInPictureParams(new PictureInPictureParams.Builder()
    .setSeamlessResizeEnabled(true)
    .build());

Gérer l'UI pendant le mode PIP

Lorsque l'activité passe en mode Picture-in-picture (PIP) ou en sort, le système appelle Activity.onPictureInPictureModeChanged() ou Fragment.onPictureInPictureModeChanged().

Android 15 introduit des modifications qui assurent une transition encore plus fluide lorsque vous passez 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 Picture-in-picture.

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 de l'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'UI. Lorsque l'application passe en mode plein écran à partir de la fenêtre PIP, utilisez le rappel onPictureInPictureModeChanged() pour afficher ces éléments, comme indiqué dans les exemples suivants :

Kotlin

override fun onPictureInPictureUiStateChanged(pipState: PictureInPictureUiState) {
        if (pipState.isTransitioningToPip()) {
          // Hide UI elements.
        }
    }

Java

@Override
public void onPictureInPictureUiStateChanged(PictureInPictureUiState pipState) {
        if (pipState.isTransitioningToPip()) {
          // Hide UI elements.
        }
    }

Kotlin

override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean) {
        if (isInPictureInPictureMode) {
          // Unhide UI elements.
        }
    }

Java

@Override
public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode) {
        if (isInPictureInPictureMode) {
          // Unhide UI elements.
        }
    }

Cette option permet de masquer rapidement les éléments d'interface utilisateur non pertinents (pour une fenêtre PIP) afin de garantir une animation d'entrée PIP plus fluide et sans scintillement.

Remplacez ces rappels pour redessiner les éléments d'interface utilisateur de l'activité. N'oubliez pas qu'en mode Picture-in-picture, votre activité s'affiche dans une petite fenêtre. Les utilisateurs ne peuvent pas interagir avec les éléments de l'UI de votre application lorsqu'elle est en mode PIP, et les détails des petits éléments de l'UI 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 Ajouter des commandes sur cette page. Supprimez les autres éléments d'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 des actions personnalisées de manière explicite en créant PictureInPictureParams avec PictureInPictureParams.Builder.setActions() avant de passer en mode PIP, puis en transmettant les paramètres lorsque vous passez en mode PIP à l'aide de enterPictureInPictureMode(android.app.PictureInPictureParams) ou setPictureInPictureParams(android.app.PictureInPictureParams). Soyez prudent. Si vous essayez d'ajouter plus de getMaxNumPictureInPictureActions(), vous n'obtiendrez que le nombre maximal.

Poursuivre la lecture d'une vidéo en mode Picture-in-picture

Lorsque votre activité passe en mode PIP, le système la met en pause et appelle la méthode onPause() de l'activité. La lecture de la vidéo ne doit pas être mise en pause, mais doit continuer si l'activité est mise en pause lors du passage en mode Picture-in-picture.

Dans Android 7.0 et versions ultérieures, vous devez suspendre et reprendre la lecture vidéo lorsque le système appelle les méthodes onStop() et onStart() de votre activité. Cela vous évite de devoir vérifier si votre application est en mode PIP dans onPause() et de continuer 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 :

Kotlin

override fun onPause() {
    super.onPause()
    // If called while in PiP mode, do not pause playback.
    if (isInPictureInPictureMode) {
        // Continue playback.
    } else {
        // Use existing playback logic for paused activity behavior.
    }
}

Java

@Override
public void onPause() {
    // If called while in PiP mode, do not 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 PIP. 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.

Bonnes pratiques

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 Gestion de 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 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 Gestion de la priorité audio. Si vous recevez une notification de perte du focus audio en mode PIP, mettez la lecture de la vidéo en pause ou arrêtez-la.

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 multifenêtres, il est possible que l'activité ci-dessous s'affiche et redevienne visible à côté de l'activité PIP. Vous devez gérer ce cas en conséquence, y compris l'activité ci-dessous qui reçoit 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).