HDMIモード切り替え用のAPI

Amazon Fire TV（第2世代）は、4K UHD TVに接続されていても1080p@60fpsモードで動作します。4K UHDコンテンツを再生するには、接続先のTVを4K UHD表示モードに切り替える必要があります。このようなHDMI表示モードの切り替えはHDMIモード切り替えと呼ばれ、4K UHDコンテンツを再生するアプリによってトリガーされます。

• HDMIモード切り替え用のAPI
• HDMIモード切り替えを使用する手順
• 開発者向けインターフェイス
• Amazon 4K拡張ライブラリ
  • UHDHelperクラス
    • setPreferredDisplayModeId()
    • getSupportedModes()
    • getMode()
  • UhdHelperListenerクラス
  • Display.Modeクラス
• モード切り替え中のインタースティシャル

HDMIモード切り替え用のAPI

Googleは、Android Marshmallowで4K Display.Mode APIを導入しました。Display.Modeでは、アプリが実際のディスプレイサイズに関する問い合わせを行い、別のHDMI表示モードに切り替えることができます。Fire OS 6の場合、Android Nougatをベースとしているため、このDisplay.Mode APIをすぐに使用できます。

Fire OS 5（Display.Modeリリース前のLollipopがベース）搭載のFire TVデバイスについては、AmazonがDisplay.Mode APIを実装しました。そのため、Fire OS 5でも、アプリがこのDisplay.Mode APIを使用してHDMIモード切り替えを実行できます。

このAPIはAndroid APIレベル21（Lollipop）には含まれてないため、アプリがAPIにアクセスするには「リフレクション」を使用する必要があります。あるいは、Amazonが作成した4K拡張ライブラリを使用することもできます。このライブラリでは、リフレクションでラッピングしたAndroid APIをシンプルなインターフェイスで利用できます。

さらに、Amazon提供のオプションのインタースティシャルを表示して、HDMIモード切り替えをユーザーに知らせることもできます。このインタースティシャルは、Amazonの4K用拡張ライブラリの一部として配布されます。

Fire OSでは、接続先のディスプレイでサポートされている最大解像度を報告するsys.display-sizeシステムプロパティも利用できます。

HDMIモード切り替えを使用する手順

Android APIを使用してHDMIモード切り替えを開始する一般的な手順は、次のとおりです。

1. サポートされている表示モードをDisplay.getSupportedModes()で問い合わせます。

   Display.getSupportedModes()は、Display.Modeオブジェクトの配列を返します。この同期APIは、Fire TVデバイスと接続先のディスプレイの両方でサポートされているモード（解像度とフレームレート）を返します。接続先のディスプレイが4K UHD対応の場合、リストに4K UHDモードが表示されます。

   フレームレート変換では最適な結果を得られない可能性があるため、再生するコンテンツの実際のフレームレートやそれに近いフレームレート（4K@24fps、4K@25fps、4K@30fps）に切り替えることをお勧めします。

2. Display.getMode()を使用して、現在のディスプレイの解像度とフレームレートを取得します。

   Display.getMode()は、Display.Modeオブジェクト内の現在のディスプレイの解像度とリフレッシュレートを返します。

3. 表示モードをWindowManager.LayoutParams.preferredDisplayModeIdプロパティで設定します。

   アプリはWindowManager.LayoutParams.preferredDisplayModeIdプロパティを使用してモード切り替えを開始します。これにより、アプリがフルHD（1080p）で起動した後、ユーザーが4K UHDコンテンツの再生を開始したときに4K UHDへのモード切り替えを開始します。以下に注意してください。

   • 両方のアクティビティで同じモードが推奨されている場合、アクティビティ移行中にモード切り替えは開始されません。
   • システムと音声のオーバーレイではモード切り替えは開始されません。
   • アプリとアクティビティのいずれかが終了すると、表示はフルHD（1080p）解像度に戻ります。
   • Display.Modeクラスの定義はAndroid Marshmallowの定義と一致します。

4. モード切り替えのネゴシエーション完了時に通知を受け取ります。

   モード切り替えのネゴシエーション完了時に通知を受け取るには、onDisplayChanged(int displayId)メソッドを使用します。

   DisplayManager.DisplayListenerは、論理ディスプレイのプロパティが変更されるとコールバックを送信します。このコールバックは、モード変更の完了時に受信されます。コールバック受信後の数秒間、表示中のコンテンツが見えなくなる場合があります。

開発者向けインターフェイス

アプリは、リフレクションで直接これらのAPIを使用するか、Amazonが提供するラッパー（4K拡張ライブラリ）を使用してこれらのAPIにアクセスできます。次のコード例では、拡張ライブラリを使用せずモードを直接変更しています。

