Medienprojektion

Mit den in Android 5 (API-Level 21) eingeführten android.media.projection APIs kannst du den Inhalt eines Gerätedisplays als Mediastream erfassen, den du wiedergeben, aufzeichnen oder auf andere Geräte wie Fernseher streamen kannst.

Mit Android 14 (API-Level 34) wird die App-Bildschirmfreigabe eingeführt. Damit können Nutzer unabhängig vom Fenstermodus ein einzelnes App-Fenster anstelle des gesamten Gerätebildschirms freigeben. Bei der App-Bildschirmfreigabe werden die Statusleiste, die Navigationsleiste, Benachrichtigungen und andere System-UI-Elemente nicht auf dem freigegebenen Bildschirm angezeigt, auch wenn die App-Bildschirmfreigabe verwendet wird, um eine App im Vollbildmodus aufzunehmen. Nur die Inhalte der ausgewählten App werden geteilt.

Die App-Bildschirmfreigabe schützt den Datenschutz der Nutzer, erhöht die Produktivität und verbessert das Multitasking, da Nutzer mehrere Apps ausführen, die Freigabe von Inhalten aber auf eine einzelne App beschränken können.

Drei Displaydarstellungen

Bei einer Medienprojektion werden die Inhalte eines Gerätedisplays oder App-Fensters erfasst und dann auf ein virtuelles Display projiziert, das das Bild auf einer Surface rendert.

Das Display des echten Geräts wird auf das virtuelle Display projiziert. Inhalte des virtuellen Displays, die in die von der Anwendung bereitgestellte „Surface“ geschrieben werden.
Abbildung 1. Der Bildschirm des echten Geräts oder das App-Fenster wird auf das virtuelle Display projiziert. Virtuelles Display, das in die von der Anwendung bereitgestellte Surface geschrieben wird.

Die Anwendung stellt die Surface über eine MediaRecorder, SurfaceTexture oder ImageReader bereit, die den Inhalt des erfassten Displays nutzt und es Ihnen ermöglicht, auf der Surface gerenderte Bilder in Echtzeit zu verwalten. Du kannst die Bilder als Aufnahme speichern oder auf einen Fernseher oder ein anderes Gerät streamen.

Echtes Display

Beginne eine Medienprojektionssitzung, indem du ein Token anforderst, mit dem deine App die Inhalte des Gerätedisplays oder App-Fensters aufnehmen kann. Das Token wird durch eine Instanz der Klasse MediaProjection dargestellt.

Verwenden Sie die Methode getMediaProjection() des Systemdienstes MediaProjectionManager, um eine MediaProjection-Instanz zu erstellen, wenn Sie eine neue Aktivität starten. Starten Sie die Aktivität mit einem Intent aus der Methode createScreenCaptureIntent(), um einen Screenshot-Vorgang anzugeben:

val mediaProjectionManager = getSystemService(MediaProjectionManager::class.java)
var mediaProjection: MediaProjection?

val startMediaProjection = registerForActivityResult(
    StartActivityForResult()
) { result ->
    if (result.resultCode == RESULT_OK) {
        result.data?.let { data ->
            mediaProjection = mediaProjectionManager
                .getMediaProjection(result.resultCode, data)
        }
    }
}

startMediaProjection.launch(mediaProjectionManager.createScreenCaptureIntent())

Virtuelles Display

Das Herzstück einer Medienprojektion ist das virtuelle Display, das Sie durch Aufrufen von createVirtualDisplay() für eine MediaProjection-Instanz erstellen:

virtualDisplay = mediaProjection.createVirtualDisplay(
    "ScreenCapture",
    width,
    height,
    screenDensity,
    DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
    surface,
    null, null
)

Die Parameter width und height geben die Abmessungen des virtuellen Displays an. Verwende die in Android 11 (API-Level 30) eingeführten WindowMetrics-APIs, um Werte für Breite und Höhe abzurufen. (Details hierzu finden Sie im Abschnitt Größe der Medienprojektion.)

