音频空间化 SDK

**音频空间化** SDK 提供了控制应用程序如何将音频从音频源一个组件，用于在场景中将音频剪辑回放到音频监听器或通过音频混音器。 更多信息
请参阅 术语表传输到周围空间的方法。它是原生音频插件 SDK 的扩展。

音频源的内置声像定位是一种简单的空间化形式。它获取源并根据音频监听器一个充当麦克风的组件，接收场景中音频源的声音并输出到计算机扬声器。 更多信息
请参阅 术语表和音频源之间的距离和角度来调节左右耳贡献的增益。这为玩家提供了水平面上的简单方向提示。

Unity 音频空间化 SDK 和示例实现

为了提供灵活性并支持音频空间化，Unity 提供了一个开放接口，即音频空间化 SDK，作为原生音频插件 SDK 之上的扩展。您可以用更高级的声像定位器替换 Unity 中的标准声像定位器，并允许它访问计算所需的有关源和监听器的重要元数据。

有关原生空间化音频插件的示例，请参阅Unity 原生音频插件 SDK。该插件仅支持直接头部相关传递函数 (HRTF)，仅供示例使用。

您可以使用插件中包含的简单混响将音频数据从空间化插件路由到混响插件。HRTF 滤波基于 KEMAR 数据集的修改版本。有关 KEMAR 数据集的更多信息，请参阅麻省理工学院媒体实验室的文档和测量文件。

如果您想探索从人类受试者获得的数据集，请参阅IRCAM 的数据集。

初始化 Unity 音频空间化

Unity 在音频源解码音频数据后立即应用空间化效果。这会产生一个音频数据流，其中每个源都有自己的独立效果实例。Unity 仅使用其对应的效果实例处理来自该源的音频。

要使插件能够作为空间化器运行，您需要在效果的描述位字段中设置一个标志。

definition.flags |= UnityAudioEffectDefinitionFlags_IsSpatializer;

如果设置了UnityAudioEffectDefinitionFlags_IsSpatializer标志，则 Unity 会在插件扫描阶段将该插件识别为空间化器。当 Unity 创建插件实例时，它会为UnityAudioEffectState结构的spatializerdata成员分配UnityAudioSpatializerData结构。

要在项目中使用空间化器，请在项目设置中选择它（菜单：编辑 > 项目设置 > 音频）

然后，在您想要与空间化器插件一起使用的音频源的检查器一个 Unity 窗口，显示有关当前选定游戏对象、资源或项目设置的信息，允许您检查和编辑值。 更多信息
请参阅 术语表窗口中，启用空间化

您还可以通过 C# 脚本使用AudioSource.spatialize属性为音频源启用空间化器。

在包含大量声音的应用程序中，您可能希望仅为附近的音频启用空间化器，而对远处的音频使用传统的声像定位，以减少空间化器效果对混合线程的 CPU 负载。

如果您希望 Unity 将空间数据传递给不是空间化器的音频混音器插件，则可以使用描述位字段中的以下标志

definition.flags |= UnityAudioEffectDefinitionFlags_NeedsSpatializerData;

如果插件使用UnityAudioEffectDefinitionFlags_NeedsSpatializerData标志初始化，则插件会接收UnityAudioSpatializerData结构，但只有listenermatrix字段有效。有关 UnityAudioSpatializerData 的更多信息，请参阅空间化器效果元数据部分。

要停止 Unity 代表空间化器插件应用距离衰减，请使用以下标志

definition.flags |= UnityAudioEffectDefinitionFlags_AppliesDistanceAttenuation;

UnityAudioEffectDefinitionFlags_AppliesDistanceAttenuation标志指示 Unity 空间化器处理距离衰减的应用。有关距离衰减的更多信息，请参阅衰减曲线和可听性部分。

空间化器效果元数据

与在混合声音上运行的其他 Unity音频效果任何可以修改音频混音器组件输出的效果，例如过滤声音的频率范围或应用混响。 更多信息
请参阅 术语表不同，Unity 在音频源解码音频数据后立即应用空间化器。空间化器效果的每个实例都有自己的UnityAudioSpatializerData实例，主要与有关音频源的数据相关联。

struct UnityAudioSpatializerData
{
    float listenermatrix[16];   // Matrix that transforms sourcepos into the local space of the listener
    float sourcematrix[16];     // Transform matrix of the Audio Source
    float spatialblend;         // Distance-controlled spatial blend
    float reverbzonemix;        // Reverb zone mix level parameter (and curve) on 
                                // the Audio Source
    float spread;               // Spread parameter of the Audio Source (0..360 degrees)
    float stereopan;            // Stereo panning parameter of the Audio Source (-1: fully left, 1: fully right)
                                // The spatializer plugin may override the distance attenuation to
                                // influence the voice prioritization (leave this callback as NULL 
                                // to use the built-in Audio Source attenuation curve)
    UnityAudioEffect_DistanceAttenuationCallback distanceattenuationcallback;
    float minDistance;          // The minimum distance of the Audio Source. 
                                // This value may be useful for determining when to apply near-field effects. 
    float maxDistance;          // The maximum distance of the Audio Source, or the 
                                // distance where the audio becomes inaudible to the listener. 
    
};

该结构包含与检查器中音频源组件的属性相对应的字段：空间混合、混响区域混合、扩展、立体声声像、最小距离和最大距离。

