【Unity】Androidのハードウェア音量操作・ハードウェアキーの無効化をする

2017/12/04 Mon [edit]

　これは音量操作のプラグインのアップデート版となる。以前の記事にはプラグインの内部的なコード（Java）や仕様説明を書いたので、今回は Unity 側のコードやプレファブの使い方などを中心に書いておこう。プラグイン自体のセットアップからはじめる場合は、以前の記事を参照して欲しい。

＞＞プラグイン＆サンプルをダウンロード
(Google Drive を利用。画面右上にあるダウンロードアイコンを押す)

端末のハードボタンを無効化して、Unityのみで音量を制御できるようにオプションを追加。実験してみたけどハードウェア（端末）・ソフトウェア（AudioMixer）音量どちらもUnityで思い通りに操作できるね。5.6.3p1～2017.2.0でも問題なく使えた。これならVRでもシステムUI出さずに操作できる。 pic.twitter.com/Eh3LCMqxjy
— ヽ｜∵｜ゝ(Fantom) (@fantom_1x) 2017年12月3日

■プラグインのセットアップ
■ハードウェア音量操作する際の AndroidManifest.xml について
■HardVolumeController（プレファブ）の使い方
■HardVolumeController のセットアップ例
■スクリプトでハードウェア音量操作・取得などをする
　●ハードウェア音量を取得する [メディア音量のみ]
　●ハードウェア音量を設定・増減をする [メディア音量のみ]
　●ハードウェアボタン押下による、端末自身での音量操作を有効/無効化する
　●ハードウェアボタン押下のイベントを取得するリスナーを登録する
■更新履歴

(※) Unity 5.6.3p1 / AndroidStudio 2.3.3 / Windows10(x64) / Galaxy S7 Edge (Android 7.0) で確認

■ハードウェア音量操作する際の AndroidManifest.xml について

　プラグインのセットアップにも書いてあるが、ここではもう少し詳細に解説しておこう。ハードウェア音量ボタンを押したときのイベントを取得する際には Unity で通常使われるアクティビティ「UnityPlayerActivity」をオーバーライドした、「HardVolKeyOnUnityPlayerActivity」（ハードウェア音量イベント取得用アクティビティ：プラグイン内に入っている）または「FullPluginOnUnityPlayerActivity」（プラグイン機能のすべてが入っている）を使う必要がある。これらのアクティビティ（Activity）はこのプラグイン独自のアクティビティで、ハードウェアキーのイベントを監視するコードが含まれている（初期のバージョンではあるが、Java コードは以前の記事に掲載してある）。インポートした「Assets/Plugins/Android/」にはマニフェストファイルのテンプレとして「AndroidManifest-HardVolKey～.xml」または「AndroidManifest-FullPlugin～.xml」が含まれているので、これらの中から適切なものを選んで（「縦置き・横置き」とか「API Level」とか）、「AndroidManifest.xml」にリネームしてビルドすることで利用することが可能になる。音量の取得・増減だけなら特別な権限はいらないので、使用するアクティビティさえ指定すれば、独自に書き換えても構わない。

　なお、ハードウェアボタンのイベントを受け取らず、Unity から一方的に音量を設定するだけなら、オーバーライドしたアクティビティを使う必要はない。具体的には例えば、後述する「GetMediaVolume()」「SetMediaVolume()」「AddMediaVolume()」（ハードウェア音量[メディア音量のみ]の取得と設定）のみの使用なら、これらマニフェストファイルは必要ない（Unity がデフォルトのマニフェストファイルを用意してくれる）。

(※) 独自のマニフェストファイルでビルドすると警告「Unable to find unity activity in manifest. You need to make sure orientation attribute is set to sensorPortrait manually.」が出るが、「UnityPlayerActivity」以外のアクティビティを使うと出るものなので気にしなくて良い（orientation＝画面回転はUnity側のアプリの設定に合わせた方が良い）。

■HardVolumeController（プレファブ）の使い方

　サンプルシーンにも含まれている「HardVolumeController.prefab」はスクリプト「HardVolumeController.cs」をアタッチしたハードウェア音量操作をするプレファブである。同じように「HardVolumeControllerWithToast.prefab」「HardVolumeControllerWithToast.cs」というものも入っているが、これらは音量が操作されたときにプラグインでトースト（Toast）で現在音量を表示する機能を追加しただけのものである。つまり音量の表示方法以外は内容的に変わらないので、例ではどちらの場合でも置き換えて考えて欲しい。

　端末と連携してこれらプレファブを利用するには、オプションの設定とコールバックを上手く使う必要がある。少しその辺は紛らわしいので、その解説と設定例などをなるべく詳細に書いておこう。

●オプション設定やコールバックの説明

