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

Android 5(API レベル 21)で導入された android.media.projection API を使用すると、デバイス ディスプレイのコンテンツをメディア ストリームとしてキャプチャし、テレビなどの他のデバイスで再生、録画、キャストできます。

Android 14(API レベル 34)では、アプリの画面共有が導入されています。これにより、ユーザーはウィンドウ モードに関係なく、デバイス画面全体ではなく、単一のアプリ ウィンドウを共有できます。アプリの画面共有では、ステータスバー、ナビゲーション バー、通知、その他のシステム UI 要素が共有ディスプレイから除外されます。これは、アプリの画面共有を使用してアプリを全画面でキャプチャする場合でも同様です。選択したアプリのコンテンツのみが共有されます。

アプリの画面共有は、ユーザーのプライバシーを保護し、ユーザーの生産性を高め、マルチタスクを強化します。ユーザーは複数のアプリを実行できますが、コンテンツの共有は 1 つのアプリに制限されます。

3 つのディスプレイ表現

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

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

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

実際のディスプレイ

メディア プロジェクション セッションを開始するには、デバイスのディスプレイまたはアプリ ウィンドウのコンテンツをキャプチャする権限をアプリに付与するトークンを取得します。トークンは、MediaProjection クラスのインスタンスで表されます。

新しいアクティビティを開始するときに、MediaProjectionManager システム サービスの getMediaProjection() メソッドを使用して MediaProjection インスタンスを作成します。createScreenCaptureIntent() メソッドのインテントを使用してアクティビティを開始し、画面キャプチャ オペレーションを指定します。

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

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

startMediaProjection.launch(mediaProjectionManager.createScreenCaptureIntent())

仮想ディスプレイ

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

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

width および height パラメータは、仮想ディスプレイのサイズを指定します。幅と高さの値を取得するには、Android 11(API レベル 30)で導入された WindowMetrics API を使用します。(詳しくは、メディア プロジェクションのサイズのセクションをご覧ください)。

Surface

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

Android 12L(API レベル 32)以降では、キャプチャしたコンテンツをサーフェスにレンダリングする際に、コンテンツの両方の寸法(幅と高さ)がサーフェスの対応する寸法以下になるように、アスペクト比を維持しながらコンテンツを均等にスケーリングします。キャプチャされたコンテンツは、サーフェスの中央に配置されます。

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

フォアグラウンド サービスの権限

Android 14 以降をターゲットとするアプリの場合、アプリ マニフェストに mediaProjection フォアグラウンド サービス タイプの権限の申告を含める必要があります。

<manifest ...>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
    <application ...>
        <service
            android:name=".MyMediaProjectionService"
            android:foregroundServiceType="mediaProjection"
            android:exported="false">
        </service>
    </application>
</manifest>

startForeground() を呼び出して、メディア プロジェクション サービスを開始します。

呼び出しでフォアグラウンド サービス タイプを指定しない場合、タイプはデフォルトで、マニフェストで定義されたフォアグラウンド サービス タイプのビット単位の整数になります。マニフェストでサービスタイプが指定されていない場合、システムは MissingForegroundServiceTypeException をスローします。

アプリは、メディア プロジェクション セッションごとにユーザーの同意をリクエストする必要があります。セッションは createVirtualDisplay() への 1 回の呼び出しです。MediaProjection トークンは、呼び出しを行うために 1 回だけ使用する必要があります。

Android 14 以降では、アプリが次のいずれかを行うと、createVirtualDisplay() メソッドは SecurityException をスローします。

  • createScreenCaptureIntent() から返された Intent インスタンスを getMediaProjection() に複数回渡す
  • 同じ MediaProjection インスタンスで createVirtualDisplay() を複数回呼び出す

メディア プロジェクションのサイズ

メディア プロジェクションは、ウィンドウ モードに関係なく、デバイスのディスプレイ全体またはアプリ ウィンドウをキャプチャできます。

初期サイズ

全画面メディア プロジェクションでは、アプリはデバイス画面のサイズを判断する必要があります。アプリの画面共有では、ユーザーがキャプチャ領域を選択するまで、アプリはキャプチャされたディスプレイのサイズを特定できません。そのため、メディア プロジェクションの初期サイズはデバイスの画面サイズになります。

プラットフォーム WindowManager の getMaximumWindowMetrics() メソッドを使用して、デバイス画面の WindowMetrics オブジェクトを返します。メディア プロジェクション ホストアプリがマルチ ウィンドウ モードで実行されていてディスプレイの一部だけを占有している場合でも、このメソッドを使用します。

API レベル 14 までの互換性を確保するには、Jetpack WindowManager ライブラリの WindowMetricsCalculator computeMaximumWindowMetrics() メソッドを使用します。

WindowMetrics getBounds() メソッドを呼び出して、デバイス ディスプレイの幅と高さを取得します。

サイズの変更

