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 中引入的概念。 它用來傳達使用者一次只能專注於單一音訊串流，例如聽音樂或播客，但無法同時聽兩件事。 在某些情況下，多個音訊串流可以同時播放，但使用者只會專注於其中一條，另一條則在背景播放。 例如，在音樂以較低音量播放（也就是蹲下）時，駕駛指示會被講解。

當應用程式請求音訊焦點時，表示它想「擁有」音訊焦點來播放音訊。 讓我們來檢視不同類型的焦點請求、請求後的回傳價值，以及損失時的回應。

注意：應用程式在獲得焦點前不應播放任何內容。

<h3>不同類型的焦點請求</h3>

專注請求有四種類型。 成功對兩者進行聚焦請求後，系統與先前持有音訊聚焦的應用程式會產生不同行為。 <UL><LI>AudioManager#AUDIOFOCUS_GAIN 表示你的應用程式現在是使用者唯一正在收聽的音訊來源。 音訊播放的持續時間未知，且可能非常長：使用者在完成與應用程式互動後，不會期待下一次音訊串流會恢復。 這種聚焦增益的用途範例包括音樂播放、遊戲或影音播放器。</李>

<LI>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT 是針對這種情況，當你知道應用程式暫時從現有擁有者那裡取得焦點，但使用者期望播放在應用程式不再需要音訊焦點後，會回到原本的位置。 例如播放鬧鐘或在 VoIP 通話中。 播放是有限的：鬧鐘會逾時或被駁回，VoIP 通話有開始和結束。 當這些事件結束，且使用者在音樂開始時正在聽音樂，使用者預期音樂會恢復，但不希望同時聽兩個。</李>

<李>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK：這種專注請求類型類似 AUDIOFOCUS_GAIN_TRANSIENT 於專注請求的暫時性，但它也表達了在你擁有專注期間，你允許另一個應用程式以較低音量繼續播放，也就是「蹲下」。 例如播放駕駛路線或通知時，音樂可以繼續播放，但音量不會大到讓路線難以理解。 「蹲伏」應用程式典型的衰減是 0.2f（或 -14dB），例如使用此類別播放時可應用 MediaPlayer.setVolume(0.2f) 此因子。</李>

<LI>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE 也是臨時請求，但同時表示你的應用程式預期裝置不會播放其他東西。 這通常用於錄音或語音辨識，且不希望系統在這段時間播放通知。</li></ul>

一個 AudioFocusRequest 實例總是包含上述四種請求類型之一。 當AudioFocusRequest以建構子Builder中建AudioFocusRequest.Builder#Builder(int)構實例時，會傳遞該實例，或在複製帶有 AudioFocusRequest.Builder#setFocusGain(int)的現有實例後傳遞AudioFocusRequest.Builder#Builder(AudioFocusRequest)。

「注意」><b>注意：</b> 如果應用程式針對 Android 15（API 等級 35）或更高，除非是頂尖應用程式或執行前台服務，否則無法請求音訊聚焦。 此要求與音訊播放的要求相似。 若應用程式在不符合這些需求時請求音訊聚焦，該方法會回傳 <c>AudioManager#AUDIOFOCUS_REQUEST_FAILED</c>。 </旁白>

<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>暫停與蹲下</h4>

當應用程式請求音訊聚焦時 AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK，系統會避開當前焦點擁有者。

注意：這種行為是 <Android>O</b> 的新設計，而針對 SDK 層級至 API 25 的應用程式，當收到焦點損失 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)這樣系統會呼叫你的 focus lister，而不是自動蹲下。

<h4>範例</h4>

以下範例涵蓋了以下步驟，適用於任何播放音訊並使用音訊聚焦的應用程式。 這裡我們播放有聲書，應用程式在失去焦點時會暫停而非閃避。 這些步驟包括： <ul><li>創建 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 文件 android.media.AudioFocusRequest。

本頁部分內容為基於 Open Source Project 所創建與分享的作品，並依授權條款所描述的使用進行修改。