生产工作流程
AMS 将音频分析转换为可复用数据和运行时控制。编辑器提供四个专用工作区,运行时模块则提供组件、资源、Blueprint 辅助函数和 C++ 接口。
PAUTINKAAudio Motion System 1.0
概览
AMS 将音频分析转换为可复用数据和运行时控制。编辑器提供四个专用工作区,运行时模块则提供组件、资源、Blueprint 辅助函数和 C++ 接口。
预览用于快速迭代;最终结果通过可复用资源和运行时组件进入实际项目。
技术信息
安装
AudioMotionSystem 放到 [Project]/Plugins/.Intermediate 或 Saved 文件夹到其他电脑。
快速开始
Connect Audio Motion 或已 Bake 的 Audio Motion Clip.语音驱动控制
音乐驱动 Motion
抑制全局位移。
用于原地播放。使用规划轨迹。
当序列需要移动时使用。使用稳定后的全局轨迹路径。
当规划位移需要稳定处理时使用。
标量输出
创建 Audio Motion Dialogue Curve 当你需要用于 Blueprint 或材质参数的单个预计算标量值时使用。
运行时直接读取预计算曲线,无需重复编辑器分析。
Connect Dialogue Curve Asset 会在目标 Actor 上创建或复用 Audio Motion Dialogue Curve 组件,并使用资源设置启动它。
当前标量值可通过 Get Dialogue Curve Value。如果启用了材质输出,相同数值会写入所选标量参数。
Animation Sequence + Dialogue
根据参考层级和几何结构构建 Source-to-Target Mapping。
目标 Rig 的原生动画会跳过 retargeting。以 Auto 为基础,可替换或清除需要修正的 Mapping。
用于特殊或低置信度情况。对已知 Source / Target 配对复用已保存的 Retarget Profile。
最适合重复的生产工作。
架构
AudioMotionRuntime运行时音频评估、组件、Blueprint 辅助函数、资源、Mapping 和 Choreography 数据。Game + EditorAudioMotionAnimation运行时运行时 AnimGraph 控制节点。动画系统AudioMotionEditor编辑器Tools 窗口、资源工厂、Preview、制作、Bake 和 Animation Mixer。仅编辑器AudioMotionRuntime 并在需要时依赖 AudioMotionAnimation。不要添加 AudioMotionEditor 依赖到 shipping runtime 代码。运行时模块会将紧凑的 AMS Vocabulary 与 view 文件从 Content/AMSData 作为 NonUFS 运行时依赖进行暂存。
*.amsvocab.json
*.amsvocabz
*.amsview.json
如果存在,运行时构建规则支持的项目侧 Vocabulary 文件夹也可以一起暂存。
主要集成节点
Blueprint 辅助函数会在目标 Actor 上创建或复用 AMS 组件。必填输入会被验证;设置失败时返回 None / nullptr.
UAudioMotionComponent*创建或复用主 Audio Motion Component,准备 Voice Sound 路径,重建 Dialogue bindings,连接目标 Rig 组件并开始处理。
UAudioMotionComponent*将 baked Audio Motion Clip 连接到目标 Actor。此路径不需要播放源音频。
UAudioMotionComponent*将主组件配置为音乐驱动处理,并把所选 SoundWave 作为 Background Music。处理可以独立于 Voice 源继续运行。
UAudioMotionComponent*将 Voice Sound 和独立 Background Music 连接到同一个 Audio Motion Component。当 Voice 播放停止后,组件仍继续处理,以便音乐路径继续运行。
UAudioMotionComponent*查找目标 Actor 上第一个 Audio Motion Component;如果没有则返回 None。
UAudioMotionDialogueCurveComponent*创建或复用 Dialogue Curve 组件,并将其标量输出连接到 Blueprint;默认情况下也连接到材质标量参数。
UAudioMotionDialogueCurveComponent*创建或复用 Dialogue Curve 组件,并应用完整生成的 Dialogue Curve 资源:源声音、baked 曲线、响应设置、循环状态、材质目标、材质槽和参数名称。
UAudioMotionPulseComponent*创建或复用紧凑的标量 Audio Pulse 组件。来源可以是 Voice、整体音乐能量、频段、onset、beat 或自定义 Audio Motion 通道。
运行时控制
头文件: AudioMotionComponent.h · 模块: AudioMotionRuntime
SetAudioSource(UAudioComponent*)设置 Audio Component 输入并更新源状态。SetSourceSound(USoundWave*)设置 SoundWave 源路径。SetSourceClip(UAudioMotionClip*)设置 baked Audio Motion Clip 源。StartProcessing(bool)开始评估;可选择重置播放时间。StopProcessing(bool)停止评估;可选择停止源音频。ResetProcessing(float)将处理器状态重置到指定时间。PushEnvelopeValue(float)为 Manual Envelope 输入模式提供手动 envelope 值。EvaluateAtTime(float,float)评估明确指定的时间和 envelope 值。EvaluateSourceAtTime(float)在指定时间评估当前配置的源。ApplyExternalFrame(FAudioMotionFrame,bool)应用预构建的 frame,并可选择应用自动 bindings。RefreshAutomaticConnection()重新解析自动运行时目标连接。ResetAutomaticBindings()清除缓存的自动 binding 状态。SetTargetSkeletalMesh(...)为运行时应用明确设置目标 Rig 组件。GetChannelValue(EAudioMotionChannel)从当前 frame 读取一个值。GetPlaybackTimeSeconds()返回当前主播放时钟。GetSourceDurationSeconds()可用时返回已配置源的时长。IsProcessing()返回处理状态。SetBackgroundMusic(...)设置独立的 Background Music SoundWave。PlayBackgroundMusic(float)从指定的本地时间开始播放 Background Music。StopBackgroundMusic()停止 Background Music 播放。SetBackgroundMusicVolume(float)更新 Background Music 音量。IsBackgroundMusicPlaying()返回 Background Music 播放状态。On Frame UpdatedOn Speech Value UpdatedOn Speech StartedOn Speech Stopped头文件: AudioMotionPulseComponent.h · 模块: AudioMotionRuntime
读取所选 AMS 通道或独立声音,通过 Input/Output 范围并结合 attack/release 平滑进行映射,可选择写入动态材质标量,并提供阈值事件。
StartPulse()开始 tick 和源评估。StopPulse(bool)停止评估;可选择停止独立音频。SetStandaloneSound(USoundWave*,bool)更改独立源,并可选择立即播放。GetPulseValue()返回当前标量输出。On Pulse Value UpdatedOn Pulse头文件: AudioMotionDialogueCurveComponent.h · 模块: AudioMotionRuntime
派生自 Audio Motion Pulse Component。分配 Curve Asset 后,其 baked 曲线成为标量源,并把播放/材质设置复制到组件。
SetCurveAsset(UAudioMotionDialogueCurveAsset*,bool)分配资源,并可选择启动其源声音。GetDialogueCurveValue()返回当前 baked 曲线标量值。公共头文件
只添加你自己的代码实际使用的模块。
PublicDependencyModuleNames.AddRange(new[]
{
"AudioMotionRuntime",
"AudioMotionAnimation" // only when your runtime animation module needs FAnimNode_AudioMotion
});
AudioMotionEditor 只能从 Editor 模块添加。不要让 shipping runtime 模块依赖 AMS Editor 模块。UAudioMotionComponentAudioMotionComponent.h主要运行时求值器:源选择、处理时钟、帧求值、自动连接、背景音乐和通道读取。UAudioMotionBlueprintLibraryAudioMotionBlueprintLibrary.hBlueprint Connect 节点使用的静态便捷层,也可直接从 C++ 调用。UAudioMotionProfileAudioMotionProfile.h包含 envelope、Dialogue、音乐和求值设置的 Primary Data Asset。UAudioMotionBindingProfileAudioMotionBindingProfile.h用于目标 Mapping 的 Primary Data Asset。公共 helper:FindDialogueRole、EnsureDialogueRoles、RebuildDialogueBindings。UAudioMotionClipAudioMotionClip.hBaked Dialogue 曲线。EvaluateChannel、EvaluateFrame、BuildFromFrames、ClearClip、IsEmpty。UAudioMotionDialogueCurveAssetAudioMotionDialogueCurveAsset.h可移植标量曲线资源。EvaluateCurve 和 GetSourceSound。UAudioMotionPulseComponentAudioMotionPulseComponent.h带材质输出和触发事件的标量音频反应组件。UAudioMotionDialogueCurveComponentAudioMotionDialogueCurveComponent.h派生自 Pulse、用于求值 baked Dialogue Curve 资源的组件。FAudioMotionDialogueProcessorAudioMotionDialogueProcessor.h确定性 Dialogue 处理器。Reset(seed)、Evaluate(...)。FAudioMotionMusicAnalyzerAudioMotionMusicAnalyzer.h用于 SoundWave 或 Audio Component 求值的音乐分析 helper。FAudioMotionFrameAudioMotionTypes.h共享帧容器。GetChannel / SetChannel,以及 Dialogue 和音乐通道值。UAMSMotionDataSubsystemAMSMotionDataSubsystem.h加载紧凑 Vocabulary 数据的引擎 subsystem。ReloadData、GetVocabulary、GetDefaultVocabulary、GetVocabularyIds。UAMSMotionVocabularyAMSMotionVocabulary.hVocabulary 元数据和 Motion 引用。FindMotion、GetMotionCount、ValidateVocabulary。UAMSMotionClipAMSMotionClip.h测量得到的 Motion Unit 数据:轨道求值、pose 应用、authoring 验证和过渡元数据。UAMSMotionLibraryAMSMotionLibrary.h由 Vocabulary 和 Book 数据构建、供 Planner 使用的候选库。UAMSPerformanceBookAMSPerformanceBook.hChoreography 策略/语法 Data Asset,包含内置 Book helper、验证和 family rules。FAMSPerformancePlannerAMSPerformancePlanner.h确定性的静态 BuildPlan 接口:Book/Library + Analysis + Planner Settings → Motion Sequence。UAMSMotionSequenceAMSMotionSequence.h计划好的 Choreography sequence:持续时间/时间归一化、pose 求值、compiled track 构建与验证。UAMSRigProfileAMSRigProfile.hRig Mapping 配置:解析 Mapping、从参考层级构建、手动 overrides、验证和参考比例。FAnimNode_AudioMotionAnimNode_AudioMotion.hRuntime AnimGraph 控制节点,默认从所属的 Audio Motion Component 读取帧。#include "AudioMotionBlueprintLibrary.h"
#include "AudioMotionComponent.h"
UAudioMotionComponent* ConnectAMS(
AActor* TargetActor,
UAudioMotionProfile* Profile,
UAudioMotionBindingProfile* BindingProfile,
USoundWave* VoiceSound)
{
return UAudioMotionBlueprintLibrary::ConnectAudioMotion(
TargetActor,
Profile,
BindingProfile,
VoiceSound,
nullptr,
true,
false);
}
#include "AudioMotionDialogueCurveAsset.h"
float ReadDialogueCurve(
const UAudioMotionDialogueCurveAsset* CurveAsset,
float TimeSeconds)
{
return CurveAsset
? CurveAsset->EvaluateCurve(TimeSeconds, false)
: 0.0f;
}
资源与数据类型
Envelope、Dialogue、音乐分析和评估频率设置。
目标 Mapping 与生成的 Dialogue bindings。
可复用的 baked 帧通道曲线。
源 SoundWave、一个 baked 标量曲线以及材质设置。
Rig Mapping、手动 overrides、拓扑数据与参考比例。
Vocabulary 元数据以及对 Motion Units 的引用。
由 Vocabulary 和 Book 数据构建的 Planner 候选库。
Planner 使用的选择策略/语法。
计划的 Choreography 条目和可选的编译轨道。
保存可复用 Source/Target Mapping 与位移设置的 Editor 资源。
EAudioMotionModeEAudioMotionInputModeEAudioMotionChannelEAudioMotionPulseSourceEAudioMotionTransformChannelEAudioMotionTargetTypeEAudioMotionDialogueRoleEAudioMotionDialogueTargetTypeEAMSRigProfileKindEAMSMotionSequenceModeEAMSTrajectoryModeEAMSMotionCurveModeEAMSMotionActionKindEAMSMotionPathKindEAMSMotionDirectionEAMSMotionLevelEAMSMotionTimeQualityEAMSMotionForceQualityEAMSMotionFlowQualityEAMSSupportState
为保证 API 准确性,文档保留精确的 C++ 标识符。编辑器对主要面向生产的 Dialogue 角色使用中性显示标签。
FAudioMotionFrameFAudioMotionMusicSettingsFAudioMotionEnvelopeSettingsFAudioMotionDialogueSettingsFAudioMotionValueMappingFAudioMotionDialogueTargetConfigFAudioMotionDialogueRoleTargetFAudioMotionMorphBindingFAudioMotionMaterialScalarBindingFAudioMotionSceneBindingFAMSPerformanceAnalysisFAMSPerformancePlannerSettingsFAMSRigSlotMappingFAMSRigManualOverrideFAMSMotionKeyFAMSMotionTrack
资源安全
AMS 使用配置的 Output Folder 作为根目录。依赖 Mesh 的资源会保存在以所选 Rig Mesh 命名的文件夹中。
/Game/AudioMotion/
SK_MyRig/
Profiles/
Clips/
Animations/
Retarget/
Choreography/
RigProfiles/
Generated/
DialogueCurves/
生成的最终资源使用 Unreal 的唯一命名机制,不会静默覆盖已有资源。
Dialogue Curve 资源是共享的,不绑定到特定 Rig Mesh。
兼容性
故障排除
确认项目已启用插件,并在激活后重启了编辑器。同时确认软件包与项目的 Unreal Engine 版本匹配。
检查 Voice Sound 分析数据、Profile/Binding Profile 选择、目标 Rig Mesh 和自动分配。在重新构建或 Bake 前检查缺失或可疑的 Mapping。
验证 Rig Profile。切换到 Custom Mapping,以自动结果为基础,只修正错误行,执行 Validate 和 Apply,然后重新构建已编译的 Choreography track。
按照编辑器状态提示操作。当 AMS 启用所需分析设置后,保存 SoundWave,让 Unreal 重建音频分析数据,然后再次运行 Analyze + Build + Compile。
确认已启用材质输出、标量参数存在、Material Slot 正确,并且 Target Component Name 与目标 mesh 组件匹配;也可以留空,让 AMS 使用第一个合适的 mesh 组件。
使用 Custom 模式,以 Auto Mapping 为基础,只替换或清除错误行;如果 Source/Target 配对还会再次使用,请保存可复用的 Retarget Profile。
安装/使用与该引擎版本完全匹配的 AMS 源代码软件包,并使用该版本支持的编译器/工具链重新构建。不要复用其他引擎版本的 Binaries 或 Intermediate 输出。
Pautinka
请提供 Unreal Engine 版本、AMS 版本、问题出现于 Editor Preview / Runtime / Bake 中的哪个环节、准确复现步骤以及相关 Unreal 日志片段。
对于 Mapping 或 Animation Mixer 问题,还请提供 Source/Target Rig 类型以及使用的是 Auto、Custom 还是 Profile 模式。
将 Editor 制作、可复用资源、Blueprint 集成和公共 C++ 运行时 API 汇集到一个生产工作流程中。