Surface

Passen Sie die Größe der Medienprojektionsfläche an, um die Ausgabe in der entsprechenden Auflösung zu erzeugen. Wähle eine große Oberfläche (niedrige Auflösung) für das Screencasting auf Fernseher oder Computermonitore und eine kleine Oberfläche (hohe Auflösung) für die Aufnahme des Gerätedisplays.

Ab Android 12L (API-Level 32) skaliert das System beim Rendern von aufgenommenen Inhalten auf der Oberfläche die Inhalte einheitlich und behält das Seitenverhältnis bei, sodass beide Dimensionen des Inhalts (Breite und Höhe) kleiner oder gleich den entsprechenden Dimensionen der Oberfläche sind. Der erfasste Inhalt wird dann auf der Oberfläche zentriert.

Der Skalierungsansatz von Android 12L verbessert das Streamen auf Fernseher und andere große Displays, indem die Größe des Oberflächenbilds maximiert und gleichzeitig das richtige Seitenverhältnis beibehalten wird.

Berechtigung für Dienste im Vordergrund

Wenn Ihre App auf Android 14 oder höher ausgerichtet ist, muss das App-Manifest eine Erklärung zu Berechtigungen für den Diensttyp im Vordergrund mediaProjection enthalten:

<manifest ...>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
    <application ...>
        <service
            android:name=".MyMediaProjectionService"
            android:foregroundServiceType="mediaProjection"
            android:exported="false">
        </service>
    </application>
</manifest>

Starten Sie den Medienprojektionsdienst mit einem Aufruf von startForeground().

Wenn Sie den Typ des Diensts im Vordergrund im Aufruf nicht angeben, wird standardmäßig ein bitweiser Ganzzahlwert der im Manifest definierten Typen von Diensten im Vordergrund verwendet. Wenn im Manifest keine Diensttypen angegeben sind, gibt das System MissingForegroundServiceTypeException aus.

In Ihrer App muss vor jeder Medienprojektionssitzung die Nutzereinwilligung eingeholt werden. Eine Sitzung ist ein einzelner Aufruf von createVirtualDisplay(). Ein MediaProjection-Token darf nur einmal für den Aufruf verwendet werden.

Unter Android 14 oder höher löst die Methode createVirtualDisplay() eine SecurityException aus, wenn Ihre App eine der folgenden Aktionen ausführt:

  • Übergibt eine von createScreenCaptureIntent() zurückgegebene Intent-Instanz mehrmals an getMediaProjection()
  • Ruft createVirtualDisplay() mehr als einmal auf derselben MediaProjection-Instanz auf

Größe der Medienprojektion

Bei einer Medienprojektion kann das gesamte Gerätedisplay oder ein App-Fenster unabhängig vom Fenstermodus erfasst werden.

Anfangsgröße

Bei der Vollbild-Medienprojektion muss deine App die Größe des Gerätebildschirms ermitteln. Bei der App-Bildschirmfreigabe kann Ihre App die Größe des aufgenommenen Displays erst bestimmen, wenn der Nutzer den Aufnahmebereich ausgewählt hat. Die Anfangsgröße einer Medienprojektion ist also die Größe des Gerätebildschirms.

Verwende die Plattformmethode WindowManager getMaximumWindowMetrics(), um ein WindowMetrics-Objekt für den Gerätebildschirm zurückzugeben, auch wenn sich die Host-App für die Medienprojektion im Mehrfenstermodus befindet und nur einen Teil des Displays belegt.

Für die Kompatibilität bis API-Level 14 verwenden Sie die Methode WindowMetricsCalculator computeMaximumWindowMetrics() aus der Jetpack-Bibliothek WindowManager.

Rufen Sie die WindowMetrics-Methode getBounds() auf, um die Breite und Höhe des Gerätedisplays abzurufen.

