AudioFocusSession
音频焦点会话允许进行音频焦点管理，例如请求音频焦点和释放音频焦点。播放流使用音频焦点会话来请求音频焦点或释放音频焦点。播放流构建器可以使用setAudioFocusSessionId来指定要使用的音频焦点会话。
所需服务
API需要声明系统音频服务：
[wants]
[[wants.service]]
id = "com.amazon.audio.control"
使用的类型
- *
构造函数
new AudioFocusSession()
new AudioFocusSession(
id): AudioFocusSession
参数
id
number
会话ID获取自
返回值
属性
sessionId
sessionId:
number
focusUsage
focusUsage:
number
方法
getAudioSessionId()
getAudioSessionId():
number
获取此实例的会话ID。
返回值
number
number 分配给此实例的会话ID
示例
/* 返回会话ID并将其存储在sessionId中 *
const session = new AudioFocusSession(1); const sessionId = session.getAudioSessionId(); //值应为1
getUsage()
getUsage():
number
获取此焦点会话的当前音频使用类型。如果未请求焦点，则返回USAGE_NONE。
返回值
number
number 来自types/AudioCoreClientTypes.AudioUsageType枚举的当前音频使用类型
示例
/*
请求音频焦点，解析Promise后返回AudioFocusStatus类型
假设会话是一个AudioFocusSession对象
*\/
const attr: AudioFocusAttributes = {
usage: audioSource.usage
};
const status = session.requestAudioFocusAsync(attr)
.then((status) => {return status;}).catch((error) => console.log(error));
let usage = session.getUsage(); // 必须等于请求焦点时使用的用法。
registerAudioFocusListenerAsync()
registerAudioFocusListenerAsync(callback:
(value: any) => void):Promise<AudioFocusStatus>
注册回调以接收音频焦点更改通知。每次会话只能注册一个回调函数。
参数
callback
(value: any) => void
接收焦点变化事件的函数。事件包括：
GRANTED (0)： 焦点已获批准RELEASED (1)： 焦点已释放DUCKED (2)： 音频被调低（音量降低）PAUSED (3)： 音频已暂停STOPPED (4)： 音频停止
返回值
Promise<AudioFocusStatus>
Promise 解析为如下的Promise：
AUDIO_FOCUS_STATUS_NO_ERROR (0)： 回调注册成功AUDIO_FOCUS_STATUS_BAD_VALUE (-2)： 回调无效AUDIO_FOCUS_STATUS_NO_INIT (-3)： 会话未初始化AUDIO_FOCUS_STATUS_INVALID_OPERATION (-8)： 回调已注册
示例
/*
创建一个函数并在音频焦点侦听器中进行注册，
以便在音频焦点状态发生变化时执行该函数；当Promise解析后，将返回的AudioFocusStatus类型
存储在status中
假设会话是一个AudioFocusSession对象
*\/
const callbackFunction = (event: any) => {
switch (event.focusChange) {
case AudioFocusChange.GRANTED:
// 当授予音频焦点时触发
break;
case AudioFocusChange.RELEASED:
// 当释放音频焦点时触发
break;
case AudioFocusChange.DUCKED:
// 当应该调低音频（降低音量）时触发
break;
case AudioFocusChange.PAUSED:
// 当应该暂停音频时触发
break;
case AudioFocusChange.STOPPED:
// 当应该停止音频时触发
break;
case AudioFocusChange.MUTED:
// 当应该将音频静音时触发（目前没有产品支持此功能）
break;
}
};
const status = session.registerAudioFocusListenerAsync(callbackFunction)
.then((status) => {return status;}).catch((error) => console.log(error));
releaseAudioFocusAsync()
releaseAudioFocusAsync():
Promise<AudioFocusStatus>
释放之前请求的音频焦点。必须在音频播放完成或不再需要焦点时调用此方法。
返回值
Promise<AudioFocusStatus>
Promise 解析为如下的Promise：
AUDIO_FOCUS_STATUS_NO_ERROR (0)： 焦点成功释放AUDIO_FOCUS_STATUS_BAD_VALUE (-2)： 会话状态无效AUDIO_FOCUS_STATUS_NO_INIT (-3)： 会话未初始化AUDIO_FOCUS_STATUS_INVALID_OPERATION (-8)： 无焦点保持
示例
/*
释放音频焦点，解析Promise后返回AudioFocusStatus类型
假设会话是一个AudioFocusSession对象
*\/
const status = session.releaseAudioFocusAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
requestAudioFocusAsync()
requestAudioFocusAsync(attr?: AudioFocusAttributes
| undefined):Promise<AudioFocusStatus>
请求具有指定属性的会话的音频焦点。授予焦点后，可以根据使用类型调低、暂停或停止任何先前聚焦的音频。
参数
attr?
AudioFocusAttributes | undefined
焦点请求的可选配置。如果未提供，则默认设置为USAGE_MEDIA。
返回值
Promise<AudioFocusStatus>
Promise 解析为如下的Promise：
AUDIO_FOCUS_STATUS_NO_ERROR (0)： 已成功授予焦点AUDIO_FOCUS_STATUS_DENIED (1)： 焦点请求被拒绝AUDIO_FOCUS_STATUS_DELAYED (2)： 焦点请求延迟AUDIO_FOCUS_STATUS_BAD_VALUE (-2)： 属性无效AUDIO_FOCUS_STATUS_NO_INIT (-3)： 会话未初始化AUDIO_FOCUS_STATUS_INVALID_OPERATION (-8)： 操作无效
示例
/*
请求音频焦点，解析Promise后返回AudioFocusStatus类型
假设会话是一个AudioFocusSession对象
*\/
const attr: AudioFocusAttributes = {
usage: audioSource.usage
};
const status = session.requestAudioFocusAsync(attr)
.then((status) => {return status;}).catch((error) => console.log(error));
unregisterAudioFocusListenerAsync()
unregisterAudioFocusListenerAsync():
Promise<AudioFocusStatus>
注销之前注册的焦点变更回调。
返回值
Promise<AudioFocusStatus>
Promise 解析为如下的Promise：
AUDIO_FOCUS_STATUS_NO_ERROR (0)： 回调注销成功AUDIO_FOCUS_STATUS_BAD_VALUE (-2)： 会话状态无效AUDIO_FOCUS_STATUS_NO_INIT (-3)： 会话未初始化AUDIO_FOCUS_STATUS_INVALID_OPERATION (-8)： 未注册任何回调
示例
/*
取消注册回调函数并将返回的AudioFocusStatus类型
存储在status中
*\/
const status = session.unregisterAudioFocusListenerAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
Last updated: 2026年7月22日
