大画面でのメディアプロジェクション

Android 5（API レベル 21）で導入されたメディアプロジェクション API を使用すると、デバイスディスプレイのコンテンツをメディアストリームとしてキャプチャし、テレビなどの他のデバイスで再生、録画、キャストできます。

メディアプロジェクションは、デバイスディスプレイにおける次の 3 つの表現に対応しています。

仮想ディスプレイに実際のデバイスディスプレイを投影する。仮想ディスプレイのコンテンツをアプリが提供する「サーフェス」に書き込む。 — **図 1.** 仮想ディスプレイに実際のデバイスディスプレイを投影する。仮想ディスプレイのコンテンツをアプリが提供する `Surface` に書き込む。

メディアプロジェクションでは、デバイスディスプレイのコンテンツをキャプチャし、キャプチャした画像を仮想ディスプレイに投影して、Surface にレンダリングします。

アプリは、キャプチャされたディスプレイのコンテンツを使用する SurfaceView または ImageReader によって Surface を提供します。ImageReader の OnImageAvailableListener を使用すると、Surface でレンダリングされる画像をリアルタイムで管理できます。録画として画像を保存したり、テレビなどのデバイスにキャストしたりできます。

メディアプロジェクション

メディアプロジェクションセッションを開始するには、ディスプレイのコンテンツ、デバイスオーディオ、またはその両方をキャプチャする権限をアプリに付与するトークンを取得します。トークンは、MediaProjection クラスのインスタンスで表されます。このクラスのインスタンスは、新しいアクティビティの開始時に作成できます。

以前の方法

以前の方法でメディアプロジェクショントークンを取得するには、MediaProjectionManager システムサービスの createScreenCaptureIntent() メソッドによって返されたインテントを使用して、startActivityForResult() を呼び出します。

Kotlin

startActivityForResult(mediaProjectionManager.createScreenCaptureIntent(),
                       REQUEST_MEDIA_PROJECTION)

Java

startActivityForResult(mediaProjectionManager.createScreenCaptureIntent(),
                       REQUEST_MEDIA_PROJECTION);

この呼び出しによって、表示されたすべての情報（機密情報や個人を特定できる情報を含む）がメディアプロジェクションによってキャプチャされたことをユーザーに通知する、確認ダイアログボックスが表示されます。

ユーザーが確認すると、startActivityForResult() が onActivityResult() コールバックに結果コードとデータを渡します。

次に MediaProjectionManager から getMediaProjection() メソッドにデータと結果コードを渡して、MediaProjection のインスタンスを作成できます。

Kotlin

mediaProjection = mediaProjectionManager.getMediaProjection(resultCode, resultData)

Java

mediaProjection = mediaProjectionManager.getMediaProjection(resultCode, resultData);

推奨の方法

メディアプロジェクショントークンを取得する推奨の方法では、Jetpack Activity ライブラリの API を使用します。

Kotlin

val mediaProjectionManager = getSystemService(MediaProjectionManager::class.java)
var mediaProjection : MediaProjection

val startMediaProjection = registerForActivityResult(
  StartActivityForResult()
) { result ->
  if (result.resultCode == RESULT_OK) {
    mediaProjection = mediaProjectionManager
      .getMediaProjection(result.resultCode, result.data!!)
  }
}

startMediaProjection.launch(mediaProjectionManager.createScreenCaptureIntent())

Java

final MediaProjectionManager mediaProjectionManager =
  getSystemService(MediaProjectionManager.class);
final MediaProjection[] mediaProjection = new MediaProjection[1];

ActivityResultLauncher<Intent> startMediaProjection = registerForActivityResult(
  new StartActivityForResult(),
  result -> {
    if (result.getResultCode() == Activity.RESULT_OK) {
      mediaProjection[0] = mediaProjectionManager
        .getMediaProjection(result.getResultCode(), result.getData());
    }
  }
);

仮想ディスプレイ