Größenänderungen

Die Größe der Medienprojektion kann sich ändern, wenn das Gerät gedreht wird oder der Nutzer ein App-Fenster als Aufnahmebereich für die App-Bildschirmfreigabe auswählt. Die Medienprojektion kann im Letterbox-Format angezeigt werden, wenn die aufgenommenen Inhalte eine andere Größe haben als die maximalen Fenstergrößen, die bei der Einrichtung der Medienprojektion ermittelt wurden.

Damit die Medienprojektion genau der Größe des aufgenommenen Inhalts für jeden aufgenommenen Bereich und bei jeder Gerätedrehung entspricht, verwenden Sie den Callback onCapturedContentResize(), um die Größe der Aufnahme anzupassen. Weitere Informationen finden Sie im Abschnitt Anpassung unten.

Anpassung

In deiner App kannst du die Nutzererfahrung bei der Medienprojektion mit den folgenden MediaProjection.Callback-APIs anpassen:

  • onCapturedContentVisibilityChanged(): Ermöglicht der Host-App (der App, die die Medienprojektion gestartet hat), die geteilten Inhalte ein- oder auszublenden.

    Mit diesem Callback können Sie die Benutzeroberfläche Ihrer App anpassen, je nachdem, ob der aufgenommene Bereich für den Nutzer sichtbar ist. Wenn Ihre App beispielsweise für den Nutzer sichtbar ist und die aufgenommenen Inhalte in der Benutzeroberfläche der App anzeigt und die aufgenommene App ebenfalls für den Nutzer sichtbar ist (wie durch diesen Callback angegeben), sieht der Nutzer dieselben Inhalte zweimal. Verwenden Sie den Callback, um die Benutzeroberfläche Ihrer App zu aktualisieren, die aufgenommenen Inhalte auszublenden und Layoutplatz in Ihrer App für andere Inhalte freizugeben.

  • onCapturedContentResize(): Ermöglicht der Host-App, die Größe der Medienprojektion auf dem virtuellen Display und die Medienprojektion Surface basierend auf der Größe des erfassten Displaybereichs zu ändern.

    Wird ausgelöst, wenn sich die Größe des aufgenommenen Inhalts (ein einzelnes App-Fenster oder das gesamte Gerätedisplay) ändert, z. B. durch Drehen des Geräts oder wenn die aufgenommene App in einen anderen Fenstermodus wechselt. Verwenden Sie diese API, um die Größe des virtuellen Displays und der Oberfläche anzupassen, damit das Seitenverhältnis mit den aufgenommenen Inhalten übereinstimmt und die Aufnahme nicht im Letterbox-Format erfolgt.

Ressourcenrückgewinnung

Ihre App sollte den MediaProjection-Callback onStop() registrieren, um informiert zu werden, wenn die Medienprojektionssitzung beendet und ungültig wird. Wenn die Sitzung beendet wird, sollte deine App die von ihr verwendeten Ressourcen freigeben, z. B. das virtuelle Display und die Projektionsfläche. In einer beendeten Medienprojektionssitzung kann kein neues virtuelles Display mehr erstellt werden, auch wenn Ihre App zuvor kein virtuelles Display für diese Medienprojektion erstellt hat.

Das System ruft den Callback auf, wenn die Medienprojektion beendet wird. Diese Beendigung kann aus verschiedenen Gründen erfolgen, z. B.:

  • Der Nutzer beendet die Sitzung über die Benutzeroberfläche der App oder den Chip für die Medienprojektion in der Statusleiste des Systems.
  • der Bildschirm wird gesperrt
  • eine andere Medienprojektionssitzung gestartet wird
  • der App-Prozess beendet wird

Wenn Ihre App den Callback nicht registriert, wird bei jedem Aufruf von createVirtualDisplay() der Fehler IllegalStateException ausgegeben.

Deaktivieren

