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

À partir d'Android 8.0 (niveau d'API 26), Android autorise le lancement des activités en mode Picture-in-picture (PIP). Le PIP 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 exploite les API multifenêtres disponibles dans Android 7.0 pour fournir la fenêtre vidéo en superposition épinglée. Pour ajouter le mode PIP à votre application, vous devez enregistrer vos activités compatibles avec le mode PIP, passer en mode PIP si nécessaire, et vous assurer que les éléments d'interface utilisateur sont masqués et que la lecture de la vidéo se poursuit lorsque l'activité est en mode PIP.

La fenêtre PIP apparaît dans la couche supérieure de l'écran, dans un angle choisi par le système.

Le mode PIP est également pris en charge sur les appareils compatibles équipés de l'OS Android TV et équipés d'Android 14 (niveau d'API 34) ou version ultérieure. Bien qu'il existe de nombreuses similitudes, d'autres considérations doivent être prises en compte lors de l'utilisation du 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 d'activation/désactivation du plein écran, un bouton de fermeture, un bouton des 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 passer de la taille PIP actuelle à la taille PIP maximale ou minimale. Par exemple, appuyer deux fois sur une fenêtre agrandie la réduit. L'inverse est également vrai.

  • Pour masquer la fenêtre, faites-la glisser vers le bord gauche ou droit. Pour la sortir, appuyez sur la partie visible de la fenêtre placée dans la cachette ou faites-la glisser.

  • Redimensionnez la fenêtre PIP 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 d'accueil ou balaie l'écran vers le haut jusqu'à l'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 passer une vidéo en mode PIP lorsque l'utilisateur revient en arrière pour parcourir un autre contenu.

  • 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 récapitulatives sur le prochain épisode de la série.

  • Votre application peut permettre aux utilisateurs de mettre des contenus supplémentaires en 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 compatibilité avec le mode PIP

Par défaut, le système ne prend pas automatiquement en charge le mode PIP pour les applications. Si vous souhaitez utiliser le mode PIP dans votre application, enregistrez votre activité vidéo dans votre fichier manifeste en définissant android:supportsPictureInPicture sur true. Indiquez également que votre activité gère les modifications de configuration de mise en page afin qu'elle ne soit pas relancée 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"
    ...

Basculer votre 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 de fournir des transitions bien plus fluides. Pour en savoir plus, consultez Rendre les transitions vers le mode PIP plus fluides depuis 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 fait passer une activité en mode PIP lorsque l'utilisateur clique sur un bouton dédié dans l'interface utilisateur 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 fait passer une activité en mode PIP au lieu de passer en arrière-plan. Par exemple, Google Maps passe en mode PIP si l'utilisateur appuie sur le bouton d'accueil ou le bouton "Récents" pendant la navigation dans l'application. Vous pouvez repérer ce cas en remplaçant onUserLeaveHint():

Kotlin

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

Java

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

Recommandation: Offrir aux utilisateurs une expérience de transition PIP soignée

Android 12 a apporté des améliorations esthétiques importantes aux transitions animées entre les fenêtres en plein écran et PIP. Nous vous recommandons vivement d'implémenter toutes les modifications applicables. Une fois ces modifications effectuées, elles s'adaptent automatiquement aux grands écrans, tels que les appareils pliables et les tablettes, sans qu'aucune action supplémentaire ne soit requise de votre part.

Si votre application n'inclut pas de mises à jour applicables, les transitions PIP restent fonctionnelles, mais les animations sont moins soignées. Par exemple, le passage du 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 impliquent les éléments suivants.

  • Rendre les transitions vers le mode PIP plus fluides depuis la navigation par gestes
  • Définir un sourceRectHint approprié pour accéder au mode PIP et le quitter
  • Désactiver le redimensionnement fluide pour les contenus autres que vidéo

Reportez-vous à l'exemple PictureInPicture Android Kotlin comme référence pour bénéficier d'une expérience de transition soignée.

Transitions vers le mode PIP plus fluides depuis la navigation par gestes

À partir d'Android 12, l'indicateur setAutoEnterEnabled fournit 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 vers le haut depuis le mode plein écran).

Pour effectuer cette modification, procédez comme suit et consultez cet exemple pour obtenir des informations de 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 à l'avance avec le PictureInPictureParams mis à jour. 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 lors de toute lecture suivante si le format est modifié.

  3. Appelez setAutoEnterEnabled(false), mais uniquement lorsque cela est nécessaire. Par exemple, vous ne souhaiterez probablement pas passer en mode PIP si la lecture en cours est mise en pause.

Définissez un sourceRectHint approprié pour accéder au mode PIP et le quitter.

À partir de l'introduction du PIP dans Android 8.0, setSourceRectHint désignait la zone de l'activité 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 à l'entrée et à la sortie du mode PIP.

Pour configurer correctement sourceRectHint afin d'activer et de quitter le mode PIP:

  1. Créez 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 sourceRectHint avant que le système ne commence 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 présentée dans sa configuration de destination (par exemple, plein écran). L'application peut associer un écouteur de changement de mise en page à sa vue racine ou à sa vue cible (comme 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 autres que vidéo

