SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场audio-and-metasounds

audio-and-metasounds

编程与开发

查看项目

更新于 11-06 16:19

技能介绍

用途

该技能用于在 Unreal Engine 中播放和控制音频，覆盖从 C++ 代码触发音效、音乐、UI 声音，到 3D 空间化、混音、程序化音频与节拍同步的完整流程。

主要能力

声音资产类型

  • USoundWave：导入的 PCM 音频片段，作为原始音频，在 SoundCue 或 MetaSound 中组合变化。
  • USoundCue：传统节点图，适合对波形做简单随机化或调制。
  • UMetaSoundSource：现代图，带类型化输入输出，适合程序化、参数驱动、可组合 DSP 的音频。
  • USoundBase：抽象基类，所有播放函数接受的类型。

新动态音频建议优先使用 MetaSounds；SoundCues 仍完全支持，适合轻量随机化。USoundWave 不会在游戏代码中直接播放，它是被 cue 或 MetaSound 图引用的叶子资产。

从 C++ 播放声音

  • UGameplayStatics::PlaySound2D：2D 播放（UI、音乐），即发即忘，无空间化。
  • UGameplayStatics::PlaySoundAtLocation：在世界位置 3D 播放，即发即忘。
  • UGameplayStatics::SpawnSoundAttached：附着到组件并返回可控的 UAudioComponent，可后续 FadeIn、FadeOut、设置参数。

PlaySound* 函数为即发即忘；需要停止、淡入淡出、改参数或响应 OnAudioFinished 时，应使用 SpawnSound* 或放置在 actor 上的 UAudioComponent，并将其存入 UPROPERTY() 成员以防播放中被 GC 回收。

3D 空间化与衰减

USoundAttenuation 资产包含距离模型与衰减半径、空间化算法（声像或 HRTF 插件）、遮挡、混响发送、空气吸收和优先级衰减。可在声音资产上指定，也可在每次调用时覆盖。没有衰减资产的声音会以平坦 2D 播放，无论音频组件在世界何处。内半径定义恒定音量区，衰减从内半径开始，到衰减距离处降为零。

混音：声音类、子混音、并发

  • Sound Class（USoundClass）：将声音分组（SFX / Music / Voice），共享音量、音高和属性设置。
  • Sound Mix（USoundMix）：推送临时类调整，例如 Voice 播放时压低 Music。
  • Submix（USoundSubmix）：DSP 总线，应用效果（混响、EQ、压缩）、计量、录制音频。
  • Concurrency（USoundConcurrency）：限制组内同时发声数，达到上限时选择抢占规则。

声音默认路由到其声音类的子混音。子混音发送可让声音复制信号到额外总线（如混响或分析总线）而不离开主链。Audio Buses（UAudioBus）是另一种总线类型，在源效果前或后路由，适合侧链。

MetaSound 运行时参数

MetaSound Source 暴露图中声明的类型化输入（float、int32、bool、trigger、wave），可从所属音频组件驱动：

AC->SetFloatParameter(TEXT("Intensity"),   0.8f);
AC->SetBoolParameter(TEXT("IsUnderwater"), true);
AC->SetIntParameter(TEXT("FootSurface"),   2);
AC->SetTriggerParameter(TEXT("OnImpact"));
AC->SetWaveParameter(TEXT("ImpactWave"), GroundHitWave);

输入名称是大小写敏感的 FName，必须与图的 Input 节点名称完全匹配。不匹配不会报错也不会生效。MetaSounds 也暴露输出（如 float 计量值），可通过 UMetaSoundSource::GetGeneratorForAudioComponent 获得的 UMetasoundGeneratorHandle 读取，仅在声音播放时可用。

Quartz：节拍量化播放

Quartz 提供游戏线程音乐时钟（UQuartzClockHandle），在拍/小节边界触发事件，用于精确按拍启动声音而不漂移：

UQuartzSubsystem* Quartz = UQuartzSubsystem::Get(GetWorld());
UQuartzClockHandle* Clock = Quartz->CreateNewClock(this, TEXT("MusicClock"),
    FQuartzClockSettings{});

FQuartzQuantizationBoundary Boundary;
Boundary.Quantization = EQuartzCommandQuantization::Bar;
Boundary.BoundaryType = EQuarztQuantizationBoundaryType::FromNow;
AC->PlayQuantized(GetWorld(), Clock, Boundary, {});

从游戏与动画触发

脚步、撞击和武器声音应从 Anim Notifies 或游戏事件触发，而非手动计时器，以在任何播放速率或时间膨胀下保持音频同步。高频撞击应使用并发限制同时实例数并选择合适抢占规则。

使用方式

该技能以参考文档形式组织，包含：

  • references/audiocomponent-and-playback.md：完整 UAudioComponent API、播放状态机、委托和 Quartz。
  • references/attenuation-and-spatialization.md：FSoundAttenuationSettings 字段、距离模型、HRTF、Audio Gameplay Volumes。
  • references/mixing-classes-submixes-concurrency.md：并发抢占规则、子混音效果链、音频总线发送、动态混音。
  • references/metasound-parameters-and-builder.md：运行时参数 API、输出监视、MetaSound Builder API。

适用场景

  • 从 C++ 播放 SFX（枪声、脚步、撞击）、音乐或 UI 声音。
  • 将循环或位置声音附着到 actor（引擎嗡鸣、环境音）。
  • 3D 空间化与距离衰减配置。
  • 混音：音量分组、对话时压低音乐、限制声音数。
  • 通过 MetaSounds 实现程序化/参数化音频（变化的脚步、自适应音乐）。
  • 使用 Quartz 时钟系统实现节拍同步音频事件。
  • 通过 Builder API 在运行时构建或修改 MetaSound 图。

限制与注意事项

  • 即发即忘与需要控制混淆：PlaySound* 无返回值；需要后续停止、淡入淡出或改参数应使用 SpawnSound* 或组件。
  • 无衰减资产时 3D 声音按 2D 播放，无衰减。
  • MetaSounds 参数名不匹配会静默无效，无日志警告。
  • 无并发限制会导致声音泛滥和削波。
  • 音频组件未放入 UPROPERTY 会在播放中被 GC 回收，声音停止。
  • 对 SoundCue 调用 SetWaveParameter 无效；wave 参数针对 MetaSound wave 输入（或传统 SoundCue wave 参数，属不同系统）。
  • 组件上设置 bDisableParameterUpdatesWhilePlaying 时，参数调用会排队但不转发到活动声音。
  • 仅导入 PCM WAV；变化应在 MetaSound 或 SoundCue 图中构建，而非烘焙进文件。
  • 虚拟化：USoundBase 上的 EVirtualizationMode 控制循环声音被逐出时是静默继续（PlayWhenSilent）、重启还是丢弃。默认 Disabled；忘记配置虚拟化是重负载下音乐“消失”的常见原因。

版本说明

  • MetaSounds 在 UE5.0 引入；Builder API（Beta）在 5.4–5.5 显著扩展；通过 UMetasoundGeneratorHandle 的输出监视在 5.4 稳定。
  • EVirtualizationMode::SeekRestart 在 UE 5.6–5.8 为实验性（SoundBase.h:76）。
  • FAudioComponentParam（旧命名参数结构）在 UE 5.0 弃用；改用 FAudioParameter / SetFloatParameter 等。
  • UMetaSoundSource 上的 OnGeneratorInstanceCreated / OnGeneratorInstanceDestroyed 在 5.6 弃用；改用 OnGeneratorInstanceInfoCreated / OnGeneratorInstanceInfoDestroyed（MetasoundSource.h:338–344）。