MediaProjection

public final class MediaProjection
extends Object

java.lang.Object
   ↳ 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 MediaProjectionManager.createScreenCaptureIntent(). This grants the ability to capture screen contents, but not system audio.

Summary

Nested classes

class MediaProjection.Callback

Callbacks for the projection session. 

Public methods

VirtualDisplay createVirtualDisplay(String name, int width, int height, int dpi, int flags, Surface surface, VirtualDisplay.Callback callback, Handler handler)

Creates a VirtualDisplay to capture the contents of the screen.

void registerCallback(MediaProjection.Callback callback, Handler handler)

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

void stop()

Stops projection.

void unregisterCallback(MediaProjection.Callback callback)

Unregister a MediaProjection listener.

Inherited methods

Public methods

createVirtualDisplay

Added in API level 21 
public VirtualDisplay createVirtualDisplay (String name, 
                int width, 
                int height, 
                int dpi, 
                int flags, 
                Surface surface, 
                VirtualDisplay.Callback callback, 
                Handler handler)

Creates a 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.
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: DisplayManager.VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY, DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR, DisplayManager.VIRTUAL_DISPLAY_FLAG_PUBLIC. Value is either 0 or a combination of DisplayManager.VIRTUAL_DISPLAY_FLAG_PUBLIC, DisplayManager.VIRTUAL_DISPLAY_FLAG_PRESENTATION, DisplayManager.VIRTUAL_DISPLAY_FLAG_SECURE, DisplayManager.VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY, 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
surface Surface: The surface to which the content of the virtual display should be rendered, or null if there is none initially.
callback VirtualDisplay.Callback: Callback invoked when the virtual display's state changes, or 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 main Looper.
Returns
VirtualDisplay The created VirtualDisplay, or null if no VirtualDisplay could be created.
Throws
IllegalStateException If the target SDK is U and up, and if no Callback is registered.
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 
public void registerCallback (MediaProjection.Callback callback, 
                Handler handler)

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.
Throws
NullPointerException If the given callback is null.

stop

Added in API level 21 
public void stop ()

Stops projection.

unregisterCallback

Added in API level 21 
public void unregisterCallback (MediaProjection.Callback callback)

Unregister a MediaProjection listener.

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