Audio Manager
音频管理器允许进行音频管理,例如音量调整和静音控制。
- TOC
所需权限
API需要特定权限才能执行某些操作:
[[needs.privilege]]
id = "com.amazon.audio.privilege.settings.control"
API还需要声明系统音频服务:
[wants]
[[wants.service]]
id = "com.amazon.audio.control"
使用的类型
请参阅音频核心类型
AudioVolumeTypeAudioVolumeFlagsAudioStatusAudioEventAudioDeviceAudioRoleAudioAttributesAudioContentTypeAudioUsageTypeAudioFlagsSinkFormatsSelectionPolicy
静态方法
AudioManager.setVolumeAsync(type, volume, flags)
描述
将某种音频的音量设置为指定音量。如果输入的音量大于100,则将音量设置为100。如果输入的音量小于0,则将音量设置为 0。
返回值
返回解析为AudioStatus类型的promise。
参数
需要权限com.amazon.audio.privilege.settings.control
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| type | AudioVolumeType | 是 | 表示用于音量调整的音频类型。 |
| volume | Int32 | 是 | 表示音频源音量百分比的整数值 |
| flags | AudioVolumeFlags | 否 | 设置标记,如果未输入,则默认为AudioVolumeFlags.VOLUME_FLAG_NONE |
代码示例
/*
将音频类型警报的音量设置为50%。在解析Promise之后,将返回的AudioStatus类型
存储在status中;如果解析Promise失败,
则存储undefined并打印错误
*/
const status = AudioManager.setVolumeAsync(AudioVolumeType.VOLUME_TYPE_ALARM, 50)
.then((status) => {return status;}).catch((error) => console.log(error));
AudioManager.getVolumeAsync(type)
描述
检索指定音频类型的音量。
返回值
返回解析为整数的Promise,表示特定类型的音量当前的百分比。
参数
需要权限com.amazon.audio.privilege.settings.control
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| type | AudioVolumeType | 是 | 表示用于音量调整的音频类型。 |
代码示例
/*
在解析Promise之后,检索音频类型媒体的音量百分比并将其存储在volume中
*/
const volume = AudioManager.getVolumeAsync(AudioVolumeType.VOLUME_TYPE_MEDIA)
.then((volume) => {return volume;}).catch((error) => console.log(error));
AudioManager.setMicMuteAsync(mute)
描述
根据布尔值输入,将所有麦克风输入静音或取消静音。
返回值
返回解析为AudioStatus类型的promise。
参数
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| mute | 布尔值 | 是 | 表示是将麦克风输入静音还是取消静音的布尔值。输入True将使麦克风输入静音,输入false将使麦克风输入取消静音。 |
代码示例
/*
将麦克风输入静音,并在解析Promise之后将返回的AudioStatus类型存储在status中
resolves
*/
const status = AudioManager.setMicMuteAsync(true).then((status) => {return status;}).catch((error) => console.log(error));
AudioManager.getMicMuteAsync()
描述
检索麦克风输入的静音状态。
返回值
返回解析为布尔值的Promise,表示麦克风输入的静音状态。
代码示例
/*
获取麦克风输入的静音状态,并在解析Promise之后将返回的布尔值
存储在mute_status中
*/
const mute_status = AudioManager.getMicMuteAsync()
.then((mute_status) => {return mute_status;}).catch((error) => console.log(error));
AudioManager.setGlobalVolumeMuteAsync(mute, flags)
描述
根据布尔值输入,在全局范围内静音或取消静音所有音频源类型。
返回值
返回解析为AudioStatus类型的promise。
参数
需要权限com.amazon.audio.privilege.settings.control
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| mute | 布尔值 | 是 | 表示是将所有音频源类型静音还是取消静音的布尔值 |
| flags | AudioVolumeFlags | 否 | 设置标记,如果未输入,则默认为AudioVolumeFlags.VOLUME_FLAG_NONE |
代码示例
/*
将全局静音设置为true,并在解析Promise之后将返回的AudioStatus类型
存储在status中
*/
const status = AudioManager.setGlobalVolumeMuteAsync(true).then((status) => {return status;}).catch((error) => console.log(error));
AudioManager.getGlobalVolumeMuteAsync()
描述
检索全局静音状态。
返回值
返回解析为布尔值的Promise,表示全局静音状态。
代码示例
/*
获取全局静音状态,并在解析Promise之后将布尔值存储在global_mute中
*/
const global_mute = AudioManager.getGlobalVolumeMuteAsync().then((global_mute) => {return global_mute;}).catch((error) => console.log(error));
AudioManager.registerAudioEventObserverAsync(callback)
描述
注册一个回调函数,一旦检测到音频更改事件即会执行该函数。一次只能注册一个回调函数。
返回值
返回解析为AudioStatus类型的promise。
参数
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| callback | 函数 | 是 | 回调函数,该函数接收一个事件并根据该事件执行某些操作 |
代码示例
/*
创建一个函数并将其注册到记录Audio Event Observer中,
以便在音频发生更改时执行此函数,并在解析Promise之后将返回的AudioStatus类型
存储在status中
*/
// 注册系统范围的音频事件
await AudioManager.registerAudioEventObserverAsync((event) => {
// 事件对象将根据事件类型包含不同的属性
switch (event.audioEvent) {
case AudioEvent.DEVICE_STATE_UPDATE:
// 当音频设备的连接状态发生变化时触发
// 参数:
// - device: AudioDevice枚举值
// - role: AudioRole枚举值
// - connect:表示设备是已连接 (true) 还是已断开连接 (false) 的布尔值
console.log(`Device ${event.device} with role ${event.role} ${event.connect ? 'connected' : 'disconnected'}`);
break;
case AudioEvent.VOLUME_UPDATE:
// 当任何音频类型的音量发生变化时触发
// 参数:
// - type: AudioVolumeType枚举值
// - volume:数字 (0-100)
console.log('Volume changed for:', event.audioEvent, 'to:', event.volume);
break;
case AudioEvent.GLOBAL_VOLUME_MUTE_UPDATE:
// 当全局静音状态发生变化时触发
// 参数:
// - mute:表示系统是否静音的布尔值
console.log('全局静音更新为状态:', event.mute);
break;
case AudioEvent.SERVER_DOWN:
// 当音频服务器变得不可用时触发
console.log('音频服务器停止');
break;
case AudioEvent.SERVER_UP:
// 当音频服务器变得可用时触发
console.log('音频服务器已启动');
break;
case AudioEvent.AUDIO_USAGE_STATE_CHANGE:
// 当音频使用状态发生变化时触发
// 参数:
// - usage: AudioUsageType枚举值
// - active:表示使用是否处于活动状态的布尔值
console.log('使用情况:', event.usage);
console.log('活动状态:', event.active);
break;
case AudioEvent.MIC_MUTE_STATE_UPDATE:
// 当麦克风静音状态发生变化时触发
// 参数:
// - state:表示麦克风是否静音的布尔值
console.log('麦克风静音状态已更改:', event.muteState);
break;
case AudioEvent.VOLUME_MUTE_UPDATE:
// 当特定音量类型的音量静音状态发生变化时触发
// 参数:
// - volumeType: AudioVolumeType枚举值
// - mute:表示类型是否静音的布尔值
console.log('Volume type: ', event.volumeType);
console.log('静音状态:', event.muteState);
break;
case AudioEvent.TELEPHONY_MUTE_UPDATE:
// 当电话静音状态发生变化时触发
// 参数:
// - deviceType: AudioDevice枚举值
// - address:表示设备地址的字符串
// - deviceName:表示设备名称的字符串
// - mute:表示电话是否静音的布尔值
console.log('电话静音更新!:');
console.log('设备类型:', event.deviceType);
console.log('设备地址:', event.deviceAddress);
console.log('设备名称:', event.deviceName);
console.log('设备静音状态:', event.muteState);
break;
}
});
// 清理
await AudioManager.unregisterAudioEventObserverAsync();
AudioManager.unregisterAudioEventObserverAsync()
描述
取消注册任何当前注册的回调函数。如果没有注册回调,则什么也不会发生。
返回值
返回解析为AudioStatus类型的promise。
代码示例
/*
取消注册回调函数,并在解析promise后将返回的AudioStatus类型
存储在status中
*/
const status = AudioManager.unregisterAudioEventObserverAsync().then((status) => {return status;}).catch((error) => console.log(error));
AudioManager.isServerReadyAsync()
描述
检查AudioServer是否准备好处理命令。
返回值
返回解析为布尔值的Promise,表示服务器是否准备就绪。
代码示例
// 如果服务器准备好接收命令,则返回true;如果未准备就绪,则返回false
const server_ready = AudioManager.isServerReadyAsync()
.then((ready) => {return ready;}).catch((error) => console.log(error));
AudioManager.setTelephonyMuteAsync(device, address, mute)
描述
将电话上行链路静音/取消静音。
返回值
返回带有音频状态码的Promise(AudioStatus类型)
参数
需要权限com.amazon.audio.privilege.settings.control
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| device | AudioDevice | 是 | 用于设置静音状态的设备类型 |
| address | string | 是 | 指向所请求设备的地址 |
| mute | 布尔值 | 是 | 请求的静音状态 |
代码示例
let muteStatus = await AudioManager.setTelephonyMuteAsync(AudioDevice.DEVICE_TELEPHONY, "0X859978AF", true);
if (muteStatus == 0) {
console.log("setTelephonyMuteAsync(): Result: SUCCESS")
status = status + "setTelephonyMuteAsync():\nResult: SUCCESS\n";
} else {
console.log("setTelephonyMuteAsync(): Result: ERROR: ", muteStatus);
status = status + "setTelephonyMuteAsync():\nResult: ERROR: " + muteStatus.toString() + "\n";
}
AudioManager.getTelephonyMuteAsync(device, address)
描述
将电话上行链路静音/取消静音。
返回值
返回带有音频状态码的Promise(AudioStatus类型)
参数
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| device | AudioDevice | 是 | 用于设置静音状态的设备类型 |
| address | string | 是 | 指向所请求设备的地址 |
代码示例
let muteStatus = await AudioManager.getTelephonyMuteAsync(AudioDevice.DEVICE_TELEPHONY, "0X859978AF");
console.log("getTelephonyMuteAsync(): SUCCESS, Mute state: ", Boolean(muteStatus));
AudioManager.setActiveVolumeAsync(volume)
描述
Set volume of active stream.
返回值
返回带有音频状态码的Promise(AudioStatus类型)
参数
需要权限com.amazon.audio.privilege.settings.control
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| volume | Int32/数字 | 是 | 请求的音量从0到100 |
代码示例
export const testSetActiveVolumeAsync = async (volume: number) => {
let requestStatus = await AudioManager.setActiveVolumeAsync(parseInt(volume));
if (requestStatus == 0) {
console.log("setActiveVolumeAsync SUCCESS");
} else {
console.log("setActiveVolumeAsync(): ERROR: " + requestStatus);
}
};
AudioManager.updateVolumeAsync(type, mode)
描述
更新特定类型的音量(例如音乐/通知等)
返回值
返回带有音频状态码的Promise(AudioStatus类型)
参数
需要权限com.amazon.audio.privilege.settings.control
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| type | AudioVolumeType | 是 | 要更新的音量类型 |
| mode | Int32 | 是 | 0 = 加,1 = 减 |
代码示例
const testUpdateVolumeAsync = async () => {
let updateStatus = await AudioManager.updateVolumeAsync(AudioVolumeType.VOLUME_TYPE_MEDIA, 0);
if (updateStatus == 0) {
console.log("updateVolumeAsync() SUCCESS");
} else {
console.log("updateVolumeAsync(): ERROR: " + updateStatus);
}
};
AudioManager.updateActiveVolumeAsync(update, fallbackType)
描述
更新活跃流的音量 如果没有活跃流,音频服务器将为回退类型设置音量
返回值
返回带有音频状态码的Promise(AudioStatus类型)
参数
需要权限com.amazon.audio.privilege.settings.control | 参数名称 | 类型 | 必填项 | 描述 | |— |— |— |— | | 更新 | Int32 | 是 |0 = 加,1 = 减 | | fallbackType | VolumeType | 是 | 要更新的音量类型|
代码示例
const testUpdateActiveVolumeAsync = async () => {
let updateStatus = await AudioManager.updateActiveVolumeAsync(0, AudioVolumeType.VOLUME_TYPE_MEDIA);
if (updateStatus == 0) {
console.log("updateActiveVolumeAsync() SUCCESS");
} else {
console.log("updateActiveVolumeAsync(): ERROR: " + updateStatus);
}
};
AudioManager.setMuteAsync(volType, mute)
描述
为音量类型设置静音。如果为true,则无论单个流音量如何,音量类型的音频输出都将被静音。
返回值
返回带有音频状态码的Promise(AudioStatus类型)
参数
需要权限com.amazon.audio.privilege.settings.control
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| volType | AudioVolumeType | 是 | 要静音的音量类型 |
| mute | 布尔值 | 是 | 已请求静音状态 |
代码示例
const testSetMuteAsync = async () => {
let updateStatus = await AudioManager.setMuteAsync(AudioVolumeType.VOLUME_TYPE_MEDIA, true);
if (updateStatus == 0) {
console.log("setMuteAsync() SUCCESS");
} else {
console.log("setMuteAsync(): ERROR: " + updateStatus);
}
};
AudioManager.getMuteAsync(volType)
描述
查询音频音量类型当前是否为静音状态
返回值
返回静音状态的Promise(布尔值)
参数
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| volType | AudioVolumeType | 是 | 要查询静音状态的音量类型 |
代码示例
const testGetMuteAsync = async () => {
let muteStatus = await AudioManager.setMuteAsync(AudioVolumeType.VOLUME_TYPE_MEDIA);
console.log("setMuteAsync(): SUCCESS, Mute state: ", Boolean(muteStatus));
};
AudioManager.setMaxVolumeAsync(maxVolume)
描述
设置最大音量限制。客户可以使用此API来设置所有类型音量级别的最大限制。默认情况下,最大音量限制为100,使用此API可以将其设置为0-100。
返回值
返回带有音频状态码的Promise(AudioStatus类型)
参数
需要权限com.amazon.audio.privilege.settings.control
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| maxVolume | Int32 | 是 | 新的最大限制占真实最大音量的百分比 |
代码示例
const testSetMaxVolume = async () => {
let volumeChangeStatus = await AudioManager.setMaxVolumeAsync(50);
if (volumeChangeStatus == 0) {
console.log("setMaxVolumeAsync() SUCCESS");
} else {
console.log("setMaxVolumeAsync(): ERROR: " + volumeChangeStatus);
}
};
AudioManager.getMaxVolumeAsync()
描述
获取最大音量限制 使用setMaxVolume() API或系统默认值 (0-100) 检索先前设置的最大音量限制。
返回值
返回带有当前最大音量限制 (Int32) 的Promise。
参数
| 参数名称 | 类型 | 必填项 | 描述 | | ————– | —- | ——– | ———– |
代码示例
const testGetMaxVolume = async () => {
let maxVolume = await AudioManager.getMaxVolumeAsync();
console.log("getMaxVolumeAsync(): SUCCESS, Max volume: ", maxVolume);
};
AudioManager.getSupportedPlaybackConfigurationsAsync(attributes, deviceType)
描述
设置最大音量限制。客户可以使用此API来设置所有类型音量级别的最大限制。默认情况下,最大音量限制为100,使用此API可以将其设置为0-100。
返回值
返回带有对象数组的Promise,其中包含给定参数的所有支持的音频配置。收到的对象的结构包含:{
- sampleRate: AudioSampleRate
- channelMask: AudioChannelMask
- format: AudioSampleFormat
- layout: SampleLayout
}
参数
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| attributes | AudioAttributes | 是 | 要查询的音频属性 |
| deviceType | AudioDevice | 是 | 要查询的音频设备类型 |
注意: 对当前音频设备使用AudioDevice.DEVICE_DEFAULT。
代码示例
let supportedAudioConfigs = await AudioManager.getSupportedPlaybackConfigurationsAsync(configAttr, AudioDevice.DEVICE_DEFAULT);
for (let audioConfig: supportedAudioConfigs) {
console.log("format", audioConfig.format);
console.log("采样率", audioConfig.sampleRate);
console.log("channel mask", audioConfig.channelMask);
console.log("layout", audioConfig.layout);
}
AudioManager.setSinkFormatsSelectionPolicyAsync(policy)
描述
设置音频接收器格式选择策略
返回值
返回带有音频状态码的Promise(AudioStatus类型)
参数
| 参数名 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| policy | SinkFormatsSelectionPolicy | 是 | 将要应用的接收器策略 |
代码示例
const testSetSinkFormatsSelectionPolicyAsync = async () => {
let sinkStatus = await AudioManager.setSinkFormatsSelectionPolicyAsync(SinkFormatsSelectionPolicy.AUTO);
if (sinkStatus == 0) {
console.log("setSinkFormatsSelectionPolicyAsync(): Result: SUCCESS")
} else {
console.log("setSinkFormatsSelectionPolicyAsync(): Result: ERROR: ", sinkStatus);
}
};
AudioManager.getSinkFormatsSelectionPolicyAsync()
描述
获取当前的音频接收器模式格式选择策略
返回值
返回带有当前选择策略的Promise (Int32)
参数
| 参数名称 | 类型 | 必填项 | 描述 | | ————– | —- | ——– | ———– |
代码示例
const testGetSinkFormatsSelectionPolicyAsync = async () => {
let currentSinkPolicy = await AudioManager.getSinkFormatsSelectionPolicyAsync();
console.log("getSinkFormatsSelectionPolicyAsync() Current format: ", currentSinkPolicy);
};
AudioManager.getSupportedSinkFormatsSelectionPoliciesAsync()
描述
获取所有支持的接收器格式选择策略列表
返回值
返回包含所有支持策略的数组的Promise。
参数
| 参数名称 | 类型 | 必填项 | 描述 | | ————– | —- | ——– | ———– |
代码示例
const testGetSupportedSinkFormatsSelectionPoliciesAsync = async () => {
let supportedSinkFormats = await AudioManager.getSupportedSinkFormatsSelectionPoliciesAsync();
if (supportedSinkFormats.length > 0) {
supportedSinkFormats.forEach(data => {
console.log("Supported policy (integer representation): ", parseInt(data), "\n");
});
}
};
Last updated: 2025年10月2日