Enable Hard Key	このスクリプトからは常にハードウェアの音量操作はできるのだが（Unity → Android）、端末のハードボタンを押したときにもスクリプトを利用するか否かの設定（Android → Unity[→何らかの動作]）をするオプションとなる。別の言い方をすれば、「端末のハードボタンを押したときのイベントを受け取るか否か」と同義だ。端末のハードボタンと連携したいときはオンにする必要がある。オンにしたとき、端末のハードボタンで音量大を押すと Android → Unity へ "VolumeUp" メッセージ（文字列）が送られ、コールバック：OnHardVolumeKeyUp() が呼ばれる。同じようにハードボタンで音量小を押したときは Android → Unity へ "VolumeDown" メッセージが送られ、コールバック：OnHardVolumeKeyDown() が呼ばれる。インスペクタでこれらコールバックに何らかのメソッドを登録しておけば、端末のハードボタンを操作したとき独自のアクションが設定できる。オフにしたときは、端末のハードボタンのイベントを無視するので、端末側で操作したときの影響は受けない（端末での操作とは別々になる）。デフォルトはオフ（Unityでの操作、端末での操作は別々に行える）。
Hard Operation	端末のハードボタンを押したとき、端末自身での音量操作をするか否かのオプション。オフにすると端末自身での音量操作は無効となり、Unity 側だけの音量操作となる。「Enable Hard Key」をオンにすることでハードボタン押下のイベントは受け取れるので、「Hard Operation=オフ＋Enable Hard Key=オン」の組み合わせで「Android 端末で音量無効→イベントだけUnityで受け取る→コールバックでUIなどを表示→UnityからAndroidへ音量設定」のような流れを作ることで Unity 側でのハード音量操作を完全に制御できる。逆に「Hard Operation=オフ＋Enable Hard Key=オフ」にするとユーザーは音量操作が全くできなくなってしまうので注意。デフォルトはオン（Android端末側でも音量操作は可能）。
Show UI	Unity で音量操作を行ったとき、端末のシステムUIを表示するか否かのオプション。あくまで Unity 側からの操作のときのみなので、端末自身のハードボタンで操作したときには影響しない。
On Volume Called(int) （コールバック）	音量の増減操作や現在の音量取得をしたときのコールバック。通常は UI などの呼び出しに使うと良い。「HardVolumeControllerWithToast」はこのコールバックでトースト（Toast）を呼び出すセットアップがされている。独自の UI などを作成したときはここにその表示メソッドを登録すれば良いだろう。引数の値（整数）は操作後の音量となる。
On Hard Key Volume Up （コールバック）	端末のハードボタンで音量が上げられたときのコールバック。ハードボタン押下のイベントを受け取る必要があるので「Enable Hard Key=オン」である必要がある。「Hard Operation=オフ」のときは、端末自身で音量操作ができなくなるため、ここに音量アップのメソッドを登録すると良い（HardVolumeController.VolumeUp() でも良い）。「Hard Operation=オン」のときは、端末自身で音量操作ができるため、現在音量の表示だけで良いだろう（HardVolumeController.VolumeNow() 等）。逆にハードボタンを無視するならば登録する必要はない。
On Hard Key Volume Down （コールバック）	端末のハードボタンで音量が下げられたときのコールバック。ハードボタン押下のイベントを受け取る必要があるので「Enable Hard Key=オン」である必要がある。「Hard Operation=オフ」のときは、端末自身で音量操作ができなくなるため、ここに音量アップのメソッドを登録すると良い（HardVolumeController.VolumeDown() でも良い）。「Hard Operation=オン」のときは、端末自身で音量操作ができるため、現在音量の表示だけで良いだろう（HardVolumeController.VolumeNow() 等）。逆にハードボタンを無視するならば登録する必要はない。

■HardVolumeController のセットアップ例

　言葉で説明すると少し難しく感じるので、簡単なセットアップ例を掲載しておこう。サンプルのシーンには微妙に異なったセットアップのプレファブが配置してあるので、動作確認して自分の使いたい機能に近いものを利用するのも良いだろう。

（例１）端末自身のハードボタン・Unity ともに音量操作をしたとき、端末のシステムUIとトースト（Toast）が表示されるセットアップ。
（※）サンプルのシーン「Assets/_Test/Scenes/PluginTest」に配置してある。

Enable Hard Key → ハードボタンのイベントを受け取る。
Hard Operation → 端末自身での音量操作も可能とする。
Show UI → Unity で音量操作をしたときも端末のシステムUIを表示する。
On Volume Called → Unity, 端末自身ともに音量操作したとき、トーストを表示する。
On Hard Key Volume Up →ハードボタンで音量を上げるイベントを受信したとき、現在音量を表示する（→トーストで表示される）。
On Hard Key Volume Down → ハードボタンで音量を下げるイベントを受信したとき、現在音量を表示する（→トーストで表示される）。

（例２）端末のハードボタンが押されたとき、Unity で独自の UI にて現在音量を表示し音量操作をする。また端末のシステムUIは表示しないセットアップ。
（※）サンプルのシーン「Assets/_Test/Scenes/DialogExTest」に配置してある。

（※）「VolumeUI」は独自のUI（uGUI）

Enable Hard Key → ハードボタンのイベントを受け取る。
Hard Operation → 端末自身での音量操作を無効化する（システムUIを表示させない）。
Show UI → Unity で音量操作をしたときに端末のシステムUIを表示しない。
On Volume Called → Unity, 端末自身ともに音量操作したとき、独自UIを表示する。
On Hard Key Volume Up → ハードボタンで音量を上げるイベントを受信したとき、Unity で端末の音量を上げる。
On Hard Key Volume Down → ハードボタンで音量を下げるイベントを受信したとき、Unity で端末の音量を下げる。

