AudioFocusRequestClass クラス

定義

[Android.Runtime.Register("android/media/AudioFocusRequest", ApiSince=26, DoNotGenerateAcw=true)]
public sealed class AudioFocusRequestClass : Java.Lang.Object

[<Android.Runtime.Register("android/media/AudioFocusRequest", ApiSince=26, DoNotGenerateAcw=true)>]
type AudioFocusRequestClass = class
    inherit Object

継承

Object

JavaObject

Object

AudioFocusRequestClass

属性

RegisterAttribute

注釈

オーディオ フォーカス要求に関する情報をカプセル化するクラス。 AudioFocusRequest インスタンスはBuilderによって構築され、AudioManager#requestAudioFocus(AudioFocusRequest)とAudioManager#abandonAudioFocusRequest(AudioFocusRequest)でそれぞれオーディオ フォーカスを要求および破棄するために使用されます。

<h3>オーディオ フォーカスとは</h3>

オーディオ フォーカスは、API 8 で導入された概念です。 これは、ユーザーが音楽やポッドキャストを聴いているなど、一度に 1 つのオーディオ ストリームにのみ集中できるが、同時に両方に集中できないという事実を伝えるために使用されます。 場合によっては、複数のオーディオ ストリームを同時に再生できますが、ユーザーが実際にリッスンする (フォーカスする) のは 1 つだけで、もう 1 つのオーディオ ストリームはバックグラウンドで再生されます。 その例として、音楽が音量を下げる (ダッキングなど) 再生中に、方向が読み上げられることがあります。

アプリケーションがオーディオ フォーカスを要求すると、オーディオを再生するためにオーディオ フォーカスを "所有" する意図が表されます。 さまざまな種類のフォーカス要求、要求後の戻り値、および損失に対する応答を確認してみましょう。

注: アプリケーションは、フォーカスが付与されるまで何も再生しないでください。

<h3>さまざまな種類のフォーカス要求</h3>

フォーカス要求の種類は 4 つあります。 それぞれのフォーカス要求が成功すると、システムと、以前にオーディオ フォーカスを保持していた他のアプリケーションによって異なる動作が生成されます。 <ul><li>AudioManager#AUDIOFOCUS_GAIN は、アプリケーションが現在、ユーザーがリッスンしている唯一のオーディオ ソースであるという事実を表します。 オーディオ再生の継続時間は不明であり、非常に長い可能性があります。ユーザーがアプリケーションとの対話を完了した後、別のオーディオ ストリームが再開されるとは思われません。 このフォーカス ゲインの使用例は、音楽の再生、ゲームやビデオ プレーヤーなどです。</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT は、アプリケーションが現在の所有者から一時的にフォーカスを取得していることがわかっているが、ユーザーは、アプリケーションがオーディオフォーカスを必要としなくなった時点に再生が戻ってくることを期待している状況を想定しています。 たとえば、アラームを再生したり、VoIP 通話中に再生したりします。 再生は有限であることが知られています。アラームはタイムアウトまたは無視され、VoIP 呼び出しには開始と終了があります。 これらのイベントのいずれかが終了し、開始時にユーザーが音楽を聴いていた場合、ユーザーは音楽が再開することを期待しますが、同時に両方を聴くことを望んでいませんでした</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK: このフォーカス要求の種類は、フォーカス要求の一時的な側面の AUDIOFOCUS_GAIN_TRANSIENT に似ていますが、フォーカスを所有している間の事実も表し、別のアプリケーションが "ダッキング" の音量を下げ続けることができます。 たとえば、ルート案内や通知を再生する場合は、音楽を再生し続けても問題ありませんが、方向が理解しにくくならないように十分な大きさではありません。 "ダッキング" アプリケーションによる一般的な減衰は、0.2f (または -14dB) の係数です。たとえば、このクラスを playback.MediaPlayer.setVolume(0.2f) に使用する場合、<で適用できます。/li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE は一時的な要求用でもありますが、アプリケーションはデバイスが他の何も再生しないことを期待していることを表しています。 これは通常、オーディオ録音や音声認識を行っていて、その間にシステムによって例の通知が再生されないようにする場合に使用されます</li></ul>

