音频焦点会话
音频焦点会话
重要须知： 亚马逊机密信息。本文档是预发布技术文档，用于介绍尚未向公众发布的即将上线产品。
音频焦点会话允许进行音频焦点管理，例如请求音频焦点和释放音频焦点。播放流使用音频焦点会话来请求音频焦点或释放音频焦点。播放流构建器可以使用setAudioFocusSessionId来指定要使用的音频焦点会话。
所需服务
API需要声明系统音频服务：
[wants]
[[wants.service]]
id = "com.amazon.audio.control"
使用的类型
请参阅音频核心类型
AudioFocusAttributesAudioFocusStatusAudioFocusChange
方法
requestAudioFocusAsync(attr)
描述
在使用所选音频用法类型的会话中请求音频聚焦。
返回值
返回解析为AudioFocusStatus类型的Promise。
参数
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| attr | AudioFocusAttributes | 否 | 确定如何处理音频焦点。如果未指定新属性，则创建一个。 |
代码示例
/*
请求音频焦点，解析Promise后返回AudioFocusStatus类型
假设会话是一个AudioFocusSession对象
*/
const attr: AudioFocusAttributes = {
usage: audioSource.usage
};
const status = session.requestAudioFocusAsync(attr)
.then((status) => {return status;}).catch((error) => console.log(error));
releaseAudioFocusAsync()
描述
在会话中释放音频焦点。
返回值
返回解析为AudioFocusStatus类型的Promise。
代码示例
/*
释放音频焦点，解析Promise后返回AudioFocusStatus类型
假设会话是一个AudioFocusSession对象
*/
const status = session.releaseAudioFocusAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
registerAudioFocusListenerAsync(callback)
描述
注册一个回调函数，一旦检测到音频焦点事件即会执行该函数。一次只能注册一个回调函数。
返回值
返回解析为AudioFocusStatus类型的Promise。
参数
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| callback | 函数 | 是 | 回调函数，该函数会接收事件并根据该事件输出内容 |
代码示例
/*
创建一个函数并在音频焦点侦听器中进行注册，
以便在音频焦点状态发生变化时执行该函数；当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));
unregisterAudioFocusListenerAsync()
描述
取消注册任何当前为音频焦点注册的回调函数。
返回值
返回解析为AudioFocusStatus类型的Promise。
代码示例
/*
取消注册回调函数并将返回的AudioFocusStatus类型
存储在status中
*/
const status = session.unregisterAudioFocusListenerAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
getAudioSessionId()
描述
获取成员变量sessionId的值，该变量表示给定焦点会话的会话ID。
返回值
返回表示会话ID的数字。
代码示例
/*
返回会话ID并将其存储在sessionId中
*/
const session = new AudioFocusSession(1);
const sessionId = session.getAudioSessionId(); // 值应为1
getUsage()
描述
获取音频焦点用法值
返回值
返回表示音频焦点用法的数字。
代码示例
/*
请求音频焦点，解析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(); // 必须等于请求焦点时使用的用法。
Last updated: 2025年10月2日