Unter Android 14 oder höher ist die App-Bildschirmfreigabe standardmäßig aktiviert. Bei jeder Medienprojektionssitzung können Nutzer ein App-Fenster oder das gesamte Display freigeben.

In Ihrer App können Sie die App-Bildschirmfreigabe deaktivieren, indem Sie die Methode createScreenCaptureIntent(MediaProjectionConfig) mit dem Argument MediaProjectionConfig aufrufen, das von einem Aufruf von createConfigForDefaultDisplay() zurückgegeben wird.

Ein Aufruf von createScreenCaptureIntent(MediaProjectionConfig) mit einem MediaProjectionConfig-Argument, das von einem Aufruf von createConfigForUserChoice() zurückgegeben wurde, entspricht dem Standardverhalten, d. h. einem Aufruf von createScreenCaptureIntent().

Apps mit anpassbarer Größe

Sorgen Sie dafür, dass die Größe Ihrer Medienprojektions-Apps immer angepasst werden kann (resizeableActivity="true"). Apps, deren Größe angepasst werden kann, unterstützen Änderungen der Gerätekonfiguration und den Mehrfenstermodus (siehe Unterstützung für mehrere Fenster).

Wenn die Größe deiner App nicht angepasst werden kann, muss sie die Anzeigegrenzen aus einem Fensterkontext abfragen und getMaximumWindowMetrics() verwenden, um die WindowMetrics des maximalen Anzeigebereichs abzurufen, der der App zur Verfügung steht :

val windowContext = context.createWindowContext(
    context.display,
    WindowManager.LayoutParams.TYPE_APPLICATION, null
)
val projectionMetrics = windowContext.getSystemService(WindowManager::class.java)
    .maximumWindowMetrics

Statusleisten-Chip und automatisches Beenden

Bei Ausnutzung von Bildschirmprojektion werden personenbezogene Nutzerdaten wie Finanzinformationen offengelegt, da Nutzer nicht wissen, dass ihr Gerätebildschirm geteilt wird.

Bei Apps, die auf Geräten mit Android 15 QPR1 oder höher ausgeführt werden, werden Nutzer über einen großen und gut sichtbaren Chip in der Statusleiste über eine laufende Bildschirmprojektion informiert. Nutzer können auf den Chip tippen, um zu verhindern, dass ihr Bildschirm geteilt, gestreamt oder aufgezeichnet wird. Außerdem wird die Bildschirmprojektion automatisch beendet, wenn das Display des Geräts gesperrt wird.

Abbildung 2. Chip in der Statusleiste für Bildschirmfreigabe, Streaming und Aufzeichnung.

Testen Sie die Verfügbarkeit des Chips für die Medienprojektion in der Statusleiste, indem Sie die Bildschirmfreigabe, das Streaming oder die Aufzeichnung starten. Der Chip sollte in der Statusleiste angezeigt werden.

Damit deine App Ressourcen freigibt und ihre Benutzeroberfläche aktualisiert, wenn die Bildschirmprojektion durch Nutzerinteraktion mit dem Statusleisten-Chip oder durch Aktivierung des Sperrbildschirms beendet wird, gehe so vor:

  • Erstellen Sie eine Instanz von MediaProjection.Callback.

  • Implementieren Sie die Callback-Methode onStop(). Die Methode wird aufgerufen, wenn die Bildschirmprojektion beendet wird. Geben Sie alle Ressourcen frei, die Ihre App belegt, und aktualisieren Sie die Benutzeroberfläche der App nach Bedarf.

Wenn du den Callback testen möchtest, tippe auf den Chip in der Statusleiste oder sperre den Bildschirm des Geräts, um die Bildschirmprojektion zu beenden. Prüfen Sie, ob die Methode onStop() aufgerufen wird und Ihre App wie vorgesehen reagiert.

Zusätzliche Ressourcen

Weitere Informationen zur Medienprojektion findest du unter Video- und Audiowiedergabe aufnehmen.