Added in API level 21

MediaProjection

class MediaProjection
kotlin.Any
   ↳ android.media.projection.MediaProjection

A token granting applications the ability to capture screen contents and/or record system audio. The exact capabilities granted depend on the type of MediaProjection.

A screen capture session can be started through android.media.projection.MediaProjectionManager#createScreenCaptureIntent. This grants the ability to capture screen contents, but not system audio.

Summary

Nested classes
abstract

Callbacks for the projection session.
Public methods
VirtualDisplay?
createVirtualDisplay(name: String, width: Int, height: Int, dpi: Int, flags: Int, surface: Surface?, callback: VirtualDisplay.Callback?, handler: Handler?)

Creates a android.hardware.display.VirtualDisplay to capture the contents of the screen.
Unit

Register a listener to receive notifications about when the MediaProjection or captured content changes state.
Unit

Stops projection.
Unit

Unregister a MediaProjection listener.

Public methods

createVirtualDisplay

Added in API level 21
fun createVirtualDisplay(
    name: String, 
    width: Int, 
    height: Int, 
    dpi: Int, 
    flags: Int, 
    surface: Surface?, 
    callback: VirtualDisplay.Callback?, 
    handler: Handler?
): VirtualDisplay?

Creates a android.hardware.display.VirtualDisplay to capture the contents of the screen.

To correctly clean up resources associated with a capture, the application must register a Callback before invocation. The app must override Callback.onStop() to clean up resources (by invokingVirtualDisplay.release(), Surface.release() and related resources) and to update any available UI regarding the MediaProjection status.

Parameters
name String: The name of the virtual display, must be non-empty. This value cannot be null.
width Int: The width of the virtual display in pixels. Must be greater than 0.
height Int: The height of the virtual display in pixels. Must be greater than 0.
dpi Int: The density of the virtual display in dpi. Must be greater than 0.
surface Surface?: The surface to which the content of the virtual display should be rendered, or null if there is none initially.
flags Int: A combination of virtual display flags. See DisplayManager for the full list of flags. Note that DisplayManager.VIRTUAL_DISPLAY_FLAG_PRESENTATION is always enabled. The following flags may be overridden, depending on how the component with {android.Manifest.permission.MANAGE_MEDIA_PROJECTION} handles the user's consent: android.hardware.display.DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY, android.hardware.display.DisplayManager#VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR, android.hardware.display.DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC. Value is either 0 or a combination of android.hardware.display.DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC, android.hardware.display.DisplayManager#VIRTUAL_DISPLAY_FLAG_PRESENTATION, android.hardware.display.DisplayManager#VIRTUAL_DISPLAY_FLAG_SECURE, android.hardware.display.DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY, android.hardware.display.DisplayManager#VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_CAN_SHOW_WITH_INSECURE_KEYGUARD, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_SUPPORTS_TOUCH, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_ROTATES_WITH_CONTENT, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_DESTROY_CONTENT_ON_REMOVAL, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_SHOULD_SHOW_SYSTEM_DECORATIONS, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_TRUSTED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_OWN_DISPLAY_GROUP, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_ALWAYS_UNLOCKED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_TOUCH_FEEDBACK_DISABLED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_OWN_FOCUS, and android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_STEAL_TOP_FOCUS_DISABLED
callback VirtualDisplay.Callback?: Callback invoked when the virtual display's state changes, or null.
handler Handler?: The android.os.Handler on which the callback should be invoked, or null if the callback should be invoked on the calling thread's main android.os.Looper.
Return
VirtualDisplay? The created VirtualDisplay, or null if no VirtualDisplay could be created.
Exceptions
java.lang.IllegalStateException If the target SDK is U and up, and if no Callback is registered.
java.lang.SecurityException In any of the following scenarios:
  1. If attempting to create a new virtual display associated with this MediaProjection instance after it has been stopped by invoking stop().
  2. If attempting to create a new virtual display associated with this MediaProjection instance after a MediaProjection.Callback.onStop() callback has been received due to the user or the system stopping the MediaProjection session.
  3. If the target SDK is U and up, and if this instance has already taken a recording through createVirtualDisplay, but stop() wasn't invoked to end the recording.
  4. If the target SDK is U and up, and if MediaProjectionManager.getMediaProjection was invoked more than once to get this MediaProjection instance.
In cases 2 & 3, no exception is thrown if the target SDK is less than U. Instead, recording doesn't begin until the user re-grants consent in the dialog.

registerCallback

Added in API level 21
fun registerCallback(
    callback: MediaProjection.Callback, 
    handler: Handler?
): Unit

Register a listener to receive notifications about when the MediaProjection or captured content changes state.

The callback must be registered before invoking createVirtualDisplay(java.lang.String,int,int,int,int,android.view.Surface,android.hardware.display.VirtualDisplay.Callback,android.os.Handler) to ensure that any notifications on the callback are not missed. The client must implement Callback.onStop() to properly handle MediaProjection clean up any resources it is holding, e.g. the VirtualDisplay and Surface. This should also update any application UI indicating the MediaProjection status as MediaProjection has stopped.

Parameters
callback MediaProjection.Callback: The callback to call. This value cannot be null.
handler Handler?: The handler on which the callback should be invoked, or null if the callback should be invoked on the calling thread's looper.
Exceptions
java.lang.NullPointerException If the given callback is null.

stop

Added in API level 21
fun stop(): Unit

Stops projection.

unregisterCallback

Added in API level 21
fun unregisterCallback(callback: MediaProjection.Callback): Unit

Unregister a MediaProjection listener.

Parameters
callback MediaProjection.Callback: The callback to unregister. This value cannot be null.
Exceptions
java.lang.NullPointerException If the given callback is null.