语言

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
继承
AudioFocusRequestClass
特性

注解

用于封装有关音频焦点请求信息的类。 实例由一个AudioFocusRequest实例生成,用于分别使用Builder和AudioManager#requestAudioFocus(AudioFocusRequest)放弃音频AudioManager#abandonAudioFocusRequest(AudioFocusRequest)焦点。

<h3>什么是音频焦点?</h3>

音频焦点是 API 8 中引入的概念。 它用于传达这样一个事实:用户一次只能专注于单个音频流,例如收听音乐或播客,但不能同时关注这两种音频流。 在某些情况下,多个音频流可以同时播放,但只有一个用户真正收听(焦点),而另一个在后台播放。 例如,在减少音量(即躲避)的音乐播放时,驾驶方向被说出来。

当应用程序请求音频焦点时,它表示其意图是“拥有”音频焦点来播放音频。 让我们查看不同类型的焦点请求、请求后的返回值以及对丢失的响应。

注意:在授予焦点之前,应用程序不应播放任何内容。

<h3>不同类型的焦点请求</h3>

有四种焦点请求类型。 一个成功的焦点请求,每个请求都会由系统以及以前保留音频焦点的其他应用程序产生不同的行为。 <ul><li>AudioManager#AUDIOFOCUS_GAIN 表示,应用程序现在是用户正在侦听的唯一音频来源。 音频播放的持续时间未知,并且可能很长一段时间:用户完成与应用程序交互后(s)他不希望另一个音频流恢复。 此焦点增益的使用示例适用于音乐播放、游戏或视频播放器。</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT 用于了解应用程序暂时从当前所有者获取焦点的情况,但用户希望播放返回到应用程序不再需要音频焦点的位置。 例如,播放警报或在 VoIP 呼叫期间播放。 众所周知,播放是有限的:警报将超时或被消除,VoIP 呼叫有一个开始和结束。 当其中任何一个事件结束时,如果用户在启动时正在听音乐,则用户希望音乐能够恢复,但不希望同时收听这两个事件。</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK:此焦点请求类型类似于 AUDIOFOCUS_GAIN_TRANSIENT 焦点请求的临时方面,但它也表达了在自己焦点的时间的事实,你允许另一个应用程序继续在减少的音量上播放,“躲避”。 例如,播放驾驶路线或通知时,音乐可以继续播放,但不够响亮,无法阻止方向难以理解。 “鸭子”应用程序的典型衰减是 0.2f(或 -14dB),例如,使用此类播放时可以应用 MediaPlayer.setVolume(0.2f) 这种衰减。</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE 也用于临时请求,但也表示应用程序希望设备不会播放任何其他内容。 这通常用于执行音频录制或语音识别,并且不希望系统在此期间播放示例通知。</li></ul>

AudioFocusRequest实例始终包含上述四种类型的请求之一。 在构造函数中使用AudioFocusRequest其生成器生成Builder实例时,或者在复制AudioFocusRequest.Builder#Builder(int)现有实例后传递AudioFocusRequest.Builder#setFocusGain(int)AudioFocusRequest.Builder#Builder(AudioFocusRequest)它。

注意:如果应用面向 Android 15(API 级别 35)或更高版本,则它无法请求音频焦点,除非它是顶级应用或运行前台服务。 此要求类似于音频播放的要求。 如果应用在不符合这些要求时请求音频焦点,该方法将 Failed返回。

<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 的新增行为,而面向 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>示例</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文档android.media.AudioFocusRequest。

本页的某些部分是根据 创建和共享的工作进行的修改,并根据 许可证中所述的条款使用。

属性

名称 说明
AudioAttributes

返回此设置AudioAttributes,AudioFocusRequest如果未设置任何属性,则返回默认属性。

Class

返回此 Object的运行时类。

(继承自 Object)
FocusGain

返回为此 AudioFocusRequest配置的音频焦点请求的类型。

Handle

基础 Android 实例的句柄。

(继承自 Object)
JniIdentityHashCode

获取互操作运行时分配给此Java对等的标识哈希代码。

(继承自 Object)
JniManagedPeerState

获取运行时上次分配的状态标志。

(继承自 JavaObject)
JniPeerMembers