WindowManager.LayoutParams mWindowAttributes = mTargetWindow.getAttributes();
try {
  if (attributeFlagField == null) {
    Class < ? > cLayoutParams = mWindowAttributes.getClass();
    attributeFlagField = cLayoutParams.getDeclaredField(sPreferredDisplayModeIdFieldName);
  }

  //attempt mode switch
  attributeFlagField.setInt(mWindowAttributes, modeId);
  mTargetWindow.setAttributes(mWindowAttributes);
} catch (Exception e) {
  Log.e(TAG, e.getLocalizedMessage(), e);
}

4K拡張ライブラリを使用した方法については、次のセクションで説明します。

Amazon 4K拡張ライブラリ

Amazon Fire TV（第2世代）のHDMIモード切り替えAPIは、Android Lollipop SDKでは使用できません。このAPIを使用するには、リフレクションを使用する必要があります。4K拡張ライブラリ（ソースコード形式で提供）は、Android APIの使用方法を説明し、ヘルパークラスを提供することを目的にAmazonが作成したものです。 

Amazon 4K拡張ライブラリをダウンロード

拡張ライブラリZIPファイルのtestフォルダ内には、「DisplayModeCheckSample」というサンプルアプリがあります。 また、Javadocファイルも含まれています。このファイルは、[doc] > [javadoc] の順にフォルダを展開し、index.htmlファイルを開いて参照できます。

アプリを作成するには、Android Studioで [File] > [Open] の順にクリックし、DisplayModeCheckSampleプロジェクトを選択します。次に、[Run ‘app’] ボタンをクリックします。アプリを作成すると、次のような画面が表示されます。

モードを切り替えると、（Ultra HD TVに）インタースティシャルが表示され、アプリが4K Ultra HDモードに切り替わります。

Amazonの4K拡張ライブラリには、次のセクションに挙げているクラスが含まれています。また、「Amazonインタースティシャル」を表示するためのAPIも含まれています。これは、Amazonの4KデバイスでのHDMIモード切り替えをユーザーに知らせるためのものです。次の各セクションでは、これらのクラスについて説明します。

UHDHelperクラス

UHDHelpderはコンビニエンスクラスで、4K UHD機能とモード切り替え用のAPIをラップしています。次のパブリックメソッドが用意されています。

setPreferredDisplayModeId()

public void setPreferredDisplayModeId(Window targetWindow, int modeId, boolean allowOverlayDisplay)

このメソッドを使用すると、特定の表示モード（解像度とリフレッシュレート）をリクエストすることができます。表示がリクエストしたモードに設定されていない場合、このメソッドは、サポートされているデバイスでモード切り替えを開始します。UhdHelperListenerを使用すると、HDMIモード切り替えネゴシエーションの完了時にアプリに通知できます。

モード切り替えリクエストは失敗する可能性があります。失敗した場合はモードをUHDHelperListener#onModeChanged(Display.Mode mode)から確認するか、getMode()を呼び出すようにしてください。コンテンツの再生を開始する前に、モード切り替えが完了するまで待機する必要があります。

getSupportedModes()

public Display.Mode[] getSupportedModes()

接続先デバイスで使用可能なモードを判定します。

getMode()

public Display.Mode getMode()

現在設定されている表示モードを返します。このメソッドを使用して、モード切り替えが成功したかどうかを判断することもできます。モード切り替えの進行中は、getMode()の結果は未定義です。

UhdHelperListenerクラス

UhdHelperListenerクラスには、onModeChanged(Display.Mode mode)メソッドが用意されています。このメソッドを使用してHDMIモード切り替えネゴシエーションの完了をアプリに通知できます。また、モードの変更が成功した場合は、現在のモード（リクエストしたモードが想定されます）を提供します。

Display.Modeクラス

Display.Modeクラスは、Android MarshmallowのDisplay.Modeクラスに対応します。表示モードの解像度とリフレッシュレートを記述するために使用されます。

モード切り替え中のインタースティシャル

HDMIモード切り替え中はユーザーエクスペリエンスが中断されます。そのため、オプションで使用できるインタースティシャルが用意されています。これをHDMIモード切り替え時に表示して、切り替えを知らせることができます。このインタースティシャルをトリガーするコードは、4K用のAmazon拡張ライブラリにあります。

拡張ライブラリコードを使用してインタースティシャルを表示するには、前述のメソッドを呼び出します。

public voide setPreferredDisplayModeId(Window targetWindow, int modeId, boolean allowOverlayDisplay)

このとき、パラメーターのallowOverlayDisplayをtrueに設定してください。モード切り替えが開始される前に、オーバーレイが2秒間表示されます。

Last updated: 2020年10月29日