Diese Seite wurde von der Cloud Translation API übersetzt.

Videos mit Bild im Bild (BiB) hinzufügen

Ab Android 8.0 (API-Ebene 26) können Aktivitäten im Bild-im-Bild-Modus (BiB) gestartet werden. BiB ist ein spezieller Mehrfenstermodus, der hauptsächlich für die Videowiedergabe verwendet wird. Nutzer können sich ein Video in einem kleinen Fenster ansehen, das an einer Ecke des Bildschirms angepinnt ist, während sie zwischen Apps wechseln oder Inhalte auf dem Hauptbildschirm durchsuchen.

BiB nutzt die in Android 7.0 verfügbaren Mehrfenster-APIs, um das angepinnte Video-Overlay-Fenster bereitzustellen. Um BiB deiner App hinzuzufügen, musst du Aktivitäten registrieren, die BiB unterstützen, bei Bedarf in den BiB-Modus wechseln und darauf achten, dass UI-Elemente ausgeblendet sind und die Videowiedergabe im BiB-Modus fortgesetzt wird.

Das BiB-Fenster wird in der obersten Ebene des Bildschirms in einer vom System ausgewählten Ecke angezeigt.

BiB wird auch auf kompatiblen Android TV-Geräten mit Android 14 (API-Level 34) oder höher unterstützt. Es gibt zwar viele Ähnlichkeiten, aber bei der Verwendung von BiB auf Fernsehern sind weitere Überlegungen erforderlich.

Wie Nutzer mit dem BiB-Fenster interagieren können

Nutzer können das BiB-Fenster an eine andere Stelle ziehen. Ab Android 12 können Nutzer außerdem:

Tippe einmal auf das Fenster, um eine Ein/Aus-Schaltfläche im Vollbildmodus, eine Schaltfläche zum Schließen, eine Schaltfläche für die Einstellungen und von deiner App bereitgestellte benutzerdefinierte Aktionen (z. B. Wiedergabesteuerung) anzuzeigen.
Tippe doppelt auf das Fenster, um zwischen der aktuellen BiB-Größe und der maximalen oder minimalen BiB-Größe zu wechseln. Wenn du z. B. doppelt auf ein maximiertes Fenster tippst, wird es minimiert und umgekehrt.
Verschieben Sie das Fenster, indem Sie es an den linken oder rechten Rand ziehen. Um die Verriegelung des Fensters aufzuheben, tippen Sie entweder auf den sichtbaren Teil des verschobenen Fensters oder ziehen Sie ihn heraus.
Ändern Sie die Größe des BiB-Fensters, indem Sie zum Zoomen die Finger auseinander- und zusammenziehen.

Deine App legt fest, wann die aktuelle Aktivität in den BiB-Modus wechselt. Hier einige Beispiele:

Eine Aktivität kann in den BiB-Modus wechseln, wenn der Nutzer auf die Startbildschirmtaste tippt oder nach oben wischt. So werden in Google Maps weiterhin Wegbeschreibungen angezeigt, während der Nutzer gleichzeitig eine andere Aktivität ausführt.
Deine App kann ein Video in den BiB-Modus versetzen, wenn der Nutzer vom Video zurückkehrt, um andere Inhalte zu durchsuchen.
Deine App kann ein Video in den BiB-Modus versetzen, während sich ein Nutzer das Ende einer Episode ansieht. Der Hauptbildschirm zeigt Werbe- oder zusammenfassende Informationen zur nächsten Folge der Serie an.
Ihre App bietet Nutzern die Möglichkeit, zusätzliche Inhalte in die Warteschlange zu stellen, während sie sich ein Video ansehen. Das Video wird im BiB-Modus weiter abgespielt, während auf dem Hauptbildschirm eine Inhaltsauswahl angezeigt wird.

BiB-Unterstützung deklarieren

BiB wird für Apps standardmäßig nicht automatisch unterstützt. Wenn BiB in deiner App unterstützt werden soll, registriere deine Videoaktivität in deinem Manifest, indem du android:supportsPictureInPicture auf true setzt. Gib außerdem an, dass deine Aktivität Layout-Konfigurationsänderungen verarbeitet, sodass sie nicht neu gestartet wird, wenn Layoutänderungen während Wechsel des BiB-Modus vorgenommen werden.

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

Aktivitäten auf BiB umstellen

Ab Android 12 kannst du deine Aktivitäten in den BiB-Modus versetzen, indem du das Flag setAutoEnterEnabled auf true setzt. Mit dieser Einstellung wechselt eine Aktivität bei Bedarf automatisch in den BiB-Modus, ohne dass enterPictureInPictureMode() in onUserLeaveHint explizit aufgerufen werden muss. Das hat den zusätzlichen Vorteil, dass die Übergänge viel reibungsloser sind. Weitere Informationen

