Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/android/media/projection/MediaProjection#nestedclasses) \| [Methods](https://developer.android.com/reference/android/media/projection/MediaProjection#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/media/projection/MediaProjection#inhmethods)

# MediaProjection

*** ** * ** ***

[Kotlin](https://developer.android.com/reference/kotlin/android/media/projection/MediaProjection "View this page in Kotlin") \|Java


`
public

final

class
MediaProjection
`


`

extends https://developer.android.com/reference/java/lang/Object


`

`


`

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.media.projection.MediaProjection |

<br />

*** ** * ** ***

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 `https://developer.android.com/reference/android/media/projection/MediaProjectionManager#createScreenCaptureIntent()`. This grants the ability to
capture screen contents, but not system audio.

## Summary

| ### Nested classes ||
|---|---|
| ` class` | `https://developer.android.com/reference/android/media/projection/MediaProjection.Callback` Callbacks for the projection session. |

| ### Public methods ||
|---|---|
| ` https://developer.android.com/reference/android/hardware/display/VirtualDisplay` | ` https://developer.android.com/reference/android/media/projection/MediaProjection#createVirtualDisplay(java.lang.String,%20int,%20int,%20int,%20int,%20android.view.Surface,%20android.hardware.display.VirtualDisplay.Callback,%20android.os.Handler)(https://developer.android.com/reference/java/lang/String name, int width, int height, int dpi, int flags, https://developer.android.com/reference/android/view/Surface surface, https://developer.android.com/reference/android/hardware/display/VirtualDisplay.Callback callback, https://developer.android.com/reference/android/os/Handler handler) ` Creates a `https://developer.android.com/reference/android/hardware/display/VirtualDisplay` to capture the contents of the screen. |
| ` void` | ` https://developer.android.com/reference/android/media/projection/MediaProjection#registerCallback(android.media.projection.MediaProjection.Callback,%20android.os.Handler)(https://developer.android.com/reference/android/media/projection/MediaProjection.Callback callback, https://developer.android.com/reference/android/os/Handler handler) ` Register a listener to receive notifications about when the `https://developer.android.com/reference/android/media/projection/MediaProjection` or captured content changes state. |
| ` void` | ` https://developer.android.com/reference/android/media/projection/MediaProjection#stop()() ` Stops projection. |
| ` void` | ` https://developer.android.com/reference/android/media/projection/MediaProjection#unregisterCallback(android.media.projection.MediaProjection.Callback)(https://developer.android.com/reference/android/media/projection/MediaProjection.Callback callback) ` Unregister a `https://developer.android.com/reference/android/media/projection/MediaProjection` listener. |

| ### Inherited methods |
|---|---|
| From class ` https://developer.android.com/reference/java/lang/Object ` |---|---| | ` https://developer.android.com/reference/java/lang/Object` | ` https://developer.android.com/reference/java/lang/Object#clone()() ` Creates and returns a copy of this object. | | ` boolean` | ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` https://developer.android.com/reference/java/lang/Object#finalize()() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final https://developer.android.com/reference/java/lang/Class<?>` | ` https://developer.android.com/reference/java/lang/Object#getClass()() ` Returns the runtime class of this `Object`. | | ` int` | ` https://developer.android.com/reference/java/lang/Object#hashCode()() ` Returns a hash code value for the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notify()() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notifyAll()() ` Wakes up all threads that are waiting on this object's monitor. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/Object#toString()() ` Returns a string representation of the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait()() ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*. | ||

## Public methods

### createVirtualDisplay

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

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

Creates a `https://developer.android.com/reference/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
`https://developer.android.com/reference/android/media/projection/MediaProjection.Callback` before invocation. The app must override `https://developer.android.com/reference/android/media/projection/MediaProjection.Callback#onStop()` to clean up
resources (by invoking`https://developer.android.com/reference/android/hardware/display/VirtualDisplay#release()`, `https://developer.android.com/reference/android/view/Surface#release()` and related
resources) and to update any available UI regarding the MediaProjection status.

<br />

| Parameters ||
|---|---|
| `name` | `String`: The name of the virtual display, must be non-empty. This value cannot be `null`. <br /> |
| `width` | `int`: The width of the virtual display in pixels. Must be greater than 0. <br /> |
| `height` | `int`: The height of the virtual display in pixels. Must be greater than 0. <br /> |
| `dpi` | `int`: The density of the virtual display in dpi. Must be greater than 0. <br /> |
| `flags` | `int`: A combination of virtual display flags. See `https://developer.android.com/reference/android/hardware/display/DisplayManager` for the full list of flags. Note that `https://developer.android.com/reference/android/hardware/display/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: `https://developer.android.com/reference/android/hardware/display/DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY`, `https://developer.android.com/reference/android/hardware/display/DisplayManager#VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR`, `https://developer.android.com/reference/android/hardware/display/DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC`. Value is either `0` or a combination of the following: - `https://developer.android.com/reference/android/hardware/display/DisplayManager#VIRTUAL_DISPLAY_FLAG_PUBLIC` - `https://developer.android.com/reference/android/hardware/display/DisplayManager#VIRTUAL_DISPLAY_FLAG_PRESENTATION` - `https://developer.android.com/reference/android/hardware/display/DisplayManager#VIRTUAL_DISPLAY_FLAG_SECURE` - `https://developer.android.com/reference/android/hardware/display/DisplayManager#VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY` - `https://developer.android.com/reference/android/hardware/display/DisplayManager#VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR` |
| `surface` | `Surface`: The surface to which the content of the virtual display should be rendered, or null if there is none initially. <br /> |
| `callback` | `VirtualDisplay.Callback`: Callback invoked when the virtual display's state changes, or null. <br /> |
| `handler` | `Handler`: The `https://developer.android.com/reference/android/os/Handler` on which the callback should be invoked, or null if the callback should be invoked on the calling thread's main `https://developer.android.com/reference/android/os/Looper`. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/hardware/display/VirtualDisplay` | The created `https://developer.android.com/reference/android/hardware/display/VirtualDisplay`, or `null` if no `https://developer.android.com/reference/android/hardware/display/VirtualDisplay` could be created. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | If the target SDK is `https://developer.android.com/reference/android/os/Build.VERSION_CODES#UPSIDE_DOWN_CAKE` and up, and if no `https://developer.android.com/reference/android/media/projection/MediaProjection.Callback` is registered. |
| `https://developer.android.com/reference/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 `https://developer.android.com/reference/android/media/projection/MediaProjection#stop()`. 2. If attempting to create a new virtual display associated with this MediaProjection instance after a `https://developer.android.com/reference/android/media/projection/MediaProjection.Callback#onStop()` callback has been received due to the user or the system stopping the MediaProjection session. 3. If the target SDK is `https://developer.android.com/reference/android/os/Build.VERSION_CODES#UPSIDE_DOWN_CAKE` and up, and if this instance has already taken a recording through `#createVirtualDisplay`, but `https://developer.android.com/reference/android/media/projection/MediaProjection#stop()` wasn't invoked to end the recording. 4. If the target SDK is `https://developer.android.com/reference/android/os/Build.VERSION_CODES#UPSIDE_DOWN_CAKE` and up, and if `https://developer.android.com/reference/android/media/projection/MediaProjectionManager#getMediaProjection(int,%20android.content.Intent)` 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 `https://developer.android.com/reference/android/os/Build.VERSION_CODES#UPSIDE_DOWN_CAKE`. Instead, recording doesn't begin until the user re-grants consent in the dialog. |

**See also:**

- `https://developer.android.com/reference/android/hardware/display/VirtualDisplay`
- `https://developer.android.com/reference/android/hardware/display/VirtualDisplay.Callback`

### registerCallback

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public void registerCallback (MediaProjection.Callback callback, 
                Handler handler)
```

Register a listener to receive notifications about when the `https://developer.android.com/reference/android/media/projection/MediaProjection` or
captured content changes state.

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

<br />

| Parameters ||
|---|---|
| `callback` | `MediaProjection.Callback`: The callback to call. This value cannot be `null`. <br /> |
| `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. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | If the given callback is null. |

**See also:**

- `https://developer.android.com/reference/android/media/projection/MediaProjection#unregisterCallback(android.media.projection.MediaProjection.Callback)`

### stop

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public void stop ()
```

Stops projection.

<br />

### unregisterCallback

Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public void unregisterCallback (MediaProjection.Callback callback)
```

Unregister a `https://developer.android.com/reference/android/media/projection/MediaProjection` listener.

<br />

| Parameters ||
|---|---|
| `callback` | `MediaProjection.Callback`: The callback to unregister. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | If the given callback is null. |

**See also:**

- `https://developer.android.com/reference/android/media/projection/MediaProjection#registerCallback(android.media.projection.MediaProjection.Callback,%20android.os.Handler)`