開発者コンソール

HDMIモード切り替え用のAPI

HDMIモード切り替え用のAPI

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

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が作成したものです。 

拡張ライブラリ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モード切り替えネゴシエーションの完了時にアプリに通知できます。

パラメーター 説明
targetWindow 表示パラメーターと呼び出しパラメーターを設定するために使用するウィンドウ。
modeId 切り替え後のモード。プラットフォームで使用可能なモードにしてください。
allowOverlayDisplay 対応デバイスで表示オーバーレイを許可するフラグリクエスト。

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

getSupportedModes()

public Display.Mode[] getSupportedModes()

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

戻り値
Modeオブジェクトの配列。エラーが発生した場合はNULL。

getMode()

public Display.Mode getMode()

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

戻り値
システムに現在設定されているモード。エラーが発生した場合はNULL。

UhdHelperListenerクラス

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

パラメーター 説明
mode 切り替え先のモードが含まれるModeオブジェクト。モード変更中にタイムアウトや内部エラーが発生した場合はNULL。

Display.Modeクラス

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

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

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

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

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

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