UnityAudioSpatializerData结构包含音频监听器和音频源的完整 4x4 变换矩阵。监听器矩阵被反转，以便您可以将这两个矩阵相乘以获得相对方向向量。监听器矩阵始终是正交的，因此您可以快速计算逆矩阵。

Unity 的音频系统仅提供原始源声音作为立体声信号。即使源是单声道或多通道，信号也是立体声，并且 Unity 根据需要使用上混或下混。

矩阵约定

sourcematrix字段包含音频源变换矩阵的副本。对于未旋转的游戏对象Unity 场景中的基本对象，可以表示角色、道具、场景、摄像机、路点等。游戏对象的功用由附加在其上的组件定义。 更多信息
请参阅 术语表上的默认音频源，该矩阵是一个平移矩阵，其中位置编码在元素 12、13 和 14 中。

listenermatrix字段包含音频监听器变换矩阵的逆。

您可以确定从音频监听器到音频源的方向向量，如下所示，其中 L 是listenermatrix，S 是sourcematrix

float dir_x = L[0] * S[12] + L[4] * S[13] + L[ 8] * S[14] + L[12];
float dir_y = L[1] * S[12] + L[5] * S[13] + L[ 9] * S[14] + L[13];
float dir_z = L[2] * S[12] + L[6] * S[13] + L[10] * S[14] + L[14];

（L[12]、L[13]、L[14]）中的位置实际上是您在 Unity 的检查器窗口中看到的摄像机一个组件，用于创建场景中特定视点的图像。输出要么绘制到屏幕上，要么捕获为纹理。 更多信息
请参阅 术语表矩阵的负值。如果摄像机也旋转了，您还必须首先撤消旋转的影响。要反转变换旋转矩阵，请转置 L 的左上角 3x3 旋转矩阵，并按如下所示计算位置

float listenerpos_x = -(L[0] * L[12] + L[ 1] * L[13] + L[ 2] * L[14]);
float listenerpos_y = -(L[4] * L[12] + L[ 5] * L[13] + L[ 6] * L[14]);
float listenerpos_z = -(L[8] * L[12] + L[ 9] * L[13] + L[10] * L[14]);

有关音频空间化插件代码中的示例，请参阅Plugin_Spatializer.cpp 文件中的第 215 行。

衰减曲线和可听性

除非您指定了UnityAudioEffectDefinitionFlags_AppliesDistanceAttenuation标志（如初始化 Unity 音频空间化部分中所述），否则 Unity 音频系统仍会控制距离衰减。Unity 在声音进入空间化阶段之前对其应用距离衰减，并允许音频系统知道源的近似可听性。音频系统使用近似可听性根据重要性对声音进行动态虚拟化，以匹配用户定义的最大真实声音限制。

Unity 不从实际信号电平测量中检索可听性信息，而是使用从距离控制衰减曲线读取的值、音量属性和混音器应用的衰减的组合。

您可以直接覆盖衰减曲线，或者可以使用音频源曲线计算的值作为修改的基础。要覆盖或修改该值，请使用UnityAudioSpatializerData结构中的回调，如下所示

typedef UNITY_AUDIODSP_RESULT (UNITY_AUDIODSP_CALLBACK* UnityAudioEffect_DistanceAttenuationCallback)(
    UnityAudioEffectState* state,
    float distanceIn,
    float attenuationIn,
    float* attenuationOut);

您还可以使用简单的自定义对数曲线，如下所示

UNITY_AUDIODSP_RESULT UNITY_AUDIODSP_CALLBACK SimpleLogAttenuation(
    UnityAudioEffectState* state,
    float distanceIn,
    float attenuationIn,
    float* attenuationOut)
{
    const float rollOffScale = 1.0f; // Similar to the one in the Audio Project Settings
    *attenuationOut = 1.0f / max(1.0f, rollOffScale * distanceIn);
    return UNITY_AUDIODSP_OK;
}

使用 Unity API 中的 C# 脚本

音频源上有两种方法允许设置和获取空间化器效果的参数：SetSpatializerFloat和GetSpatializerFloat。这些方法的工作方式类似于通用原生音频插件接口中的SetFloatParameter和GetFloatParameter方法。但是，SetSpatializerFloat和GetSpatializerFloat获取它们必须设置或读取的参数的索引，而SetFloatParameter和GetFloatParameter则按名称引用参数。

布尔属性AudioSource.spatializer链接到 Unity 的音频源检查器窗口中的空间化选项。该属性控制 Unity 如何根据您在音频项目设置一系列广泛的设置，允许您配置物理、音频、网络、图形、输入以及项目其他许多方面的行为方式。 更多信息
请参阅 术语表中选择的插件来实例化和释放空间化器效果。

如果空间化器效果的实例化在内存或项目中的其他资源方面非常占用资源，那么从预设的“池”中分配空间化效果可能会更有效，这样 Unity 就无需在每次需要使用它时都创建一个新的空间化器实例。如果您保持 Unity 插件接口绑定非常轻量级并动态分配音频效果，则可以避免项目中的帧下降或其他性能问题。

示例插件的已知限制

由于快速卷积算法，快速移动会导致一些拉链伪像，您可以通过使用重叠保存卷积或交叉淡入淡出缓冲区来消除这些伪像。

该代码也不支持倾斜听众的头部，无论听众是直接附加到玩家角色上，还是位于其他地方的摄像机。