Wenn deine App auf Android 11 oder niedriger ausgerichtet ist, muss eine Aktivität enterPictureInPictureMode() aufrufen, um in den BiB-Modus zu wechseln. Mit dem folgenden Code wird beispielsweise eine Aktivität in den BiB-Modus versetzt, wenn der Nutzer auf eine spezielle Schaltfläche in der Benutzeroberfläche der App klickt:

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;
    }
    ...
}

Möglicherweise möchten Sie eine Logik einbinden, die eine Aktivität in den BiB-Modus verwandelt, anstatt in den Hintergrund zu gehen. Google Maps wechselt beispielsweise in den BiB-Modus, wenn der Nutzer während der Navigation in der App die Startbildschirmtaste oder die Schaltfläche „Letzte“ drückt. Sie können diesen Fall abfangen, indem Sie onUserLeaveHint() überschreiben:

Kotlin

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

Java

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

Empfohlen: Nutzern eine optimierte BiB-Umstellung anbieten

Bei Android 12 wurden die animierten Übergänge zwischen Vollbild- und BiB-Fenstern deutlich verbessert. Wir empfehlen dringend, alle entsprechenden Änderungen zu implementieren. Danach werden diese Änderungen automatisch auf große Bildschirme wie faltbare Smartphones und Tablets angewendet, ohne dass ein zusätzlicher Aufwand erforderlich ist.

Wenn deine App keine entsprechenden Updates enthält, funktionieren BiB-Übergänge weiterhin, die Animationen sind jedoch weniger ausgefeilt. Ein Wechsel vom Vollbildmodus in den BiB-Modus kann beispielsweise dazu führen, dass das BiB-Fenster während des Übergangs ausgeblendet wird, bevor es nach Abschluss des Übergangs wieder angezeigt wird.

Diese Änderungen beinhalten Folgendes.

Reibungsloserer Wechsel in den BiB-Modus von der Bedienung über Gesten
Richtige sourceRectHint zum Aufrufen und Beenden des BiB-Modus festlegen
Nahtlose Größenanpassung für Nicht-Video-Inhalte deaktivieren

Informationen zur Aktivierung eines ausgefeilten Übergangs finden Sie im Android Kotlin PictureInPicture-Beispiel.

Einfacher Wechsel zum BiB-Modus von der Bedienung über Gesten

Ab Android 12 bietet das Flag setAutoEnterEnabled eine viel reibungslosere Animation für den Wechsel zu Videoinhalten im BiB-Modus mithilfe der Gestennavigation, z. B. wenn vom Vollbildmodus zum Startbildschirm nach oben gewischt wird.

Führen Sie die folgenden Schritte aus, um diese Änderung vorzunehmen. Sehen Sie sich als Referenz dieses Beispiel an:

Verwenden Sie setAutoEnterEnabled, um PictureInPictureParams.Builder zu erstellen:

Kotlin

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

Java

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

Rufe setPictureInPictureParams mit dem aktuellen PictureInPictureParams frühzeitig auf. Die App wartet nicht auf den onUserLeaveHint-Callback, wie es bei Android 11 der Fall gewesen wäre.

So kannst du beispielsweise bei der allerersten Wiedergabe und jeder nachfolgenden Wiedergabe setPictureInPictureParams aufrufen, wenn sich das Seitenverhältnis ändert.
Rufen Sie setAutoEnterEnabled(false) auf, aber nur bei Bedarf. Beispielsweise möchtest du BiB wahrscheinlich nicht eingeben, wenn die aktuelle Wiedergabe pausiert ist.

Richtige `sourceRectHint` zum Aufrufen und Beenden des BiB-Modus festlegen

Seit der Einführung von BiB in Android 8.0 gibt setSourceRectHint den Bereich der Aktivität an, der nach dem Übergang zu Bild im Bild sichtbar ist, z. B. die Begrenzungen der Videowiedergabe in einem Videoplayer.

Unter Android 12 verwendet das System sourceRectHint, um sowohl beim Starten als auch beim Beenden des BiB-Modus eine viel flüssigere Animation zu implementieren.

So richtest du sourceRectHint richtig ein, um den BiB-Modus zu starten und zu beenden:

Erstellen Sie PictureInPictureParams mit den richtigen Grenzen als sourceRectHint. Wir empfehlen außerdem, dem Videoplayer einen Listener für Layoutänderungen hinzuzufügen:

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);