Android 12 ajoute l'indicateur setSeamlessResizeEnabled, qui fournit une animation en fondu enchaîné beaucoup plus fluide lors du redimensionnement d'un contenu autre que vidéo dans la fenêtre PIP. Auparavant, le redimensionnement d'un contenu autre que vidéo dans une fenêtre PIP pouvait créer des artefacts visuels choquants.

Pour désactiver le redimensionnement fluide pour les contenus autres que vidéo:

Kotlin

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

Java

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

Gérer l'UI en mode PIP

Lorsque l'activité passe en mode PIP ou la quitte, le système appelle Activity.onPictureInPictureModeChanged() ou Fragment.onPictureInPictureModeChanged().

Vous devez ignorer ces rappels pour redessiner les éléments d'interface utilisateur de l'activité. Gardez à l'esprit qu'en mode PIP, votre activité s'affiche dans une petite fenêtre. Les utilisateurs ne peuvent pas interagir avec les éléments d'interface utilisateur de votre application en mode PIP, et les détails des petits éléments d'interface utilisateur peuvent être difficiles à voir. Les activités de lecture de vidéos avec une interface utilisateur 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 d'interface utilisateur avant que votre activité n'entre en mode PIP et restaurez-les lorsque votre activité repasse en plein écran:

Kotlin

override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean,
                                           newConfig: Configuration) {
    if (isInPictureInPictureMode) {
        // Hide the full-screen UI (controls, etc.) while in PiP mode.
    } else {
        // Restore the full-screen UI.
    }
}

Java

@Override
public void onPictureInPictureModeChanged (boolean isInPictureInPictureMode, Configuration newConfig) {
    if (isInPictureInPictureMode) {
        // Hide the full-screen UI (controls, etc.) while in PiP mode.
    } else {
        // Restore the full-screen UI.
        ...
    }
}

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 depuis la télécommande du téléviseur).

Si une application dispose d'une session multimédia active, les commandes lecture, pause, suivant et précédent apparaissent.

Vous pouvez également spécifier explicitement des actions personnalisées en compilant 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 de setPictureInPictureParams(android.app.PictureInPictureParams). Soyez vigilant. Si vous essayez d'en ajouter plus de getMaxNumPictureInPictureActions(), vous n'obtiendrez que le nombre maximal.

Poursuite de la lecture de la vidéo en mode PIP

Lorsque votre activité passe au 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 et doit se poursuivre si l'activité est mise en pause lors du passage en mode PIP.

À partir d'Android 7.0, vous devez mettre en pause et reprendre la lecture de la vidéo lorsque le système appelle les onStop() et onStart() de votre activité. Ainsi, vous n'aurez pas à vérifier si votre application est en mode PIP dans onPause() et à poursuivre explicitement la lecture.

Si vous n'avez pas défini l'indicateur setAutoEnterEnabled sur true et que vous devez suspendre 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. Par 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 la méthode onResume().

Utiliser une activité de lecture unique pour le mode PIP

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. Lancez la nouvelle vidéo dans l'activité de lecture existante en mode plein écran au lieu de lancer une nouvelle activité qui pourrait induire l'utilisateur en erreur.

Pour vous assurer qu'une seule activité est utilisée pour les requêtes de lecture vidéo et que le mode PIP est activé ou désactivé 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 toute lecture vidéo existante si nécessaire.

pour réussir votre lancement

Il est possible que le mode PIP soit désactivé sur les appareils à faible 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 incluent des vidéos en plein écran. Lorsque vous passez votre activité en mode PIP, évitez d'afficher des contenus à l'exception du contenu vidéo. Suivez le passage de votre activité en mode PIP et masquez les éléments d'interface utilisateur, comme décrit dans la section Gérer l'interface utilisateur pendant le mode PIP.

Par défaut, lorsqu'une activité est en mode PIP, elle n'est pas sélectionnée. Pour recevoir des événements d'entrée en mode PIP, utilisez MediaSession.setCallback(). Pour en savoir plus sur l'utilisation de setCallback(), consultez la section 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 une application de recherche vocale. Pour éviter cela, demandez la priorité audio lorsque vous lancez la lecture de la vidéo et gérez les notifications de changement de ciblage audio, comme décrit dans Gérer le ciblage audio. Si vous recevez une notification de perte de la focalisation audio en mode PIP, mettez en pause ou arrêtez la lecture vidéo.

Lorsque votre application est sur le point d'entrer en mode PIP, notez que seule l'activité supérieure entre en Picture-in-picture. Dans certains cas, par exemple sur les appareils multifenêtres, il est possible que l'activité ci-dessous soit désormais affichée et redevienne visible en même temps que l'activité PIP. Vous devez gérer ce cas en conséquence, y compris l'activité qui consiste à obtenir 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é vidéo en cours de lecture 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 sous Android, consultez Exemple Picture-in-picture. Pour télécharger une application exemple écrite en Kotlin, consultez Exemple Android PictureInPicture (Kotlin).