Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

@amazon-devices/keplerscript-audio-lib

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发布说明。

Kepler音频接口API提供在应用中管理音频的功能。它由几个关键组件组成：

音频管理器：处理音量、静音和设备管理等系统级音频控制。
音频播放：使用可配置属性启用音频流播放。
音频焦点管理：管理不同音频流的音频焦点。

该API专门用于适用于Kepler的React Native应用，为构建具有以下特性的支持音频的应用奠定了基础：

不同音频类型的音量和静音控制
音频设备管理
系统声音管理
音频焦点处理
音频流配置和管理

开始使用

设置

将以下库依赖项添加到package.json文件的dependencies部分。
已复制到剪贴板。
```
 "@amazon-devices/keplerscript-audio-lib": "~2.0.0"
```

在您的manifest.toml中添加以下权限和服务请求。

已复制到剪贴板。

[[needs.privilege]]
id = "com.amazon.audio.privilege.microphone.access" 

[wants]

// 只添加所需的服务
[[wants.service]]
id = "com.amazon.audio.stream" // 用于使用AudioStream API进行音频播放。
[[wants.service]]
id = "com.amazon.audio.control" // 用于AudioManager、AudioFocus API的使用。
[[wants.service]]
id = "com.amazon.audio.system" // 用于使用SoundPlayer或SystemSound API以低延迟播放简短的声音。

有关清单文件的needs部分的更多信息，请参阅清单needs部分。

用法

将KeplerAudioInterface Turbo模块导入您的项目。

已复制到剪贴板。

import { 
    AudioManager,
    AudioPlaybackStream,
    AudioPlaybackStreamBuilder,
    AudioFocusManager,
    AudioFocusSession
} from '@amazon-devices/keplerscript-audio-lib';

Audio

管理音频音量

已复制到剪贴板。

// 设置媒体音量
await AudioManager.setVolumeAsync(AudioVolumeType.VOLUME_TYPE_MEDIA, 75, AudioVolumeFlags.VOLUME_FLAG_SHOW_UI);

// 获取当前音量
const volume = await AudioManager.getVolumeAsync(AudioVolumeType.VOLUME_TYPE_MEDIA);

创建和管理音频播放

已复制到剪贴板。

// 创建播放流
const builder = new AudioPlaybackStreamBuilder();
builder.setAudioConfig({
    sampleRate: AudioSampleRate.SAMPLE_RATE_44_1_KHZ,
    channelMask: AudioChannelMask.CHANNEL_STEREO,
    format: AudioSampleFormat.FORMAT_PCM_16_BIT
});
builder.setAudioAttributes({
    contentType: AudioContentType.CONTENT_TYPE_MUSIC,
    usage: AudioUsageType.USAGE_MEDIA,
    flags: AudioFlags.FLAG_NONE
});

const playbackStream = await builder.buildAsync();
await playbackStream.startAsync();

管理音频焦点

已复制到剪贴板。

// 创建并请求音频焦点
const focusSession = await AudioFocusManager.createAudioFocusSessionAsync();
await focusSession.requestAudioFocusAsync({
    usage: AudioUsageType.USAGE_MEDIA
});

// 注册焦点变化
await focusSession.registerAudioFocusListenerAsync((focusChange) => {
    console.log('焦点已变化：', focusChange);
});

事件观察程序

音频管理器事件

已复制到剪贴板。

// 注册系统范围的音频事件
await AudioManager.registerAudioEventObserverAsync((event) => {
    // 事件对象将根据事件类型包含不同的属性
    switch (event.audioEvent) {
        case AudioEvent.DEVICE_STATE_UPDATE:
            // 当音频设备的连接状态发生变化时触发
            // 参数：
            // - device： AudioDevice枚举值
            // - role： AudioRole枚举值
            // - connect：表示设备是已连接 (true) 还是已断开连接 (false) 的布尔值
            console.log(`设备${event.device}（具有角色${event.role}）${event.connect ? '已连接' : '断开连接'}`);
            break;

        case AudioEvent.VOLUME_UPDATE:
            // 当任何音频类型的音量发生变化时触发
            // 参数：
            // - type： AudioVolumeType枚举值
            // - volume：数字 (0-100)
            console.log('音量已对此项更改：', event.type, '为：', 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('音量类型：', 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();

播放流

已复制到剪贴板。

const playbackStream = await builder.buildAsync();

await playbackStream.registerEventObserverAsync((event) => {
    switch (event.type) {
        case AudioPlaybackEvent.DIED:
            // 当播放流变得不可用时触发
            break;

        case AudioPlaybackEvent.RECOVERED:
            // 当播放流从终止状态恢复时触发
            break;

        case AudioPlaybackEvent.STOPPED:
            // 当播放流停止时触发
            break;

        case AudioPlaybackEvent.MUTE_STATE_UPDATE:
            // 当流的静音状态发生变化时触发
            // 参数：
            // - muted：表示流是否静音的布尔值
            console.log('MuteState: ', event.muteState);
            break;

        case AudioPlaybackEvent.FRAME_UNDERRUN:
            // 发生缓冲区欠载时触发
            // 参数：
            // - size：表示欠载大小的数字（以帧为单位）
            console.log('缓冲区欠载计数：', event.underrunCount);
            break;
    }
});

// 清理
await playbackStream.unregisterEventObserverAsync();

音频焦点

已复制到剪贴板。

const focusSession = await AudioFocusManager.createAudioFocusSessionAsync();

await focusSession.registerAudioFocusListenerAsync((focusChange) => {
    switch (focusChange.type) {
        case AudioFocusChange.GRANTED:
            // 当授予音频焦点时触发
            break;

        case AudioFocusChange.RELEASED:
            // 当释放音频焦点时触发
            break;

        case AudioFocusChange.DUCKED:
            // 当应该调低音频（降低音量）时触发
            break;

        case AudioFocusChange.PAUSED:
            // 当应该暂停音频时触发
            break;

        case AudioFocusChange.STOPPED:
            // 当应该停止音频时触发
            break;
    }
});

// 清理
await focusSession.unregisterAudioFocusListenerAsync();

故障排除

权限问题：
1. 错误：没有权限例外
2. 解决方案：确保您已在manifest.toml中声明了所需的权限。
未创建AudioManager：
1. 错误：getAudioManager() 返回undefined
2. 解决方案：确保您在自己的应用环境中正确设置KeplerAudioInterface Turbo模块。
无效的观察程序或回调：
1. 错误：“not invoking Callback“（未调用回调）
2. 解决方案：确保您正确订阅了观察程序。
取消订阅失败：
1. 错误：取消订阅受拒
2. 解决方案：检查您使用的观察程序对象是否正确，以及它是否尚未被用来取消订阅。

其他资源

Audio Manager
音频播放流生成器
音频播放流
音频焦点会话
音频焦点管理器
有关特定问题或故障，请联系音频开发支持团队。

文件

枚举

类

Last updated: 2025年11月17日