Aktualisieren Sie bei Bedarf die sourceRectHint, bevor das System den Übergang zum Beenden beginnt. Wenn das System den BiB-Modus verlässt, wird die Ansichtshierarchie der Aktivität gemäß ihrer Zielkonfiguration (z. B. Vollbild) dargestellt. Die App kann einen Listener für Layoutänderungen an die Stamm- oder Zielansicht (z. B. die Videoplayeransicht) anhängen, um das Ereignis zu erkennen und sourceRectHint vor Beginn der Animation zu aktualisieren.

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

Nahtlose Größenanpassung für Inhalte, die keine Videos sind, deaktivieren

In Android 12 wird das Flag setSeamlessResizeEnabled hinzugefügt, das eine viel flüssigere Überblendungsanimation ermöglicht, wenn die Größe von Inhalten ohne Videos im BiB-Fenster geändert wird. Bisher konnten durch die Größenänderung von Nicht-Video-Inhalten in einem BiB-Fenster irritierte visuelle Artefakte entstehen.

So deaktivieren Sie die nahtlose Größenanpassung für Inhalte, die keine Videos sind:

Kotlin

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

Java

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

UI während BiB verarbeiten

Wenn die Aktivität in den BiB-Modus wechselt oder diesen beendet, wird Activity.onPictureInPictureModeChanged() oder Fragment.onPictureInPictureModeChanged() aufgerufen.

Sie sollten diese Callbacks überschreiben, um die UI-Elemente der Aktivität neu zu zeichnen. Im BiB-Modus wird deine Aktivität in einem kleinen Fenster angezeigt. Nutzer können mit den UI-Elementen deiner App im BiB-Modus nicht interagieren und die Details kleiner UI-Elemente sind möglicherweise schwer zu erkennen. Die Videowiedergabe mit einer minimalen UI ermöglicht die beste User Experience.

Wenn deine App benutzerdefinierte Aktionen für BiB bereitstellen muss, findest du weitere Informationen unter Steuerelemente hinzufügen auf dieser Seite. Entferne andere UI-Elemente, bevor deine Aktivität in BiB erscheint, und stelle sie wieder her, wenn deine Aktivität wieder im Vollbildmodus angezeigt wird:

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.
        ...
    }
}

Steuerelemente hinzufügen

Im BiB-Fenster können Steuerelemente angezeigt werden, wenn der Nutzer das Fenster des Fensters öffnet. Dazu kann er auf einem Mobilgerät auf das Fenster tippen oder das Menü auf der Fernbedienung des Fernsehers auswählen.

Wenn eine App eine aktive Mediensitzung hat, werden die Steuerelemente für Wiedergabe, Pause, Weiter und Zurück angezeigt.

Du kannst auch explizit benutzerdefinierte Aktionen angeben, indem du PictureInPictureParams mit PictureInPictureParams.Builder.setActions() erstellst, bevor du den BiB-Modus aktivierst, und die Parameter übergeben, wenn du mit enterPictureInPictureMode(android.app.PictureInPictureParams) oder setPictureInPictureParams(android.app.PictureInPictureParams) in den BiB-Modus wechselst. Sei vorsichtig. Wenn Sie mehr als getMaxNumPictureInPictureActions() hinzufügen, erhalten Sie nur die maximale Anzahl.

Videowiedergabe im BiB-Modus fortsetzen

Wenn deine Aktivität zu BiB wechselt, wird sie vom System in den pausierten Status versetzt und die Methode onPause() der Aktivität aufgerufen. Die Videowiedergabe sollte nicht pausiert und stattdessen fortgesetzt werden, wenn die Aktivität beim Wechsel in den BiB-Modus pausiert wird.

Unter Android 7.0 und höher solltest du die Videowiedergabe anhalten und fortsetzen, wenn das System onStop() und onStart() deiner Aktivität aufruft. So musst du nicht prüfen, ob sich deine App in onPause() im BiB-Modus befindet, und die Wiedergabe explizit fortsetzen.

Wenn du das Flag setAutoEnterEnabled nicht auf true gesetzt hast und die Wiedergabe in deiner onPause()-Implementierung pausieren musst, überprüfe den BiB-Modus, indem du isInPictureInPictureMode() aufrufst und die Wiedergabe entsprechend anpasst. Beispiel:

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.
        ...
    }
}

Wenn deine Aktivität aus dem BiB-Modus zurück in den Vollbildmodus wechselt, setzt das System die Aktivität fort und ruft die Methode onResume() auf.

Einzelne Wiedergabeaktivität für BiB verwenden