メディア プロジェクションのサイズは、デバイスが回転されたときや、ユーザーがアプリの画面共有でキャプチャ領域としてアプリ ウィンドウを選択したときに変更されることがあります。キャプチャされたコンテンツのサイズが、メディア プロジェクションの設定時に取得された最大ウィンドウ指標と異なる場合、メディア プロジェクションはレターボックス表示されることがあります。

キャプチャされた領域やデバイスの回転に関係なく、メディア プロジェクションがキャプチャされたコンテンツのサイズと正確に一致するようにするには、onCapturedContentResize() コールバックを使用してキャプチャのサイズを変更します。(詳しくは、後述のカスタマイズ セクションをご覧ください)。

カスタマイズ

アプリは、次の MediaProjection.Callback API を使用して、メディア プロジェクションのユーザー エクスペリエンスをカスタマイズできます。

  • onCapturedContentVisibilityChanged(): ホストアプリ(メディア プロジェクションを開始した アプリ)が共有コンテンツを表示または非表示にできるようにします。

    このコールバックを使用すると、キャプチャされた領域がユーザーに表示されているかどうかに基づいて、アプリの UI をカスタマイズできます。たとえば、アプリがユーザーに表示され、キャプチャされたコンテンツがアプリの UI 内に表示され、キャプチャされたアプリもユーザーに表示される場合(このコールバックで示されるように)、ユーザーには同じコンテンツが 2 回表示されます。コールバックを使用してアプリの UI を更新し、キャプチャされたコンテンツを非表示にして、アプリのレイアウト スペースを他のコンテンツ用に解放します。

  • onCapturedContentResize(): ホストアプリが、キャプチャされたディスプレイ領域のサイズに基づいて、仮想ディスプレイとメディア プロジェクション Surface のメディア プロジェクションのサイズを変更できるようにします。

    キャプチャされたコンテンツ(単一のアプリ ウィンドウまたはデバイスのディスプレイ全体)のサイズが変更されるたびにトリガーされます(デバイスの回転や、キャプチャされたアプリが別のウィンドウ モードに移行したことが原因)。この API を使用して、仮想ディスプレイとサーフェスの両方のサイズを変更し、アスペクト比がキャプチャされたコンテンツと一致し、キャプチャがレターボックス化されないようにします。

リソースの回収

アプリは、MediaProjection onStop() コールバックを登録して、メディア プロジェクション セッションが停止して無効になったときに通知を受け取る必要があります。セッションが停止すると、アプリは保持しているリソース(仮想ディスプレイや投影サーフェスなど)を解放する必要があります。停止したメディア プロジェクション セッションでは、アプリがそのメディア プロジェクションの仮想ディスプレイを以前に作成していない場合でも、新しい仮想ディスプレイを作成できなくなります。

メディア プロジェクションが終了すると、システムはコールバックを呼び出します。この終了は、次のような理由で発生する可能性があります。

アプリがコールバックを登録しない場合、createVirtualDisplay() を呼び出すと IllegalStateException がスローされます。

オプトアウト

Android 14 以降では、アプリの画面共有がデフォルトで有効になっています。各メディア プロジェクション セッションでは、アプリ ウィンドウまたはディスプレイ全体を共有するオプションがユーザーに提供されます。

アプリは、createConfigForDefaultDisplay() の呼び出しから返された MediaProjectionConfig 引数を指定して createScreenCaptureIntent(MediaProjectionConfig) メソッドを呼び出すことで、アプリの画面共有をオプトアウトできます。

createConfigForUserChoice() の呼び出しから返された MediaProjectionConfig 引数を使用して createScreenCaptureIntent(MediaProjectionConfig) を呼び出すことは、デフォルトの動作(createScreenCaptureIntent() の呼び出し)と同じです。

サイズ変更可能なアプリ

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

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

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

ステータスバーのチップと自動停止

画面投影の悪用は、デバイスの画面が共有されていることにユーザーが気付かないため、金融情報などの機密データが漏洩する可能性があります。

Android 15 QPR1 以降を搭載したデバイスで実行されているアプリの場合、進行中の画面投影をユーザーに知らせるために、ステータスバーに大きく目立つチップが表示されます。ユーザーはチップをタップして、画面の共有、キャスト、録画を停止できます。また、デバイスの画面がロックされると、画面投影は自動的に停止します。

図 2. 画面共有、キャスト、録画用のステータスバー チップ。

画面共有、キャスト、録画を開始して、メディア プロジェクション ステータスバー チップが利用可能かどうかをテストします。ステータスバーにチップが表示されます。

ステータスバー チップのユーザー操作またはロック画面の有効化によって画面の投影が停止されたときに、アプリがリソースを解放して UI を更新するようにするには、次の操作を行います。

  • MediaProjection.Callback のインスタンスを作成します。

  • コールバック onStop() メソッドを実装します。このメソッドは、画面の投影が停止したときに呼び出されます。アプリが保持しているリソースを解放し、必要に応じてアプリの UI を更新します。

コールバックをテストするには、ステータスバーのチップをタップするか、デバイスの画面をロックして、画面の投影を停止します。onStop() メソッドが呼び出され、アプリが意図したとおりに応答することを確認します。

参考情報

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