MediaProjection

Kotlin |Java

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	`Callback` 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	`registerCallback(callback: MediaProjection.Callback, handler: Handler?)` Register a listener to receive notifications about when the `MediaProjection` or captured content changes state.
Unit	`stop()` Stops projection.
Unit	`unregisterCallback(callback: MediaProjection.Callback)` 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 (by invokingVirtualDisplay#release(), Surface#release() and related resources).

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: `DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY`, `DisplayManager#VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR`, `DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC`.
`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`.

Exceptions

java.lang.IllegalStateException If the target SDK is U and up, and if no Callback is registered.

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: If attempting to create a new virtual display associated with this MediaProjection instance after it has been stopped by invoking `stop()`. 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. 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.

java.lang.SecurityException

In any of the following scenarios:

If attempting to create a new virtual display associated with this MediaProjection instance after it has been stopped by invoking stop().
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.
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.

See Also

registerCallback

Added in API level 21

fun registerCallback(
    callback: MediaProjection.Callback, 
    handler: Handler?
): Unit

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() and clean up any resources it is holding, e.g. the VirtualDisplay and Surface.

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.

See Also

#unregisterCallback

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.

See Also

#registerCallback