获取用于访问此Java绑定成员的 JNI 元数据。

PeerReference

获取此Java对等方的 JNI 对象引用。

(继承自 Object)
ThresholdClass

此 API 支持 Mono for Android 基础结构,不打算直接从代码使用。

(继承自 Object)
ThresholdType

此 API 支持 Mono for Android 基础结构,不打算直接从代码使用。

(继承自 Object)

方法

名称 说明
AcceptsDelayedFocusGain()

返回将使用此应用程序 AudioFocusRequest 是否支持在临时请求失败后授予的焦点获取。

Clone()

创建并返回此对象的副本。

(继承自 Object)
Construct(JniObjectReference, JniObjectReferenceOptions)

将此对等方的构造委托给运行时的值管理器。

(继承自 JavaObject)
Dispose()

释放此Java对等方持有的资源。

(继承自 Object)
Dispose(Boolean)

释放此Java对等方持有的资源。

(继承自 Object)
DisposeUnlessReferenced()

要求值管理器释放此对等方,除非其映射保留此相同的托管实例。

(继承自 JavaObject)
Equals(Object)

测试另一个托管对等方是否引用同一Java对象。

(继承自 JavaObject)
Equals(Object)

指示其他对象是否“等于”此对象。

(继承自 Object)
GetHashCode()

返回对象的哈希代码值。

(继承自 Object)
JavaFinalize()
已过时.

当垃圾回收确定不再引用该对象时,由对象上的垃圾回收器调用。

(继承自 Object)
Notify()

唤醒正在等待此对象的监视器的单个线程。

(继承自 Object)
NotifyAll()

唤醒正在等待此对象的监视器的所有线程。

(继承自 Object)
SetHandle(IntPtr, JniHandleOwnership)

设置 Handle 属性。

(继承自 Object)
SetPeerReference(JniObjectReference, JniObjectReferenceOptions)

在不创建 JNI 引用副本的情况下,将引用值存储在控制块中。

(继承自 JavaObject)
ToArray<T>()

从此Java数组包装器创建托管数组。

(继承自 Object)
ToString()

返回对象的字符串表示形式。

(继承自 Object)
UnregisterFromRuntime()

从互操作运行时取消注册此Java对等。

(继承自 Object)
Wait()

导致当前线程等待,直到它被唤醒,通常是通过 通知 或 中断。

(继承自 Object)
Wait(Int64, Int32)

使当前线程等待直到唤醒,通常是通过 通知 或 中断,或直到经过一定数量的实时。

(继承自 Object)
Wait(Int64)

使当前线程等待直到唤醒,通常是通过 通知 或 中断,或直到经过一定数量的实时。

(继承自 Object)
WillPauseWhenDucked()

返回当应用程序请求鸭子时,使用此应用程序是否会 AudioFocusRequest 暂停。

显式接口实现

名称 说明
IJavaPeerable.Disposed()

将此对等方标记为已释放,并将disposing调用Dispose设置为 true.

(继承自 JavaObject)
IJavaPeerable.Finalized()

将此对等方标记为已释放,并将disposing调用Dispose设置为 false.

(继承自 JavaObject)
IJavaPeerable.JniObjectReferenceControlBlock

获取此对等方使用的本机控制块指针。

(继承自 JavaObject)
IJavaPeerable.SetJniIdentityHashCode(Int32)

存储运行时提供的标识哈希代码。

(继承自 JavaObject)
IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates)

替换存储的托管对等状态标志。

(继承自 JavaObject)
IJavaPeerable.SetPeerReference(JniObjectReference)

更新对等引用,并在引用无效时释放已释放的对等方控制块。

(继承自 JavaObject)

扩展方法

名称 说明
GetJniTypeName(IJavaPeerable)

获取实例 self类型的 JNI 名称。

JavaAs<TResult>(IJavaPeerable)

尝试强制self键入TResult,检查强制是否在Java端有效。

JavaCast<TResult>(IJavaObject)

执行 Android 运行时检查的类型转换。

JavaCast<TResult>(IJavaObject)

重复使用兼容的托管对等,或获取请求类型的包装器。

TryJavaCast<TResult>(IJavaPeerable, TResult)

尝试强制self键入TResult,检查强制是否在Java端有效。

适用于