AudioFocusRequest インスタンスには、上で説明した 4 種類の要求のいずれかが常に含まれています。 これは、AudioFocusRequest コンストラクター Builderでビルダーを使用してAudioFocusRequest.Builder#Builder(int) インスタンスをビルドするとき、または AudioFocusRequest.Builder#setFocusGain(int) を使用して既存のインスタンスをコピーした後、AudioFocusRequest.Builder#Builder(AudioFocusRequest)で渡されます。

"note"><b>Note:</b> アプリが Android 15 (API レベル 35) 以降を対象とする場合、トップ アプリまたはフォアグラウンド サービスを実行している場合を除き、オーディオ フォーカスを要求することはできません。 この要件は、オーディオ再生の要件に似ています。 アプリがこれらの要件を満たしていないときにオーディオ フォーカスを要求すると、メソッドは <c>AudioManager#AUDIOFOCUS_REQUEST_FAILED</c> を返します。 </aside>

<h3>フォーカス要求の条件</h3><h4>フォーカス要求が必要な場合</h4>

フォーカス要求は、要求に従うオーディオ ユース ケースを記述する AudioAttributes ( Builder#setAudioAttributes(AudioAttributes)を参照) によって修飾されます (成功または許可された後)。 要求には、オーディオ/メディアの再生に使用する属性と同じ AudioAttributes を使用することをお勧めします。 <br>属性が設定されていない場合は、 AudioAttributes#USAGE_MEDIA の既定の属性が使用されます。

<h4>フォーカスの表示</h4>

音声フォーカスは、さまざまな理由でシステムによって "ロック" される可能性があります。電話中、デバイスが接続されている車が緊急メッセージを再生するとき。.このような状況をサポートするために、アプリケーションは要求が満たされたときに通知を受け取るように要求できます。要求に遅延フォーカスを受け入れるようにフラグを設定し、 Builder#setAcceptsDelayedFocusGain(boolean)。 <br>システムによってロックされている間にフォーカスが要求された場合、 AudioManager#requestAudioFocus(AudioFocusRequest) は AudioManager#AUDIOFOCUS_REQUEST_DELAYEDを返します。 フォーカスがロックされなくなった場合、 Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener) または Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener, Handler) で設定されたフォーカス リスナーが呼び出され、オーディオ フォーカスが所有されているアプリケーションに通知されます。

<h4>Pausing vs ducking</h4>

アプリケーションが AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCKでオーディオ フォーカスを要求すると、システムは現在のフォーカス所有者をアヒルします。

注: この動作は Android O</b> では<b>新しい動作ですが、API 25 までの SDK レベルを対象とするアプリケーションでは、AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCKのフォーカスが失われたときにダッキング自体を実装する必要がありました。

しかし、ダッキングは常にユーザーが期待する動作であるとは限りません。 一般的な例として、ユーザーがオーディオ ブックやポッドキャストを聞いている間にデバイスが方向を再生し、ナビゲーション プロンプトと音声コンテンツを同時に理解するのが難しいため、アヒルの代わりにオーディオ再生が一時停止することを想定している場合です。 したがって、システムは、それがダッキングの話されたコンテンツであると検出したときに自動的にダッキングされることはありません。そのようなコンテンツは、プレイヤーの AudioAttributes が AudioAttributes#CONTENT_TYPE_SPEECHによって修飾されたときに検出されます。 オーディオブック、ポッドキャスト用のメディア再生アプリケーションを作成する場合は、たとえば AudioAttributes.Builder#setContentType(int) と MediaPlayer#setAudioAttributes(AudioAttributes) を参照してください。システムは音声を再生するアプリケーションを自動的にダッキングしないため、代わりにフォーカス リスナーを呼び出して AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCKを通知するため、代わりに一時停止できます。 この動作は、 AudioFocusRequestの使用とは無関係ですが、 AudioAttributesの使用に関連付けられていることに注意してください。

音声を再生する以外の理由でダッキングの代わりにアプリケーションを一時停止する必要がある場合は、 Builder#setWillPauseWhenDucked(boolean)で宣言することもできます。これにより、システムは自動的にダッキングするのではなく、フォーカス リスナーを呼び出すことができます。

<h4>Example</h4>

次の例では、オーディオを再生し、オーディオ フォーカスを使用するすべてのアプリケーションで見つかる次の手順について説明します。 ここではオーディオブックを再生し、アプリケーションはフォーカスを失ったときにアヒルではなく一時停止することを目的としています。 これらの手順は、再生とフォーカス要求に使用する <ul><li>Creating AudioAttributes で構成されます。</li><li>目的のフォーカス動作を定義する AudioFocusRequest インスタンスの構成と作成.</li><li>オーディオ フォーカスを要求し、リターン コードを確認して、再生がすぐに発生するか、遅延が発生しているかどうかを確認します。</li><li>フォーカスの増減に対応するためのフォーカス変更リスナーの実装。</li></ul>

// initialization of the audio attributes and focus request
            mAudioManager = (AudioManager) Context.getSystemService(Context.AUDIO_SERVICE);
            mPlaybackAttributes = new AudioAttributes.Builder()
                    .setUsage(AudioAttributes.USAGE_MEDIA)
                    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
                    .build();
            mFocusRequest = new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
                    .setAudioAttributes(mPlaybackAttributes)
                    .setAcceptsDelayedFocusGain(true)
                    .setWillPauseWhenDucked(true)
                    .setOnAudioFocusChangeListener(this, mMyHandler)
                    .build();
            mMediaPlayer = new MediaPlayer();
            mMediaPlayer.setAudioAttributes(mPlaybackAttributes);
            final Object mFocusLock = new Object();

            boolean mPlaybackDelayed = false;

            // requesting audio focus
            int res = mAudioManager.requestAudioFocus(mFocusRequest);
            synchronized (mFocusLock) {
                if (res == AudioManager.AUDIOFOCUS_REQUEST_FAILED) {
                    mPlaybackDelayed = false;
                } else if (res == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
                    mPlaybackDelayed = false;
                    playbackNow();
                } else if (res == AudioManager.AUDIOFOCUS_REQUEST_DELAYED) {
                   mPlaybackDelayed = true;
                }
            }

            // implementation of the OnAudioFocusChangeListener
            @Override
            public void onAudioFocusChange(int focusChange) {
                switch (focusChange) {
                    case AudioManager.AUDIOFOCUS_GAIN:
                        if (mPlaybackDelayed || mResumeOnFocusGain) {
                            synchronized (mFocusLock) {
                                mPlaybackDelayed = false;
                                mResumeOnFocusGain = false;
                            }
                            playbackNow();
                        }
                        break;
                    case AudioManager.AUDIOFOCUS_LOSS:
                        synchronized (mFocusLock) {
                            // this is not a transient loss, we shouldn't automatically resume for now
                            mResumeOnFocusGain = false;
                            mPlaybackDelayed = false;
                        }
                        pausePlayback();
                        break;
                    case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT:
                    case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK:
                        // we handle all transient losses the same way because we never duck audio books
                        synchronized (mFocusLock) {
                            // we should only resume if playback was interrupted
                            mResumeOnFocusGain = mMediaPlayer.isPlaying();
                            mPlaybackDelayed = false;
                        }
                        pausePlayback();
                        break;
                }
            }

            // Important:
            // Also set "mResumeOnFocusGain" to false when the user pauses or stops playback: this way your
            // application doesn't automatically restart when it gains focus, even though the user had
            // stopped it.

Javaドキュメント。

このページの一部は、によって作成および共有され、に記載されている条件に従って使用される作業に基づく変更です。