メディアプロジェクションの中心となるのは仮想ディスプレイです。仮想ディスプレイは、MediaProjection インスタンスで createVirtualDisplay() を呼び出して作成します。

Kotlin

virtualDisplay = mediaProjection.createVirtualDisplay(
                     "ScreenCapture",
                     width,
                     height,
                     screenDensity,
                     DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
                     surface,
                     null, null)

Java

virtualDisplay = mediaProjection.createVirtualDisplay(
                     "ScreenCapture",
                     width,
                     height,
                     screenDensity,
                     DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
                     surface,
                     null, null);

width および height パラメータは、仮想ディスプレイの幅と高さを指定します。メディアプロジェクションの幅と高さに一致する値を取得するには、Android 11（API レベル 30）で導入された WindowMetrics API を使用します。

WindowMetrics

メディアプロジェクションを作成するアプリが全画面モードとマルチウィンドウモードのどちらで実行されているかにかかわらず、メディアプロジェクションはディスプレイ全体をキャプチャします。

メディアプロジェクションの寸法を取得するには、WindowManager#getMaximumWindowMetrics() を使用します。このメソッドは、メディアプロジェクションアプリがマルチウィンドウモードで実行されていてディスプレイの一部だけを占有している場合であっても、ディスプレイ全体を表す WindowMetrics オブジェクトを返します。

API レベル 14 までの互換性をさかのぼって確保するには、Jetpack WindowManager ライブラリの WindowMetricsCalculator#computeMaximumWindowMetrics() を使用します。

メディアプロジェクションの仮想ディスプレイの正しい幅と高さを取得するには、WindowMetrics#getBounds() を呼び出します（仮想ディスプレイを参照）。

メディアプロジェクションアプリは、必ずサイズ変更可能にしてください。サイズ変更が可能なアプリは、デバイス設定の変更とマルチウィンドウモードをサポートします（マルチウィンドウのサポートをご覧ください）。

アプリがサイズ変更不可の場合は、ウィンドウコンテキストから表示境界をクエリし、WindowManager#getMaximumWindowMetrics() を使用して、アプリで利用可能な最大表示領域の WindowMetrics を取得する必要があります。

Kotlin

val windowContext = context.createWindowContext(context.display!!,
      WindowManager.LayoutParams.TYPE_APPLICATION, null)
val projectionMetrics = windowContext.getSystemService(WindowManager::class.java)
      .maximumWindowMetrics

Java

Context windowContext = context.createWindowContext(context.getDisplay(),
      WindowManager.LayoutParams.TYPE_APPLICATION, null);
WindowMetrics projectionMetrics = windowContext.getSystemService(WindowManager.class)
      .getMaximumWindowMetrics();

Surface

必要な解像度で出力を生成するには、メディアプロジェクションサーフェスのサイズを調整する必要があります。テレビやパソコンのモニターに画面をキャストする場合は大きいサイズ（低解像度）に、デバイスのディスプレイを録画する場合は小さいサイズ（高解像度）にします。

12L（API レベル 32）以降では、サーフェスで仮想ディスプレイをレンダリングする際に、ImageView の centerInside オプションと同様のプロセスを使用して、仮想ディスプレイがサーフェスに合わせてスケーリングされます。

この新しいスケーリング方法により、適切なアスペクト比を維持しながら、サーフェス画像のサイズを最大化することで、テレビや他の大型ディスプレイに画面をキャストしやすくなります。

参考情報

メディアプロジェクションの詳細については、動画と音声の再生のキャプチャをご覧ください。

大画面でのメディア プロジェクション

メディア プロジェクション

以前の方法

Kotlin

Java

Kotlin

Java

推奨の方法

Kotlin

Java

仮想ディスプレイ

Kotlin

Java

WindowMetrics

Kotlin

Java

Surface

おすすめ

参考情報

大画面でのメディアプロジェクション

メディアプロジェクション