as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
AWS
文档
Support
Contact Us
My Cases
新手入门
设计和开发
应用发布
参考
支持

Audio Manager

Audio Manager

音频管理器允许进行音频管理,例如音量调整和静音控制。

  • TOC

所需权限

API需要特定权限才能执行某些操作:

[[needs.privilege]]
id = "com.amazon.audio.privilege.settings.control"

API还需要声明系统音频服务:

[wants]
[[wants.service]]
id = "com.amazon.audio.control"

使用的类型

请参阅音频核心类型

  • AudioVolumeType
  • AudioVolumeFlags
  • AudioStatus
  • AudioEvent
  • AudioDevice
  • AudioRole
  • AudioAttributes
  • AudioContentType
  • AudioUsageType
  • AudioFlags
  • SinkFormatsSelectionPolicy

静态方法

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日