Added in API level 21

MediaProjectionManager


public final class MediaProjectionManager
extends Object

java.lang.Object
   ↳ android.media.projection.MediaProjectionManager


Manages the retrieval of certain types of MediaProjection tokens.

    An example flow of starting a media projection will be:
  1. Declare a foreground service with the type mediaProjection in the AndroidManifest.xml.
  2. Create an intent by calling MediaProjectionManager#createScreenCaptureIntent() and pass this intent to Activity#startActivityForResult(Intent, int).
  3. On getting Activity#onActivityResult(int, int, Intent), start the foreground service with the type ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION.
  4. Retrieve the media projection token by calling MediaProjectionManager#getMediaProjection(int, Intent) with the result code and intent from the Activity#onActivityResult(int, int, Intent) above.
  5. Start the screen capture session for media projection by calling MediaProjection#createVirtualDisplay(String, int, int, int, int, Surface, android.hardware.display.VirtualDisplay.Callback, Handler).

Summary

Public methods

Intent createScreenCaptureIntent()

Returns an Intent that must be passed to Activity#startActivityForResult(Intent, int) (or similar) in order to start screen capture.

Intent createScreenCaptureIntent(MediaProjectionConfig config)

Returns an Intent that must be passed to Activity#startActivityForResult(Intent, int) (or similar) in order to start screen capture.

MediaProjection getMediaProjection(int resultCode, Intent resultData)

Retrieves the MediaProjection obtained from a successful screen capture request.

Inherited methods

Public methods

createScreenCaptureIntent

Added in API level 21
public Intent createScreenCaptureIntent ()

Returns an Intent that must be passed to Activity#startActivityForResult(Intent, int) (or similar) in order to start screen capture. The activity will prompt the user whether to allow screen capture. The result of this activity (received by overriding onActivityResult(int, int, Intent)) should be passed to getMediaProjection(int, android.content.Intent).

Identical to calling createScreenCaptureIntent(android.media.projection.MediaProjectionConfig) with a MediaProjectionConfig#createConfigForUserChoice().

Should be used instead of createScreenCaptureIntent(android.media.projection.MediaProjectionConfig) when the calling app does not want to customize the activity shown to the user.

Returns
Intent This value cannot be null.

createScreenCaptureIntent

Added in API level 34
public Intent createScreenCaptureIntent (MediaProjectionConfig config)

Returns an Intent that must be passed to Activity#startActivityForResult(Intent, int) (or similar) in order to start screen capture. Customizes the activity and resulting MediaProjection session based up the provided config. The activity will prompt the user whether to allow screen capture. The result of this activity (received by overriding onActivityResult(int, int, Intent)) should be passed to getMediaProjection(int, android.content.Intent).

If MediaProjectionConfig was created from:

Should be used instead of createScreenCaptureIntent() when the calling app wants to customize the activity shown to the user.

Parameters
config MediaProjectionConfig: Customization for the MediaProjection that this Intent requests the user's consent for. This value cannot be null.

Returns
Intent An Intent requesting the user's consent, specialized based upon the given configuration. This value cannot be null.

getMediaProjection

Added in API level 21
public MediaProjection getMediaProjection (int resultCode, 
                Intent resultData)

Retrieves the MediaProjection obtained from a successful screen capture request. The result code and data from the request are provided by overriding onActivityResult(int, int, Intent), which is called after starting an activity using createScreenCaptureIntent().

Starting from Android R, if your application requests the SYSTEM_ALERT_WINDOW permission, and the user has not explicitly denied it, the permission will be automatically granted until the projection is stopped. The permission allows your app to display user controls on top of the screen being captured.

An app targeting SDK version Q or later must invoke getMediaProjection and maintain the capture session (MediaProjection#createVirtualDisplay) while running a foreground service. The app must set the foregroundServiceType attribute to FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION in the <service> element of the app's manifest file.

For an app targeting SDK version U or later, the user must have granted the app with the permission to start a projection, before the app starts a foreground service with the type ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION. Additionally, the app must have started the foreground service with that type before calling this API here, or else it'll receive a SecurityException from this API call, unless it's a privileged app. Apps can request the permission via the createScreenCaptureIntent() and Activity#startActivityForResult(Intent, int) (or similar APIs).

Parameters
resultCode int: The result code from onActivityResult(int, int, Intent).

resultData Intent: The result data from onActivityResult(int, int, Intent). This value cannot be null.

Returns
MediaProjection The media projection obtained from a successful screen capture request, or null if the result of the screen capture request is not RESULT_OK.

Throws
IllegalStateException On pre-Q devices if a previously obtained MediaProjection from the same resultData has not yet been stopped.
SecurityException On Q+ devices if not invoked from a foreground service with type FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION, unless caller is a privileged app.