In Ihrer App kann ein Nutzer ein neues Video auswählen, wenn er auf dem Hauptbildschirm nach Inhalten sucht, während sich eine Videowiedergabe im BiB-Modus befindet. Spiele das neue Video in der bestehenden Wiedergabeaktivität im Vollbildmodus ab, anstatt eine neue Aktivität zu starten, die den Nutzer verwirren könnte.

Damit eine einzelne Aktivität für Videowiedergabeanfragen verwendet und bei Bedarf in den BiB-Modus gewechselt bzw. deaktiviert wird, setze den android:launchMode der Aktivität in deinem Manifest auf singleTask:

<activity android:name="VideoActivity"
    ...
    android:supportsPictureInPicture="true"
    android:launchMode="singleTask"
    ...

Überschreiben Sie in Ihren Aktivitäten onNewIntent() und verarbeiten Sie das neue Video. Beenden Sie die vorhandene Videowiedergabe bei Bedarf.

Best Practices

BiB ist auf Geräten mit wenig RAM möglicherweise deaktiviert. Bevor deine Anwendung BiB verwendet, prüfe durch Aufrufen von hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE), ob sie verfügbar ist.

BiB ist für Aktivitäten gedacht, bei denen ein Video im Vollbildmodus abgespielt wird. Wenn du in den BiB-Modus wechselst, solltest du nur Videoinhalte zeigen. Nachverfolgen, wann deine Aktivität in den BiB-Modus wechselt, und UI-Elemente ausblenden, wie unter Umgang mit der Benutzeroberfläche während BiB beschrieben.

Wenn eine Aktivität im BiB-Modus ist, wird standardmäßig kein Eingabefokus angezeigt. Verwenden Sie MediaSession.setCallback(), um im BiB-Modus Eingabeereignisse zu empfangen. Weitere Informationen zur Verwendung von setCallback() findest du unter Now Playing-Karte anzeigen.

Wenn sich deine App im BiB-Modus befindet, kann die Videowiedergabe im BiB-Fenster eine andere App stören, z. B. eine Musikplayer-App oder eine Sprachsuche-App. Um dies zu vermeiden, kannst du den Audiofokus zu Beginn der Videowiedergabe anfordern und Benachrichtigungen zu Änderungen des Audiofokus verarbeiten, wie unter Audiofokus verwalten beschrieben. Wenn du im BiB-Modus eine Benachrichtigung erhältst, dass der Audiofokus verloren geht, pausiere oder beende die Videowiedergabe.

Wenn in deiner App BiB gestartet wird, wird nur die oberste Aktivität als Bild im Bild aktiviert. In einigen Situationen, z. B. auf Geräten mit Mehrfenstermodus, ist es möglich, dass die unten stehende Aktivität jetzt zusammen mit der BiB-Aktivität wieder sichtbar wird. Sie sollten diesen Fall entsprechend behandeln, einschließlich der folgenden Aktivität, um einen onResume()- oder onPause()-Callback zu erhalten. Es ist auch möglich, dass der Nutzer mit der Aktivität interagiert. Wenn du beispielsweise eine Videolistenaktivität und die Videowiedergabe im BiB-Modus siehst, kann der Nutzer ein neues Video aus der Liste auswählen und die BiB-Aktivität wird entsprechend aktualisiert.

Zusätzlicher Beispielcode

Informationen zum Herunterladen einer Beispiel-App für Android findest du unter Beispiel für Bild im Bild. Informationen zum Herunterladen einer in Kotlin geschriebenen Beispiel-App finden Sie unter Android PictureInPicture Sample (Kotlin).

Videos mit Bild im Bild (BiB) hinzufügen

Wie Nutzer mit dem BiB-Fenster interagieren können

BiB-Unterstützung deklarieren

Aktivitäten auf BiB umstellen

Kotlin

Java

Kotlin

Java

Empfohlen: Nutzern eine optimierte BiB-Umstellung anbieten

Einfacher Wechsel zum BiB-Modus von der Bedienung über Gesten

Kotlin

Java

Richtige sourceRectHint zum Aufrufen und Beenden des BiB-Modus festlegen

Kotlin

Java

Kotlin

Java

Nahtlose Größenanpassung für Inhalte, die keine Videos sind, deaktivieren

Kotlin

Java

UI während BiB verarbeiten

Kotlin

Java

Steuerelemente hinzufügen

Videowiedergabe im BiB-Modus fortsetzen

Kotlin

Java

Einzelne Wiedergabeaktivität für BiB verwenden

Best Practices

Zusätzlicher Beispielcode

Richtige `sourceRectHint` zum Aufrufen und Beenden des BiB-Modus festlegen