■スクリプトでハードウェア音量操作・取得などをする [メディア音量のみ]

　以前の記事にもコードは掲載してあるが、ここでは改めて機能ごとに分けて書いておこう。

●ハードウェア音量を取得する [メディア音量のみ]

using FantomLib;

#if UNITY_ANDROID && !UNITY_EDITOR
    int vol = AndroidPlugin.GetMediaVolume();     //現在音量の取得
    int max = AndroidPlugin.GetMediaMaxVolume();  //最大音量の取得
#endif

//HardVolumeController を使用するなら（内容は全く同じ）
HardVolumeController hardVolumeController = FindObjectOfType<HardVolumeController>();
int vol = hardVolumeController.volume;     //現在音量の取得
int max = hardVolumeController.maxVolume;  //最大音量の取得

●ハードウェア音量を設定・増減をする [メディア音量のみ]

using FantomLib;

#if UNITY_ANDROID && !UNITY_EDITOR
    int vol = AndroidPlugin.SetMediaVolume(4, showUI);  //音量=4
        vol = AndroidPlugin.SetMediaVolume(0, showUI);  //ミュート：音量=0
        vol = AndroidPlugin.AddMediaVolume(1, showUI);  //現在の音量+１
        vol = AndroidPlugin.AddMediaVolume(-1, showUI); //現在の音量-１
#endif

//HardVolumeController を使用するなら（内容は全く同じ）
HardVolumeController hardVolumeController = FindObjectOfType<HardVolumeController>();
hardVolumeController.volume = 4;    //音量=4
hardVolumeController.VolumeMute();  //ミュート：音量=0
hardVolumeController.VolumeUp();    //現在の音量+１
hardVolumeController.VolumeDown();  //現在の音量-１

●ハードウェアボタン押下による、端末自身での音量操作を有効/無効化する

using FantomLib;

#if UNITY_ANDROID && !UNITY_EDITOR
    AndroidPlugin.HardKey.SetVolumeOperation(true);  //端末自身での音量操作が可能
    AndroidPlugin.HardKey.SetVolumeOperation(false); //端末自身での音量操作を無効化
#endif

//HardVolumeController を使用するなら（内容は全く同じ）
HardVolumeController hardVolumeController = FindObjectOfType<HardVolumeController>();
hardVolumeController.HardOperation = true;   //端末自身での音量操作が可能
hardVolumeController.HardOperation = false;  //端末自身での音量操作を無効化

●ハードウェアボタン押下のイベントを取得するリスナーを登録する

using FantomLib;

void OnEnable()  //MonoBehaviour イベント
{
#if UNITY_ANDROID && !UNITY_EDITOR
    //ハードウェア音量キーのリスナー登録（"HardVolumeKeyChange"はコールバックハンドラ）
    AndroidPlugin.HardKey.SetKeyVolumeUpListener(gameObject.name, "HardVolumeKeyChange", "VolumeUp");
    AndroidPlugin.HardKey.SetKeyVolumeDownListener(gameObject.name, "HardVolumeKeyChange", "VolumeDown");
#endif
}

void OnDisable()  //MonoBehaviour イベント
{
#if UNITY_ANDROID && !UNITY_EDITOR
    //ハードウェア音量キーの全リスナー解除
    AndroidPlugin.HardKey.RemoveAllListeners();
#endif
}

//ハードウェア音量キーのイベントハンドラ（Android ネイティブから呼ばれる）
void HardVolumeKeyChange(string message)
{
    if (message == "VolumeUp")
    {
        //音量を上げる操作されたときの処理
    }
    else if (message == "VolumeDown")
    {
        //音量を下げる操作されたときの処理
    }
}

//※内容は「HardVolumeController.cs」と同じもの。

　サンプルコードは「Assets/FantomLib/Scripts/Module/HardVolumeController.cs」にまとまっているので適当にコピペしたり、継承して新しいクラスを作るのも良いだろう。またプレファブ「Assets/FantomLib/Prefabs/System/HardVolumeControllerWithToast」にはトースト（Toast）で操作したときの音量を表示できるようにセットアップしてある。少し改造すればVR（Cardboard/ハコスコ）にも応用できるだろう。シーン「PluginTest」「DialogTest」「DialogExTest」にはそれぞれ異なったセットアップのプレファブが配置がされているので、自分の好みに合ったものを利用するのも良いだろう。

VR(Cardboard/ハコスコ)でもハード音量操作の動作確認済み。5.6.3p2以降は音量操作するとシステムUIが表示されるようになったのだが、２眼だとシステムUIは見えない。でもプラグイン使ってUIを独自に作ればVRでも音量を確認できる。BlueToothがあれば手元でも操作できるのでGearVRっぽくてなお良い。 pic.twitter.com/SWWX1xY9gV
— ヽ｜∵｜ゝ(Fantom) (@fantom_1x) 2017年12月3日