bevy-audio

Bevy 0.19 — 音频

何时使用此技能

• 通过 AudioPlayer 和音频接收器组件生成或控制片段／循环播放。
• 构建音乐／环境音过渡、混音类别、闪避或暂停策略。
• 添加空间音源／监听器，或定义内置 HRTF／效果处理的边界。
• 在浏览器上发布音频，或评估用于图形后端的 bevy_seedling 0.8。

对于简单片段、循环播放、播放控制和简单空间立体声，请使用 Bevy 内置的基于实体的音频。为类别和过渡添加应用级混音策略。只有当实测或设计需求超出此范围时，才改用音频图形库。

规范模式

use bevy::{audio::Volume, prelude::*};

#[derive(Component)]
struct Music;

fn start_music(mut commands: Commands, assets: Res<AssetServer>) {
    commands.spawn((
        Name::new("Exploration music"),
        Music,
        AudioPlayer::new(assets.load("audio/exploration.ogg")),
        PlaybackSettings::LOOP.with_volume(Volume::Decibels(-9.0)),
    ));
}

fn mute_music(mut sinks: Query<&mut AudioSink, With<Music>>) {
    for mut sink in &mut sinks {
        sink.mute();
    }
}

非空间播放开始后，Bevy 会插入 AudioSink；空间播放则会插入 SpatialAudioSink。查询音频接收器，即可实时调整音量、静音、暂停、速度、位置、跳转和停止。更改 PlaybackSettings 或 GlobalVolume 不会更新已经播放的音频。

PlaybackSettings::{ONCE, LOOP, DESPAWN, REMOVE} 定义播放结束后的处理方式。ONCE 播放器的音频接收器耗尽后，无法直接重新播放；需要移除／重新插入音频组件，或生成新的播放器。在 AudioPlayer 仍存在时移除音频接收器，会导致未更改的音源重新开始播放。

注意事项

• PlaybackSettings 和 GlobalVolume 只影响初始播放，不影响已有的音频接收器。
• 只有播放开始后才会出现音频接收器；查询时应将其设为可选。
• ONCE 播放耗尽后，若不替换音频组件便无法重新播放。
• 在播放器未更改且仍存在时移除音频接收器，会导致音源重新开始播放。
• 内置空间音频仅提供立体声声像移动，不支持 HRTF 或通用效果图。

空间音频的边界

fn spawn_spatial_loop(mut commands: Commands, assets: Res<AssetServer>) {
    commands.spawn((
        SpatialListener::new(0.2),
        Transform::default(),
    ));
    commands.spawn((
        AudioPlayer::new(assets.load("audio/generator.ogg")),
        PlaybackSettings::LOOP.with_spatial(true),
        Transform::from_xyz(4.0, 0.0, 0.0),
    ));
}

只保留一个 SpatialListener；将其附加到权威的监听器／摄像机姿态上。如果世界单位与音频距离不匹配，请配置 SpatialScale。内置空间化仅提供简单的左右立体声声像移动，不支持 HRTF 或完整的 3D 声学模型。

混音组和过渡

内置音频不提供通用总线／效果图。将类别（Master、Music、Sfx、Dialogue、Ambience、Ui）建模为应用状态，并为播放器实体添加标签。根据主音量 × 分组音量 × 过渡／闪避 × 音源增益计算有效增益，然后写入音频接收器。以分贝或感知上更实用的曲线存储滑块值，不要使用原始线性 UI，以免大部分有效范围被压缩到几个像素内。

更改音乐／环境音时，让旧循环和新循环重叠，并根据暂停策略使用真实时间／虚拟时间进行交叉淡化。只有当旧实体的音频接收器达到静音后，才将其销毁。对于对延迟敏感的过渡，应提前加载资源，并定义新曲目尚未就绪时的处理方式。

浏览器规则

浏览器通常会阻止在用户激活前播放可听见的音频。应将音频解锁视为明确的应用状态：让首次主动输入恢复／启动音频；如果播放受阻，则保留待处理请求，并提供可用的静音／解锁控件。测试刷新、标签页切换到后台／前台、设备更改和移动浏览器；启动时能播放，并不意味着所有浏览器都会允许播放。

内置音频与 Seedling

简单播放、控制和空间声像移动请选择 Bevy 内置音频。对于 Bevy 0.19，当需要总线／效果、池化发声器、采样级调度、更丰富的路由或通过 Firewheel 技术栈实现 HRTF 时，可使用兼容的基于图形的方案 bevy_seedling 0.8。HRTF 并非默认功能；请启用 Seedling 的 hrtf 功能（仅在需要所有嵌入的受试者时才启用 hrtf_subjects）。使用 Seedling 时，请禁用 Bevy 内置的 audio 功能，避免两个后端／类型相互冲突。请固定并测试具体的库版本和平台。

选择相关的深入指南

问题	阅读
播放器、播放模式、输出端、重放和清理	内置音频
混音模型、交叉淡化、闪避、暂停和资源生命周期	混音、生命周期与过渡
空间音频限制、浏览器解锁、无障碍和 Seedling 边界	空间音频、Web 与 Seedling

检查清单

• 播放实体的所有权和完成模式经过有意设置。
• 运行时更改针对输出端，而不是 PlaybackSettings。
• 更改组或主音量时，会更新正在播放的输出端，且不会丢失源音量。
• 过渡能处理延迟加载的资源、快速状态变化、暂停和实体清理。
• 只存在一个监听器，且缩放和位姿遵循预期视点。
• 浏览器音频解锁失败会明确显示，并可恢复。
• 对话配有字幕，重要音频提示也有非音频替代方式。
• 无头测试会测试混音器／状态逻辑，且不需要音频设备。

另请参阅

• bevy-a11y — 字幕、提示的替代方式、动态范围和控件。
• bevy-assets — 加载状态、句柄和资源生命周期。
• bevy-testing — 确定性的混音器／过渡测试。
• Bevy 音频模块
• bevy_seedling 0.8